Tag (View Helpers)¶
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 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 template.
NOTE
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 <doctype>
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
The above example will produce:
The default value is HTML5
which generates:
You can output the doctype using getDocType()
in your views:
or in Volt:
Title¶
Phalcon\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
.
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
use Phalcon\Tag;
Tag::setTitle('Phalcon');
echo Tag::getTitle(); // 'Phalcon'
Tag::appendTitle(' Framework');
Tag::appendTitle(' Rocks');
echo Tag::getTitle(); // 'Phalcon Framework Rocks'
Tag::appendTitle('Will be replaced');
Tag::appendTitle(
[
' Framework',
' Rocks',
]
);
echo Tag::getTitle(); // 'Phalcon Framework Rocks'
friendlyTitle()
¶
Converts text to URL-friendly strings. It accepts the following parameters: - text
- The text to be processed - parameters
- Array of parameters to generate the friendly title
The parameters can be: - lowercase
- bool
Whether to convert everything to lowercase or not - separator
- string
- The separator. Defaults to -
- replace
- array
- Key value array to replace characters with others. This uses [str_replace][str_replace] internally for this replacement
<?php
use Phalcon\Tag;
echo Tag::friendlyTitle('Phalcon Framework');
// 'Phalcon-Framework';
echo Tag::friendlyTitle(
'Phalcon Framework',
[
'separator' => '_',
'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
use Phalcon\Tag;
Tag::setTitleSeparator(' ');
Tag::prependTitle('Hello');
Tag::setTitle('World');
Tag::appendTitle('from Phalcon');
echo Tag::getTitle(); // 'Hello World from Phalcon';
echo Tag::getTitle(false); // 'World from Phalcon';
echo Tag::getTitle(true, false); // 'Hello World';
echo Tag::getTitle(false, false); // 'World';
getTitleSeparator()
¶
Returns the current title separator. The default value is an empty string.
prependTitle()
¶
Prepends text to the current title. The method accepts either a string
or an array
.
NOTE
If a string
is supplied, it will be added to the internal collection holding the prepend title text. If however you supply an array
the internal collection will be replaced.
<?php
use Phalcon\Tag;
Tag::setTitle('Rocks');
echo Tag::getTitle(); // 'Rocks'
Tag::prependTitle('Phalcon ');
Tag::prependTitle('Framework ');
echo Tag::getTitle(); // 'Phalcon Framework Rocks'
Tag::prependTitle('Will be replaced');
Tag::prependTitle(
[
'Phalcon ',
'Framework ',
]
);
echo Tag::getTitle(); // 'Phalcon Framework Rocks'
renderTitle()
¶
Returns the current title wrapped in <title>
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
use Phalcon\Tag;
Tag::setTitleSeparator(' ');
Tag::prependTitle('Hello');
Tag::setTitle('World');
Tag::appendTitle('from Phalcon');
echo Tag::renderTitle();
// '<title>Hello World from Phalcon</title>';
echo Tag::renderTitle(false);
// '<title>World from Phalcon</title>';
echo Tag::renderTitle(true, false);
// '<title>Hello World</title>';
echo Tag::renderTitle(false, false);
// '<title>World</title>';
setTitle()
¶
Sets the title text.
setTitleSeparator()
¶
Set the separator of the title.
Input¶
checkField()
¶
Builds a HTML input[type='check']
tag. Accepts an array with the attributes of the element. The first element of the array is the name of the element.
<?php
use Phalcon\Tag;
echo Tag::checkField(
[
'terms',
'value' => 'Y',
]
);
// <input type='checkbox' id='terms' name='terms' value='Y' />
HTML syntax:
Volt syntax:
colorField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::colorField(
[
'background',
'class' => 'myclass',
]
);
// <input type='color' id='background' name='background' class='myclass' />
HTML syntax:
Volt syntax:
dateField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::dateField(
[
'born',
'value' => '1980-01-01',
]
);
// <input type='date' id='born' name='born' value='1980-01-01' />
HTML syntax:
Volt syntax:
dateTimeField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::dateTimeField(
[
'born',
'value' => '1980-01-01 01:02:03',
]
);
// <input type='datetime' id='born' name='born'
// value='1980-01-01 01:02:03' />
HTML syntax:
Volt syntax:
dateTimeLocalField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::dateTimeLocalField(
[
'born',
'value' => '1980-01-01 01:02:03',
]
);
// <input type='datetime-local' id='born' name='born'
// value='1980-01-01 01:02:03' />
HTML syntax:
Volt syntax:
fileField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::fileField(
[
'document',
'class' => 'input',
]
);
// <input type='file' id='document' name='document' class='input' />
HTML syntax:
Volt syntax:
hiddenField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::hiddenField(
[
'id',
'value' => '1234',
]
);
// <input type='hidden' id='id' name='id' value='1234' />
HTML syntax:
Volt syntax:
imageInput()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::imageInput(
[
'src' => '/img/button.png',
]
);
// <input type='image' src='/img/button.png' />
HTML syntax:
Volt syntax:
monthField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::monthField(
[
'month',
'value' => '04',
]
);
// <input type='month' id='month' name='month' value='04' />
HTML syntax:
Volt syntax:
numericField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::numericField(
[
'price',
'min' => '1',
'max' => '5',
]
);
// <input type='number' id='price' name='price' min='1' max='5' />
HTML syntax:
Volt syntax:
radioField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::radioField(
[
'gender',
'value' => 'Male',
]
);
// <input type='radio' id='gender' name='gender' value='Male' />
HTML syntax:
Volt syntax:
rangeField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::rangeField(
[
'points',
'min' => '0',
'max' => '10',
]
);
// <input type='range' id='points' name='points' min='0' max='10' />
HTML syntax:
Volt syntax:
searchField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::searchField(
[
'search',
'q' => 'startpage',
]
);
// <input type='search' id='search' name='search' q='startpage' />
HTML syntax:
Volt syntax:
submitButton()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::submitButton(
[
'Save',
]
);
// <input type='submit' value='Save' />
HTML syntax:
Volt syntax:
telField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::telField(
[
'mobile',
'size' => '12',
]
);
// <input type='tel' id='mobile' name='mobile' size='12' />
HTML syntax:
Volt syntax:
passwordField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::textField(
[
'name',
'size' => '30',
]
);
// <input type='text' id='name' name='name' size='30' />
HTML syntax:
Volt syntax:
timeField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::timeField(
[
'start',
'size' => '5',
]
);
// <input type='time' id='start' name='start' size='5' />
HTML syntax:
Volt syntax:
urlField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::urlField(
[
'homepage',
]
);
// <input type='url' id='homepage' name='homepage' />
HTML syntax:
Volt syntax:
weekField()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::weekField(
[
'week',
'size' => '2',
]
);
// <input type='week' id='week' name='week' size='2' />
HTML syntax:
Volt syntax:
Elements¶
image()
¶
Builds a 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
use Phalcon\Tag;
echo Tag::image(
[
'img/hello.gif',
'alt' => 'alternative text',
]
);
// <img alt='alternative text' src='/your-app/img/hello.gif'>
echo Tag::image(
'http://static.mywebsite.com/img/bg.png',
false
);
// <img src='http://static.mywebsite.com/img/bg.png'>
HTML syntax:
<?php echo $this->tag->image(
[
'img/hello.gif',
'alt' => 'alternative text',
]
); ?>
<?php echo $this->tag->image(
'http://static.mywebsite.com/img/bg.png',
false
); ?>
Volt syntax:
{% raw %}{{ image('img/hello.gif', 'alt': 'alternative text') }}
{{ image('http://static.mywebsite.com/img/bg.png', false) }}{% endraw %}
select()
¶
select()
is a helper that allows you to create a <select>
element based on a Phalcon\Mvc\Model
resultset. You will need to have a valid database connection set up in your DI container for this method to produce the correct HTML. 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 - using
- array
- required a two element array defining the key and value fields of the model to populate the select - 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
- Resultset
the resultset from the model operation.
<?php
use MyApp\Constants\Status;
use MyApp\Models\Invoices;
use Phalcon\Tag;
$resultset = Invoices::find(
[
'conditions' => 'inv_status_flag = :status:',
'bind' => [
'status' => Status::UNPAID,
]
]
);
echo Tag::select(
[
'invoiceId',
$resultset,
'using' => [
'inv_id',
'inv_title',
],
'useEmpty' => true,
'emptyText' => 'Choose an Invoice to pay',
'emptyValue' => '0',
]
);
// <select id='invoiceId' name='invoiceId'>
// <option value='0'>Choose an Invoice to pay</option>
// <option value='24'>Chocolates 24oz box</option>
// <option value='77'>Sugar 1 bag</option>
// </select>
HTML syntax:
<?php echo $this->tag->select(
[
'invoiceId',
$resultset,
'using' => [
'inv_id',
'inv_title',
],
'useEmpty' => true,
'emptyText' => 'Choose an Invoice to pay',
'emptyValue' => '0',
]
); ?>
Volt syntax:
{% raw %}{{ select(
[
'invoiceId',
$resultset,
'using' : [
'inv_id',
'inv_title',
],
'useEmpty' : true,
'emptyText' : 'Choose an Invoice to pay',
'emptyValue' : '0',
]
) }}{% endraw %}
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
use MyApp\Constants\Status;
use MyApp\Models\Invoices;
use Phalcon\Tag;
$resultset = [
24 => 'Chocolates 24oz box',
77 => 'Sugar 1 bag',
];
echo Tag::selectStatic(
[
'invoiceId',
$resultset,
'useEmpty' => true,
'emptyText' => 'Choose an Invoice to pay',
'emptyValue' => '0',
]
);
// <select id='invoiceId' name='invoiceId'>
// <option value='0'>Choose an Invoice to pay</option>
// <option value='24'>Chocolates 24oz box</option>
// <option value='77'>Sugar 1 bag</option>
// </select>
HTML syntax:
<?php echo $this->tag->selectStatic(
[
'invoiceId',
$resultset,
'useEmpty' => true,
'emptyText' => 'Choose an Invoice to pay',
'emptyValue' => '0',
]
); ?>
Volt syntax:
{% raw %}{{ select(
[
'invoiceId',
$resultset,
'useEmpty' : true,
'emptyText' : 'Choose an Invoice to pay',
'emptyValue' : '0',
]
) }}{% endraw %}
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 to 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. <tag>
vs. <tag></tag>
) - useEol
- bool
- add a PHP_EOL
at the end of the generated string or not
<?php
use Phalcon\Tag;
echo Tag::tagHtml(
'canvas',
[
'id' => 'canvas1',
'width' => '300',
'class' => 'cnvclass',
],
false,
true,
true
);
echo 'This is my canvas';
echo Tag::tagHtmlClose('canvas');
// <canvas id='canvas1' width='300' class='cnvclass'>
// This is my canvas
// </canvas>
HTML syntax:
<?php
echo $this->tag->tagHtml(
'canvas',
[
'id' => 'canvas1',
'width' => '300',
'class' => 'cnvclass',
],
false,
true,
true
);
echo 'This is my canvas';
echo $this->tag->tagHtmlClose('canvas');
?>
Volt syntax:
{% raw %}
{{ tag_html('canvas', ['id': 'canvas1', width': '300', 'class': 'cnvclass'], false, true, true) }}
This is my canvas
{{ tag_html_close('canvas') }}
{% endraw %}
Assets¶
Phalcon\Tag offers helper methods to generate stylesheet and javascript HTML tags.
stylesheetLink()
¶
The first parameter a string
or an array
is the parameters 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
use Phalcon\Tag;
echo Tag::stylesheetLink('css/style.css');
// <link rel='stylesheet' href='/css/style.css'>
echo Tag::stylesheetLink(
'https://fonts.googleapis.com/css?family=Rosario',
false
);
// <link rel='stylesheet'
// href='https://fonts.googleapis.com/css?family=Rosario'
// type='text/css'>
echo Tag::stylesheetLink(
[
'href' => 'https://fonts.googleapis.com/css?family=Rosario',
'class' => 'some-class',
],
false
);
// <link rel='stylesheet'
// href='https://fonts.googleapis.com/css?family=Rosario'
// type='text/css'>
HTML syntax
<?php echo $this->tag->stylesheetLink('css/style.css'); ?>
<?php
echo $this->tag->stylesheetLink(
'https://fonts.googleapis.com/css?family=Rosario',
false
); ?>
<?php
echo $this->tag->stylesheetLink(
[
'href' => 'https://fonts.googleapis.com/css?family=Rosario',
'class' => 'some-class',
],
false
); ?>
Volt Syntax:
{% raw %}{{ 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
)
}}{% endraw %}
javascriptInclude()
¶
The first parameter a string
or an array
is the parameters 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
use Phalcon\Tag;
echo Tag::javascriptInclude('js/jquery.js');
// <script src='/js/jquery.js' type='text/javascript'></script>
echo Tag::javascriptInclude(
'https://code.jquery.com/jquery/jquery.min.js',
false
);
// <script src='https://code.jquery.com/jquery/jquery.min.js'
// type='text/javascript'></script>
echo Tag::javascriptInclude(
[
'src' => 'https://code.jquery.com/jquery/jquery.min.js',
'type' => 'application/javascript',
],
false
);
// <script src='https://code.jquery.com/jquery/jquery.min.js'
// type='application/javascript'></script>
HTML syntax
<?php echo $this->tag->javascriptInclude('js/jquery.js'); ?>
<?php
echo $this->tag->javascriptInclude(
'https://fonts.googleapis.com/css?family=Rosario',
false
); ?>
<?php
echo $this->tag->javascriptInclude(
[
'src' => 'https://code.jquery.com/jquery/jquery.min.js',
'type' => 'application/javascript',
],
false
); ?>
Volt Syntax:
{% raw %}{{ 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
)
}}{% endraw %}
Links¶
A common task in any web application is to show links that help with the navigation from one area to another. Phalcon\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
use Phalcon\Tag;
echo Tag::linkTo('signup/register', 'Register Here!');
// <a href='/signup/register'>Register Here!</a>
echo Tag::linkTo(
[
'signup/register',
'Register Here!',
'class' => 'btn-primary',
]
);
// <a href='/signup/register' class='btn-primary'>Register Here!</a>
echo Tag::linkTo('https://phalcon.io/', 'Phalcon', false);
// <a href='https://phalcon.io/'>Phalcon</a>
echo Tag::linkTo(
[
'https://phalcon.io/',
'Phalcon Home',
false,
]
);
// <a href='https://phalcon.io/'>Phalcon Home</a>
HTML syntax:
<?php
echo $this->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:
{% raw %}
{{ 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
) }}{% endraw %}
If you have named routes, you can use the for
keyword in your parameter array to reference it. Phalcon\Tag will resolve the route internally and produce the correct URL using Phalcon\Url.
<?php
use Phalcon\Tag;
echo Tag::linkTo(
[
[
'for' => 'invoice-view',
'title' => 12345,
'name' => 'invoice-12345'
],
'Show Invoice'
]
);
HTML syntax:
<?php
echo $this->tag->linkTo(
[
[
'for' => 'invoice-view',
'title' => 12345,
'name' => 'invoice-12345'
],
'Show Invoice'
]
);
?>
Volt syntax:
{% raw %}
{{ link_to('signup/register', 'Register Here!') }}
{{ link_to(
[
'for' : 'invoice-view',
'title' : 12345,
'name' : 'invoice-12345'
],
'Show Invoice',
'class': 'edit-btn'
) }}{% endraw %}
Forms¶
Forms play an important role in any web application, since they are used to collect input from the user. Phalcon\Tag offers the form()
and endForm()
methods, which create <form>
elements.
<?php
use Phalcon\Tag;
echo Tag::form(
[
'/admin/invoices/create',
'method' => 'post',
'class' => 'input'
]
);
// <form action='admin/invoices/create' method='post' class='input'>
// ...
echo Tag::endForm();
// </form>
HTML syntax:
<?php
echo $this->tag->form(
[
'/admin/invoices/create',
'method' => 'post',
'class' => 'input'
]
);
// ...
echo $this->tag->endForm();
?>
Volt syntax:
{% raw %}
{{ form(
[
'/admin/invoices/create',
'method' : 'post',
'class' : 'input'
]
);
{{ end_form() }}{% endraw %}
Phalcon also provides a form builder to create forms in an object-oriented manner.
Data¶
setDefault()
¶
You can use setDefault()
to pre populate values for elements generated by Phalcon\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
use Phalcon\Tag;
Tag::setDefault('framework', 'Phalcon');
echo Tag::textField(
[
'framework',
'class' => 'input'
]
);
// <input type='text' id='framework' name='framework'
// value='Phalcon' class='class' />
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
use Phalcon\Tag;
Tag::setDefaults(
[
'framework' => 'Phalcon',
'version' => '4.0',
]
);
echo Tag::textField(
[
'framework',
'class' => 'input'
]
);
// <input type='text' id='framework' name='framework'
// value='Phalcon' class='class' />
echo Tag::textField(
[
'version',
'class' => 'input'
]
);
// <input type='text' id='version' name='version'
// value='4.0' class='class' />
getValue()
¶
This method is called from every helper in this component, to find whether a value has been set for an element wither by having used setDefault()
before or in the $_POST
superglobal.
<?php
use Phalcon\Tag;
Tag::setDefaults(
[
'framework' => '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
use Phalcon\Tag;
Tag::setDefaults(
[
'framework' => 'Phalcon',
'version' => '4.0',
]
);
echo Tag::hasValue('framework'); // 'true'
$_POST = [
'framework' => 'Phalcon',
'version' => '4.0',
];
echo Tag::hasValue('framework'); // 'true'
Escaping¶
Phalcon\Tag automatically escapes text supplied for its helpers. If your application requires it, you can disable automatic escaping by using setAutoEscape()
.
<?php
use Phalcon\Tag;
echo Tag::textField(
[
'framework',
'value' => '<h1>hello</h1>',
]
);
// <input type="text" id="framework" name="framework"
// value="<h1>hello</h1>" />
Tag::setAutoescape(false);
echo Tag::textField(
[
'framework',
'value' => '<h1>hello</h1>',
]
);
// <input type="text" id="framework" name="framework"
// value="<h1>hello</h1>" />
Dependency Injection¶
If you use the Phalcon\Di\FactoryDefault container, the Phalcon\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
use Phalcon\Di;
use Phalcon\Tag;
$container = new Di();
$container->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 is as simple as accessing the tag
property.
<?php
use Phalcon\Mvc\Controller;
use Phalcon\Tag;
/**
* @property Tag $tag
*/
class SessionController extends Controller
{
public function indexAction()
{
$this->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 that 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 yourcustomhelpers
directory. - Extend the Phalcon\Tag class and implement your own methods.
<?php
namespace MyApp;
use Phalcon\Tag;
class MyTags extends Tag
{
/**
* Generates a widget to show a HTML5 audio tag
*
* @param array
* @return string
*/
public static function audioField($parameters)
{
// Converting parameters to array if it is not
if (true !== is_array($parameters)) {
$parameters = [$parameters];
}
// Determining attributes 'id' and 'name'
$parameters[0] = $parameters[0] ?? $parameters['id'];
$id = $parameters[0];
$parameters['name'] = $parameters['name'] ?? $id;
// Determining widget value,
// \Phalcon\Tag::setDefault() allows to set the widget value
if (true === isset($parameters['value'])) {
$value = $parameters['value'];
unset($parameters['value']);
} else {
$value = self::getValue($id);
}
// Generate the tag code
$code = sprintf(
'<audio id="%s" value="%s" ',
$id,
$value
);
foreach ($parameters as $key => $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
use Phalcon\Loader;
use Phalcon\Mvc\Application;
use Phalcon\Di\FactoryDefault();
use Phalcon\Exception as PhalconException;
try {
$loader = new Loader();
$loader->registerDirs(
[
'../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
echo MyTags::audioField(
[
'name' => 'test',
'id' => 'audio_test',
'src' => '/path/to/audio.mp3',
]
);
?>
You can also check out Volt a faster template engine for PHP, where you can use a more developer friendly syntax for helpers provided by Phalcon\Tag.