Download the PHP package level-2/transphporm without Composer
On this page you can find all versions of the php package level-2/transphporm. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download level-2/transphporm
More information about level-2/transphporm
Files in level-2/transphporm
Package transphporm
Short Description A new approach at templating
License BSD-2-Clause
Homepage https://github.com/Level-2/Transphporm
Informations about the package transphporm
Transphporm Style Sheets
Transphporm is a fresh approach to templating in PHP. Let's face it, templating in PHP sucks because it involves code like this:
Or some variation of this mess:
or
Why does this suck? It mixes the logic with the template. There are processing instructions mixed inside the template. In the case of the middle example, it's just barely abstracted PHP code. Whoever is writing the template is also in charge of writing the display logic and understanding the data structures that have been supplied.
Template systems like this still mix logic and markup, the one thing they're trying to avoid.
This is equivalent to <h1 style="font-weight:bold">Title</h1>
, as it mixes two very different concerns.
Transphporm is different
Project Goals
- To completely separate the markup from the processing logic. (No
if
statements or loops in the template!) - To follow CSS concepts and grammar as closely as possible. (This makes it incredibly easy to learn for anyone who already understands CSS.)
With Transphporm, the designer just supplies some raw HTML or XML that contains some dummy data. (Designers much prefer lorem ipsum to seeing {{description}}
in their designs!)
It's pure markup without any processing instructions. Transphporm then takes the markup and replaces the dummy data with the real data you want.
But where are the processing instructions? Transphporm follows CSS's lead. All of the processing logic is stored externally in "Transformation Style Sheets", a completely separate file that contains entirely reusable processing instructions.
At its most basic, Transphporm works by supplying a stylesheet and HTML/XML as strings.
Transphporm allows you to insert content into any element on a page. Traditional template engines force you to place markers in the markup which will then be replaced (essentially using str_replace
) within the content.
Transphporm takes a different approach and allows you to insert content using a CSS-like syntax. You don't need to provide special markers in the template; the template is plain old HTML without any special syntax. The elements on the page can then be targeted using CSS-style selectors.
For example, this stylesheet:
will set the content of any <h1>
Tag to "My Title". Given the following code:
The output will be:
The arguments for Transphporm\Builder can either be HTML/XML and TSS strings, or file names to load.
This allows an unprecedented level of flexibility. Rather than having to consider which parts of the content may be dynamic and adding things like {{user.name}}
in the template at the correct position, these concerns can be ignored when designing the template and some static content inserted in its place. Transphporm can then replace any content on the page. This allows you to-reuse a template. Sometimes you might replace some content, other times you might use the default from the template!
5 Reasons to use Transphporm
-
Write content to any element. With traditional template engines the designer needs to place markers in the template, e.g.
{{name}}
, everywhere that content needs to be injected into the template. With Transphporm, the designer doesn't need to worry about whether specific content will be replaced (effectively withstr_replace
). Instead Transphporm allows the developer to write content to any HTML element on the page, and the designer to focus on design rather than worrying about what content might be added. -
Anything can be a partial. Traditional template engines force you to put each partial in its own file. This is bad for the designer because they cannot quickly an easily see how the partial looks inside the complete layout. With Transphporm, the designer can work with complete HTML files and the developer can extract any element from any file as a partial.
-
Resuable display logic. Because display logic is placed in its own external file, you can use the same display logic with as many XML files as you like. This is the difference between external CSS files and
style=
attributes inside your HTML. -
Render your template on the client or the server. The TSS format is not barely-abstracted PHP code like traditional template engines; it's a custom format with no reliance on PHP. Because of this, you can take an XML file and a TSS file and render it on the server using Transphporm or inside the browser using the JavaScript implementation Tranjsform.
- If you've used CSS, Transphporm is easy to learn. Transphporm closely follows CSS syntax and uses some of the same vocabulary. If you have even a basic understanding of CSS, you'll be able to learn to use Transphporm with ease!
Transphporm gives both designers and developers an unprecedented level of flexibility that just isn't possible with traditional template engines.
Installation
The preferred method of installing Transphporm is via Composer. Transphporm is available from Packagist as:
level-2/transphporm
However, if you don't want to use Composer you can manually install Transphporm:
- Download and extract Transphporm into your project
- Use a PSR-0 compliant autoloader such as Axel
- Register Transphporm's
src
directory with the autoloader. Using Axel this is done via:
Data
It's not usually possible to specify the content in a static file like a stylesheet. The tss
format also allows referencing external data. This data is supplied to the template builder's output
method and can be referenced in the stylesheet using the data()
function. This can be thought of like the url()
function in CSS, in that it references an external resource.
Output:
Most of the time, you will need to work with much more complex data structures. Transphporm allows for reading data from within data structures using the inbuilt data function:
Which will output:
Content
The content property can take multiple values, either a function call such as data
or a quoted string as each value, and will concatenate any supplied values:
Output:
For more information on inserting content see the wiki pages Basic usage: Inserting Content and Basic Usage: External Data
Loops
Going back to the user list example, consider the following data structure:
Using Transphporm, the user list can be generated like this:
repeat
tells Transphporm to repeat the selected element for each of the supplied array.
data(users)
reads $data['users']
as supplied in PHP.
iteration(name)
points at the value for the current iteration and reads the name
property. This code outputs:
Similarly, iteration
can read specific values and be used in nested nodes:
Which will output:
For more information on loops see the Wiki page Basic usage: Loops.
Removing Blocks
Lifted straight from CSS grammar, Transphporm supports display: none
which will actually remove the element from the document entirely:
Output:
N.b. this is very useful with the iteration value pseudo element. For more examples of conditonal logic see the Wiki page on Basic usage: Conditional logic.
CSS Selectors
Transphporm supports the following CSS selectors:
tagName
#id
.className
tagName.className
direct > descendant
[attribute]
[attribute=value]
[attribute!=value]
And any of these can be chained:
main .post > .author[data-admin=true]
will match any element with the class name author
which has the data-admin
attribute set to true and is directly inside an element with the class name post
that is inside the <main>
element.
For a full list of supported selectors and example of each one, see the Wiki page on Basic Usage: CSS Selectors.
Pseudo Elements
Transphporm also supports several pseudo elements:
:before
and :after
which allows writing content to the beginning or end of a node.
:nth-child(n)
:nth-child(odd)
:nth-child(even)
For examples of each of these, please see the Wiki page Basic Usage: Pseudo Elements.
Iteration values
Transphporm can also inspect the iterated data for an element. This is particularly useful when you want to hide a specific block based on the content of an iterated value:
The format is:
This will select any element whose iteration content's name
attribute is equal to value
.
The following code will hide any user whose type is 'Admin'.
Output:
Writing to Attributes
Unlike CSS, Transphporm selectors allow direct selection of individual attributes to set their value. This is done using the pseudo element :attr(name)
which selects the attribute on the matched elements.
Will select the element's ID attribute.
Working example:
Notice this uses multiple values for the content
property to concatenate the full URL with mailto
.
Output:
Reading from attributes
It's also possible to read from attributes using attr(name)
inside the content property.
Output:
HTTP Headers
Transphporm supports setting HTTP Headers. You must target an element on the page such as HTML and you can use the :header
pseudo element to set a HTTP header. For example a redirect can be done like this:
Transphporm does not directly write HTTP headers. The return value of the output()
function is an array consisting of a body
and headers
. body
is the rendered HTML code and headers
contains any HTTP headers which have been set.
Will print:
To actually send the headers to the browser you need to manually call the header command:
Conditionally applying HTTP headers
In most cases, you will want to conditionally display a header. For example:
- Redirect on success.
- Send a 404 header when a record could not be found.
To do this, you can use conditional data lookups:
Prints:
To use this, you should then call the inbuilt php http_response_code
function with this status:
Transphporm does not send any headers
Transphporm does not send any output to the browser by default. This is for maximum flexibility. You still must manually send the headers and echo the body.
Formatting data
Transphporm supports formatting of data as its output. The syntax for formatting is this:
String formatting
Transphporm currently supports the following formats for strings:
- uppercase
- lowercase
- titlecase
Examples:
String format: uppercase
Prints:
String format: lowercase
Prints:
String format: titlecase
Prints:
Number formats
Transphporm supports formatting numbers to a number of decimal places using the decimal
format. You can specify the number of decimal places:
Number format: decimal
Prints:
Locales
For date, time and currency formatting, Transphporm supports locales. Currently only enGB is supplied but you can write your own.
To set a locale, use the builder::setLocale
method. This takes either a locale name, for a locale inside Formatter/Locale/{name}.json
e.g.
Currently only enGB is supported. Alternatively, you can provide an array which matches the format used in Formatter/Locale/enGB.json
.
Date formats
Transphporm supports formatting dates. Either you can reference a \DateTime
object or a string. Strings will be converted to dates automatically, if possible:
This will format the date using the date format specified in the locale. For enGB this is d/m/Y
Alternatively you can specify a format as the second parameter of the formatter:
You can also format using time
which defaults to H:i
in the locale:
Relative times
You can supply the relative
formatter to a date, which will display things like:
- "Tomorrow"
- "Yesterday"
- "Two hours ago"
- "3 weeks ago"
- "In 3 months"
- "In 10 years"
The strings are specified in the locale.
Importing other files
Like CSS, Transphporm supports @import
for importing other TSS files:
imported.tss
Output:
Caching
Transphporm has two types of caching, both of which need to be enabled:
-
Caching TSS and XML files. This prevents them from being parsed each time the template is rendered. It is worthwhile to enable this even if you do not intend on using
update-frequency
(see below). update-frequency
This is a property which allows you to update an element at a specified interval.
To enable caching, you must create (or use) a caching class that implements PHP's inbuilt \ArrayAccess
interface, for example Level-2/SimpleCache. Then assign an instance to the builder:
Doing this will automatically enable file-caching. Once a cache has been assigned, TSS files will only be parsed whenever they are updated. This saves parsing the TSS file each time your page loads and is worthwhile even if you are not using update-frequency
.
update-frequency
update-frequency
is a TSS directive that describes how frequently a given TSS rule should run. Behind the scenes, Transphporm will save the final output each time a template is rendered and make changes to it based on update-frequency
. For example:
This will only run the TSS rule every 10 minutes. The way this works behind the scenes is:
- The rendered template is stored in the cache.
- Next time the page loads, the previously rendered template is loaded.
- If the timer has expired, the repeat/content/etc. directives are run again on the cached version of the template and the template is updated.
This allows different parts of the page to be updated at different frequencies.
Caching in MVC
If you are using real MVC (not PAC, which most frameworks actually use) and you are passing your model into your view, if your model is passed in as the data
argument and has a getUsers
function, Transphporm can call this and only execute the query when the template is updated.
Most frameworks do not pass models into views, however for those that do this allows a two-level cache. The query is only run when the view is updated based on the view's timeout.
Building a whole page
Transphporm uses a top-down approach to construct pages. Most frameworks require writing a layout template and then pulling content into it. This makes it very difficult to make changes to the layout on a per-page basis. (At minimum you'd need to add some code to the layout HTML). Transphporm uses a top-down approach rather than the popular bottom-up approach where the child template is inserted into the layout at a specific point.
You still have two files, one for the layout and one for the content, but the TSS is applied to the layout which means the TSS can change anything in the layout you want (adding script tags, adding CSS, changing the page title and meta tags, etc).
layout.xml
And then home.xml
:
The TSS file can then be used to include one inside another:
home.tss
Which will then set the content of the <main>
element to the content of the template stored in home.xml
using the following code:
Obviously you could then add an about page by adding the relevant about.xml
and then a TSS:
There's a little repetition here which can be solved in two ways.
1) Put the layout rules in their own file, e.g. base.tss:
And then import it in about.tss
and home.tss
e.g.
2) Use data to describe the relevant parts externally:
page.tss
This allows a top down approach. Most frameworks work on a bottom up approach where you build the layout, then build the content and put the output of one in the other. This presents a problem: How do you set the title per page? Or perhaps include a different sidebar on each page? Frameworks tend to do this using what are essentially global variables to store the page title and any layout options. TSS builds the entire page in one go, so any page can alter any part of the layout.
Credits
Transphporm was originally developed by Tom Butler ( @TomBZombie ) with additional feature implementation, bugfixes and suggestions by Richard Sollee ( @solleer )