Add Demos to the Help Browser

About Creating Demos

You can provide demos for toolboxes you create and make them available in the Help browser. Demos allow you to present the features of your toolbox. Adding your demos to the Help browser is the best way to make them accessible.

There are no requirements about the types of demos you can provide. However, if you provide the same types of demos that MathWorks products provide, users of your software are already familiar with using them.

This documentation includes an example folder which contains two demos and refers to a third one that comes with MATLAB. Click here to add this example folder to your search path, or run the following command:

addpath(fullfile(matlabroot,'help','techdoc','matlab_env','examples','demo_examples'))

The Contents pane of the Help browser displays an entry called Example Demos under the Other Demos entry. As shown in the following figure, within that entry you see three demos:

• Formatting Text for Publishing

• Square Waves from Fourier Series

• A video demo from MATLAB, Working in the Development Environment

To remove the demos you just added, take their folder off the search path:

rmpath(fullfile(matlabroot,'help','techdoc','matlab_env','examples','demo_examples'))

How to Add Demos

Tip   Print or bookmark this page of instructions. Then, when you view your own HTML pages in the Help browser, you can view the instructions at the same time.

After you create a demo, you can access the demo from the Help browser after you perform the following steps:

1. Create demos for your toolbox. See About Creating Demos.

   You can effectively produce MATLAB code demos using the cell-publishing features available in the Editor. Publishing creates an HTML file that includes code, can include figures, describes how to use your code, and enables you to execute the code from the Help browser. For more information, see Overview of Publishing MATLAB Code.

2. Add the demos files to the Help browser using a special XML file that you create. See Workflow for Providing Demos.

3. Provide the demo files, along with instructions for including these files in the Help browser. See Providing Demos to Others.

The sections that follow refer to a folder of demo examples provided with this documentation. Adapt the contents of that folder to set up your own demos.

Workflow for Providing Demos

To include demos for your toolbox in the Help browser Contents pane, you must create and provide a demos.xml file and content for your demos. Specify a location to MATLAB where the files will reside:

1. Create or choose a folder for storing your demos files. You must have write access to the folder. If you have created a toolbox, the toolbox folder is a good location for storing related demos.

   For the example, the folder is /demo_examples.

2. Create your demo files by publishing code files, constructing a GUI, or another method.

3. Put all the demos files you created in the folder.

4. Add the folder for your demos files to the search path.

   Note   The folder cannot be the current folder when you add it to the path or the Help browser will be unable to locate your demos.

5. Get the example demos.xml file to use as a template for your own file. Click here to copy that file to your current folder, or

   1. Copy matlabroot/help/techdoc/matlab_env/examples/demo_examples/demos.xml to the folder for your demos files:

      copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',...
               'examples','demo_examples','demos.xml'),pwd)

   2. Verify that the copied demos.xml file is writable. If it is read-only, make in writable with:

      fileattrib('demos.xml','+w')

6. Edit the content of your copy of demo.xml, changing it to describe and point to your demo files. For details, see More About the demos.xml File.

7. View your demos.xml file in the Help browser. A new node, Other Demos, appears at the bottom of the Help browser Contents pane. Expand the node to view the entries you added.

8. If the Other Demos entry does not appear at the bottom of the Help Navigator, refresh the Help browser. You can refresh in two ways:

   • Right-click on Demos in the Contents pane, and select Refresh Demos. Doing so refreshes all demos on the search path and can take a moment.

   • Remove the folder containing your demos.xml file from the search path using rmpath. Then, use addpath to add your demos folder back on the search path.

   Note   The Help browser Filter by Product preference does not provide an Other Demos entry or list the toolbox demos you add. However, the Help browser always shows toolbox demos that you add to the search path.

More About the demos.xml File

Within the demos.xml file, the root tag is <demos>. This element includes one <name>, <type>, <icon> and <description> for the main demo page for your toolbox.

Include a <demoitem> for each demo you add. Provide multiple categories of demos by including a <demosection> for each category. Put <demoitem> entries within that category. If you include any categories, then all demos must be in categories. In other words, if there is even one <demosection>, then all demoitem tags must be within demosection tags.

Step 5 of the previous procedure tells how to obtain the example demos.xml file. This example contains the following XML code:

<?xml version="1.0" encoding="utf-8"?>
<!-- Example demos.xml file for adding demos to the Help browser -->
<!-- Your version of this file must be named "demos.xml" -->
<demos>
    <!-- Top-level Demo title in TOC -->
    <name>Example Demos</name>
    <type>toolbox</type>
    <icon>HelpIcon.DEMOS</icon>
    <description>These demos are given as examples to  
    demonstrate how to add demo files for your own toolbox.
    </description>
    <website>
    <a href="http://www.mathworks.com">Link to your Web site here</a>
    </website>
    <!-- First group of demos begins here -->
    <demosection>
        <label>Markup Demos</label>
        <!-- First demo begins here -->
        <demoitem>
            <!-- How demo is described in the Contents pane -->
            <label>Formatting Text for Publishing</label>
            <!-- Type adds a system icon and this name next to demo item -->
            <type>M-file</type>
            <!-- File to display in the Viewing pane -->
            <file>./html/formatted_block_demo.html</file>
            <!-- Supply optinoal thumbnail for demo as a .png file -->
            <!-- Name it <demo_name>.png -->
            <!-- for this demo it is ./html/formatted_block_demo.png -->
        </demoitem>
    </demosection>
    <!-- Second group of demos begins here -->
    <demosection>
       <label>Computational Demos</label>
       <demoitem>
           <!-- How demo is described in the Contents pane -->
           <label>Sguare Waves from Fourier Series</label>
            <!-- Do not add a <type> element if demo is executable -->
            <!-- File to execute for "Run this demo" -->
           <callback>fourier_demo</callback>
           <!-- File to display in the Viewing pane -->
           <file>./html/fourier_demo2.html</file>
       </demoitem>
    </demosection>
    <!-- Third group of demos begins here -->
    <demosection>
        <label>Video Demos</label>
        <demoitem>
            <!-- Type adds a system icon and this name next to demo item -->
            <type>video</type>
            <!-- How demo is described in the Contents pane -->
            <!-- This is an actual MATLAB Flash video demo -->
            <!-- If Flash is installed, it runs in your system bowser -->
            <label>Working in The Development Environment (4 min, 7 sec)</label>
            <!-- Command or file to execute for "Run this demo" -->
            <callback>
              playbackdemo('WorkingInTheDevelopmentEnvironment',...
                  'toolbox/matlab/web/demos');
            </callback>
        </demoitem>
    </demosection>
</demos>

Lines starting with <!-- and ending with --> are comments. The code contains two <demosection> items, each containing one <demoitem>. The first demo consists of HTML documentation only (a <file> element). The second one has both HTML documentation and MATLAB code that the reader can execute (a <callback> element). When you include a callback element, it must contain an executable command. The reader can execute that command by clicking Run this demo at the top of the demo page.

The next table describes the demos.xml file listed above, and found in the folder matlabroot/help/techdoc/matlab_env/examples/demo_examples.

Supplying Thumbnail Images for Demos.  If your demo has an HTML file to describe it, you can include a thumbnail, a small image typifying the demo. The demos.xml file does not specify thumbnail images directly.

To include a thumbnail, you only need to supply a .png image file in the same folder as the HTML file for the demo. Keep the image size to within 96-by-64 pixels (width-by-height). Give the .png file the same name as the HTML file. Thus, if the <file> element for your demo is ./html/formatted_block_demo.html, then your thumbnail must be named formatted_block_demo.png and reside in the same folder.

When you publish a MATLAB script to HTML with the publish command or Editor File menu item, you get a .png thumbnail file in the correct place with the correct name by default.

Back to Top

Providing Demos to Others

Anyone who wants to use your demos needs the files and instructions for using them:

1. Provide recipients with a folder containing:

   • Your demo files

   • All data, images or other files referenced by the demo files

   • Your demos.xml file

2. Instruct recipients to add the folder containing the demos files to the search path.

3. Inform recipients that the toolbox demos appear under Other Demos, the last entry in the Contents pane.

Back to Top

Add Documentation to the Help Browser

Address Validation Errors for info.xml Files

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit