Skip to content

Inline examples

Jump to bottom Edit New page
nene edited this page Aug 8, 2012 · 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.

To make the inline examples work, you have to create an extjs-build/ directory inside the JSDuck output directory. For start, just copy over the full ExtJS SDK download:

$ 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. That's how the default eg-iframe.html file looks like:

    <!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">
     
        <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>

You can create a modified version of this file and pass it to JSDuck through --eg-iframe option. The file will then be copied to the directory you specified by --output option. Instead of the default extjs-build/ dir, you can place the source files to any other directory and modify the <script> and <link> tags in eg-iframe.html to point to these.

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 you will receive the following options object:

{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 of what to do with them.

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.

Add a custom footer
Add a custom sidebar

Clone this wiki locally