Suite Labs: Customizing SuiteHelp Output


Published on

Sponsored by: Suite Solutions Ltd.
Presenter: Adena Frazer
In this webinar you will learn how to customize SuiteHelp output using the SuiteHelp customization plug-in, configuration files, and Shakespearean templates.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Suite Labs: Customizing SuiteHelp Output

  1. 1. SuiteHelp Customization Adena Frazer, Suite Solutions
  2. 2. Who am I? Adena Frazer • Background in Computer Science and Education • Early and senior member of the Suite Solutions team • Given many public and private training seminars over the past five years • Extensive expertise implementing DITA and CMS solutions for a wide variety of organizations • Responsible for internal training and mentoring for developers at Suite Solutions • Help companies get it right the first time
  3. 3. About Suite Solutions Our Vision: Enable companies to engage their customers by providing quick access to relevant information • Help companies get it right the first time • XML-based Authoring/Publishing Solutions • Enterprise Intelligent Dynamic Content: SuiteShare • Consultancy, Systems Integration, Application Development • Cross-Industry Expertise • High Tech, Aerospace & Defense • Healthcare, Discrete Manufacturing • Blue Chip Customer Base • Hundreds of Person Years of Experience on Staff
  4. 4. SuiteShare: Dynamic Publishing Taking the Leap to a New Paradigm • Variety of content: documentation, videos, how-to articles, safety information, data sheets, marketing material • Context filtering: quick, goal-oriented access to contextually relevant content • Personalized docs: allow readers to assemble content on demand and render to PDF for print and eBook for offline mobile access • Audience Participation: allow your audience to add new content, comment on existing content, express approval, and easily share knowledge with others on the KB and on social media • Modern User Experience: smooth transition between mobile and desktop • Activity often starts on mobile, moves to desktop, returns to mobile • Internet connection not always available
  5. 5. Main Topics  Technical Architecture • SuiteHelp Process Flow • DITA Accelerator • Methods for Customization  Customizing the SuiteHelp GUI • SuiteHelp customization plugin • SuiteHelp configuration files • Customizing the CSS styling  Lucius Overview  Lucius Case Studies • Customizing the HTML layout  Hamlet Overview  Hamlet Case Studies
  6. 6. SuiteHelp Process Flow Using Native HTML5 Generation Using DITA Open Toolkit XHTML Generation Note: As of version 1.7.1 the DITA-OT is starting to support HTML5
  7. 7. DITA Accelerator Core Technology • Set of libraries for processing XML content • Generates variety of output formats: HTML5, SuiteHelp and EPUB • Used as the main rendering engine for the SuiteShare dynamic publishing platform • Note: These libraries are released as compiled executables, and are not customizable by clients. Internationalization Support • Integrates ICU (International Components for Unicode) libraries • See for more details
  8. 8. DITA Accelerator Developed in Haskell • Functional programming language • Strong static typing • Lazy evaluation • Extensive open source modules Benefits for the DITA Accelerator • Great performance • It allows the codebase to be powerful, clear, and concise
  9. 9. Methods for Customization • Configuration Files • UI Configuration files • Classmap: Maps between DITA elements and attributes to HTML5 • Shakespearean Templates • Hamlet – HTML templating language • Lucius – CSS templating language • Advantages: - Compile-time guarantees on well-formed content - Static type safety, aids in the prevention of XSS (cross-site scripting) attacks - Automated checking of valid URLs through type-safe URLs • See • JavaScript
  10. 10. Customizing the GUI  Customizing the SuiteHelp GUI • SuiteHelp customization plugin • SuiteHelp configuration files • Customizing the CSS styling  Lucius Overview  Lucius Case Studies • Customizing the HTML layout  Hamlet Overview  Hamlet Case Studies
  11. 11. Suitehelp-Customization Plugin • Provides out of the box styling (skin) for SuiteHelp output • Use this as a basis for your own customization • Best practices: • Rename this folder with a descriptive name for your customization • Keep a copy of the original suitehelp-customization folder for future reference and starting new customizations • All customizations should be located in this folder; do not make changes in the suitehelp plugin folder • Makes it easier to upgrade to new versions of SuiteHelp
  12. 12. Naming your Customization Plugin Using the DITA Toolkit Make the following changes in your customization folder: 1. Change the name of the customization folder in conductor.xml to your custom name a. Change the suitehelp-conf property name b. Change the pointer to index.html 2. Change the id of your plugin in plugin.xml <plugin id="com.suite-sol.your-customization-name"> 3. Run integrator.xml C:DITA-OT>ant –f integrator.xml <property name="suitehelp-conf" value="${dita.dir}/plugins/your-customization-name/suitehelp-conf.xml"/> file="${dita.dir}/plugins/your-customization-name/homepage/index.html"
  13. 13. Naming your Customization Plugin Without using the DITA Toolkit 1. Change the name of the customization folder in suitehelp.bat: --suitehelp-conf suitehelpyour-customization-name suitehelp-conf.xml For all SuiteHelp Configurations After these files have been updated: 1. Rename the customization folder name to your new customization name Note: You must first close all open files in that folder before you will be able to rename the customization folder. 2. Confirm that all of the names match and are spelled correctly 3. Run SuiteHelp and confirm that output is generated successfully
  14. 14. SuiteHelp Configuration Files • SuiteHelp uses XML configuration files • The suitehelp plugin contains: • Suitehelp-conf-prereqs.xml – Prerequisite configuration options • Suitehelp-conf.xml – core SuiteHelp configuration data • The suitehelp-customization plugin contains: • Suitehelp-conf.xml – custom configuration options • The configuration files in the suitehelp directory should not be changed. • The contents of the suitehelp configuration files can be overridden by the configuration file in the suitehelp-customization directory
  15. 15. SuiteHelp Configuration Files • suitehelpsuitehelp-conf-prereqs.xml includes: • Supporting JS files • License file • Catalog file • DITA-OT build file • suitehelpsuitehelp-conf.xml includes: • Lucius files • Main JS file • Static directory • Hamlet file • Strings Directory • CSS Variables • Search configuration options
  16. 16. SuiteHelp Configuration Files • The suitehelp-customizationsuitehelp-conf.xml file is the file that controls most of the SuiteHelp customizations • Out of the box, it includes: • Lucius Files • JS File • Static Directory • CSS Variables • Classmap file for running SuiteHelp in native mode • Sample custom callback • When customizing SuiteHelp, existing values in this file can be changed, and elements can be added to override the configuration files in the SuiteHelp directory.
  17. 17. CSS Variables • Variables that control CSS output can be set in the SuiteHelp configuration files. • These variables are processed by the DITA Accelerator and are made available to the Shakespearean templates for inclusion in the output. • When the DITA Accelerator creates the HTML and CSS files from the Shakespearean templates, the variables are resolved, and their values appear in the resulting files. Available CSS Variables topHeight tabsHeight draggerTopHeight logoWidth leftWidth topNavHeight centerLeftMargin mobileWidth bottomHeight
  18. 18. CSS Customization: Lucius What is Lucius? • Lucius is a template language that is used to generate CSS files. • All CSS files are valid Lucius files Why use Lucius instead of using CSS directly? • Lucius has powerful features which enhance and simplify CSS generation: • Variable interpolation • URL interpolation • Nested CSS blocks • Local variables can be declared and used
  19. 19. Lucius Files used by SuiteHelp • Out of the box, the suitehelp-conf.xml file references two Lucius files which should be used for CSS customization • The file paths are relative to the suitehelp-customization directory <cssfiles> <file>templates/css/screen.lucius</file> </cssfiles> <cssprintfiles> <file>templates/css/print.lucius</file> </cssprintfiles> • Screen.lucius is used to generate screen.css, which controls the formatting in the browser • Print.lucius is used to generate print.css, which controls the formatting when printing.
  20. 20. CSS • CSS files define styling for HTML content • CSS rules consist of a selector and at least one declaration (Diagram from For more information, see: • for a tutorial and reference information • for detailed W3C recommendations and specifications
  21. 21. CSS Selectors Some CSS Selectors: Selector Example Example description element p Selects all <p> elements element,element div,p Selects all <div> elements and all <p> elements element element div p Selects all <p> elements which are descendants of <div> elements element>element div>p Selects all <p> elements which are the children of a <div> element .class .tabs Selects all elements with class=“tabs" #id #leftbar Selects the element with id=“leftbar“ (Adapted from • Selectors can be combined using combinators such as whitespace and the > sign.
  22. 22. Variable Interpolation • The Lucius files have access to the DITA Accelerator variables that are in scope when the Lucius file is processed. • This is common to all of the Shakespearean Templates • Variable interpolation syntax: #{<variable name>} • Example from suitehelp-customizationtemplatesCSSscreen.lucius: #leftbar .tabs { height: #{tabsHeight}; } • Note: The value of the tabsHeight variable is taken from the corresponding CSS Variable in suitehelp-conf.xml
  23. 23. URL Interpolation • Haskell utilizes type-safe URLs which provide the following benefits: • Easily updateable when URLs change • Suitable for all use cases, including RSS and Atom feeds • Allows the compiler to check for URL issues • Type-safe URLs are implemented using data types which model URLs, and URL rendering functions. • The Shakespearean templates have access to the data constructors that are associated with these data types. • URL interpolation syntax: @{<Haskell type-safe URL data constructor>} • This feature is not currently used in the SuiteHelp templates
  24. 24. Nested CSS Blocks • Lucius allows CSS blocks to be nested • Standard CSS: article code { background-color: grey; } article p { text-indent: 2em; } article a { text-decoration: none; } • Lucius syntax: article { code { background-color: grey; } p { text-indent: 2em; } a { text-decoration: none; } } • The SuiteHelp Lucius files use nested CSS blocks. (Examples from
  25. 25. Local Variables • Lucius allows for local variables • For example, a text color can be defined and reused: @textcolor: #ccc; body { color: #{textcolor} } a:link, a:visited { color: #{textcolor} } • This feature is not used in the SuiteHelp templates out of the box, but can be very useful for customization purposes (Example from
  26. 26. Lucius Case Studies  Lucius Case Studies • Bolding the selected page in the TOC • Move the tabs to the top of the TOC panel • Change the colors on the page
  27. 27. Bolding the Selected Page in the TOC To bold the selected page in the TOC: 1. Figure out which element needs to change. An easy way to do this is to use the inspect element feature of Chrome. *Note that the current link has class=“current” 2. Formulate the change in CSS. Test directly in outstaticscreen.css to make sure that the output looks correct. 3. Add the change to screen.lucius and regenerate SuiteHelp output. 4. Confirm that the generated output is correct Solution: .toc >nav a.current{ font-weight: bold; }
  28. 28. Move the tabs above the TOC Pane To move the tabs above the TOC Pane: 1. Figure out which element needs to change. An easy way to do this is to use the inspect element feature of Chrome. *Note that the left bar has the following structure: <div id=“leftbar”> <ul class=“tabs”> // Contains navigation tabs <nav class=“toc”> // TOC pane <nav class=“index”> // Index pane <nav class=“search”> // Search pane 2. Formulate the change in CSS. Test directly in outstaticscreen.css to make sure that the output looks correct. 3. Add the change to screen.lucius and regenerate SuiteHelp output. 4. Confirm that the generated output is correct Solution:
  29. 29. Move the tabs above the TOC Pane Solution: To change the top attribute of the nav and tabs elements to the new positioning. *Note: SuiteHelp often uses absolute positioning on the screen #leftbar > nav { top: #{tabsHeight}; bottom: 0; } #leftbar .tabs { top: 0; height: #{tabsHeight}; }
  30. 30. Change colors on the page Changing the colors on the page can often be accomplished most efficiently by declaring local variables for colors, which can then be reused. Solution: Declare a new variable for the background color in screen.lucius: @backgroundColor: yellow; Use this variable wherever applicable: #leftbar { background-color: #{backgroundColor}; top: 150px; }
  31. 31. Features of Hamlet Features of Hamlet: • Variable interpolation • URL interpolation • Local variables • Nesting is indicated via indentation. • Closing tags are not used. • Hamlet is sensitive to whitespace. • Whitespace is preserved by using # at the end of the line and in the beginning of a line. • Special syntax for id and class attributes. • # is used for the id attribute • . is used for the class attribute
  32. 32. Body.hamlet • The layout of the SuiteHelp GUI is based on the body.hamlet template file. • By default, the suitehelptemplateshtmlbody.hamlet is used. • An alternate body.hamlet file can be specified in the customization directory for custom styling: 1. Copy suitehelptemplateshtmlbody.hamlet to suitehelp- customizationtemplateshtml. 2. Rename the new file with a descriptive name (i.e. body- webinar.hamlet). 3. Reference your custom hamlet file in suitehelp- customizationsuitehelp-conf.xml: <body-template>templates/html/body-webinar.hamlet</body-template>
  33. 33. Hamlet Case Studies  Hamlet Case Studies • Remove the Index tab • Reorder the Tabs • Close the space on top of the UI
  34. 34. Remove the Index tab To remove the index tab, remove the corresponding <li> and <nav> elements from the left bar in the Hamlet file. Out of the Box Customization <div id=leftbar> <ul .tabs> <li .currentli> <a .current .toc href=#> <span>_{TOC Pane} <li> <a .index href=#> <span>_{Index Pane} <li> <a .glossary href=#> <span>_{Glossary Pane} <div id=leftbar> <ul .tabs> <li .currentli> <a .current .toc href=#> <span>_{TOC Pane} <li> <a .glossary href=#> <span>_{Glossary Pane} <nav .toc .current> <nav .index> <nav .glossary> <nav .toc .current> <nav .glossary>
  35. 35. Reorder the tabs To change the order of the tabs, reorder the tab <li> elements in the leftbar. Before After <div id=leftbar> <ul .tabs> <li .currentli> <a .current .toc href=#> <span>_{TOC Pane} <li> <a .search href=#> <span>_{Search Pane} <div id=leftbar> <ul .tabs> <li> <a .search href=#> <span>_{Search Pane} <li .currentli> <a .current .toc href=#> <span>_{TOC Pane}
  36. 36. Close the space on top of the UI 1. Remove the header element from body.hamlet <header> <a href=#{approot}index.html id=logo-link> <img id=logo src=#{approot}#{logo}> <h1>#{pubtitle} 2. Change the related positioning of the other elements in the page in screen.lucius a. Understand the HTML components of the SuiteHelp layout b. Identify the correct selectors to change in the screen.css c. Update screen.lucius and suitehelp-conf.xml accordingly
  37. 37. SuiteHelp HTML Components 1.2/architectural_specification.html header #breadcrumbs #topbuttons#searchform article #dragger #leftbar
  38. 38. Close the space on top of the UI Selector Old top value New top value #leftbar 150px 75px #searchform 75px 0px #breadcrumbs 102px 27px article 150px 75px #topbuttons 70px 0px To move the SuiteHelp elements up, change the values of the top attributes in screen.lucius: The top attribute of the dragger is controlled by the draggerTopHeight CSS variable. By default, this variable only exists in the suitehelp plugin. To customize, add this variable to suitehelp-customizationsuitehelp-conf.xml and change the value to: <cssvar name="draggerTopHeight">75px</cssvar>
  39. 39. Questions? Feel free to be in contact: Join the SuiteHelp Forum!
  40. 40. Keep in Touch! For additional information, contact: Joe Gelb U.S. Office EMEA Office (609) 360-0650 +972-2-993-8054