Suite Labs: Customizing SuiteHelp Output

SuiteHelp Customization
Adena Frazer, Suite Solutions

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

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

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

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

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

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 http://site.icu-project.org/ for more details

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

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 http://www.yesodweb.com/book/shakespearean-templates
• JavaScript

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

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

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"

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

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

• 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

• 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.

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

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

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.

CSS
• CSS files define styling for HTML content
• CSS rules consist of a selector and at least one declaration
(Diagram from http://www.w3schools.com/css/css_syntax.asp)
For more information, see:
• http://www.w3schools.com/css for a tutorial and reference information
• http://www.w3.org/Style/CSS/Overview.en.html for detailed W3C
recommendations and specifications

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 http://www.w3schools.com/cssref/css_selectors.asp)
• Selectors can be combined using combinators such as whitespace and
the > sign.

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

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

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 http://www.yesodweb.com/book/shakespearean-templates)

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 http://www.yesodweb.com/book/shakespearean-templates)

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

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;
}

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:

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};
}

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;
}

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

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>

Hamlet Case Studies
 Hamlet Case Studies
• Remove the Index tab
• Reorder the Tabs
• Close the space on top of the UI

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>
<span>_{TOC Pane}
<li>
<a .glossary href=#>
<span>_{Glossary Pane}
<nav .toc .current>
<nav .index>
<nav .glossary>
<nav .toc .current>
<nav .glossary>

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>
<span>_{TOC Pane}
<li>
<a .search href=#>
<span>_{Search Pane}
<div id=leftbar>
<ul .tabs>
<li>
<a .search href=#>
<span>_{Search Pane}
<li .currentli>
<span>_{TOC Pane}

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

SuiteHelp HTML Components
http://www.suite-sol.com/downloads/suitehelp/suitehelp-ditaspec-
1.2/architectural_specification.html
header
#breadcrumbs
#topbuttons#searchform
article
#dragger
#leftbar

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>

Questions?
Feel free to be in contact: adenaf@suite-sol.com
Join the SuiteHelp Forum! www.suite-sol.com/forums

Keep in Touch!
For additional information, contact:
Joe Gelb
solutions@suite-sol.com
U.S. Office EMEA Office
(609) 360-0650 +972-2-993-8054
www.suite-sol.com

Suite Labs: Customizing SuiteHelp Output

Recommandé

Recommandé

Contenu connexe

En vedette

En vedette (7)

Plus de Suite Solutions

Plus de Suite Solutions (18)

Dernier

Dernier (20)

Suite Labs: Customizing SuiteHelp Output