Search results

DITA: Add a jQuery show/hide toggle

The show/hide toggle allows you to hide content within your page. This helps you compress long content in a more user friendly way.

There are a lot of different jQuery show/hide toggles. The one we'll be implementing is here: Simple Expand. Additionally, the instructions here show you how to implement the toggle with the twisty arrows.

For a demo of the effect, see the webhelp output of the DITA QRG.

Sponsored

  1. Download the minified script from the jQuery Simple Expand plugin site and copy it to your clipboard.
  2. In a text editor, open the following js file: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js/webhelp_topic.js.
  3. Insert the copied script at the bottom right before the closing });. 
    $('.expander').simpleexpand();

    This function triggers the script. Wherever the expander class exists, the the simpleexpand function will trigger. This script will appear in your webhelp topic frame (instead of your sidebar).

  4. Save the close the file.
  5. In a text editor, open the following file: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/css/webhelp_topic.css.
  6. Insert the following styles: 
    .content {display:none;}
.expander.expanded {
    padding-left: 13px;
    background-position: left center;
    background-repeat: no-repeat;
    background-image: url(../img/expanded.gif);
}

.expander.collapsed {
    padding-left: 13px;
    background-position: left center;
    background-repeat: no-repeat;
    background-image: url(../img/collapsed.gif);
}

    Any element with the class content will be hidden. When the script is run, the content class will be removed and one of the other classes will be added.

    In my demo, I added some more classes to style how the expand and collapse sections appear. If you want to style your output like the demo, use these styles instead of the previous:

    .content{
    display:none;
}
.expander.expanded{
    padding-left:13px;
    background-position:left center;
    background-repeat:no-repeat;
    cursor: pointer;
    font-size: 16px;
    color: blue;
    box-sizing: border-box;
    display: inline-block;
    background: #ececec url(../img/expanded.gif) no-repeat 1% center;
    border-top: 1px dashed #ccc;
    border-bottom: 1px dashed #ccc;
    color: #444;
    font: normal 13px/22px "Helvetica Neue","HelveticaNeue",Helvetica,sans-serif;
    cursor: pointer;
    padding: 9px 5px 8px 25px;
    width: 100%;
    font-weight:bold;

}

.expander.collapsed{
    padding-left:13px;
    background-position:left center;
    background-repeat:no-repeat;
    cursor: pointer;
    font-size: 16px;
    color: blue;
    box-sizing: border-box;
    display: inline-block;
    background: #ececec url(../img/collapsed.gif) no-repeat 1% center;
    border-top: 1px dashed #ccc;
    border-bottom: 1px dashed #ccc;
    color: #444;
    font: normal 13px/22px "Helvetica Neue","HelveticaNeue",Helvetica,sans-serif;
    cursor: pointer;
    padding: 9px 5px 8px 25px;
    width: 100%;
    font-weight:bold;
}

  7. Grab the two arrow images: expanded.gif and collapsed.gif

    Right-click the images (they appear in the upper-left corner) and save the images to your computer.

  8. Copy the images into this folder: [Oxygen Install Directory]/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/img.

    Now you've set up your jQuery script, styles, and images. The next step shows how to incorporate the show/hide effect in a page.

  9. To include a show/hide instance on a page, add the following: 
       <sectiondiv>
    <p outputclass="expander">View details</p>
    <p outputclass="content">This is the content that gets expanded.</p>
   </sectiondiv>

    Adding outputclass on an element renders it to class in the HTML output.

    It's not absolutely necessary to include the sectiondiv tag. However, if you have multiple elements with an outputclass="content" on your elements, and those elements are siblings (rather than in a parent/child hierarchy), all the siblings will expand. By containing each element with outputclass="content" inside a sectiondiv tag, then only that element inside the sectiondiv will expand.

    This is because the default behavior of the Simple Expand plugin is to climb up to the parent element and expand all child elements containing the content class. By using sectiondiv elements, you create multiple parent-child relationships.

    The sectiondiv tag works only inside a section element, which is only allowed in concept and general task elements. For task elements, you can use the info, stepxmp, context or other div block elements.

  10. You can also transclude content from another page.

    The transclusion source might look like this: 
    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
  <concept id="lipsum_source">
  <title>Sample Show/Hide Content</title>
 <shortdesc id="lipsum_shortdesc">This is a page containing sample content that acts as the transclusion source for the show/hide demo.</shortdesc>
<conbody>

<section id="lipsum1"><title>Lipsum section 1</title>
  <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.</p>
</section>

<section id="lipsum2"><title>Lipsum section 2</title>
  <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.</p>
</section>
</conbody>
</concept>

    If so, the transclusion target would look like this:

     <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="concept_cmy_2g1_kp">
 <title>Show/hide demo</title>
 <shortdesc>This is a demo of the show/hide functionality.</shortdesc>
 <conbody>
  <p>This first expandable section is transcluded from this page: <xref href="jquery_showhide_sample_content.dita"/>.</p>
  <p outputclass="expander">View more</p>

  <section conref="jquery_showhide_sample_content.dita#lipsum_source/lipsum1" outputclass="content"/>
  <section conref="jquery_showhide_sample_content.dita#lipsum_source/lipsum2" outputclass="content"/>
  <section conref="jquery_showhide_sample_content.dita#lipsum_source/lipsum3" outputclass="content"/>
  </conbody>
</concept>

    For more details about using conref, see Conref (re-use of content).

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, agent skills, tech comm careers, and more. Check out my AI courses for more on the latest in AI and tech comm. If you're looking for info about documenting APIs, see my API documentation course.

If you're a technical writer and want to keep on top of the latest trends in tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me.

Finally, I want to note a couple of things. I usually write the first drafts of my posts myself and then use AI to improve accuracy, clarity, and detail in places, so my writing is a mix of human and AI. (Hopefully that's not too off-putting.) Also, the opinions I express on my blog are my own perspectives, not those of my employer.

© 2026 Tom Johnson