# Creating interactive examples
It is possible to define interactive examples. Examples or parts of an example can be embedded in any page. A auto-generated link enables the visitor to open the example in a playground where she can change the template, partials, input, and so on and can see the resulting output.
# Creating examples
In order to define an example, create a new markdown file in the examples
-directory. The example data is defined in
the frontmatter of the referenced example page. See all-features-example-raw for a
complete demonstration of all features.
The following frontmatter properties are supported:
layout
: Must always beInteractivePlaygroundLayout
example
: Contains the exampletemplate
: The main Handlebars templatepartials
: An object with on property for each registered partial, the key is the partial-name, the value is the partial contentpreparationScript
: A script that is executed before compiling and running the template.Handlebars
is available as global variable in this script.input
: The template-input as embedded YAML-object.errorExpected
: A boolean (default:false
) that specifies that this example is expected to throw an error. By default, examples that throw an error during execution, cause the build of the whole site to fail. If you write an example that describes an error, you need to set this flag totrue
.
The output of the example is automatically computed using the latest release version of Handlebars.
# Example data
If possible, examples should use variations of a common data set. Therefore, the file src/examples/_example-base-data.yaml (opens new window) contains data that can be reused and adapted to each example. If the data in that file is insufficient, please add new data, but please make sure it is somehow related.
# Embedding parts of an example.
The <ExamplePart>
-component allows you to show a part of the example in the current part.
<ExamplePart examplePage="/examples/builtin-helper-each-block" show="template"/>
will result in
The props for this component are:
examplePage
: path to the example page below thesrc
-foldershow
: The part of the example that should be inserted into the page. Possible values aretemplate
,input
,output
,error
,preparationScript
andpartial
name
(optional): This prop is needed only whenshow="partial"
. It defines the name of the partial that should be inserted into the example.
The component is very useful if you want to embed the parts of an example into flowing text, You can insert the input
JSON by using <ExamplePart examplePage="/examples/all-features" show="input" />
and the following code snippet will
appear in the page:
Then, in order to show the reader the template you can use show="template"
with the same examplePage
.
You can render a partial using for example show=partial
and name=person
If you have an example with helpers, you might also want to include the preparation script:
# Horizontal layout
If you want to layout two example-parts horizontally, you can use the <Flex>
-component.
<Flex>
<ExamplePart examplePage="/examples/builtin-helper-each-block" show="template"/>
<ExamplePart examplePage="/examples/builtin-helper-each-block" show="input"/>
</Flex>
becomes