Skip to content
This repository has been archived by the owner on Apr 11, 2018. It is now read-only.

Commit

Permalink
move custom tags docs to new extending page
Browse files Browse the repository at this point in the history
  • Loading branch information
@paularmstrong
paularmstrong committed Aug 17, 2013
1 parent 5b4a192 commit 1bbb8df
Show file tree
Hide file tree
Showing 7 changed files with 245 additions and 131 deletions.
7 changes: 6 additions & 1 deletion Makefile
View file
Expand Up @@ -115,13 +115,18 @@ docs/docs/tags.json: FORCE
@echo "Building $@..."
@${BIN}/jsdoc lib/tags/ lib/lexer.js ${JSDOCOPTS} > $@

docs/docs/extending.json: FORCE
@echo "Building $@..."
@${BIN}/jsdoc lib/parser.js lib/lexer.js ${JSDOCOPTS} > $@

.SECONDARY build-docs: \
docs/index.json

.INTERMDIATE build-docs: \
docs/docs/api.json \
docs/docs/filters.json \
docs/docs/tags.json
docs/docs/tags.json \
docs/docs/extending.json

build-docs: FORCE
@echo "Documentation built."
Expand Down
158 changes: 158 additions & 0 deletions docs/docs/extending.html
View file
@@ -0,0 +1,158 @@
{% extends "./layout.html" %}

{% block title %}{% parent %} » Extending Swig{% endblock %}

{% block content %}

{% macro description(el) %}
<p>{{ el.description|replace('\n', '</p><p>')|raw }}</p>
{% endmacro %}

<h1 id="extending">Extending Swig</h1>

<section class="doc" id="tags">
<h2>Custom Tags</h2>

<p>Swig can be extended to handle custom tags that will perform operations on full blocks of your templates. Use <a href="{{ baseurl }}/docs/api/#addTag"><code data-language="js">swig.addTag(name, parse, compile, ends)</code></a> to add your custom tag.</p>

<p>All of Swig's tags are written using the same api (with a few exceptions for core modules, like <var>extends</var> and <var>block</var>). View a tag's source to see more examples to write your own custom tags.</p>

{% for t in typedefs %}{% if t.name === 'parse' or t.name === 'compile' %}
<section id="{{ t.name }}" class="doc">
<h3>{{ t.name }}({% for p in t.params %}{{ p.name }}{% if not loop.last %}, {% endif %}{% endfor %})</h3>

<p>{{ description(t)|raw }}</p>

<h4>Arguments</h4>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
{% for p in t.params %}
<tr>
<td><var data-language="js">{{ p.name }}</var></td>
<td><code data-language="js">{{ p.type }}</code></td>
<td>{% if p.optional %}✔{% endif %}</td>
<td><samp data-language="js">{{ p.default }}</samp></td>
<td>{{ p.description|raw }}</td>
</tr>
{% endfor %}
</tbody>
</table>

{% for ex in t.examples %}
<pre><code data-language="js">{{ ex }}</code></pre>
{% endfor %}

</section>
{% endif %}{% endfor %}

<section id="ends" class="doc">
<h3>ends</h3>

<p>Controls whether or not a tag must have an <code data-language="swig">{% raw %}{% end[tagName] %}{% endraw %}</code> declared after usage in templates.</p>

<pre><code data-language="js">exports.ends = true;
// => A template that fails to close this tag will throw an Error.</code></pre>

<pre><code data-language="js">exports.ends = false;
// => A template attempts close this tag will throw an Error.</code></pre>
</section>

{% for prop in properties %}
{% if prop.isEnum %}
<section id="{{ prop.name }}" class="doc">
<h3>{{ prop.name }}</h3>
<p>{{ prop.description|replace('\n', '</p><p>')|raw }}</p>
<table>
<thead>
<tr>
<th>Value</th>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><samp data-language="js">'*'</samp></td>
<td></td>
<td>For every token, run the given callback.</td>
</tr>
<tr>
<td><samp data-language="js">'start'</samp></td>
<td></td>
<td>Run before any token is parsed.</td>
</tr>
<tr>
<td><samp data-language="js">'end'</samp></td>
<td></td>
<td>Run after all other tokens have been parsed.</td>
</tr>
{% for p in prop.properties %}
<tr>
<td><samp data-language="js">{{ p.default }}</samp></td>
<td><var data-language="js">types.{{ p.name }}</var></td>
<td>{{ p.description|raw }}</td>
</tr>
{% endfor %}
</tbody>
</table>
</section>
{% endif %}
{% endfor %}

{# % for typedef in typedefs %}
{% if typedef.type|lower === 'object' %}
<section id="{{ typedef.name }}" class="doc">
<h3>{{ typedef.name }}</h3>
<p>{{ description(typedef)|raw }}</p>

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
{% for p in typedef.properties %}
<tr>
<td><var data-language="js">{{ p.name }}</var></td>
<td><code data-language="js">{{ p.type }}</code></td>
<td>{% if p.optional %}✔{% endif %}</td>
<td><samp data-language="js">{{ p.default }}</samp></td>
<td>{{ p.description|raw }}</td>
</tr>
{% endfor %}
</tbody>
</table>
</section>
{% endif %}
{% endfor % #}

</section>
{% endblock %}

{% block extendingsubnav %}
<ol>
<li>
<a href="#tags">Custom Tags</a>
<ol>
<li><a href="#parse">parse</a></li>
<li><a href="#compile">compile</a></li>
<li><a href="#ends">ends</a></li>
<li><a href="#TYPES">Token Types</a></li>
</ol>
</li>
</ol>
{% endblock %}
Empty file added docs/docs/includes/TYPES.html
View file
Empty file.
4 changes: 4 additions & 0 deletions docs/docs/layout.html
View file
Expand Up @@ -25,6 +25,10 @@
<a href="{{ baseurl }}/docs/cli/">Command-Line</a>
{% block clisubnav %}{% endblock %}
</li>
<li>
<a href="{{ baseurl }}//docs/extending/">Extending Swig</a>
{% block extendingsubnav %}{% endblock %}
</li>
</ol>
</nav>
{% endblock %}
131 changes: 8 additions & 123 deletions docs/docs/tags.html
View file
@@ -1,4 +1,4 @@
z{% extends "./layout.html" %}
{% extends "./layout.html" %}

{% block title %}{% parent %} &raquo; Tags{% endblock %}

Expand Down Expand Up @@ -53,131 +53,16 @@ <h3>Examples</h3>
{% endif %}
{% endfor %}

<section id="custom">
<h1>Custom Tags</h1>

<p>Swig can be extended to handle custom tags that will perform operations on full blocks of your templates. Use <a href="/docs/api/#addTag"><code data-language="js">swig.addTag(name, parse, compile, ends)</code></a> to add your custom tag.</p>

<p>All of Swig's tags are written using the same api (with a few exceptions for core modules, like <var>extends</var> and <var>block</var>). View a tag's source to see more examples to write your own custom tags.</p>

<section id="parse" class="doc">
<h2>parse(str, line, parser, types, options)</h2>

<p>Parses tokens within the bounds of the tag control <code data-language>{% raw %}{% tagname [tokens...] %}{% endraw %}</code></p>

<pre><code data-language="js">exports.parse = function (str, line, parser, types, options) {
parser.on('start', function () {
// ...
});
parser.on(types.STRING, function (token) {
// ...
});
};</code></pre>

<h3>parser.on(type, callback)</h3>

<p>Callbacks can be registered for various token types found while parsing</p>

<h4>Parameters</h4>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><var data-language="js">type</var></td>
<td><code data-language="js">string or LexerToken</code></td>
<td>See the list of token types.</td>
</tr>
<tr>
<td><var data-language="js">callback</var></td>
<td><code data-anguage="js">function</code></td>
<td>Function to run for the found token.</td>
</tr>
</tbody>
</table>

<section id="token-types">
<h3>Tokens Types</h3>

{% for prop in properties %}
{% if prop.name === 'TYPES' %}
<table>
<thead>
<tr>
<th>Value</th>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><samp data-language="js">'*'</samp></td>
<td></td>
<td>For every token, run the given callback.</td>
</tr>
<tr>
<td><samp data-language="js">'start'</samp></td>
<td></td>
<td>Run before any token is parsed.</td>
</tr>
<tr>
<td><samp data-language="js">'end'</samp></td>
<td></td>
<td>Run after all other tokens have been parsed.</td>
</tr>
{% for p in prop.properties %}
<tr>
<td><samp data-language="js">{{ p.default }}</samp></td>
<td><var data-language="js">types.{{ p.name }}</var></td>
<td>{{ p.description|raw }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endif %}
{% endfor %}
</section>


</section>

<section id="compile" class="doc">
<h2>compile(compiler, args, content, parent, options)</h2>

<pre><code data-language="js">exports.compile = function (compiler, args, content, parent, options) {
return '_ouput += ' + args.join('') + ';\\n';
};</code></pre>
</section>
</section>

{% endblock %}

{% block tagsubnav %}
<ol>
<li>
<a href="#tags">Built-In Tags</a>
<ol>
{% for fn in functions %}
{% if fn.access !== "private" %}
<li>
<a href="#{{ fn.name }}">{{ fn.name }}</a>
</li>
{% endif %}
{% endfor %}
</ol>
</li>
<li>
<a href="#custom">Custom Tags</a>
<ol>
<li><a href="#parse">parse</a></li>
<li><a href="#token-types">Token Types</a></li>
<li><a href="#compile">compile</a></li>
</ol>
</li>
{% for fn in functions %}
{% if fn.access !== "private" %}
<li>
<a href="#{{ fn.name }}">{{ fn.name }}</a>
</li>
{% endif %}
{% endfor %}
</ol>
{% endblock %}

0 comments on commit 1bbb8df

Please sign in to comment.