Appendix B - Mobile Responsive Output Format

There are many tools available for composing HTML that can be used to form mobile responsive output from Documaker. These include Adobe’s Dreamweaver, Eclipse Foundation's IDE for Java EE Developers, Notepad++ and many others. This section provides more insight on techniques for forming the HTML composition desired from Documaker mobile.

We recommend these steps:

  1. Start with setting up a directory with separate files for HTML, CSS, JS, IMG (images) and XSL. Place the files other than the HTML in separate sub directories under the HTML location. It is recommend to use all lowercase for all file and directory names.
  2. Build prototype HTML with hardcoded values as placeholders for variable data from Documaker. This prototype HTML should follow the design of one of the wireframe layouts defined in Mockup Design for Mobile section. The prototype HTML can then be distributed for further review and adjustment. Mark hard coded values in the HTML with a special CSS style class, such as “hardcode_val”. This will be used later in the variable content mapping process.
  3. Add @media rules to the CSS used with the prototype to adjust the style rules for various max-width values. So in step 2, if you started with the thinnest layout (mobile first design) add rules to implement the wireframe and handle styling for the larger layout(s). The idea here is to make as few updates possible in the @media rules to achieve the desired results. Doing this allows you to treat the @media rules as limited overrides to the base CSS rules and it allows changes to the base CSS rules to flow through to all layout sizes without requiring special attention in the @media definitions.
  4. Add JavaScript automation to the prototype that supports your desired mobile page navigation. This may include handling click events on a document menu or other navigation UI paradigm. Place the JavaScript syntax required in a file with a *.js extension in the directory setup for JS files. You may consider using jQuery as a framework for implementing mobile document automation and UI event handling.
  5. Add JavaScript automation to the prototype that supports your desired content data based interactions (things such as table row drill in). Again place the JavaScript syntax in a file (can be the same file as step 4) with a *.js extension in the directory setup for JS files.
  6. Merge the prototype HTML just created with the XSL Stylesheet developed previously to process the XML produced by the Documaker MRO and snippets. Depending on the tools you are using to compose HTML, either chunks of HTML can be pasted into various XSL Templates that will push out the HTML depending on XML contents from Documaker, or the HTML can mostly be placed in the root XSL Template (where match="/") and then other XSL techniques can be used to control the HTML output (such as <xsl:for-each select="myExpresion">). Also find the variable fields that were hardcoded in the prototype HTML syntax and replace their hardcoded values with XSL <xsl:value-of select=" FLD[@N=’FldName’]"/> syntax so that live XML values from Documaker will flow through to the HTML output for testing.

    Note: Change the HTML CSS style class used on the values that are now mapped from XSL to a new value such as “variable_val”. It helps you identify what values are live and what values are hard coded.

  7. Optionally add support for rendering charts and tables from Documaker in your mobile output. There are examples of both table and chart rendering logic contained the default snippets supplied with Documaker mobile for this purpose. This logic can be taken from the Documaker mobile defaults and reused in your own output to form charts and tables based on the JSON data produced by the Documaker MRO.
  8. Create a master snippet in your snippet library deployed with Documaker. You can copy the default master.xml snippet and save it with a new name by adding a context value to the file name with an underscore (for example: “master_benefits.xml”, the context value is “benefits”). In the new master snippet update the XSL Stylesheet reference to equate to the XSL Stylesheet you have created by updating the href attribute of line “<?xml-stylesheet type="text/xsl" href="resources/xsl/default.xsl" ?>” replacing the “resources/xsl/default.xsl” entry so it equates to the location of your XSL Stylesheet.
  9. In Documaker Studio, update the Documaker Application Definition for the formset (KEY1/KEY2) whose composition output will be used to drive this mobile output with a global context value. This value will be used to locate the desired master snippet. For example, if the global context value is set to “benefits” in Studio then the Documaker MRO will look for snippets that have “*_ benefits.xml” in their file name, starting with the master snippet: “master_benefits.xml”. Usually the only snippet you will need to customize is the master, so you will not need to copy and create any other snippets with a “*_ benefits.xml” name. In the example above the Documaker MRO will first look for snippets named “*_ benefits.xml” and then it will look for the default snippet names that do not have the “_ benefits” in their name.
  10. Generate Mobile Output by printing with the MRO or Mobile Responsive Output delivery channel. This will drop an XML dataset file (assuming XML based snippets) that you can use for testing in a browser by directly opening the XML file with a browser. The browser (IE9+, Firefox, Chrome, Safari, iOS, Android) will run an XML to HTML transform on the XML file that was directly opened so you can test.
    As testing continues, most of the updates required will usually be to the XSL Stylesheet, either adjusting XSLT logic or adjusting the HTML being written by the XSLT to achieve the mobile presentation desired. As changes are made to the XSL, CSS, JS or XML data file the change impacts can be viewed and retested by refreshing the browser window. Once testing looks solid with an initial transaction, create several Documaker transactions to test with. Make sure to touch on various transaction configurations from Documaker to test as many possible combinations and ordering of XML from the Documaker MRO as possible for your document.
  11. When development testing is complete, it's time to reorganize the document’s mobile components for production deployment. Review the CSS, JS, IMG and XSL files for looking for referenced content that can be embedded in the XSL for the document. For example, CSS rules that were developed just for this mobile document can be placed in the XSL as part of the root XSL Template so they are emitted as in-line styles with the HTML results. Placing the CSS rules in the XSL eliminates management and delivery (via HTTP/HTTPS) of an external file along with the mobile document.
    All CSS and JS files that are not shared resources between other documents or web pages should be embedded in the XSL as part of the root XSL Template.
  12. Optionally move the contents of the (now probably quite a bit larger) XSL document into your master snippet XML replacing the XSL Stylesheet reference in the master snippet XML. This removes the XSL document an external file that must be managed (and delivered via HTTP/HTTPS) along with the mobile document. Now all the mobile composition instructions for this document are housed in the master snippet, and the resulting mobile output requires a minimum delivery footprint of files from the Web server. The last step in this process is to involve your company’s web masters to discuss mobile document delivery options such as your company web portal.