Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

More documentation

Signed-off-by: Steven Hoffman <fustrate@me.com>
  • Loading branch information...
commit 5626645742ca4cd603655831c5ef0b8842adaea6 1 parent 925dcc4
@Fustrate Fustrate authored
View
121 docs/04 - Filters.md
@@ -3,7 +3,7 @@
## Overview
Filters are used on variable and language references to manipulate the value that
-is output. There are currently 32 filters built into the smCore template engine,
+is output. There are currently 33 filters built into the smCore template engine,
and developers can add their own filters with a simple method call.
**The filter syntax has not yet been updated from the percent+semicolon syntax.
@@ -13,7 +13,7 @@ This document references a future syntax.**
Formatting is very easy to use. In order to add a filter to an existing reference,
add `|filter_name($param, 'eters')` at the end of the reference. Multiple filters
-can be added to a single reference.
+can be added to a single reference, and are evaluated from left to right.
In most cases, expressions with filters might look like the following:
@@ -33,154 +33,199 @@ In most cases, expressions with filters might look like the following:
Formats $price into something like 2,000.57
{$thing |my_filter($first, $second.param, 'third', #fourth)}
- Formats using a custom filter named 'my_formatter' with many parameters.
+ Applies a custom filter named 'my_formatter' with many parameters.
+
+On the code level, filters are passed the current value of the reference (a variable
+or language string), and return a modified version of that value.
## Default Filters - WIP
### ucwords
Capitalizes the first character of every word.
- {$var |ucwords}
+ {$text |ucwords}
### ucfirst
Capitalizes the first chracter of the string, lowercases everything else.
- {$var |ucfirst}
+ {$text |ucfirst}
### upper
-Turns the entire string to uppercase.
+Formats the entire string into uppercase.
- {$var |upper}
+ {$scream_this |upper}
### lower
-Turns the entire string to lowercase.
+Formats the entire string into lowercase.
- {$var |lower}
+ {$whisper_this |lower}
### trim
Removes whitespace from the start and end of the string.
- {$var |trim}
+ {$text |trim}
### rtrim
Removes whitespace from the end (right) of the string.
- {$var |rtrim}
+ {$text |rtrim}
### ltrim
Removes whitespace from the start (left) of the string.
- {$var |ltrim}
+ {$text |ltrim}
### even
-Returns true if the variable is an even integer (modulo 2 = 0).
+Returns true if the variable is an even integer (modulo 2 = 0), otherwise false.
- {$var |even}
+ {$age |even}
### odd
-Returns true if the variable is an odd integer (modulo 2 = 1).
+Returns true if the variable is an odd integer (modulo 2 = 1), otherwise false.
- {$var |odd}
+ {$age |odd}
### contains
If the variable is an array, returns true if the parameter is in the array.
If the variable is a string, returns true if the parameter can be found in the string.
+Returns false in all other cases.
- {$array_of_vars |contains('5')}
- {$string_var |contains('abc')}
+ {$scores |contains('95')}
+ {$alphabet |contains('abc')}
### empty
-Returns true if the variable is empty, using PHP's `empty()` function.
+Returns true if the variable is empty, using PHP's `empty()` function, otherwise false.
- {$var |empty}
+ {$glass |empty}
### null
-Returns true if the variable is null.
+Returns true if the variable is null, otherwise false.
- {$var |null}
+ {$IQ |null}
### divisibleby
Returns true if the variable is a number divisible by the parameter.
- {$var |divisibleby(3)}
+ {$age |divisibleby(3)}
### length
Returns the length of the variable. Arrays return their count, and strings return their length.
- {$var |length}
+ {$posts |length}
+ {$name |length}
### wordcount
Returns the number of words in the variable.
- {$var |wordcount}
+ {$poem |wordcount}
### urlencode
+Returns a URL-safe version of the value.
{$var |urlencode}
+ Would turn "hello world" into "hello%20world"
### json
-Returns a JSON representation of the data in `$var`
+Returns a JSON representation of the data in the variable.
- {$var |json}
+ {$person |json}
### join
+Returns the elements in the value joined by the parameter.
- {$var |join(", ")}
+ {$tags |join(", ")}
### random
+Returns a random value from an array, optionally returns a random selection.
- {$var |random}
+ {$messages |random}
+ {$messages |random(3)}
### stripchars
+Removes the characters in the parameter from the value.
- {$var |stripchars}
+ {$speech |stripchars('qxz')}
### striptags
+Removes HTML tags from the value, and optionally allows you to keep some.
{$var |striptags}
+ {$post |striptags('b i strong em tt')}
### truncate
+Cut off the value after a certain amount of characters, and optionally append a string if it does get cut.
{$var |truncate(15)}
+ {$var |truncate(15, '...')}
### truncatewords
+Cut off the value after a certain amount of words, and optionally append a string if it does get cut.
{$var |truncatewords(12)}
+ {$var |truncatewords(12, $read_more_button)}
### wrap
+Wrap the text every X characters, regardless of words.
{$var |wrap(80)}
### wordwrap
+Wrap the text every X characters, word-aware.
{$var |wordwrap(80)}
### date
+Format a timestamp into human-readable format.
+
+ {$birthday |date}
+ Format $birthday using the default date format.
- {$var |date}
- {$var |date("n/j/Y @ g:i:s A")}
+ {$birthday |date("n/j/Y @ g:i:s A")}
+ Format $birthday with a custom formatting string.
### time
+Same as `|date`, but without a parameter it only displays the time.
{$var |time}
+ {$var |time("g:i A")}
### money
+Format the value as a monetary value, with an optional formatting string and locale.
+
+ {$price |money}
+ Might return $1,400.17
- {$var |money}
+ {$price |money("%.2n")}
+ Format according to a formatting string.
+
+ {$price |money("%.2n", "it_IT")}
+ Format Italian style!
### float
+Format the value as a float, with optional precision
+
+ {$rating |float}
+ Might return 4.81516
+
+ {$rating |float(3)}
+ If $rating is 4.815162342, return 4.815
+
+### nl2br
+Convert newline characters (such as from `|wordwrap`) into HTML break tags.
- {$var |float}
- {$var |float(3)}
+ {$poem |wordwrap(25) |nl2br}
### default
+If the value is empty according to PHP's `empty()` function, use the passed parameter instead.
- {$var |default('N/A')}
+ {$name |default('John Doe')}
### raw
+If the value would be escaped, as it normally would, do not escape it.
- {$var |raw}
+ {$safe_html |raw}
### escape
+If the value would not be escaped, such as inside a CDATA block, escape it.
- {$var |escape}
+ {$unsafe_code |escape}
View
61 docs/06 - Overlays.md
@@ -1,8 +1,7 @@
-Overlays
-================================================================================
+# Overlays
+
+## Overview
-Overview
---------------------------------------------------------------------------------
Overlays are used to apply changes to templates. An overlay consists of one or
many alterations (tpl:alter elements) which get applied to templates.
@@ -10,11 +9,11 @@ An alteration is, in other words, putting more things into the template.
A basic example of this is:
- <tpl:template name="my:name" xmlns:my="http://www.example.com/">
+ <tpl:template name="my:name">
Unknown W. Brackets
</tpl:template>
- <tpl:alter match="my:name" position="before" xmlns:my="http://www.example.com/">
+ <tpl:alter match="my:name" position="before">
Mr.
</tpl:alter>
@@ -22,9 +21,8 @@ Which would produce is output:
Mr. Unknown W. Brackets
+## Matching a template
-Matching a template
---------------------------------------------------------------------------------
The match attribute specifies a list of templates that the alteration might
match. All of these have to have namespace prefixes, so that they apply to the
correct template no matter how it is referenced.
@@ -41,8 +39,8 @@ templates.
</tpl:alter>
-Position of the alteration
---------------------------------------------------------------------------------
+## Position of the alteration
+
The position attribute tells it where the alteration will apply. It has four
possible values, each of which is useful in its own respect.
@@ -56,49 +54,52 @@ In the examples, please consider the following template and call:
<my:about>is cool.</my:about>
-before
- This will place the alteration before what the template normally outputs.
+### before
+
+This will place the alteration before what the template normally outputs.
<tpl:alter match="my:about" position="before">
Mr.
</tpl:alter>
- Mr. Unknown W. Brackets is cool. That's all you can say.
+Mr. Unknown W. Brackets is cool. That's all you can say.
+
+### after
-after
- This will place the alteration after what the template normally outputs.
+This will place the alteration after what the template normally outputs.
<tpl:alter match="my:about" position="after">
Also, llamas rock.
</tpl:alter>
- Unknown W. Brackets is cool. That's all you can say. Also, llamas rock.
+Unknown W. Brackets is cool. That's all you can say. Also, llamas rock.
-beforecontent
- If the template doesn't have a tpl:content element, this is the same as
- "after"... but if it has one, the alteration will be made before the
- tpl:content element.
+### beforecontent
+
+If the template doesn't have a tpl:content element, this is the same as
+"after"... but if it has one, the alteration will be made before the
+tpl:content element.
<tpl:alter match="my:about" position="beforecontent">
is a jerk, but that
</tpl:alter>
- Unknown W. Brackets is a jerk, but that is cool. That's all you can say.
+Unknown W. Brackets is a jerk, but that is cool. That's all you can say.
+
+### aftercontent
-aftercontent
- If there's no tpl:content element in the template, this will be the same as
- "after". When there is one, the alteration will be made immediately after
- it.
+If there's no tpl:content element in the template, this will be the same as
+"after". When there is one, the alteration will be made immediately after
+it.
<tpl:alter match="my:about" position="beforecontent">
I guess.
</tpl:alter>
- Unknown W. Brackets is cool. I guess. That's all you can say.
+Unknown W. Brackets is cool. I guess. That's all you can say.
+## Nesting
-Nesting
---------------------------------------------------------------------------------
It's important to note that elements don't need to be properly nested within
alternations, as long as the resulting template would be properly nested.
@@ -135,8 +136,8 @@ altered, had correct nesting. It would've looked like this:
</tpl:template>
-Variables
---------------------------------------------------------------------------------
+## Variables
+
When variables are given to a template, you can use them in alterations too.
For example:
View
45 docs/18 - Why Not.md
@@ -1,44 +1,43 @@
-For developers - why not X?
-================================================================================
+# For Developers - Why Not X?
+
+## Why not XSL?
-Why not XSL?
---------------------------------------------------------------------------------
XSL is a great transformation language written in XML. However, since it's an
XML application, it requires that it's well-formatted XML.
This leads to a few things that the authors of ToxG and the smCore template
engine find annoying:
- - Templates cannot contain partial elements, although this is uncommon.
+- Templates cannot contain partial elements, although this is uncommon.
+
+- Building an element with transformations requires using something like
+ xsl:tag, xsl:attribute, which are very annoying to use in practice.
- - Building an element with transformations requires using something like
- xsl:tag, xsl:attribute, which are very annoying to use in practice.
+- In practice, entity references are painful and external doctypes don't work.
- - In practice, entity references are painful and external doctypes don't work.
+- Using it usually necessitates using XML as output, which causes extra layers
+ of data output and buffering, which is less efficient.
- - Using it usually necessitates using XML as output, which causes extra layers
- of data output and buffering, which is less efficient.
+- Duplicate templates are not suported, which makes automatic additions from
+ external modules difficult, which is the main purpose of this engine.
- - Duplicate templates are not suported, which makes automatic additions from
- external modules difficult, which is the main purpose of this engine.
+## Why not use PIs?
-Why not use PIs?
---------------------------------------------------------------------------------
It's true that the tags used in this are really processing instructions,
-especially when it comes to things like <tpl:else />. XML has a standard way
+especially when it comes to things like `<tpl:else />`. XML has a standard way
of dealing with these, PIs. They aren't used because:
- - PIs must start with an identifer, which makes open/close sections seem
- out of place, although they are important and key in templating.
+- PIs must start with an identifer, which makes open/close sections seem
+ out of place, although they are important and key in templating.
- - They will confuse people with PHP, since <?php ?> is a PI, technically.
+- They will confuse people with PHP, since `<?php ?>` is a PI, technically.
- - It's still not going to be valid XML, but will look even more like it.
+- It's still not going to be valid XML, but will look even more like it.
-Why not use PHP?
---------------------------------------------------------------------------------
+## Why not use PHP?
+
PHP was originally built as a system for formatting HTML output, and is very
well documented. There's no doubt that it makes a good templating system
even used alone.
@@ -53,8 +52,8 @@ place, and not involve tons of red tape. Moreover, security needs to be the
default, instead of an afterthought.
-Why not use Smarty or ...?
---------------------------------------------------------------------------------
+## Why not use Smarty or ...?
+
There are other templating systems out there. These systems are generally well
thought out and do a good job solving some of the same problems this does.
View
43 docs/20 - Template Callbacks.md
@@ -1,8 +1,7 @@
-For developers - creating template callbacks
-================================================================================
+# For Developers - Creating Template Callbacks
+
+## Why use callbacks?
-Why use callbacks?
---------------------------------------------------------------------------------
A callback is a good way to load data for a template to use, and only load it
if the template needs it.
@@ -11,31 +10,31 @@ using callbacks (or in other words hooks) is to do things at runtime which are
necessary.
-Example scenario
---------------------------------------------------------------------------------
+## Example scenario
+
For the purposes of example, let's suppose you have the following template code:
-<tpl:template name="site:about-us">
- We are a zoo. These are the animals we have:
- <site:animals />
-</tpl:template>
+ <tpl:template name="site:about-us">
+ We are a zoo. These are the animals we have:
+ <site:animals />
+ </tpl:template>
-<tpl:template name="site:animals">
- <ul>
- <tpl:foreach from="{$animals}" as="{$animal}">
- <li>{$animal.name}</li>
- </tpl:foreach>
- </ul>
-</tpl:template>
+ <tpl:template name="site:animals">
+ <ul>
+ <tpl:foreach from="{$animals}" as="{$animal}">
+ <li>{$animal.name}</li>
+ </tpl:foreach>
+ </ul>
+ </tpl:template>
-Loading only what you need
---------------------------------------------------------------------------------
+## Loading only what you need
+
In the above template, suppose you only want to load the list of animals in the
case that they are going to be displayed, but want to leave their display up to
the template author.
-In this case, you would "hook" the <tpl:template name="site:animals"> element,
+In this case, you would "hook" the `<tpl:template name="site:animals">` element,
and load the appropriate information there. For example:
function maybeHookTemplate(ToxgBuilder $builder, $type, array $attributes, ToxgToken $token)
@@ -50,8 +49,8 @@ and load the appropriate information there. For example:
$template->listenEmitBasic('template', 'maybeHookTemplate');
-Best practices
---------------------------------------------------------------------------------
+## Best practices
+
Doing a bunch of ifs for each template does not make for very easily extended
code. Instead, you might want to add a generic hook, e.g. into your event
system (based on the name.)
Please sign in to comment.
Something went wrong with that request. Please try again.