--- title: "Tag (View Helpers)" version: "5.12" --- > Documentation Index > Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt > Use this file to discover all available pages before exploring further. # Tag (View Helpers) :::danger[DANGER] `Phalcon\Tag` will be removed in a future Phalcon version. The functionality is offered by the [Phalcon\Html\TagFactory][tagfactory] component. ::: ## Overview 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 the [Phalcon\Tag][tag] component which in turn offers view helpers to generate HTML markup. This component can be used in a plain HTML+PHP view or in a [Volt][volt] template. :::warning[WARNING] This offers the same functionality as `Phalcon\Html\TagFactory`. In future versions, this component will be replaced by the `TagFactory` one. The reason for both components is to offer as much time as possible to developers to adapt their code since HTML generation touches a lot of areas of the application, the view in particular. ::: ## DocType You can set the doctype for your page using `setDocType()`. The method accepts one of the available constants, generating the necessary `` HTML. The method returns the `Tag` component and thus the call can be chained. - `HTML32` - `HTML401_STRICT` - `HTML401_TRANSITIONAL` - `HTML401_FRAMESET` - `HTML5` - `XHTML10_STRICT` - `XHTML10_TRANSITIONAL` - `XHTML10_FRAMESET` - `XHTML11` - `XHTML20` - `XHTML5` ```php ``` The default value is `HTML5` which generates: ```html ``` You can output the doctype using `getDocType()` in your views: ```php tag->getDocType(); ?> ``` or in Volt: ```twig {{ get_doctype() }} ``` ## Title [Phalcon\Tag][tag] offers methods to set the tag of the resulting page or HTML sent to the user. There are several methods available: ### `appendTitle()` Appends text to the current title. The method accepts either a `string` or an `array`. :::info[NOTE] If a `string` is supplied, it will be added to the internal collection holding the append title text. If however, you supply an `array` the internal collection will be replaced. ::: ```php '_', 'lowercase' => true, ] ); // 'phalcon_framework echo Tag::friendlyTitle( 'Phalcon Framework', [ 'separator' => '_', 'lowercase' => true, 'replace' => [ 'a' => 'x', 'e' => 'x', 'o' => 'x', ] ] ); // 'phxlcxn_frxmxwxrk ``` ### `getTitle()` Returns the current title. The title is automatically escaped. The method accepts two parameters: - `prepend` - `bool` Whether to output any text set with `prependTitle()` - `append` - `bool` Whether to output any text set with `appendTitle()` Both parameters are `true` by default. ```php ` tags. The title is automatically escaped. The method accepts two parameters: - `prepend` - `bool` Whether to output any text set with `prependTitle()` - `append` - `bool` Whether to output any text set with `appendTitle()` Both parameters are `true` by default. ```php Hello World from Phalcon'; echo Tag::renderTitle(false); // 'World from Phalcon'; echo Tag::renderTitle(true, false); // 'Hello World'; echo Tag::renderTitle(false, false); // 'World'; ``` ### `setTitle()` Sets the title text. ```php 'Y', ] ); // ``` HTML syntax: ```php tag->checkField( [ 'terms', 'value' => 'Y', ] ); ?> ``` Volt syntax: ```twig {{ check_field('terms', 'value': 'Y') }} ``` ### `colorField()` Builds an HTML `input[type='color']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php 'myclass', ] ); // ``` HTML syntax: ```php tag->colorField( [ 'background', 'class' => 'myclass', ] ); ?> ``` Volt syntax: ```twig {{ color_field('background', 'class': 'myclass') }} ``` ### `dateField()` Builds an HTML `input[type='date']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '1980-01-01', ] ); // ``` HTML syntax: ```php tag->dateField( [ 'born', 'value' => '1980-01-01', ] ); ?> ``` Volt syntax: ```twig {{ date_field('born', 'value': '1980-01-01') }} ``` ### `dateTimeField()` Builds an HTML `input[type='datetime']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '1980-01-01 01:02:03', ] ); // ``` HTML syntax: ```php tag->dateTimeField( [ 'born', 'value' => '1980-01-01 01:02:03', ] ); ?> ``` Volt syntax: ```twig {{ date_time_field('born', 'value': '1980-01-01') }} ``` ### `dateTimeLocalField()` Builds an HTML `input[type='datetime-local']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '1980-01-01 01:02:03', ] ); // ``` HTML syntax: ```php tag->dateTimeLocalField( [ 'born', 'value' => '1980-01-01 01:02:03', ] ); ?> ``` Volt syntax: ```twig {{ date_time_local_field('born', 'value': '1980-01-01 01:02:03') }} ``` ### `fileField()` Builds an HTML `input[type='file']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php 'input', ] ); // ``` HTML syntax: ```php tag->fileField( [ 'document', 'class' => 'input', ] ); ?> ``` Volt syntax: ```twig {{ file_field('document', 'class': 'input') }} ``` ### `hiddenField()` Builds an HTML `input[type='hidden']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '1234', ] ); // ``` HTML syntax: ```php tag->hiddenField( [ 'id', 'value' => '1234', ] ); ?> ``` Volt syntax: ```twig {{ hidden_field('id', 'value': '1234') }} ``` ### `imageInput()` Builds an HTML `input[type='image']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '/img/button.png', ] ); // ``` HTML syntax: ```php tag->imageInput( [ 'src' => '/img/button.png', ] ); ?> ``` Volt syntax: ```twig {{ image_input('src': '/img/button.png') }} ``` ### `monthField()` Builds an HTML `input[type='month']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '04', ] ); // ``` HTML syntax: ```php tag->monthField( [ 'month', 'value' => '04', ] ); ?> ``` Volt syntax: ```twig {{ month_field('month', 'value': '04') }} ``` ### `numericField()` Builds an HTML `input[type='number']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '1', 'max' => '5', ] ); // ``` HTML syntax: ```php tag->numericField( [ 'price', 'min' => '1', 'max' => '5', ] ); ?> ``` Volt syntax: ```twig {{ numeric_field('price', 'min': '1', 'max': '5') }} ``` ### `radioField()` Builds an HTML `input[type='radio']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php 'Male', ] ); // ``` HTML syntax: ```php tag->radioField( [ 'gender', 'value' => 'Male', ] ); ?> ``` Volt syntax: ```twig {{ radio_field('gender', 'value': 'Male') }} ``` ### `rangeField()` Builds an HTML `input[type='range']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '0', 'max' => '10', ] ); // ``` HTML syntax: ```php tag->rangeField( [ 'points', 'min' => '0', 'max' => '10', ] ); ?> ``` Volt syntax: ```twig {{ range_field('points', 'min': '0', 'max': '10') }} ``` ### `searchField()` Builds an HTML `input[type='search']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php 'startpage', ] ); // ``` HTML syntax: ```php tag->searchField( [ 'search', 'q' => 'startpage', ] ); ?> ``` Volt syntax: ```twig {{ search_field('search', 'q': 'startsearch') }} ``` ### `submitButton()` Builds an HTML `input[type='submit']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php ``` HTML syntax: ```php tag->submitButton( [ 'Save', ] ); ?> ``` Volt syntax: ```twig {{ submit_button('Save') }} ``` ### `telField()` Builds an HTML `input[type='tel']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '12', ] ); // ``` HTML syntax: ```php tag->telField( [ 'mobile', 'size' => '12', ] ); ?> ``` Volt syntax: ```twig {{ tel_field('mobile', 'size': '12') }} ``` ### `passwordField()` Builds an HTML `input[type='text']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '30', ] ); // ``` HTML syntax: ```php tag->textField( [ 'name', 'size' => '30', ] ); ?> ``` Volt syntax: ```twig {{ text_field('name', 'size': '30') }} ``` ### `timeField()` Builds an HTML `input[type='time']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '5', ] ); // ``` HTML syntax: ```php tag->timeField( [ 'start', 'size' => '5', ] ); ?> ``` Volt syntax: ```twig {{ time_field('start', 'size': '5') }} ``` ### `urlField()` Builds an HTML `input[type='url']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php ``` HTML syntax: ```php tag->urlField( [ 'homepage', ] ); ?> ``` Volt syntax: ```twig {{ url_field('homepage') }} ``` ### `weekField()` Builds an HTML `input[type='week']` tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element. ```php '2', ] ); // ``` HTML syntax: ```php tag->weekField( [ 'week', 'size' => '2', ] ); ?> ``` Volt syntax: ```twig {{ week_field('week', 'size': '2') }} ``` ## Elements ### `image()` Builds an HTML image tag. Accepts an array with the attributes of the element. The first element of the array is the src of the element. The method accepts a second boolean parameter, signifying whether this resource is local or not. ```php 'alternative text', ] ); //

echo Tag::image( 'https://static.mywebsite.com/img/bg.png', false ); //

``` HTML syntax: ```php tag->image( [ 'img/hello.gif', 'alt' => 'alternative text', ] ); ?> tag->image( 'https://static.mywebsite.com/img/bg.png', false ); ?> ``` Volt syntax: ```twig {{ image('img/hello.gif', 'alt': 'alternative text') }} {{ image('https://static.mywebsite.com/img/bg.png', false) }} ``` ### `select()` `select()` is a helper that allows you to create a ` // // // // ``` HTML syntax: ```php tag->select( [ 'invoiceId', $resultset, 'using' => [ 'inv_id', 'inv_title', ], 'useEmpty' => true, 'emptyText' => 'Choose an Invoice to pay', 'emptyValue' => '0', ] ); ?> ``` Volt syntax: ```twig {{ select( [ 'invoiceId', $resultset, 'using' : [ 'inv_id', 'inv_title', ], 'useEmpty' : true, 'emptyText' : 'Choose an Invoice to pay', 'emptyValue' : '0', ] ) }} ``` ### `selectStatic()` This helper is similar to `select()`, but it uses a PHP array as the source. The component requires parameters and data to operate. - `parameters` - `string`/`array`. If a string is passed, it will be the name of the element. If an array is passed, the first element will be the name of the element. There available parameters are: - `id` - `string` - sets the id of the element - `useEmpty` - `bool` - defaults to `false`. If set, it will add an _empty_ option to the select box - `emptyText` - `string` - the text to display for the _empty_ option (i.e. _Choose an option_) - `emptyValue` - `string`/`number` - the value to assign for the _empty_ option - any additional HTML attributes in a key/value format - `data` - `array` the array of data with key as the id and value as the text ```php 'Chocolates 24oz box', 77 => 'Sugar 1 bag', ]; echo Tag::selectStatic( [ 'invoiceId', $resultset, 'useEmpty' => true, 'emptyText' => 'Choose an Invoice to pay', 'emptyValue' => '0', ] ); // ``` HTML syntax: ```php tag->selectStatic( [ 'invoiceId', $resultset, 'useEmpty' => true, 'emptyText' => 'Choose an Invoice to pay', 'emptyValue' => '0', ] ); ?> ``` Volt syntax: ```twig {{ select( [ 'invoiceId', $resultset, 'useEmpty' : true, 'emptyText' : 'Choose an Invoice to pay', 'emptyValue' : '0', ] ) }} ``` ### `tagHtml()` Phalcon offers a generic HTML helper that allows the generation of any kind of HTML element. It is up to the developer to produce a valid HTML element name for the helper. The accompanying `tagHtmlClose()` can be used to _close_ the tag if necessary. The `tagHtml()` accepts the following parameters - `name` - `string` - the name of the element - `attributes` - `array` - any attributes - `selfClose` - `bool` - whether this is a self-closing element or not - `onlyStart` - `bool` - whether to produce only the _opening_ part of the tag (i.e. `` vs. ``) - `useEol` - `bool` - add a `PHP_EOL` at the end of the generated string or not ```php 'canvas1', 'width' => '300', 'class' => 'cnvclass', ], false, true, true ); echo 'This is my canvas'; echo Tag::tagHtmlClose('canvas'); //

``` HTML syntax: ```php tag->tagHtml( 'canvas', [ 'id' => 'canvas1', 'width' => '300', 'class' => 'cnvclass', ], false, true, true ); echo 'This is my canvas'; echo $this->tag->tagHtmlClose('canvas'); ?> ``` Volt syntax: ```twig {{ tag_html('canvas', ['id': 'canvas1', width': '300', 'class': 'cnvclass'], false, true, true) }} This is my canvas {{ tag_html_close('canvas') }} ``` ## Assets [Phalcon\Tag][tag] offers helper methods to generate stylesheet and javascript HTML tags. ### `stylesheetLink()` The first parameter a `string` or an `array` is the parameter necessary to construct the element. The second parameter is a boolean, dictating whether the link is pointing to a local asset or a remote. ```php echo Tag::stylesheetLink( 'https://fonts.googleapis.com/css?family=Rosario', false ); // echo Tag::stylesheetLink( [ 'href' => 'https://fonts.googleapis.com/css?family=Rosario', 'class' => 'some-class', ], false ); // ``` HTML syntax ```php tag->stylesheetLink('css/style.css'); ?> tag->stylesheetLink( 'https://fonts.googleapis.com/css?family=Rosario', false ); ?> tag->stylesheetLink( [ 'href' => 'https://fonts.googleapis.com/css?family=Rosario', 'class' => 'some-class', ], false ); ?> ``` Volt Syntax: ```php {{ stylesheet_link('css/style.css') }} {{ stylesheet_link( 'https://fonts.googleapis.com/css?family=Rosario', false ) }} {{ stylesheet_link( [ 'href' : 'https://fonts.googleapis.com/css?family=Rosario', 'class' : 'some-class', ], false ) }} ``` ### `javascriptInclude()` The first parameter a `string` or an `array` is the parameter necessary to construct the element. The second parameter is a boolean, dictating whether the link is pointing to a local asset or a remote. ```php echo Tag::javascriptInclude( 'https://code.jquery.com/jquery/jquery.min.js', false ); // echo Tag::javascriptInclude( [ 'src' => 'https://code.jquery.com/jquery/jquery.min.js', 'type' => 'application/javascript', ], false ); // ``` HTML syntax ```php tag->javascriptInclude('js/jquery.js'); ?> tag->javascriptInclude( 'https://fonts.googleapis.com/css?family=Rosario', false ); ?> tag->javascriptInclude( [ 'src' => 'https://code.jquery.com/jquery/jquery.min.js', 'type' => 'application/javascript', ], false ); ?> ``` Volt Syntax: ```php {{ javascript_include('js/jquery.js') }} {{ javascript_include( 'https://code.jquery.com/jquery/jquery.min.js', false ) }} {{ javascript_include( [ 'src' : 'https://code.jquery.com/jquery/jquery.min.js', 'type' : 'application/javascript', ], false ) }} ``` ## Links A common task in any web application is to show links that help with the navigation from one area to another. [Phalcon\Tag][tag] offers `linkTo()` to help with this task. The method accepts three parameters. - `parameters` - `array`/`string` - The attributes and parameters of the element. If a string is passed it will be treated as the target URL for the link. If an array is passed, the following elements can be sent: - `action` - the URL. If the `action` is an array, you can reference a named route defined in your routes using the `for` element - `query` - the base query for the URL - `text` - the text of the link - `local` - whether this is a local or remote link - additional key/value attributes for the link - `text` - `string` - the text of the link - `local` - `bool` - whether this is a local or remote link ```php Register Here! echo Tag::linkTo( [ 'signup/register', 'Register Here!', 'class' => 'btn-primary', ] ); // Register Here! echo Tag::linkTo('https://phalcon.io/', 'Phalcon', false); // Phalcon echo Tag::linkTo( [ 'https://phalcon.io/', 'Phalcon Home', false, ] ); // Phalcon Home ``` HTML syntax: ```php tag->linkTo('signup/register', 'Register Here!'); echo $this->tag->linkTo( [ 'signup/register', 'Register Here!', 'class' => 'btn-primary', ] ); echo $this->tag->linkTo('https://phalcon.io/', 'Phalcon', false); echo $this->tag->linkTo( [ 'https://phalcon.io/', 'Phalcon Home', false, ] ); ?> ``` Volt syntax: ```twig {{ link_to('signup/register', 'Register Here!') }} {{ link_to( 'signup/register', 'Register Here!', 'class': 'btn-primary' ) }} {{ link_to('https://phalcon.io/', 'Phalcon', false) }} {{ link_to( 'https://phalcon.io/', 'Phalcon Home', false ) }} ``` If you have named routes, you can use the `for` keyword in your parameter array to reference it. [Phalcon\Tag][tag] will resolve the route internally and produce the correct URL using [Phalcon\Url][mvc-url]. ```php 'invoice-view', 'title' => 12345, 'name' => 'invoice-12345' ], 'Show Invoice' ] ); ``` HTML syntax: ```php tag->linkTo( [ [ 'for' => 'invoice-view', 'title' => 12345, 'name' => 'invoice-12345' ], 'Show Invoice' ] ); ?> ``` Volt syntax: ```twig {{ link_to('signup/register', 'Register Here!') }} {{ link_to( [ 'for' : 'invoice-view', 'title' : 12345, 'name' : 'invoice-12345' ], 'Show Invoice', 'class': 'edit-btn' ) }} ``` ## Forms Forms play an important role in any web application since they are used to collect input from the user. [Phalcon\Tag][tag] offers the `form()` and `endForm()` methods, which create ` ``` HTML syntax: ```php tag->form( [ '/admin/invoices/create', 'method' => 'post', 'class' => 'input' ] ); // ... echo $this->tag->endForm(); ?> ``` Volt syntax: ```twig {{ form( [ '/admin/invoices/create', 'method' : 'post', 'class' : 'input' ] ); {{ end_form() }} ``` Phalcon also provides a [form builder][forms] to create forms in an object-oriented manner. ## Data ### `setDefault()` You can use `setDefault()` to pre-populate values for elements generated by [Phalcon\Tag][tag]. The helpers of this component will retain the values between requests. This way you can easily show validation messages without losing entered data. Every form helper supports the parameter `value`. With it, you can specify a value for the helper directly. When the parameter is present, any preset value using `setDefault()` or via request will be ignored. ```php 'input' ] ); // ``` ### `setDefaults()` `setDefaults()` allows you to specify more than one value to be set in elements of your form, by passing a key value array. The method can be called more than one time and each time it is called it will overwrite the data set in the previous call. You can however specify the second parameter as `true` so that the values are merged. ```php 'Phalcon', 'version' => '4.0', ] ); echo Tag::textField( [ 'framework', 'class' => 'input' ] ); // echo Tag::textField( [ 'version', 'class' => 'input' ] ); // ``` ### `getValue()` This method is called from every helper in this component, to find whether a value has been set for an element whether by having used `setDefault()` before or in the `$_POST` superglobal. ```php 'Phalcon', 'version' => '4.0', ] ); echo Tag::getValue('framework'); // 'Phalcon' $_POST = [ 'framework' => 'Phalcon', 'version' => '4.0', ]; echo Tag::getValue('framework'); // 'Phalcon' ``` ### `hasValue()` This method checks if a `value` in an element has already been set using `setDefault()` or is in the `$_POST` superglobal. ```php 'Phalcon', 'version' => '4.0', ] ); echo Tag::hasValue('framework'); // 'true' $_POST = [ 'framework' => 'Phalcon', 'version' => '4.0', ]; echo Tag::hasValue('framework'); // 'true' ``` ## Escaping [Phalcon\Tag][tag] automatically escapes text supplied for its helpers. If your application requires it, you can disable automatic escaping by using `setAutoEscape()`. ```php '

hello

', ] ); // Tag::setAutoescape(false); echo Tag::textField( [ 'framework', 'value' => '

hello

', ] ); // ``` ## Dependency Injection If you use the [Phalcon\Di\FactoryDefault][factorydefault] container, the [Phalcon\Tag][tag] is already registered for you with the name `tag`. An example of the registration of the service as well as accessing it is below: **Direct** ```php set( 'tag', function () use { return new Tag(); } ); ``` You can always implement your own `tag` helper and register it in the place of `tag` in the Di container. Accessing the service from any component that implements the [Phalcon\Di\Injectable][injectable] is as simple as accessing the `tag` property. ```php tag->setTitle('Phalcon Framework'); } } ``` ## Custom You can easily extend this functionality and create your own helpers. - First, create a new directory in your application's file system where the helper files will be stored. - Name it something that will represent it. For instance, in this example, we use `customhelpers`. - Create a file called `MyTags.php` in your `customhelpers` directory. - Extend the [Phalcon\Tag][tag] class and implement your own methods. ```php $attributeValue) { if (!is_integer($key)) { $code .= sprintf('%s="%s" ', $key, $attributeValue); } } $code.=' />'; return $code; } } ``` After creating our custom helper, we will autoload the new directory that contains our helper class from our `index.php` located in the public directory. ```php setDirectories( [ '../app/controllers', '../app/models', '../app/customhelpers', // Add the new helpers folder ] ); $loader->register(); $di = new FactoryDefault(); // Assign our new tag a definition, so we can call it $di->set( 'MyTags', function () { return new MyTags(); } ); $application = new Application($di); $response = $application->handle( $_SERVER['REQUEST_URI'] ); $response->send(); } catch (PhalconException $e) { echo 'PhalconException: ', $e->getMessage(); } ``` Now you are ready to use your new helper within your views: ```php 'test', 'id' => 'audio_test', 'src' => '/path/to/audio.mp3', ] ); ?> ``` You can also check out [Volt][volt] a faster template engine for PHP, where you can use a more developer-friendly syntax for helpers provided by [Phalcon\Tag][tag]. [factorydefault]: /5.12/api/phalcon_di/#difactorydefault [injectable]: /5.12/api/phalcon_di/#diinjectable [tag]: /5.12/api/phalcon_tag/ [tagfactory]: /5.12/html-tagfactory/ [volt]: /5.12/volt/ [mvc-url]: /5.12/mvc-url/ [forms]: /5.12/forms/ [str_replace]: https://www.php.net/manual/en/function.str-replace.php Source: https://docs.phalcon.io/5.12/tag/index.mdx