DITA: Add an expanding side pane (Sidr)
For a demo of this functionality, see the Sidr pane demo here.
Although there are a variety of jQuery sidebar plugins, the Sidr works pretty well. It allows you to easily call different menus, and arrange the panel to appear on the left or right. The original purpose of Sidr was to act as a menu for mobile devices that don't have much screen real estate, but it works well in other situations too.
The particular scenario where I think this functionality is critical is with code samples. With code samples, you're limited to about 2 lines of comments per 5-10 lines of code. But a lot of the stuff that's going on in code is really complicated and warrants more extensive elaboration. This is where the side panel comes in really handy. You can elaborate as much as you want in the expanding side panels.
Integrating this plugin permanently alters the OxygenXML webhelp (though not visible, just in the scripts that are loaded and source code IDs) so make a backup of your files before committing changes. Also, the method described below is just one way of integrating the plugin, not the only way.
Integrate Sidr into OxygenXML
To integrate the Sidr plugin into OxygenXML:
- Go to the http://www.berriart.com/sidr/ and click the Download button.
From the downloaded zip file, open the jquery.sidr.min.js file and copy its contents.
The CSS file is minified. If you paste it into Oxygen and then click the format/indent button, it will de-minify the file.
Insert the copied script at the bottom right before the closing
});.Tip: Create a shortcut to this folder location -- you'll be updating this file a lot since each of the menus require individual names and triggers. On a Mac, you can create a shortcut in the Finder by dragging a folder into the Finder's sidebar.
- Open one of the CSS files, such as jquery.sidr.light.css and copy its contents.
- In a text editor, open the CSS file located here: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/css/webhelp_topic.css.
Insert the styles near the bottom of the stylesheet.
Tip: Create a shortcut to this folder location just like with the .js file. You'll probably edit your CSS styles a lot.
If desired, you can add some more styles to customize the side pane display.
Much of the default styling is for a navigation menu. This means if you add
litags, your content will look like a navigation menu rather than a list, so you may want remove some of the unncessary styles. Additionally, you may want to add a few styles of your own. Here are some styles I've added:
closeMestyle is for a close button that will appear at the bottom of the pane. The
p.spheadstyle is for a section subheading style. Note that even though you will later be giving custom names to your side panels, the script will always inject
sidras a class into the panel. The other styling is for links inside
codeblockelements. Also, since I intend to document long code blocks with this method, I wanted to lengthen the code block area beyond the default 600px (otherwise for code longer than 600px you have to use scroll bars to see the full content).
Allow IDs to pass through
id="sidepanel_1"won't appear in DITA's webhelp output (they're stripped out entirely). We need to hack Oxygen's webhelp files to allow these tags to pass through.
- In a text editor, open the file located here: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/org.dita.xhtml/xsl/xslhtml/dita2htmllmpl.xsl.
Find 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. You can add other attributes that you want to pass through here as well (such as
product) depending on what you plan to use.
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.
Add functions to trigger Sidr
Add the following functions to your webhelp_topic.js file (located here: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js/webhelp_topic.js):
$('.demo_sidepanel_1').sidr()means that we are binding the
sidrfunction to an element that has a class of
demo_sidepanel_1. You can pass the
sidrfunction a variety of parameters, but for the most part you need only to specify the side panel
namethat you want to open. (By default, the panel already opens on the left. I made this parameter explicit as an example of how to pass multiple parameters into the function.)
The panel name is the element ID of the section you want to display in the side panel. I'll explain this a bit more later, but note that "fullcode" is the topic ID of the page where the side panel appears. Although later in the code you will see that the section ID in the topic is merely "demo_sidepanel_1", upon rendering the webhelp, DITA adds the topic ID (in my sample, the topic ID is
fullcode) before the section name. DITA does this for the
sectionelement but not others (not sure why --
sectionis just special).
Add the following closing scripts to the same webhelp_topic.js file. These functions close the side panel.
In this code, a click event is bound to an element with the
event.preventDefault()keeps the code from trying to open a new window and instead allows the
sidrfunction to fire. Two arguments are passed to the
sidrfunction: the method we want the function to run:
close, and the name of the side panel we want to close:
By the way, the panel names (
fullcode__demo_sidepanel_1) and classes (
.demo_sidepanel_1) are completely customizable -- they're just what I've chosen to integrate for this demo.
Note that the selector is a class rather than an ID. This is because when you transclude topics in DITA, the ID on the transcluded source gets changed when it is pulled into the transcluded target. Fortunately the DITA OT leaves the classes alone.
Add content in your topic
Create a DITA concept topic and insert some triggers inside a code block like this:
It's important to note a few things here. For links in the codeblock, you can't use
hreftarget, so use
With each link, you must add the
outputclassthat correlates with the side panel name you want to open. In this example, the link with the class of
demo_sidepanel_1will open the element with the ID name of
fullcode__sidepanel_1. The class and ID don't need to be the same -- you could have link with a class of
tomthat opens a panel named
awesome, but just be sure you have these names set up in your webhelp_topic.js file. It depends on how you set up the triggers and menus in the jQuery scripts that you configured previously.
(In fact, now might be a good time to review the scripts you added in previous steps to the webhelp_topic.js file to get a better understanding of how this all fits together.)
Add the following for your side panel content:
Here we add an ID attribute to the
sectionelement. Note that the menu name in the jQuery scripts is
fullcode_demo_sidepanel_1, but the ID here is just written as
demo_sidepanel_1. This is because the DITA OT will automatically prepend the topic ID and two underscores before the section ID. My topic ID happens to be
fullcode, so that's why the jQuery scripts will look for
fullcode__demo_sidepanel_1as the name of the sidepanel instead of just
demo_sidepanel_1. Again, I have no idea why the DITA OT does this.
Render your content into webhelp and experiment with the trigger. If the link opens up a new page, it's because something isn't configured right. Usually it means the class on the more link doesn't align with the selector in the jQuery script. If the side panel opens but is blank, it's because the the menu name in the jQuery scripts doesn't match the menu name on the page. Look in your source code to see if the DITA OT is doing some funky shake and bake with the menu name.
Transcluding content from another page
Create a separate topic and add the following:
Let's say the topic ID of this page is
Now go to the page where you want to transclude the content (presumably, the page with the long
code block that we've been working with already). Add a
conrefelement where you want to insert the content:Note: Put the ID on the page where you're transcluding the content (the transclusion target). If you put the ID on the transclusion source, the DITA OT will randomize the ID and Sidr won't be able to trigger the menu because its name won't correspond with the name in the jQuery function.
If you're transcluding content from a standalone topic to a side panel display, you'll no doubt want to style the section headers a bit differently. That's what this style is all about:
About Tom Johnson
I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.