SlideShare a Scribd company logo
Customizing Style Sheets for HTML Outputs Aliza Merzel, Suite Solutions
Who Are We? Our Mission To increase our customers’ profitability by significantly improving the efficiency of their  information development and delivery processes. Qualitative Advantage Content Lifecycle Implementation (CLI) is Suite Solutions’  comprehensive approach – from concept to publication – to maximizing the value of your information assets. Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business.
Clients and Partners Private and Confidential Suite Solutions©2009
Who Am I? Background in Computer Science Experience in several document technologies over the past decade+ Web applications Content management systems publishing and document conversion technologies Member of Suite Solutions team since its inception PDF and HTML style sheet projects FO plug-in support for PDF output Database development Ditaval utility Customize Eclipse Infocenter Framework
Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
Common Features (1) XHTML, HTML Help, Eclipse Help and Java Help share many common features Each topic becomes a separate HTML file Break up of topics can be modified by using the “chunk” attribute on the topicref in the ditamap, see  http://docs.oasis-open.org/dita/v1.1/OS/archspec/chunking.html HTML file names are same as dita file names Can use “copy-to” attribute to provide copies of topics and/or rename html files Links are generated to parent and child topics Links are generated to related topics based on related links and are grouped by topic type
Common Features (2) XHTML, HTML Help, Eclipse Help and Java Help share many common features Title of HTML file taken from topic title by default Can control navigation title via navtitle and locktitle map attributes Can control title to appear in search results via <searchtitle> element in topic Can control processing via topicref attributes, including toc (yes/no) – Indicates if topic should appear in TOC search (yes/no) – Indicates if topic is available for searching
XHTML Transtype: xhtml Basic HTML files: no additional interface Can be viewed using only a web browser The Toolkit generates a separate file with hierarchy links based on the ditamap Default is called index.html Index page can be renamed using the args.xhtml.toc ANT parameter Index terms are not retrieved into a separate file Can be shown in html files with args.indexshow ANT parameter  The TOCJS Plug-in provides a JavaScript based interactive TOC  Download TOCJS Plug-in from the dita-users group on  www.yahoo.com   Plug-in is located in the demos directory of the files section
XHTML It is possible to generate the XHTML output in a frameset to avoid having to switch browser windows after clicking on a link: Rename index page to toc.html using an ANT parameter <property name=&quot;args.xhtml.toc&quot; value=&quot;toc&quot;/> The index.html file in found in the resource folder provides a frameset for XHTML output Copy index.html from the resource folder using the following code in your project build file:
XHTML Example
HTML Help Basic transtype: htmlhelp Context sensitivity: htmlphelp2 or htmlhelp+ downloadable from Compiled help format (.chm file) Provides tri-pane interface including TOC, index, search Provides facility for context-sensitive help Works only on the Windows platform Can only be run on a client, not web server Can not be run remotely via a network Requires Internet Explorer and ActiveX control (both come with the OS) Easy to deploy: just send the .chm file Requires HTML Help Workshop for compilation into CHM: http://msdn.microsoft.com/en-us/library/ms669985.aspx
HTML Help Interface can be customized using the HTML Help Workshop Accessory files generated by the DITA-OT hhc  – TOC (based on map hierarchy) hhk  - Index (compiled from <indexterm> elements) hhp  - Project (contains project settings and included files) Customization possibilities formatting hhp project file, property  htmlhelp2.map2hhp.xsl hhc table of contents, property  htmlhelp2.map2hhc.xsl hhk is not easily customizable, created by dost.jar context sensitivity
HTML Help Example
Eclipse Help Transtype: eclipsehelp Un-compiled help format, but can be delivered as a jar file  Provides tri-pane interface including TOC, index, search Provides facility for context-sensitive help Provides for localized help and localized interface (upcoming webinar  Introduction to Eclipse Infocenter, Aug 24 th ) Cross platform Can be run on client or server Designed for applications developed in Eclipse, although it may be deployed as a stand alone help system  Requires Java JRE 1.5 plus partial installation of Eclipse on the client
Eclipse Help Accessory files generated by the DITA-OT TOC – name based on ditamap Index –  index.xml  compiled from <indexterm> elements) Project –  plugin.xml   Customization Options Formatting, Branding Hide the Eclipse documentation Product Banner Context Sensitivity (cshelp plug-in; SourceForge)
Eclipse Help Example
Java Help Un-compiled help format, but may be packaged into jar Provides tri-pane interface including TOC, index, search Provides facility for context-sensitive help Cross platform Can only be run on a client, not a web server Designed for applications developed in Java, although it may be deployed as a stand alone help system  Requires Java JRE and Java Viewer Requires Java Help Viewer Download :  http://java.sun.com/products/javahelp/download_binary.html Set environment variable: set JHHOME=<javahelp_dir> (folder where you installed the viewer, e.g. c:avahelp)
Java Help Accessory files generated by the DITA-OT TOC –  toc.xml Index – name based on ditamap   <map_name>_index.xml Project – name based on ditamap   <map_name>_helpset.hs   Customization Options Formatting, Branding Context Sensitivity
Java Help Example
Summary of HTML Formats (1) Feature XHTML Web HTML Help Eclipse Infocenter Javahelp TOC Y Y Y Y Y Index Y Y Y Search Y Y Y Set Search Scope Y Tri-pane Y Y Y Bread Crumb Links Y Free Y Y Y Y Y
Summary of HTML Formats (2) Feature XHTML Web HTML Help Eclipse Infocenter Javahelp Cross Platform Y Y Windows Only Y Y Context Sensitive Y Y Y Ability to Customize Interface DHTML DHTML Easy Limited Very Limited Ease to Deploy Easy Easy Easy: Single Compiled File Heavy unless app is Eclipse Medium: requires coordination with developers Special Requirements Internet Explorer Eclipse runtime “plus” JRE Javahelp Viewer, JRE
Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
Overview of Customization   Why Customize the Toolkit? Create company-specific branding and formatting Add extra style support for specializations Add additional output formats  Modify processing Add extra support for localization Methods of Customization Send transtype specific information to Toolkit  Provide a custom CSS file Create plug-ins to override XSL templates (upcoming webinar:   Developing Plug-ins and Working with FO plug-in Extension Points, July 21 st ) Apply DITA specializations Add new languages and new text for localization, modify existing translations (Upcoming webinar: Localizing Style Sheets for HTML Outputs, Aug 18th )
Customization using ANT Parameters Call a Custom CSS File Override the XSL File Headers and Footers Use Transtype Specific Parameters Resources
Call Custom CSS file Name Description args.csspath  Path for CSS reference – where the HTML files should look for the CSS.  Does not support absolute local paths. Default=none (goes to output directory). args.copycss  Specifies whether the custom CSS should be copied to csspath output directory. (yes/no) args.css  Defines user specified CSS file – can be local file or on the internet  args.cssroot  Root directory and path of user specified CSS file.
Override the XSL File Relevant Parameter:  args.xsl Names an XSL file which will replace the default XSL file Files are found in c:itaotsl directory Use this method: To provide drastically different processing from the standard To maintain separate processing for multiple plugins To avoid plug-in implementation if necessary To provide the ability to change style sheets from the command line or ANT build file Import the default html stylesheets to reuse existing code, overriding the ones you need to be different Transtype Default XSL File Xhtml, eclipsehelp Dita2xhtml.xsl Javahelp, htmlhelp Dita2html.xsl
Headers and Footers Relevant Parameters: Use this method: To provide company specific branding Add company specific scripts and/or links to script files Copyright notices on each page The name of the file containing XHTML to be placed in the BODY running-footing area.  args.ftr  parameter Default XSL File args.hdf  The name of the file containing XHTML to be placed in the HEAD area.  args.hdr   The name of the file containing XHTML to be placed in the BODY running-heading area.
Use Transtype Specific Parameters See  C:itaotocITA-antscript.html  for more details Xhtml args.xhtml.toc  - The root file name of the output xhtml toc file.  The default is index Htmlhelp args.dita.locale  - The locale used for sorting indexterms.  Eclipsehelp args.eclipse.version  - The version number of the eclipse help output.  Javahelp args.javahelp.map   - The root filename of the output javahelp map file
Customization Resources   Robert Anderson’s Customization Tutorial http://www.ditausers.org/tutorials/open_toolkit/anderson/ W3Schools Tutorials and References CSS:   http://www.w3schools.com/css/default.asp XHTML:   http://www.w3schools.com/xhtml/default.asp XSLT:   http://www.w3schools.com/xsl/default.asp XPath:   http://www.w3schools.com/xpath/default.asp Toolkit Documentation ANT Parameters:  C:itaotocITA-antscript.html SourceForge Toolkit and Plug-in Downloads http://sourceforge.net/project/showfiles.php?group_id=132728 Table of Extension Points http://dita-ot.sourceforge.net/SourceForgeFiles/doc/plugin/createplugin.html Other Websites Using Eclipse to Publish DITA:  http://dita.xml.org/wiki/setting-up-the-eclipse-help-infocenter-for-publishing-dita-content
Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
Context Sensitivity Overview User experience Comes to specific help topic when calling help from specific screen Programmer experience How to call up a certain page without hard-coding html file name? HTML Help (based on WinHelp model) Each help topic has a unique context string (context ID) Each context ID is mapped to a numeric TopicID using map files (.h extension) Each TopicID is mapped to an HTML file using Alias files Applications launch the help to a particular topic based on the numeric TopicID (Integrates with programs via a Windows API call.) The map files are maintained by the application developers Eclipse Help Context id are mapped to html files in an xml file
Context Sensitivity: HtmlHelp #define  IDH_Dialog_Help  1234 ... Map (.h) file Application CHM Compilation Call to TopicID 1234 IDH_Dialog_Help = t_configuring_valve.html ... Alias file ** Automatically Generated
Context Sensitivity: Eclipse Help
Context Sensitivity: HtmlHelp How it works htmlhelp2 plug-in, available  dita-users . <resourceid appname=‘ WindowsHelpId ’ id=‘1234’/> Finds all instances of topic/prolog /resourceid [@appname=‘ WindowsHelpId ’]/@id Mapping file outputs #define  identity_1234 1234 Alias file outputs as identity_1234=page1.html Advantages Easy to maintain context information in dita topics that they pertain to Disadvantages Maintaining topics id and not context strings Generates mapping file, this is usually maintained by programmers Some CMS use the id attribute to store their internal ids We recommend topic/prolog/metadata/data[@name=‘ContextID’] <data name=‘ContextID’>my_context_id</data> Would need to modify plugins/htmlhelp2/xsl/map2csh_alias.xsl to account for different element Programmer needs to provide mapping file
Context Sensitivity: Eclipse Help How it works The Toolkit also includes a specialization of topic for context-sensitive Eclipse Help topics called cshelp.  It is maintained on SourceForge by IBM. Specialized topic that contains context sensitive information outside of your topics (<cshelp id=‘my_topic_alias’>…</cshelp>) Each cshelp topics has links to the final location in Eclipse Help For more info:  CSH_DITA_EAST_2007.ppt Advantages Transform works out of the box Disadvantages Need to maintain context information outside of help set If topic file changes, need to update the related links here also Need to include context file(s) in the final Eclipse plugin  Some CMS use the id attribute to store their internal ids We recommend topic/prolog/metadata/data[@name=‘ContextID’] <data name=‘ContextID’>my_context_id</data> We can use a mix of plugins/htmlhelp2/xsl/map2csh_alias.xsl to use for retrieving the elements and demo/cshelp/xsl/dit2context.xsl for output structure
Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
 
End of  Customizing Style Sheets for HTML Outputs Be in touch! Aliza Merzel [email_address] Let us know how we can help you further… One-on-one support and training CMS

More Related Content

CustomizingStyleSheetsForHTMLOutputs

  • 1. Customizing Style Sheets for HTML Outputs Aliza Merzel, Suite Solutions
  • 2. Who Are We? Our Mission To increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes. Qualitative Advantage Content Lifecycle Implementation (CLI) is Suite Solutions’ comprehensive approach – from concept to publication – to maximizing the value of your information assets. Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business.
  • 3. Clients and Partners Private and Confidential Suite Solutions©2009
  • 4. Who Am I? Background in Computer Science Experience in several document technologies over the past decade+ Web applications Content management systems publishing and document conversion technologies Member of Suite Solutions team since its inception PDF and HTML style sheet projects FO plug-in support for PDF output Database development Ditaval utility Customize Eclipse Infocenter Framework
  • 5. Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
  • 6. Common Features (1) XHTML, HTML Help, Eclipse Help and Java Help share many common features Each topic becomes a separate HTML file Break up of topics can be modified by using the “chunk” attribute on the topicref in the ditamap, see http://docs.oasis-open.org/dita/v1.1/OS/archspec/chunking.html HTML file names are same as dita file names Can use “copy-to” attribute to provide copies of topics and/or rename html files Links are generated to parent and child topics Links are generated to related topics based on related links and are grouped by topic type
  • 7. Common Features (2) XHTML, HTML Help, Eclipse Help and Java Help share many common features Title of HTML file taken from topic title by default Can control navigation title via navtitle and locktitle map attributes Can control title to appear in search results via <searchtitle> element in topic Can control processing via topicref attributes, including toc (yes/no) – Indicates if topic should appear in TOC search (yes/no) – Indicates if topic is available for searching
  • 8. XHTML Transtype: xhtml Basic HTML files: no additional interface Can be viewed using only a web browser The Toolkit generates a separate file with hierarchy links based on the ditamap Default is called index.html Index page can be renamed using the args.xhtml.toc ANT parameter Index terms are not retrieved into a separate file Can be shown in html files with args.indexshow ANT parameter The TOCJS Plug-in provides a JavaScript based interactive TOC Download TOCJS Plug-in from the dita-users group on www.yahoo.com Plug-in is located in the demos directory of the files section
  • 9. XHTML It is possible to generate the XHTML output in a frameset to avoid having to switch browser windows after clicking on a link: Rename index page to toc.html using an ANT parameter <property name=&quot;args.xhtml.toc&quot; value=&quot;toc&quot;/> The index.html file in found in the resource folder provides a frameset for XHTML output Copy index.html from the resource folder using the following code in your project build file:
  • 11. HTML Help Basic transtype: htmlhelp Context sensitivity: htmlphelp2 or htmlhelp+ downloadable from Compiled help format (.chm file) Provides tri-pane interface including TOC, index, search Provides facility for context-sensitive help Works only on the Windows platform Can only be run on a client, not web server Can not be run remotely via a network Requires Internet Explorer and ActiveX control (both come with the OS) Easy to deploy: just send the .chm file Requires HTML Help Workshop for compilation into CHM: http://msdn.microsoft.com/en-us/library/ms669985.aspx
  • 12. HTML Help Interface can be customized using the HTML Help Workshop Accessory files generated by the DITA-OT hhc – TOC (based on map hierarchy) hhk - Index (compiled from <indexterm> elements) hhp - Project (contains project settings and included files) Customization possibilities formatting hhp project file, property htmlhelp2.map2hhp.xsl hhc table of contents, property htmlhelp2.map2hhc.xsl hhk is not easily customizable, created by dost.jar context sensitivity
  • 14. Eclipse Help Transtype: eclipsehelp Un-compiled help format, but can be delivered as a jar file Provides tri-pane interface including TOC, index, search Provides facility for context-sensitive help Provides for localized help and localized interface (upcoming webinar Introduction to Eclipse Infocenter, Aug 24 th ) Cross platform Can be run on client or server Designed for applications developed in Eclipse, although it may be deployed as a stand alone help system Requires Java JRE 1.5 plus partial installation of Eclipse on the client
  • 15. Eclipse Help Accessory files generated by the DITA-OT TOC – name based on ditamap Index – index.xml compiled from <indexterm> elements) Project – plugin.xml Customization Options Formatting, Branding Hide the Eclipse documentation Product Banner Context Sensitivity (cshelp plug-in; SourceForge)
  • 17. Java Help Un-compiled help format, but may be packaged into jar Provides tri-pane interface including TOC, index, search Provides facility for context-sensitive help Cross platform Can only be run on a client, not a web server Designed for applications developed in Java, although it may be deployed as a stand alone help system Requires Java JRE and Java Viewer Requires Java Help Viewer Download : http://java.sun.com/products/javahelp/download_binary.html Set environment variable: set JHHOME=<javahelp_dir> (folder where you installed the viewer, e.g. c:avahelp)
  • 18. Java Help Accessory files generated by the DITA-OT TOC – toc.xml Index – name based on ditamap <map_name>_index.xml Project – name based on ditamap <map_name>_helpset.hs Customization Options Formatting, Branding Context Sensitivity
  • 20. Summary of HTML Formats (1) Feature XHTML Web HTML Help Eclipse Infocenter Javahelp TOC Y Y Y Y Y Index Y Y Y Search Y Y Y Set Search Scope Y Tri-pane Y Y Y Bread Crumb Links Y Free Y Y Y Y Y
  • 21. Summary of HTML Formats (2) Feature XHTML Web HTML Help Eclipse Infocenter Javahelp Cross Platform Y Y Windows Only Y Y Context Sensitive Y Y Y Ability to Customize Interface DHTML DHTML Easy Limited Very Limited Ease to Deploy Easy Easy Easy: Single Compiled File Heavy unless app is Eclipse Medium: requires coordination with developers Special Requirements Internet Explorer Eclipse runtime “plus” JRE Javahelp Viewer, JRE
  • 22. Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
  • 23. Overview of Customization Why Customize the Toolkit? Create company-specific branding and formatting Add extra style support for specializations Add additional output formats Modify processing Add extra support for localization Methods of Customization Send transtype specific information to Toolkit Provide a custom CSS file Create plug-ins to override XSL templates (upcoming webinar: Developing Plug-ins and Working with FO plug-in Extension Points, July 21 st ) Apply DITA specializations Add new languages and new text for localization, modify existing translations (Upcoming webinar: Localizing Style Sheets for HTML Outputs, Aug 18th )
  • 24. Customization using ANT Parameters Call a Custom CSS File Override the XSL File Headers and Footers Use Transtype Specific Parameters Resources
  • 25. Call Custom CSS file Name Description args.csspath Path for CSS reference – where the HTML files should look for the CSS. Does not support absolute local paths. Default=none (goes to output directory). args.copycss Specifies whether the custom CSS should be copied to csspath output directory. (yes/no) args.css Defines user specified CSS file – can be local file or on the internet args.cssroot Root directory and path of user specified CSS file.
  • 26. Override the XSL File Relevant Parameter: args.xsl Names an XSL file which will replace the default XSL file Files are found in c:itaotsl directory Use this method: To provide drastically different processing from the standard To maintain separate processing for multiple plugins To avoid plug-in implementation if necessary To provide the ability to change style sheets from the command line or ANT build file Import the default html stylesheets to reuse existing code, overriding the ones you need to be different Transtype Default XSL File Xhtml, eclipsehelp Dita2xhtml.xsl Javahelp, htmlhelp Dita2html.xsl
  • 27. Headers and Footers Relevant Parameters: Use this method: To provide company specific branding Add company specific scripts and/or links to script files Copyright notices on each page The name of the file containing XHTML to be placed in the BODY running-footing area. args.ftr parameter Default XSL File args.hdf The name of the file containing XHTML to be placed in the HEAD area. args.hdr The name of the file containing XHTML to be placed in the BODY running-heading area.
  • 28. Use Transtype Specific Parameters See C:itaotocITA-antscript.html for more details Xhtml args.xhtml.toc - The root file name of the output xhtml toc file. The default is index Htmlhelp args.dita.locale - The locale used for sorting indexterms. Eclipsehelp args.eclipse.version - The version number of the eclipse help output. Javahelp args.javahelp.map - The root filename of the output javahelp map file
  • 29. Customization Resources Robert Anderson’s Customization Tutorial http://www.ditausers.org/tutorials/open_toolkit/anderson/ W3Schools Tutorials and References CSS: http://www.w3schools.com/css/default.asp XHTML: http://www.w3schools.com/xhtml/default.asp XSLT: http://www.w3schools.com/xsl/default.asp XPath: http://www.w3schools.com/xpath/default.asp Toolkit Documentation ANT Parameters: C:itaotocITA-antscript.html SourceForge Toolkit and Plug-in Downloads http://sourceforge.net/project/showfiles.php?group_id=132728 Table of Extension Points http://dita-ot.sourceforge.net/SourceForgeFiles/doc/plugin/createplugin.html Other Websites Using Eclipse to Publish DITA: http://dita.xml.org/wiki/setting-up-the-eclipse-help-infocenter-for-publishing-dita-content
  • 30. Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
  • 31. Context Sensitivity Overview User experience Comes to specific help topic when calling help from specific screen Programmer experience How to call up a certain page without hard-coding html file name? HTML Help (based on WinHelp model) Each help topic has a unique context string (context ID) Each context ID is mapped to a numeric TopicID using map files (.h extension) Each TopicID is mapped to an HTML file using Alias files Applications launch the help to a particular topic based on the numeric TopicID (Integrates with programs via a Windows API call.) The map files are maintained by the application developers Eclipse Help Context id are mapped to html files in an xml file
  • 32. Context Sensitivity: HtmlHelp #define IDH_Dialog_Help 1234 ... Map (.h) file Application CHM Compilation Call to TopicID 1234 IDH_Dialog_Help = t_configuring_valve.html ... Alias file ** Automatically Generated
  • 34. Context Sensitivity: HtmlHelp How it works htmlhelp2 plug-in, available dita-users . <resourceid appname=‘ WindowsHelpId ’ id=‘1234’/> Finds all instances of topic/prolog /resourceid [@appname=‘ WindowsHelpId ’]/@id Mapping file outputs #define identity_1234 1234 Alias file outputs as identity_1234=page1.html Advantages Easy to maintain context information in dita topics that they pertain to Disadvantages Maintaining topics id and not context strings Generates mapping file, this is usually maintained by programmers Some CMS use the id attribute to store their internal ids We recommend topic/prolog/metadata/data[@name=‘ContextID’] <data name=‘ContextID’>my_context_id</data> Would need to modify plugins/htmlhelp2/xsl/map2csh_alias.xsl to account for different element Programmer needs to provide mapping file
  • 35. Context Sensitivity: Eclipse Help How it works The Toolkit also includes a specialization of topic for context-sensitive Eclipse Help topics called cshelp. It is maintained on SourceForge by IBM. Specialized topic that contains context sensitive information outside of your topics (<cshelp id=‘my_topic_alias’>…</cshelp>) Each cshelp topics has links to the final location in Eclipse Help For more info: CSH_DITA_EAST_2007.ppt Advantages Transform works out of the box Disadvantages Need to maintain context information outside of help set If topic file changes, need to update the related links here also Need to include context file(s) in the final Eclipse plugin Some CMS use the id attribute to store their internal ids We recommend topic/prolog/metadata/data[@name=‘ContextID’] <data name=‘ContextID’>my_context_id</data> We can use a mix of plugins/htmlhelp2/xsl/map2csh_alias.xsl to use for retrieving the elements and demo/cshelp/xsl/dit2context.xsl for output structure
  • 36. Customizing Stylesheets for HTML Output: Main Topics Overview of HTML Formats Overview of HTML Customization Context Sensitivity Implementation
  • 37.  
  • 38. End of Customizing Style Sheets for HTML Outputs Be in touch! Aliza Merzel [email_address] Let us know how we can help you further… One-on-one support and training CMS