For example, suppose your content has four programming language code snippets. You want to allow your users to select one language and have all the rest be hidden. You can add a content selector to your output so that users can select the type of content they want to see.
This content selector is a style switcher developed by hibbard.eu explained here: Using cookies with jQuery to make a simple style switcher. Although there are a variety of jQuery style switchers available, I like this one because it implements the jQuery cookie to remember the user's selection from page to page. This is critical for the content selector to work site-wide. (Without the cookie, the user would need to re-select an option with each new page.
To implement the content selector:
- In a text editor, open the web_topic.js file found in the following directory: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js
Before the closing
)};, add the following script:
This script is from the demo download zip file available on Hibbard's site. (Scroll to the bottom of the page where you can download the demo as a zip file; then open one of the HTML files to see the script.) There is one modification, though. I added the
#bck_toc", parent.documenttriggers to apply the same adding and removing of classes to the table of contents. This is because OxygenXML's output puts the TOC and the body in separate frames.
Save the file.
Note: You'll notice that the zip download also contains a jQuery cookie file. This is the general cookie plugin for jQuery. Fortunately, OxygenXML already includes this jQuery script, which you can verify by looking in the [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js directory.
By default, attributes you add to content, such as
platform="java"won't appear in the output (they're stripped out entirely). We need to hack Oxygen's webhelp XSLT to allow these tags to pass through. In a text editor, open the dita2htmllmpl.xsl file found in the following directory: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/org.dita.xhtml/xsl/xslhtml.
Locate the line that begins "" and replace that
section with the following:
This will allow the
idattributes to pass through as attributes in the output (so you can leverage them). Without these attributes in the output, you won't be able to select the content.
Note that in the future, this hack may be unnecessary. The ditaval file allows you to add a
passthroughattribute to elements, but this attribute does not work in Oxygen's webhelp output.
Go to your custom skin's stylesheet. Near the bottom, add the following styles:
You will need to adjust this code depending on the classes you're adding. For example, if you don't want your four selections to be java, php, dotnet, and cpp, swap in the classes you intend to use. Also, if you're not using platform but rather product or audience, make that switch as well.
Basically, here's a summary of what's going on with this CSS. By default, the content selector doesn't have an initial selection. In this example, anything tagged with the class
phpwill initially be hidden, but not
java. This is because we don't want blank spaces in the code to appear before the user selects something in the content selector. (By the way, make sure that the default content that appears (e.g., java) is first in your selector's options. This step is described later).
When a user makes a selection from the selector, the jQuery script adds a class to the
bodyelement. The selector
body.cpp [data-platform*="cpp"]says for anything inside the
bodyelement with the
cppclass that also has the attribute of
data-platform=cpp, then apply this style.
When a user makes a selection, we want to display content with that data attribute, so we set
display:block. We also hide the
java(which was never hidden by default). For any non-block level items, we want to set their display as
blockso that we don't end up with paragraph breaks for inline elements. Right now only
phelements are set as
display:inline, but if there are others, add them there following the same pattern. (Unfortunately, in the world of CSS, there is no opposite to
.ph[data-platform*="java"]selector means that for any
phclasses that contain an attribute of
data-platform, apply this style.
Add a selector in your header file to allow users to select the content they want to see. To do this, create a new XHTML file and add the following:
Replace the options with whatever you want. Just keep in mind that the values must match your classes. Also, by default, the first option will appear in the selector, even though the user hasn't actually made that selection. This is why
javais not hidden by default in the styles.
- In OxygenXML, open your map file, click the Configure Transformation Scenarios button, and duplicate the DITA Map Webhelp output.
- Edit the copy, click the Parameters tab, and in the args.hdf option, browse to the XHTML file you created.
- When you create content, add
platform="java"and such to your content. Users will be able to select the attributes they want.
For the ditamap file, instead of addding
platform="java", you must use
outputclass="java". This is because the DITA OT processes the TOC differently from the rest of the content, and any platform/data tags get stripped out of the output.
localhost/to view the content.