Dwoo relies on plugins to provide useful functionality, examples may include: if, else blocks, include functionality, string manipulation and loops. For a full list see the plugins page.
1.2 and bellow requires at least PHP 5.3 to run.
1.2 and belloware not compatible with PHP7.
Installing via Composer (recommended)
Installing from the tarball release
- Download the most recent tarball from the releases page,
- Unpack the tarball,
- Move the files somewhere in your project,
- Go to the next section to know how to use classes.
Dwoo at its simplest
Here is the simplest way to output a Dwoo template.
And a template file could look like that:
Using Template and Data objects
In this example we add the
Dwoo_Data class that serves as a data container, and the
Dwoo_Template_File class that
represents a template file in your application.
Using a Compiler object
If you want to use custom pre-processors or post-processors, you need to instantiate a
Dwoo_Compiler and add the processors to it.
Using Dwoo with loops - Blog example
Let’s assume you are looping over multiple articles of a blog that you want to display, here is what you can do to do it as lightly as possible:
You first have to create an “article.tpl” template file, the name doesn’t matter really it’s up to you, here is what goes in:
You will then use this template to render all the articles.
As already mentioned, the Dwoo runtime parses the template files to generate HTML output. In this section we introduce some common constructs to quickly get you up to speed.
As above in Dwoo simple variables are passed and rendered to HTML using an associated array, as the following example illustrates:
The variables page_title and page_content are passed to the template rendering API like such:
In the above example the $params array is loaded with parameters that are substituted in the Dwoo code snippet.
In Dwoo it is possible to ‘bundle’ your variables up into arrays on the PHP side and address them separately in a Dwoo template using the ‘dot’ operator. This helps reduce the possibility of confusion with one variable with two different purposes being used in different places in your Dwoo template. An example will be used to illustrate this:
In the above code snippet we have two bundles, the first is the auth array that includes the user’s username. The second is the array that contains the page content. This snippet is setup with the following PHP code:
The above two snippets generate roughly the same HTML as the first example using simple variables. You may wonder why using arrays to bundle your parameters has any benefit:
- It prevents naming collisions.
- Allows you to group or encapsulate related blocks of variables.
- You can have different PHP modules generating their own output arrays making your site’s design more modularized.
Dwoo has if/else constructs to allow the coder to add conditional sections to web pages. This can be used for things such as restricting content to authorized users or displaying form components only if certain conditions are met. Dwoo’s conditional statements are quite flexible, however we only cover the basics here.
Sometimes you need to repeat parts of a web page in a systematic manor. In Dwoo this is done using loops. This is best illustrated by an example:
Above is a code snippet from an HTML form. The
type_id is a simple variable (see above). The
variable is an array containing associated arrays. What occurs is that in every iteration of the loop the
loop plugin extracts the values from an array entry with its name and id as
keys and substitutes them into the template. The above snippet (if in a file called
code_snippet.tpl) would be
initialized and setup with the following PHP:
The above Dwoo snippet and PHP code extract will give the following HTML output:
This method can also be used to generate tables of data (by repeating the tr tag). It is up to you.
Breaking your webpage templates into sections
Webpages are usually broken up into sections for easy maintenance and design. An example could be a webpage which has a header, body content, and footer sections. In this case instead of everything being in one file, the page is broken up into components which can be reused for other page templates.
In PHP you can do this by writing functions, that when called output a section of the page. In Dwoo this is accomplished by using the include plugin. An example would be:
Above is a generic page whose title and main body content can be extracted from a database. You may choose to do it this way or to ‘hard code’ your content directly into a function specific template.