en:public:developer:template_system:start
Differences
This shows you the differences between two versions of the page.
|
en:public:developer:template_system:start [2012/11/18 16:12] admin |
en:public:developer:template_system:start [2012/11/20 11:38] (current) admin |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Template system ====== | + | ======= Template system ======= |
| - | This document explains the language syntax of the Arkadia template system. Arkadia’s template language is | + | ArKadia template system is a template engine for PHP, facilitating the separation of presentation (HTML/CSS) |
| - | designed to strike a balance between power and ease. It’s designed to feel comfortable to those used | + | from application logic. This implies that PHP code is application logic, and is separated from the presentation. |
| - | to working with HTML. If you have any exposure to other text-based template languages, such as Smarty | + | |
| - | or CheetahTemplate, you should feel right at home with ArKadia’s templates | + | |
| ===== Philosophy ===== | ===== Philosophy ===== | ||
| - | If you have a background in programming, or if you’re used to languages like PHP which mix programming | + | The ArKadia template system design was largely driven by these goals: |
| - | code directly into HTML, you’ll want to bear in mind that the ArKadia template system is not simply PHP | + | - clean separation of presentation from application code |
| - | embedded into HTML. This is by design: the template system is meant to express presentation, not program logic. | + | - PHP backend, ArKadia template frontend |
| - | + | - compliment PHP, not replace it | |
| - | The Arkadia template system provides tags which function similarly to some programming constructs – an if | + | - fast development/deployment for programmers and designers |
| - | tag for boolean tests, a for tag for looping, etc. – but these are not simply executed as the corresponding | + | - quick and easy to maintain |
| - | PHP code, and the template system will not execute arbitrary PHP expressions. Only the tags, filters and | + | - syntax easy to understand, no PHP knowledge required |
| - | syntax listed below are supported by default (although you can add your own extensions to the template | + | - flexibility for custom development |
| - | language as needed). | + | - security: insulation from PHP |
| - | ===== Templates ===== | ||
| - | template is simply a text file. It can generate any text-based format (HTML, XML, CSV, etc.). | + | ===== Templates: Two camps of thought ===== |
| - | A template contains variables, which get replaced with values when the template is evaluated, | + | |
| - | and tags, which control the logic of the template. | + | |
| - | Below is a minimal template that illustrates a few basics. Each element will be explained | + | |
| - | later in this document.: | + | |
| - | <code html> | + | When it comes to templating in PHP, there are basically two camps of thought. The first camp exclaims |
| - | <#doctype> | + | that "PHP is a template engine". This approach simply mixes PHP code with HTML. Although this approach |
| - | <html> | + | is fast from a pure script-execution point-of-view, many would argue that the PHP syntax is messy and |
| - | <head> | + | difficult to maintain when mixed with presentation. PHP works well for programming, but not so well |
| - | <#meta_title> | + | for templating. |
| - | <#meta_description> | + | |
| - | </head> | + | The second camp exclaims that presentation should be void of all programming code, and instead use |
| - | <body> | + | simple tags to indicate where application content is revealed. This approach is common with other |
| - | <#frame name="topframe"> | + | template engines (and other programming languages), and is the approach that ArKadia takes. The idea |
| - | </body> | + | is to keep the templates focused squarely on presentation, void of application code, and with as |
| - | </html> | + | little overhead as possible. |
| - | </code> | + | |
| - | + | ===== Why is separating PHP from templates important? ===== | |
| - | Why use a text-based template instead of an XML-based one (like Zope's TAL)? We wanted ArKadia's template | + | |
| - | language to be usable for more than just XML/HTML templates. We use it for emails, JavaScript and CSV. | + | |
| - | You can use the template language for any text-based format. | + | |
| - | + | ||
| - | + | ||
| - | ===== Basic Syntax ===== | + | |
| - | + | ||
| - | + | ||
| - | All Arkadia template tags are started within **<#** and closed within **>**. Most of tags doesn't have closing tag. | + | |
| - | + | ||
| - | Example: | + | |
| - | <code html> | + | |
| - | <#current_language> | + | |
| - | </code> | + | |
| - | + | ||
| - | Also some template tags has parameters. Parameters added to tags on the same way like in HTML. | + | |
| - | + | ||
| - | Example: | + | |
| - | <code html> | + | |
| - | <#frame name="rightframe"> | + | |
| - | </code> | + | |
| - | + | ||
| - | + | ||
| - | ==== AnalyzeTagParams ==== | + | |
| - | + | ||
| - | **AnalyzeTagParams** is a parameter can be added to any arkadia template tag to process sub arkadia template tags in this tag. Value can be 1 and 0 (0 by default not process). | + | |
| - | + | ||
| - | example: | + | |
| - | + | ||
| - | <code html> | + | |
| - | <#if condition='<#current_url> = /usa/' AnalyzeTagParams="1"> | + | |
| - | <span><#current_url></span> | + | |
| - | <#endif> | + | |
| - | </code> | + | |
| - | + | ||
| - | ===== Statements Syntax ===== | + | |
| - | + | ||
| - | The statement syntax is easy. | + | |
| - | + | ||
| - | ==== If statement ==== | + | |
| - | **if** statement started within **<#if>** has one parameter **condition** and ended within **<#endif>**. | + | There are many benefits of separating PHP code from templates, some of which are: |
| - | There are two additional tags to represent else and else if statements, **<#else>** and **<#elseif>**. | + | * **SYNTAX**: Templates typically consist of semantic markup such as HTML. PHP syntax works well for application code, but quickly degenerates when mixed with HTML. ArKadia's simple **<#tag>** syntax is designed specifically to express presentation. ArKadia focuses your templates on presentation and less on "code". This lends to quicker template deployment and easier maintenance. ArKadia syntax requires no working knowledge of PHP, and is intuitive for programmers and non-programmers alike. |
| - | **<#elseif>** also has one parameter **condition**. | + | * **FEATURES**: The template engine has many features for presentation that would otherwise need to be developed, tested and maintained in your own application code. Tags also mask the complexity of PHP statements. For example: <html><br /><br /></html><code php><?php echo strtolower(htmlspecialchars($title,ENT_QUOTES,UTF-8)); ?></code><code><#title lowercase=1 htmlencode=1></code>No different than PHP being an abstraction layer on top of C to simplify development, ArKadia is an abstraction layer on PHP to simplify template maintenance. |
| - | The result of **condition** value must be Boolean. | + | * **SANDBOXING**: When PHP is mixed with templates, there are no restrictions on what type of logic can be injected into a template. ArKadia insulates the templates from PHP, creating a controlled separation of presentation from business logic. ArKadia also has security features that can further enforce granular restrictions on templates. |
| - | Example: | + | For a syntax comparison of PHP vs ArKadia, see [[Syntax Comparison]]. |
| - | <code html> | + | |
| - | <#if condintion="a > b"> | ||
| - | <span>A is more than B</span> | ||
| - | <#elseif condition="a < c"> | ||
| - | <span>A is less than C</span> | ||
| - | <#else> | ||
| - | <span>A is less than B but more than C</span> | ||
| - | <#endif> | ||
| - | </code> | + | ===== Web designers and PHP ===== |
| + | A common question: "Web designers have to learn a syntax anyways, why not PHP?" Of course web designers | ||
| + | can learn PHP, and they may already be familiar with it. The issue isn't their ability to learn PHP, it | ||
| + | is about the maintenance of PHP mixed with HTML. **<#tags>** are simpler, more intuitive, and less fragile | ||
| + | than PHP statements. Templates also restrict what can be put in a template. PHP makes it too easy to add | ||
| + | code into templates that doesn't belong there. You could teach designers the rules of application design, | ||
| + | but this is should be unnecessary (now they are developers!) The PHP manual is intended for developers. | ||
| + | Designers would only need a small fraction of this manual, and it doesn't make it easier for them to find | ||
| + | what they need. ArKadia gives web designers exactly the tools they need, and gives developers fine-grained | ||
| + | control over these tools. | ||
| - | ==== Caseof statement ==== | + | ===== Implementation is Important ===== |
| - | The **<#caseof>** statement is similar to a series of IF statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. | + | Although ArKadia gives you the tools to make a clean separation of presentation from application code, |
| + | it also gives you plenty of room to bend those rules. A poor implementation (i.e. injecting PHP in | ||
| + | templates) will cause more problems than the presentation separation was meant to resolve. The | ||
| + | documentation does a good job of indicating what things to watch out for. Also see the [[Best | ||
| + | Practices]] section. | ||
| - | <code html> | + | ===== What does ArKadia look like, and how do I use it? ===== |
| - | <#caseof expression="<#random range='5'>" | + | |
| - | statement_0="<span>0</span>" | + | |
| - | statement_1="<span>1</span>" | + | |
| - | statement_2="<span>2</span>" | + | |
| - | statement_3="<span>3</span>" | + | |
| - | statement_4="<span>4</span>" | + | |
| - | AnalyzeTagParams="1"> | + | |
| - | </code> | + | |
| - | ==== <#casecurrentlanguage> ==== | + | The [[Crash Course]] section gives a good overview how ArKadia is typically implemented in a PHP application. |
| - | It is a quick variant of **<#caseof>** statement based on current language of page. | + | ===== How does it work? ===== |
| - | Example: | + | Under the hood, ArKadia compiles copies of the templates as PHP scripts. This way you get the benefits |
| + | of both template tag syntax and the speed of PHP. Compilation happens once when each template is | ||
| + | first invoked, and then the compiled versions are used from that point forward. ArKadia takes care | ||
| + | of this for you, so the template designer just edits the ArKadia templates and never has to manage | ||
| + | the compiled versions. This approach keeps the templates easy to maintain, and yet keeps execution | ||
| + | times extremely fast. Since the compiled versions are PHP, op-code accelerators such as APC or | ||
| + | ZendCache continue to work on the compiled scripts. | ||
| - | <code html> | + | ===== Why not use XML/XSLT syntax? ===== |
| - | <#casecurrentlanguage FRA="I'm on French version of site" | + | |
| - | RUS="I'm on Russian version of site" | + | |
| - | default="I'm on English version of site"> | + | |
| - | </code> | + | |
| + | There are a couple of good reasons. First, ArKadia can be used for more than just XML/HTML based | ||
| + | templates, such as generating emails, javascript, CSV, and PDF documents. Second, XML/XSLT syntax | ||
| + | is even more verbose and fragile than PHP code! It is perfect for computers, but horrible for humans. | ||
| + | ArKadia is about being easy to read, understand and maintain. | ||
en/public/developer/template_system/start.1353240768.txt.gz · Last modified: 2012/11/18 16:12 by admin
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
