From b3bb32b09d38b01009f0e33acaef200d7f36b2aa Mon Sep 17 00:00:00 2001 From: Robert Haritonov Date: Sun, 20 Sep 2015 18:43:42 +0200 Subject: [PATCH] #123: add spec rendering helpers doc --- docs/base/readme.md | 9 +- docs/spec-helpers/examples/buttons.html | 11 +++ docs/spec-helpers/examples/include.html | 1 + docs/spec-helpers/examples/markdown-file.md | 1 + docs/spec-helpers/examples/mask-one.html | 1 + docs/spec-helpers/examples/mask-two.html | 2 + docs/spec-helpers/examples/three.html | 1 + docs/spec-helpers/info.json | 5 + docs/spec-helpers/readme.md | 103 ++++++++++++++++++++ 9 files changed, 131 insertions(+), 3 deletions(-) create mode 100644 docs/spec-helpers/examples/buttons.html create mode 100644 docs/spec-helpers/examples/include.html create mode 100644 docs/spec-helpers/examples/markdown-file.md create mode 100644 docs/spec-helpers/examples/mask-one.html create mode 100644 docs/spec-helpers/examples/mask-two.html create mode 100644 docs/spec-helpers/examples/three.html create mode 100644 docs/spec-helpers/info.json create mode 100644 docs/spec-helpers/readme.md diff --git a/docs/base/readme.md b/docs/base/readme.md index fafa03b..fa12d14 100644 --- a/docs/base/readme.md +++ b/docs/base/readme.md @@ -118,6 +118,8 @@ By default all files are pre-processed with [EJS](http://ejs.co/), so you're fre <% if (info.title === 'Title') {% > Action! <% } %> ``` +Read more about Spec page generation helpers. + ### Client-side Templating Engines For client-side templating you don't need any magic, just link Mustache or any other JS library to your page and use it whenever you want. @@ -167,11 +169,12 @@ As a Style Guide Platform we focus on flexibility and ease of integration. All S Plugins are working in the same way as core modules, but are kept outside the main platform, allowing to separate specific features. -Here is a list of official plugins: +Here is a list of available plugins: -* [sourcejs-md-react](https://www.npmjs.com/package/sourcejs-md-react) (new) +* [sourcejs-slm](https://github.com/venticco/sourcejs-slm) (new) +* [sourcejs-md-react](https://github.com/mik01aj/sourcejs-md-react) (new) * [sourcejs-contrib-browser-sync](https://github.com/sourcejs/sourcejs-contrib-browser-sync) (new) -* [sourcejs-react](https://www.npmjs.com/package/sourcejs-react) (new) +* [sourcejs-react](https://github.com/szarouski/sourcejs-react) (new) * [sourcejs-contrib-dss](http://github.com/sourcejs/sourcejs-contrib-dss) (new) * [sourcejs-spec-status](https://github.com/sourcejs/sourcejs-spec-status) * [sourcejs-crowd-voice](https://github.com/sourcejs/sourcejs-crowd-voice) diff --git a/docs/spec-helpers/examples/buttons.html b/docs/spec-helpers/examples/buttons.html new file mode 100644 index 0000000..ba03d96 --- /dev/null +++ b/docs/spec-helpers/examples/buttons.html @@ -0,0 +1,11 @@ +

<%- info.title %>

+ +<% var buttons = ['btn-group-lg', '', 'btn-group-sm', 'btn-group-xs'] %> + +<% buttons.forEach(function(modifier){ %> +
+ + + +


+<% }); %> \ No newline at end of file diff --git a/docs/spec-helpers/examples/include.html b/docs/spec-helpers/examples/include.html new file mode 100644 index 0000000..c69ab9f --- /dev/null +++ b/docs/spec-helpers/examples/include.html @@ -0,0 +1 @@ +Included file from `spec-helpers/examples/include.html`. \ No newline at end of file diff --git a/docs/spec-helpers/examples/markdown-file.md b/docs/spec-helpers/examples/markdown-file.md new file mode 100644 index 0000000..ba9be8c --- /dev/null +++ b/docs/spec-helpers/examples/markdown-file.md @@ -0,0 +1 @@ +Processed **Markdown** file. \ No newline at end of file diff --git a/docs/spec-helpers/examples/mask-one.html b/docs/spec-helpers/examples/mask-one.html new file mode 100644 index 0000000..beb1464 --- /dev/null +++ b/docs/spec-helpers/examples/mask-one.html @@ -0,0 +1 @@ +one
\ No newline at end of file diff --git a/docs/spec-helpers/examples/mask-two.html b/docs/spec-helpers/examples/mask-two.html new file mode 100644 index 0000000..2baf36b --- /dev/null +++ b/docs/spec-helpers/examples/mask-two.html @@ -0,0 +1,2 @@ +two
+<%- includeFiles('three.html') %> \ No newline at end of file diff --git a/docs/spec-helpers/examples/three.html b/docs/spec-helpers/examples/three.html new file mode 100644 index 0000000..7a83c24 --- /dev/null +++ b/docs/spec-helpers/examples/three.html @@ -0,0 +1 @@ +three
\ No newline at end of file diff --git a/docs/spec-helpers/info.json b/docs/spec-helpers/info.json new file mode 100644 index 0000000..ca0bdee --- /dev/null +++ b/docs/spec-helpers/info.json @@ -0,0 +1,5 @@ +{ + "keywords": "ejs, include", + "title": "Spec Rendering Helpers", + "template": "doc" +} diff --git a/docs/spec-helpers/readme.md b/docs/spec-helpers/readme.md new file mode 100644 index 0000000..e05dde1 --- /dev/null +++ b/docs/spec-helpers/readme.md @@ -0,0 +1,103 @@ +## Intro + +Spec pages in SourceJS engine are the main content units. They provide a proper sandbox for demoing rendered components, usage examples and module documentation. Therefore, it's really important to make Spec pages development process as easy as possible. + + Apart from plugins, that allow integrating different technologies for generating Specs pages, the engine provides a set of native helpers based on [EJS](http://ejs.co). + + Let's dive deeper into each of available Spec generation features. + + ## Plugins + + It's really important for us to make SourceJS easy adaptable to any project needs. Having a powerful, and easy-to-develop plugins system hugely improves developers user experience working with Living Style Guides. + + Here's a list of all Spec generation focused plugins: + +* [sourcejs-slm](https://github.com/venticco/sourcejs-slm) - [Slim](http://slim-lang.com/) templates support +* [sourcejs-md-react](https://github.com/mik01aj/sourcejs-md-react) - Markdown helpers for rendering React components +* [sourcejs-react](https://github.com/szarouski/sourcejs-react) - generate specs from JSX files +* [sourcejs-contrib-dss](http://github.com/sourcejs/sourcejs-contrib-dss) - generating documentation out of CSS comments +* [sourcejs-jade](https://github.com/sourcejs/sourcejs-jade) - [Jade](http://jade-lang.com/) syntax support + +Most of the plugins have [live examples](http://sourcejs.com/specs/example-specs-showcase/) on the project website. + + ## Native Templating + + SourceJS uses powerful [EJS](http://ejs.co/) templating engine for core UI generation and Specs content processing. This means that any Spec file can use the full power of EJS templating logic. + + ```html +<% if (info.title === 'Title') {% > Action! <% } %> +``` + +Use plain JavaScript for managing conditions and generating demo content through data loops. All `info.json` file contents are by default available in each Spec scope. Apart from common [meta information](/docs/info-json) available in `info.json` files, it's possible to set any of your own custom data. + +```html +<h2><%- info.title %></h2> + +<% var buttons = ['btn-group-lg', '', 'btn-group-sm', 'btn-group-xs'] %> + +<% buttons.forEach(function(modifier){ %> + <div class="btn-group <%= modifier %>" role="group" aria-label="Default button group"> + <button type="button" class="btn btn-default">Left</button> + <button type="button" class="btn btn-default">Middle</button> + <button type="button" class="btn btn-default">Right</button> + </div><br><br> +<% }); %> +``` + +```example +<%- include('examples/buttons.html') %> +``` + +### Includes + +Providing a relative path to current Specs, it's easy to include any file. + +```html +<%- include('examples/include.html') %> +``` + +```example +<%- include('examples/include.html') %> +``` + +Note that by default, SourceJS restricts including files outside project directory for security reasons. To disable this restrictions, change `core.sandboxIncludes` configuration. + +View examples source code. + + +## EJS Custom Helpers + +Starting from v.0.5.6, SourceJS provides a set of custom EJS helpers: + +* `includeMD(path)` - include and process Markdown file +* `includeFiles(glob)` - include a set of files by mask (uses [glob](https://github.com/isaacs/node-glob)) + +Feel free to create Pull Requests with a wider set of helpers. + +### includeMD + +```html +<%- includeMD('examples/markdown-file') %> +``` + +```example +<%- includeMD('examples/markdown-file') %> +``` + +### includeFiles + +```html +<%- includeFiles('examples/mask-*.html') %> +``` + +```example +<%- includeFiles('examples/mask-*.html') %> +``` + +View examples source code. + +## Extended features + +For any other custom Spec content processing, we recommend building own SourceJS plugins. Follow our [instructions](/docs/api/plugins/) and example plugins for fast kick-off. + +It's also possible to configure custom build task, that will generate compatible Spec pages via Grunt/Gulp or any other build tool. \ No newline at end of file