Q4Widgets API Documentation

q4.briefcase

The investor briefcase widget works similar to a shopping cart. The briefcase is a 'shopping cart' for various PDF files across a site.

Important Notes:

  1. Currently only PDF files are supported for the briefcase.
  2. This widget requires a MODERN BROWSER, and the download functionality does not work correctly on mobile (current solution is hiding the download container on mobile screen sizes).
  3. This widget uses browser session storage to collect files, any items in the briefcase (aka shopping cart) will be removed upon closing the tab or window, and will not exist in new tab/windows.
  4. The briefcase.js script is required on all pages that the briefcase icon is desired, as well as the briefcase page (aka checkout page).
  5. The JSZip, JSZip-Utils and FileSaver script are only required on the briefcase page (aka checkout page), as they are used to generate the ZIP file.

 

Instructions:

  1. A class should be added to the container element of all modules/widgets which require the briefcase icon. For example, the class could be called 'add-to-briefcase' and be listed in the module properties 'CSS Class' field.
  2. Additional data attributes must be added to the module/widget container that is referenced via class through the 'contentClass' option.
    data-briefcase-title should reference the class of the title container for that content item (used for the name of the file in the briefcase)
    data-briefcase-subtitle (optional) should reference the class of a unique descriptor for that content item (used alongside title for the name of the file in the briefcase)
    data-briefcase-name should reference the type of content that items in that container should be categorized as (used for grouping and folder structure).

 

Script link
q4.briefcase.1.0.5.min.js
Source file
q4.briefcase.js, line 2
Requires

Examples

<div class="module module-news add-to-briefcase" data-briefcase-name="News" data-briefcase-title=".module_headline-link">
    <div class="module_container module_container--outer">
        <h2 class="module_title"><span class="ModuleTitle">Press Releases</span></h2>
        <div class="module_container module_container--inner">
            <div class="module_container module_container--content">
                <div class="module_item">
                    <div class="module_date-time">
                        <span class="module_date-text">January 16, 2017</span>
                    </div>
                    <div class="module_headline">
                        <a href="http://website.com/ir/news/details/2017/Press-Release-1/default.aspx" class="module_headline-link">Press Release 1</a>
                    </div>
                    <div class="module_links">
                        <a href="http://website.com/files/doc_news/release1.pdf" class="module_link">
                            <i class="q4-icon_pdf"></i>
                            <span class="module_link-text">Download</span>
                            <span class="sr-only">PDF format download (opens in new window)</span>
                        </a>
                        <a class="module_link module-briefcase_link" href="http://website.com/files/doc_news/release1.pdf">
                            <i class="q4-icon_briefcase-line"></i><span class="sr-only">Add to Briefcase</span>
                        </a>
                    </div>
                </div>
                <div class="module_item">
                    <div class="module_date-time">
                        <span class="module_date-text">January 2, 2017</span>
                    </div>
                    <div class="module_headline">
                        <a href="http://website.com/ir/news/details/2017/Press-Release-2/default.aspx" class="module_headline-link">Press-Release-2</a>
                    </div>
                    <div class="module_links">
                        <a href="http://website.com/files/doc_news/release2.pdf" class="module_link">
                            <i class="q4-icon_pdf"></i>
                            <span class="module_link-text">Download</span>
                            <span class="sr-only">PDF format download (opens in new window)</span>
                        </a>
                        <a class="module_link module-briefcase_link" href="http://website.com/files/doc_news/release2.pdf">
                            <i class="q4-icon_briefcase-line"></i><span class="sr-only">Add to Briefcase</span>
                        </a>
                    </div>
                </div>
            </div>
        </div>
    </div>
</div>
<div class="module module-presentation background--grey add-to-briefcase" data-briefcase-name="Presentations" data-briefcase-title=".module_headline-text">
    <div class="module_container module_container--outer">
        <h2 class="module_title"><span class="ModuleTitle">Presentation Archive</span></h2>
        <div class="module_container module_container--inner">
            <div class="module_container module_container--content">
                <div class="module_item">
                    <div class="module_date-time">
                        <span class="module_date-text">February 1, 2017</span>
                    </div>
                    <div class="module_headline">
                        <span class="module_headline-text">Presentation of Important Event</span>
                    </div>
                    <div class="module_links">
                        <a href="http://website.com/files/doc_downloads/presentation.pdf" target="_blank" class="module_link module-presentation_document">
                            <i class="q4-icon_pdf"></i>
                            <span class="module_link-text">View this Presentation</span>
                            <span class="sr-only">PDF Format Download (opens in new window)</span>
                            <span class="module_file-text">PDF 4 KB</span>
                        </a>
                        <a class="module_link module-briefcase_link" href="http://website.com/files/doc_downloads/presentation.pdf">
                            <i class="q4-icon_briefcase-line"></i><span class="sr-only">Add to Briefcase</span>
                        </a> 
                    </div>
                </div>
            </div>
        </div>
    </div>
</div>

Options

briefcaseContentContainer string
The class of the briefcase container element. Items added to the briefcase will be rendered inside this container using the 'briefcaseTpl' and 'emptyBriefcaseTpl'.
Default value
.module-briefcase_container--content
briefcaseDownloadContainer string
The class of the briefcase download container. The 'downloadTpl' will be used to render content in this container.
Default value
.module-briefcase_container--download
contentClass string
The class of the module or widget container which has the data-briefcase-name and data-briefcase-title attributes.
Default value
.module
contentItemClass string
The container class of the item in the module or widget which contains the file, name, icon etc..
Default value
.module_item
fileSelector string
The selector used on each file link that should have the potential to be added to the briefcase.
Default value
a.module_link[href$=".pdf"], a.module_link[href$=".PDF"], a.module_link[href$=".Pdf"]
briefcaseCls string
The class to be added to the file link identifying it as a briefcase-capable link.
Default value
.module-briefcase_link
activeCls string
The class to be added to the file selector for items existing in the briefcase.
Default value
.js--active
inBriefcaseCls string
The icon class to be added for items existing in the briefcase. This is used to change the appearance of the icon.
Default value
.q4-icon_briefcase-fill
notInBriefcaseCls string
The icon class to be added for items that do not exist in the briefcase. This is used to change the appearance of the icon.
Default value
.q4-icon_briefcase-line
iconTpl string
The template to be appended to each item to show the add to briefcase link/icon.
Parameters
url string
the URL of the file, as defined by 'fileSelector' option
cls string
the class defined by 'briefcaseCls'
Example
'<a class="module_link {{cls}}" href="{{url}}">' +
     '<i class="q4-icon_briefcase-line"></i>' +
     '<span class="sr-only">Add to Briefcase</span>' +
 '</a>'
briefcaseTpl string
The template used to render the existing briefcase items on a page. Template content is rendered inside the 'briefcaseContentContainer'.
Parameters
url string
the URL of the file, as defined by 'fileSelector' option
title string
the title of the document/content item
name string
the name of the briefcase file group. Pulled from the container element's data tag (ex. "Press Release")
Example
'<div class="module_item briefcase_content--section">' +
    '<h4>{{name}}</h4>' +
    '<ul data-briefcase-name="{{name}}">' +
        '{{#items}}' +
            '<li>' +
                '<span>{{title}}</span>' +
                '<a href="{{url}}" class="module_link module-briefcase_download">' +
                    '<i class="q4-icon_pdf"></i>' +
                    '<span class="sr-only">PDF format download (opens in new window)</span>' +
                '</a>' +
                '<a href="#!remove" class="module_link module-briefcase_remove">' +
                    '<i class="q4-icon_cross"></i>' +
                    '<span class="sr-only">Remove from briefcase</span>' +
                '</a>' +
            '</li>' +
        '{{/items}}' +
    '</ul>' +
'</div>'
emptyBriefcaseTpl string
The template used when there are no briefcase items. Template content is rendered inside the 'briefcaseContentContainer'.
Default value
<p>There are currently no items in your briefcase.</p>
removeFromBriefcaseGroupCls string
The class for the briefcase name group as seen in the briefcaseTpl. The element with this class should also have a data attribute for the briefcase name.
Default value
ul
removeFromBriefcaseItmCls string
The class for the briefcase item inside a group, as seen in the briefcaseTpl.
Default value
li
zipFileName string
The name of the ZIP file that is generated after triggering the download.
Default value
briefcase-files.zip
downloadButton string
The class of the download button, this button must be inside the 'downloadTpl'.
Default value
.button
downloadingMessage string
The message that appears after clicking the download button (it can take a few seconds depending on the number of files). The message will be rendered inside the 'briefcaseDownloadContainer'. Once the file save has been triggered, the container will revert back to its previous appearance and render the 'downloadTpl'. This is to prevent additional 'clicks' on the download button while the ZIP file is generating.
Default value
<p class="module_loader"><i class="q4-icon_spinner"></i><span class="sr-only">Downloading files...</span></p>