swiftstencil/swiftpm-stencil
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Revamp docs to separate template writers/devs

Browse Source
This commit is contained in:
Kyle Fuller
2016-12-01 01:30:33 +00:00
parent 9e2a061795
commit f90597fba1
9 changed files with 240 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@@ -39,16 +39,6 @@ let rendered = try environment.renderTemplate(name: context)
print(rendered)
```
## Installation
Installation with Swift Package Manager is recommended.
### CocoaPods
```ruby
pod 'Stencil'
```
## Philosophy
Stencil follows the same philosophy of Django:
@@ -61,8 +51,16 @@ Stencil follows the same philosophy of Django:
## The User Guide
- [Templates](http://stencil.fuller.li/en/latest/templates.html)
Resources for Stencil template authors to write Stencil templates:
- [Language overview](http://stencil.fuller.li/en/latest/templates.html)
- [Built-in template tags and filters](http://stencil.fuller.li/en/latest/builtins.html)
Resources to help you integrate Stencil into a Swift project:
- [Installation](http://stencil.fuller.li/en/latest/installation.html)
- [Getting Started](http://stencil.fuller.li/en/latest/getting-started.html)
- [API Reference](http://stencil.fuller.li/en/latest/api.html)
- [Custom Template Tags and Filters](http://stencil.fuller.li/en/latest/custom-template-tags-and-filters.html)
## License

140
docs/api.rst Normal file
View File

@@ -0,0 +1,140 @@
Template API
============
This document describes Stencils Swift API, and not the Swift template language.
.. contents:: :depth: 2
Environment
-----------
An environment contains shared configuration such as custom filters and tags
along with template loaders.
.. code-block:: swift
let environment = Environment()
You can optionally provide a loader or namespace when creating an environment:
.. code-block:: swift
let environment = Environment(loader: ..., namespace: ...)
Rendering a Template
~~~~~~~~~~~~~~~~~~~~
Environment provides convinience methods to render a template either from a
string or a template loader.
.. code-block:: swift
let template = "Hello {{ name }}"
let context = ["name": "Kyle"]
let rendered = environment.renderTemplate(string: template, context: context)
Rendering a template from the configured loader:
.. code-block:: swift
let context = ["name": "Kyle"]
let rendered = environment.renderTemplate(name: "example.html", context: context)
Loading a Template
~~~~~~~~~~~~~~~~~~
Environment provides an API to load a template from the configured loader.
.. code-block:: swift
let template = try environment.loadTemplate(name: "example.html")
Loader
------
Loaders are responsible for loading templates from a resource such as the file
system.
Stencil provides a ``FileSytemLoader`` which allows you to load a template
directly from the file system.
FileSystemLoader
~~~~~~~~~~~~~~~~
Loads templates from the file system. This loader can find templates in folders
on the file system.
.. code-block:: swift
FileSystemLoader(paths: ["./templates"])
.. code-block:: swift
FileSystemLoader(bundle: [Bundle.main])
Custom Loaders
~~~~~~~~~~~~~~
``Loader`` is a protocol, so you can implement your own compatible loaders. You
will need to implement a ``loadTemplate`` method to load the template,
throwing a ``TemplateDoesNotExist`` when the template is not found.
.. code-block:: swift
class ExampleMemoryLoader: Loader {
func loadTemplate(name: String, environment: Environment) throws -> Template {
if name == "index.html" {
return Template(templateString: "Hello", environment: environment)
}
throw TemplateDoesNotExist(name: name, loader: self)
}
}
Context
-------
A ``Context`` is a structure containing any templates you would like to use in
a template. It’s somewhat like a dictionary, however you can push and pop to
scope variables. So that means that when iterating over a for loop, you can
push a new scope into the context to store any variables local to the scope.
You would normally only access the ``Context`` within a custom template tag or
filter.
Subscripting
~~~~~~~~~~~~
You can use subscripting to get and set values from the context.
.. code-block:: swift
context["key"] = value
let value = context["key"]
``push()``
~~~~~~~~~~
A ``Context`` is a stack. You can push a new level onto the ``Context`` so that
modifications can easily be poped off. This is useful for isolating mutations
into scope of a template tag. Such as ``{% if %}`` and ``{% for %}`` tags.
.. code-block:: swift
context.push(["name": "example"]) {
// context contains name which is `example`.
}
// name is popped off the context after the duration of the closure.
``flatten()``
~~~~~~~~~~~~~
Using ``flatten()`` method you can get whole ``Context`` stack as one
dictionary including all variables.
.. code-block:: swift
let dictionary = context.flatten()

45
docs/api/context.rst
View File

@@ -1,45 +0,0 @@
Context
=======
A Context is a structure containing any templates you would like to use in a
template. It’s somewhat like a dictionary, however you can push and pop to
scope variables. So that means that when iterating over a for loop, you can
push a new scope into the context to store any variables local to the scope.
API
----
Subscripting
~~~~~~~~~~~~
You can use subscripting to get and set values from the context.
.. code-block:: swift
context["key"] = value
let value = context["key"]
``push()``
~~~~~~~~~~
A ``Context`` is a stack. You can push a new level onto the ``Context`` so that
modifications can easily be poped off. This is useful for isolating mutations
into scope of a template tag. Such as ``{% if %}`` and ``{% for %}`` tags.
.. code-block:: swift
context.push(["name": "example"]) {
// context contains name which is `example`.
}
// name is popped off the context after the duration of the closure.
``flatten()``
~~~~~~~~~~~~~
Using ``flatten()`` method you can get whole ``Context`` stack as one
dictionary including all variables.
.. code-block:: swift
let dictionary = context.flatten()

43
docs/api/environment.rst
View File

@@ -1,43 +0,0 @@
Environment
===========
An environment contains shared configuration such as custom filters and tags
along with template loaders.
.. code-block:: swift
let environment = Environment()
You can optionally provide a loader or namespace when creating an environment:
.. code-block:: swift
let environment = Environment(loader: ..., namespace: ...)
Rendering a Template
--------------------
Environment providences coninience methods to render a template either from a
string or a template loader.
.. code-block:: swift
let template = "Hello {{ name }}"
let context = ["name": "Kyle"]
let rendered = environment.render(templateString: template, context: context)
Rendering a template from the configured loader:
.. code-block:: swift
let context = ["name": "Kyle"]
let rendered = environment.render(templateName: "example.html", context: context)
Loading a Template
------------------
Environment provides an API to load a template from the configured loader.
.. code-block:: swift
let template = try environment.loadTemplate(name: "example.html")

38
docs/api/loader.rst
View File

@@ -1,38 +0,0 @@
Loader
======
Loaders are responsible for loading templates from a resource such as the file
system.
Stencil provides a ``FileSytemLoader`` which allows you to load a template
directly from the file system.
``Loader`` is a protocol, so you can implement your own compatible loaders. You
will need to implement a ``loadTemplate`` method to load the template,
throwing a ``TemplateDoesNotExist`` when the template is not found.
.. code-block:: swift
class ExampleMemoryLoader: Loader {
func loadTemplate(name: String, environment: Environment) throws -> Template {
if name == "index.html" {
return Template(templateString: "Hello", environment: environment)
}
throw TemplateDoesNotExist()
}
}
FileSystemLoader
----------------
Loads templates from the file system. This loader can find templates in folders
on the file system.
.. code-block:: swift
FileSystemLoader(paths: ["./templates"])
.. code-block:: swift
FileSystemLoader(bundle: [Bundle.main])

37
docs/getting-started.rst Normal file
View File

@@ -0,0 +1,37 @@
Getting Started
===============
The easiest way to render a template using Stencil is to create a template and
call render on it providing a context.
.. code-block:: swift
let template = Template(templateString: "Hello {{ name }}")
try template.render(["name": "kyle"])
For more advanced uses, you would normally create an ``Environment`` and call
the ``renderTemplate`` convinience method.
.. code-block:: swift
let environment = Environment()
let context = ["name": "kyle"]
try template.renderTemplate(string: "Hello {{ name }}", context: context)
Template Loaders
----------------
A template loader allows you to load files from disk or elsewhere. Using a
``FileSystemLoader`` we can easily render a template from disk.
For example, to render a template called ``index.html`` inside the
``templates/`` directory we can use the following:
.. code-block:: swift
let fsLoader = FileSystemLoader(paths: ["templates/"])
let environment = Environment(loader: fsLoader)
let context = ["name": "kyle"]
try template.renderTemplate(name: "index.html", context: context)

32
docs/index.rst
View File

@@ -31,20 +31,34 @@ feel right at home with Stencil.
]
]
do {
let template = try Template(named: "template.html")
let rendered = try template.render(context)
print(rendered)
} catch {
print("Failed to render template \(error)")
}
let environment = Environment(loader: FileSystemLoader(paths: ["templates/"])
let rendered = try environment.renderTemplate(name: context)
Contents:
print(rendered)
The User Guide
--------------
For Template Writers
~~~~~~~~~~~~~~~~~~~~
Resources for Stencil template authors to write Stencil templates.
.. toctree::
:maxdepth: 2
templates
builtins
api/context
For Developers
~~~~~~~~~~~~~~
Resources to help you integrate Stencil into a Swift project.
.. toctree::
:maxdepth: 1
installation
getting-started
api
custom-template-tags-and-filters

29
docs/installation.rst Normal file
View File

@@ -0,0 +1,29 @@
Installation
============
Swift Package Mangaer
---------------------
If you're using the Swift Package Manager, you can add ``Stencil`` to your
dependencies inside ``Package.swift``.
.. code-block:: swift
import PackageDescription
let package = Package(
name: "MyApplication",
dependencies: [
.Package(url: "https://github.com/kylef/Stencil.git", majorVersion: 0, minor: 7),
]
)
CocoaPods
---------
If you're using CocoaPods, you can add Stencil to your ``Podfile`` and then run
``pod install``.
.. code-block:: ruby
pod 'Stencil'

4
docs/templates.rst
View File

@@ -1,5 +1,5 @@
Templates
=========
Language overview
==================
- ``{{ ... }}`` for variables to print to the template output
- ``{% ... %}`` for tags