View Helpers ============ Writing and maintaining HTML markup can quickly become a tedious task because of the naming conventions and numerous attributes that have to be taken into consideration. Phalcon deals with this complexity by offering :doc:`Phalcon\\Tag <../api/Phalcon_Tag>`, which in turn offers view helpers to generate HTML markup. This component can be used in a plain HTML+PHP view or in a :doc:`Volt ` template. .. highlights:: This guide is not intended to be a complete documentation of available helpers and their arguments. Please visit the :doc:`Phalcon\\Tag <../api/Phalcon_Tag>` page in the API for a complete reference. Using Name Aliasing ------------------- You could use name aliasing to get short names for classes. In this case, a Tag name can be used to alias the :doc:`Phalcon\\Tag <../api/Phalcon_Tag>` class. .. code-block:: php Document Type of Content ------------------------ Phalcon provides Phalcon\\Tag::setDoctype() helper to set document type of the content. Document type setting may affect HTML output produced by other tag helpers. For example, if you set XHTML document type family, helpers that return or output HTML tags will produce self-closing tags to follow valid XHTML standard. Available document type constants in Phalcon\\Tag namespace are: +----------------------+------------------------+ | Constant | Document type | +======================+========================+ | HTML32 | HTML 3.2 | +----------------------+------------------------+ | HTML401_STRICT | HTML 4.01 Strict | +----------------------+------------------------+ | HTML401_TRANSITIONAL | HTML 4.01 Transitional | +----------------------+------------------------+ | HTML401_FRAMESET | HTML 4.01 Frameset | +----------------------+------------------------+ | HTML5 | HTML 5 | +----------------------+------------------------+ | XHTML10_STRICT | XHTML 1.0 Strict | +----------------------+------------------------+ | XHTML10_TRANSITIONAL | XHTML 1.0 Transitional | +----------------------+------------------------+ | XHTML10_FRAMESET | XHTML 1.0 Frameset | +----------------------+------------------------+ | XHTML11 | XHTML 1.1 | +----------------------+------------------------+ | XHTML20 | XHTML 2.0 | +----------------------+------------------------+ | XHTML5 | XHTML 5 | +----------------------+------------------------+ Setting document type. .. code-block:: php Getting document type. .. code-block:: html+php The following HTML will be produced. .. code-block:: html Volt syntax: .. code-block:: html+jinja {{ get_doctype() }} Generating Links ---------------- A real common task in any web application or website is to produce links that allow us to navigate from one page to another. When they are internal URLs we can create them in the following manner: .. code-block:: html+php 'edit-btn')) ?> 'show-product', 'title' => 123, 'name' => 'carrots'), 'Show')) ?> Actually, all produced URLs are generated by the component :doc:`Phalcon\\Mvc\\Url ` (or service "url" failing) Same links generated with Volt: .. code-block:: html+jinja {{ link_to("products/search", "Search") }} {{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show') }} Creating Forms -------------- Forms in web applications play an essential part in retrieving user input. The following example shows how to implement a simple search form using view helpers: .. code-block:: html+php "get")); ?> This last code will generate the following HTML: .. code-block:: html+php
Same form generated in Volt: .. code-block:: html+jinja {{ form("products/search", "method": "get") }} {{ text_field("q") }} {{ submit_button("Search") }}
Helpers to Generate Form Elements --------------------------------- Phalcon provides a series of helpers to generate form elements such as text fields, buttons and more. The first parameter of each helper is always the name of the element to be generated. When the form is submitted, the name will be passed along with the form data. In a controller you can get these values using the same name by using the getPost() and getQuery() methods on the request object ($this->request). .. code-block:: html+php "6", "rows" => 20 )) ?> 30 )) ?> "5" )) ?> Volt syntax: .. code-block:: html+jinja {{ text_field("username") }} {{ text_area("comment", "This is the content", "cols": "6", "rows": 20) }} {{ password_field("password", "size": 30) }} {{ hidden_field("parent_id", "value": "5") }} Making Select Boxes ------------------- Generating select boxes (select box) is easy, especially if the related data is stored in PHP associative arrays. The helpers for select elements are Phalcon\\Tag::select() and Phalcon\\Tag::selectStatic(). Phalcon\\Tag::select() has been was specifically designed to work with :doc:`Phalcon\\Mvc\\Model `, while Phalcon\\Tag::selectStatic() can with PHP arrays. .. code-block:: php array("id", "name") ) ); // Using data from an array echo Phalcon\Tag::selectStatic( array( "status", array( "A" => "Active", "I" => "Inactive", ) ) ); The following HTML will generated: .. code-block:: html You can add an "empty" option to the generated HTML: .. code-block:: php array("id", "name"), "useEmpty" => true ) ); .. code-block:: html .. code-block:: php array('id', "name') 'useEmpty' => true, 'emptyText' => 'Please, choose one...', 'emptyValue' => '@' ), ); .. code-block:: html Volt syntax for above example: .. code-block:: jinja {# Creating a Select Tag with an empty option with default text #} {{ select('productId', products, 'using': ['id', 'name'], 'useEmpty': true, 'emptyText': 'Please, choose one...', 'emptyValue': '@') }} Assigning HTML attributes ------------------------- All the helpers accept an array as their first parameter which can contain additional HTML attributes for the element generated. .. code-block:: html+php 20, "maxlength" => 30, "placeholder" => "Enter a price", ) ) ?> or using Volt: .. code-block:: jinja {{ text_field("price", "size": 20, "maxlength": 30, "placeholder": "Enter a price") }} The following HTML is generated: .. code-block:: html Setting Helper Values --------------------- From Controllers ^^^^^^^^^^^^^^^^ It is a good programming principle for MVC frameworks to set specific values for form elements in the view. You can set those values directly from the controller using Phalcon\\Tag::setDefault(). This helper preloads a value for any helpers present in the view. If any helper in the view has a name that matches the preloaded value, it will use it, unless a value is directly assigned on the helper in the view. .. code-block:: php "Yellow", "Blue" => "Blue", "Red" => "Red" ) ) ); This will generate the following select tag with the value "Blue" selected: .. code-block:: html From the Request ^^^^^^^^^^^^^^^^ A special feature that the :doc:`Phalcon\\Tag <../api/Phalcon_Tag>` helpers have is that they keep the values of form helpers between requests. This way you can easily show validation messages without losing entered data. Specifying values directly ^^^^^^^^^^^^^^^^^^^^^^^^^^ Every form helper supports the parameter "value". With it you can specify a value for the helper directly. When this parameter is present, any preset value using setDefault() or via request will be ignored. Changing dynamically the Document Title --------------------------------------- :doc:`Phalcon\\Tag <../api/Phalcon_Tag>` offers helpers to change dynamically the document title from the controller. The following example demonstrates just that: .. code-block:: php The following HTML will generated: .. code-block:: html+php Index of Posts - Your Website Static Content Helpers ---------------------- :doc:`Phalcon\\Tag <../api/Phalcon_Tag>` also provide helpers to generate tags such as script, link or img. They aid in quick and easy generation of the static resources of your application Images ^^^^^^ .. code-block:: php echo \Phalcon\Tag::image("img/hello.gif"); // Generate alternative text echo \Phalcon\Tag::image( array( "img/hello.gif", "alt" => "alternative text" ) ); Volt syntax: .. code-block:: jinja {# Generate #} {{ image("img/hello.gif") }} {# Generate alternative text #} {{ image("img/hello.gif", "alt": "alternative text") }} Stylesheets ^^^^^^^^^^^ .. code-block:: php echo \Phalcon\Tag::stylesheetLink("http://fonts.googleapis.com/css?family=Rosario", false); // Generate echo \Phalcon\Tag::stylesheetLink("css/styles.css"); Volt syntax: .. code-block:: jinja {# Generate #} {{ stylesheet_link("http://fonts.googleapis.com/css?family=Rosario", false) }} {# Generate #} {{ stylesheet_link("css/styles.css") }} Javascript ^^^^^^^^^^ .. code-block:: php echo \Phalcon\Tag::javascriptInclude("http://localhost/javascript/jquery.min.js", false); // Generate echo \Phalcon\Tag::javascriptInclude("javascript/jquery.min.js"); Volt syntax: .. code-block:: jinja {# Generate #} {{ javascript_include("http://localhost/javascript/jquery.min.js", false) }} {# Generate #} {{ javascript_include("javascript/jquery.min.js") }} Creating your own helpers ------------------------- You can easily create your own helpers by extending the :doc:`Phalcon\\Tag <../api/Phalcon_Tag>` and implementing your own helper. Below is a simple example of a custom helper: .. code-block:: php $attributeValue) { if (!is_integer($key)) { $code.= $key.'="'.$attributeValue.'" '; } } $code.=" />"; return $code; } } In next chapter, we'll talk about :doc:`Volt ` a faster template engine for PHP, where you can use a more friendly syntax for using helpers provided by Phalcon\\Tag.