How to Customize PrizmDoc Buttons, Menu Bars, and Styles
PrizmDoc is constantly evolving with a variety of new functionalities. However, there are dozens of customization options that are always available to you. The documentation references a variety of code examples to enhance your PrizmDoc experience, but for today’s tutorial, we’ll focus on custom buttons, changing the menu bar position, and modifying styles.
Each customization can improve the functionality for your user’s specific needs while also making the design consistent with your brand. Take a look at the following examples of customization options available for your use today.
An Introduction to the Customization Options
The following describes how to implement a few of the customization options that are available. Take a look at some of the most common customizations that developers use with PrizmDoc:
Adding a Custom Button
Adding a custom button is as simple as adding some markup and a little bit of JavaScript anywhere on the web page. In this example below, we will look at adding a button to the Viewing Client in a way that matches the design language and code style of the existing Viewing Client.
If you are not yet familiar with the code structure, refer to these topics:
In this topic, we will add a button to the default View tab that will add an Approved stamp annotation to the top right of the first page in the document.
Adding the Button HTML
The bulk of the Viewing Client markup is inside the file viewerTemplate.html; this includes all the toolbars and vertical slide-outs.
The View tab appears at the top of the document, and is identified by the data attribute data-pcc-nav-tab=”view”. Inside the .pcc-tab-pane, the actual menu bar, there are two lists of buttons. One is the normal list starting from the left, .pcc-left, and the second is the buttons floating on the right side, .pcc-pull-right. To add the button on the right side:
<div class="pcc-pull-right"> <button class="myCustomApprovedButton">Approve </button> <button class="pcc-icon pcc-icon-print" data-pcc-print="launch"> </button> <button data-pcc-download class="pcc-icon pcc-icon-download"> </button> </div>
You’ve added the button in bold to the rest of the list, to appear first in the right-hand side buttons.
Adding the Custom JavaScript
Associating logic to the buttons is handled in the viewer.js file.
First, find the button in the DOM. Toward the top of the file, there is a property on the Viewing Client, this.viewerNodes, which holds all of the Viewing Client DOM elements. Add the button to the end of the list:
... $searchBeginsWith: viewer.$dom.find("[data-pcc-search=beginsWith]"), $searchEndsWith: viewer.$dom.find("[data-pcc-search=endsWith]"), $searchWildcard: viewer.$dom.find("[data-pcc-search=wildcard]"), $customApproved: viewer.$dom.find(".myCustomApprovedButton") };
We have used a variable name starting with a $, the global name of jQuery, to indicate that this is a jQuery-wrapped variable. Any time a variable name starts with a $ in this file, it indicates that the object is able to use the entire jQuery API.
Second, add logic to the button’s click event. A few lines down from this section is the function bindMarkp, where logic is added to the DOM nodes. To keep with convention, go all the way to the bottom of this function, and add the click handler there:
viewer.viewerNodes.$customApproved.on("click", function (ev) { // get the first page attributes viewer.viewerControl.requestPageAttributes(1).then( function success(attributes) { // let's add a stamp now var mark = viewer.viewerControl.addMark(1, "StampRedaction"); // set the stamp text mark.setLabel("Approved"); // set the stamp location mark.setRectangle({ width: 180, height: 50, x: attributes.width - 200, y: 20 }); }, function failed(error) { // :( tell the user there was an error alert(error); }); }); </pre
Styling the Button
First, add a new custom icon to the CSS vocabulary. To support all browsers and screen types, you will need two icons: a 26×26 pixel icon, and a 40×40 pixel icon. For this example, let’s assume that you have icons already created, named check.png and check@2x.png, respectively and the icons are available in the images folder. The Viewing Client uses an icon sprite in order to optimize icon image loading. In this example, you will not be using the sprite, and instead include standalone images. Toward the top of the viewer.css file, there are the icon definitions, in the form of .pccv .pcc-icon-…. You will add the new icon at the end of this section:
.pccv .custom-icon-check { background-image: url(../img/check.png); }
Note that to support IPS screens, you will need to add a second icon inside the @media (min-width:0) media query. This media query targets all modern browsers capable of scaling icons, to ensure that any high density screen attached to a browser (that can scale icons) will get high resolution images.
Here, you will add out 2x icon image:
.pccv .custom-icon-check { background-image: url(../img/check@2x.png); background-size: 26px; background-position: center; }
Finally, update your HTML markup to use this new icon instead of text:
<button class="myCustomApprovedButton pcc-icon custom-icon-check"></button>
You have completed adding a custom button.
Changing the Position of the Menu Bar
You can change the layout of the tab panes by modifying the markup located in viewerTemplate.html.
Adding the pcc-tab-vertical class makes the tab pane vertical.
Adding either a pcc-left or pcc-right class specifies the side on which the vertical tab pane will appear.
<div class="tabset pcc-nav-tabset" data-pcc-nav> <!-- Tab --> <div class="pcc-tab" data-pcc-nav-tab="demo"> <div class="pcc-tab-item">Demo</div> <!-- This tab pane is vertical and left aligned --> <div class="pcc-tab-pane pcc-tab-vertical pcc-left"> <!-- Tab content --> </div> </div> <!-- End tab --> </div>
Customizing the Style: Working With the LESS preprocessor
The Viewing Client uses LESS to pre-process the CSS for the Viewing Client. In order to facilitate using this pre-processor in a development environment, the following files are included in the viewer-assets folder:
Gruntfile.js
package.json
In order to use these files, you will need to install Node.JS in your development environment. Then, you can run the following commands from a command line or terminal:
npm install -g grunt-cli npm install
Point the command line interface to the viewer-assets folder in order to execute these commands.
Next, you can use this command to build the CSS files required for production:
grunt buildprod
You can also build development files, which will include extra source maps helpful in debugging CSS:
grunt builddev
Finally, while developing, you may choose to run the task in such a way that it will automatically run whenever any of the Less files change, as such:
grunt dev
The Less preprocessor will generate the following files:
- css/viewer.css – contains the bulk of the Viewing Client styles
- css/fonts.css – contains fonts necessary for printing
- css/legacy.css – contains the styles necessary for IE8
Customizing the Styles
The styles should be loaded in the Viewing Client in the following order:
- normalize.min.css
- viewercontrol.css
- viewer.css
- legacy.css (in IE8 only)
Namespace
The Viewing Client uses the class .pccv in order to namespace the styles it uses. In order to override any selector used in the Viewing Client, your selector must begin with the class .pccv:
/* Set the navigation tab bar to dark red */ .pccv .pcc-nav-tabset, .pccv .pcc-nav-tabset .pcc-tab-item, .pccv .pcc-status-bar { background: #5b100d; }
Organization
All resulting CSS files have a Less counterpart in the root of the less folder. These are the only files that can be build on their own. File names beginning with an underscore ( _ ) are partial style files, and are included as modules in the root files. These individual components are split out into the following structure:
- base – These files contain the variables and mixins used by the Viewing Client, as well as the overall layout. Included here are also the reusable, generic components, such as the grid and form inputs.
- components – The files contain the large Viewing Client components, and are named in a self-explanatory way. For example, styles related to the search functionality are help in the _search.less file.
Variables
There are many variables contained in less/base/_variables.less, which control things like the image resources, color scheme, and toolbar sizing. These variables can be modified in order to propagate changes throughout the Viewing Client.
Icons
A number of icons are used throughout the Viewing Client for different UI elements. These icons are stored in the icons*.png files. The icons sprite image has a dark version for use on light backgrounds and a white version for use on dark backgrounds. There is a larger @2x version, to account for HD/Retina displays, and a regular sized version for legacy support. Since modern browsers support the background-size property, we use the @2x images for all icons and degrade to the regular sized icons for Internet Explorer 8.
Media Queries
The Viewing Client utilizes CSS3 Media Queries with expressions using min-width and max-width to adjust the layout of navigation and dialogs. The Media Query Breakpoints are set according to the Viewing Client layout. On smaller viewports the tab navigation collapses into a menu and some tools are hidden. On larger viewports the dialogs transform from horizontal to a vertical layout to utilize screen real estate.
The breakpoints are located in the less/base/_breakpoints.less file, and are used throughout the less files as detached rulesets. The breakpoints are as follows:
/* Target modern browsers that support media queries */ .modernView(@rules) { @media (min-width: 0) { @rules(); } } /* Mobile & Tablet Sizes, collapse navigation tabs into menu */ .mobileView(@rules) { @media (max-width: 767px) { @rules(); } } /* Desktop Sizes */ .desktopView(@rules) { @media (min-width: 768px) { @rules(); } }
Grid System
The Viewing Client uses a basic grid system to assist with the UI layout. Through a series of rows and columns the layout can scale dynamically. Rows are used to create horizontal groups of columns. Columns are created by defining the number of twelve columns you will span. For example, three columns would use three divs with a class of .pcc-col-4:
<div class="pcc-row"> <div class="pcc-col-4">Left</div> <div class="pcc-col-4">Center</div> <div class="pcc-col-4">Right</div> </div>
Legacy CSS support
The legacy CSS necessary for IE8 is held in the less/legacy.less file. Here we address unsupported or troublesome CSS features like drop shadows, opacity or background alpha transparency. In addition, because Media Queries are not supported in Internet Explorer 8 and no Media Query polyfills are used in this regard, we add additional styles here that are accounted for in Media Queries in modern browsers.
Viewercontrol.css
This file contains the styles required for using ViewerControl directly. This file should not be changed directly, but rather, should have any necessary rules overridden by your own CSS. If choosing not to use our Viewing Client, and instead embedding ViewerControl directly in a custom integration, this CSS file is still required.
Polyfills
There are a few polyfills used to provide support for modern browser features:
Normalize (http://necolas.github.io/normalize.css/) – Normalize provides better cross-browser consistency in the default styling of HTML elements.
For more tutorials on customization, visit the PrizmDoc documentation today!