-
Notifications
You must be signed in to change notification settings - Fork 238
Inline examples
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 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.
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
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.
see aswell using external example files