CustomizingStyleSheetsForHTMLOutputs

731 views

Published on

Published in: Education
1 Comment
0 Likes
Statistics
Notes
  • On this 'Summary of HTML Formats (1)' slide, one column header is 'Web'. Yet in the presentation so far, we had only discussed four HTML formats (XHTML, HTML Help, Eclipse Help, Java Help). What is 'Web' referring to? Is that the frame version of XHTML?
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

No Downloads
Views
Total views
731
On SlideShare
0
From Embeds
0
Number of Embeds
408
Actions
Shares
0
Downloads
0
Comments
1
Likes
0
Embeds 0
No embeds

No notes for slide

CustomizingStyleSheetsForHTMLOutputs

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

×