Skip to content

Inline examples

Jump to bottom Edit New page
Joel edited this page Dec 27, 2013 · 4 revisions

In addition to simple syntax-highlighted code blocks that you get by indenting code by 4 spaces, you can optionally turn them into live examples by adding an @example tag at the beginning of a code block (must also be indented):

    /**
     * See the example:
     *
     *     @example
     *     Ext.create('Ext.Button', {
     *         text: 'Click me',
     *         renderTo: Ext.getBody()
     *     });
     */

These are useful for demoing visible components. The code should be stand-alone and render the component into document body.

Ext JS examples

To make the inline examples of the Ext JS framework documentation work, you have to create an extjs-build/ directory inside the JSDuck output directory. So after running JSDuck to generate the docs, just copy over the full Ext JS SDK download:

$ jsduck /myproject/src --output=jsduck-output
$ cp -r ext-4.0.7/ jsduck-output/extjs-build

With this in place, the inline examples iframe can load ext-all.js and ext-all.css from there.

Examples for your own custom components

The above setup only works for the Ext JS builtin components. To be able to run examples of your own components you need to also include the code for all these components and reference all the needed resources from an HTML that JSDuck uses for running the examples.

Grab the eg-iframe.html from JSDuck repository and add additional <script> tags to load your additional code. For example:

    <!DOCTYPE html>
    <html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>Sencha Examples</title>
     
        <script type="text/javascript" src="extjs-build/ext-all.js"></script>
        <link rel="stylesheet" type="text/css" href="extjs-build/resources/css/ext-all.css">
     
        <!-- My custom components -->
        <script type="text/javascript" src="my-app-all.js"></script>

        <script type="text/javascript">
            function loadInlineExample(code, options, callback) {
                try {
                    document.body.innerHTML = '';
                    eval(code);
                    callback && callback(true);
                } catch (e) {
                    document.body.innerHTML = e;
                    callback && callback(false, e);
                }
            }
        </script>
    </head>
    <body>
    </body>
    </html>

Then pass this file to JSDuck through --eg-iframe option. The file will be copied to the directory you specified by --output option. In addition to the extjs-build/ dir, you need to place all your additional scripts where the eg-iframe.html file can load them.

So the whole process would go something like this:

$ jsduck /myproject/src --output=jsduck-output --eg-iframe=my-iframe.html
$ cp -r ext-4.1.3/ jsduck-output/extjs-build
$ cp /myproject/all.js jsduck-output/my-app-all.js

@example tag parameters

When the live example is activated the loadInlineExample function is called with the source code of the example, callback function, and an options object which will contain options written after the @example tag:

@example preview small frame

In the case of above example the following options object gets passed to loadInlineExample:

{preview: true, small: true, frame: true}

Of these the preview option is special - it will start up the example in live preview mode (otherwise it starts in code editor mode). For any other options it's up to your code inside the iframe.html to decide what to do.

The callback function is to notify the Docs app whether running of example succeeded or failed. This is only required when you want to run examples in batch mode (enabled with --tests option), but for completeness it's better to include it always.

using external example files

see aswell using external example files

Add a custom footer
Add a custom sidebar
Clone this wiki locally