视图助手（View Helpers） · Phalcon中文文档2.0.6

# 视图助手（View Helpers） # 视图助手（View Helpers） Writing and maintaining HTML markup can quickly become a tedious task because of the naming conventions and numerous attributes that have tobe taken into consideration. Phalcon deals with this complexity by offering [*Phalcon\\Tag*](#), which in turn offersview helpers to generate HTML markup. This component can be used in a plain HTML+PHP view or in a [*Volt*](#) template. > This guide is not intended to be a complete documentation of available helpers and their arguments. Please visitthe [*Phalcon\\Tag*](#) page in the API for a complete reference. ### 文档类型（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: ConstantDocument typeHTML32HTML 3.2HTML401\_STRICTHTML 4.01 StrictHTML401\_TRANSITIONALHTML 4.01 TransitionalHTML401\_FRAMESETHTML 4.01 FramesetHTML5HTML 5XHTML10\_STRICTXHTML 1.0 StrictXHTML10\_TRANSITIONALXHTML 1.0 TransitionalXHTML10\_FRAMESETXHTML 1.0 FramesetXHTML11XHTML 1.1XHTML20XHTML 2.0XHTML5XHTML 5Setting document type. ``` <pre class="calibre14">``` <?php use Phalcon\Tag; $this->tag->setDoctype(Tag::HTML401_STRICT); ?> ``` ``` Getting document type. ``` <pre class="calibre14">``` <?= $this->tag->getDoctype() ?> <html>  </html> ``` ``` The following HTML will be produced. ``` <pre class="calibre14">``` <html>  </html> ``` ``` Volt syntax: ``` <pre class="calibre14">``` {{ get_doctype() }} <html>  </html> ``` ``` ### 生成链接（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: ``` <pre class="calibre14">```  <?= $this->tag->linkTo("products/search", "Search") ?>  <?= $this->tag->linkTo(array('products/edit/10', 'Edit', 'class' => 'edit-btn')) ?>  <?= $this->tag->linkTo(array(array('for' => 'show-product', 'title' => 123, 'name' => 'carrots'), 'Show')) ?> ``` ``` Actually, all produced URLs are generated by the component [*Phalcon\\Mvc\\Url*](#) (or service “url” failing) Same links generated with Volt: ``` <pre class="calibre14">```  {{ link_to("products/search", "Search") }}  {{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show') }}  {{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show', 'class': 'edit-btn') }} ``` ``` ### 创建表单（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: ``` <pre class="calibre14">```  <?= $this->tag->form("products/search") ?> <label for="q">Search:</label> <?= $this->tag->textField("q") ?> <?= $this->tag->submitButton("Search") ?> <?= $this->tag->endForm() ?>  <?= $this->tag->form(array("products/search", "method" => "get")); ?> <label for="q">Search:</label> <?= $this->tag->textField("q"); ?> <?= $this->tag->submitButton("Search"); ?> <?= $this->tag->endForm() ?> ``` ``` This last code will generate the following HTML: ``` <pre class="calibre14">``` <form action="/store/products/search/" method="get"> <label for="q">Search:</label> <input type="text" id="q" value="" name="q" /> <input type="submit" value="Search" /> </form> ``` ``` Same form generated in Volt: ``` <pre class="calibre14">```  {{ form("products/search", "method": "get") }} <label for="q">Search:</label> {{ text_field("q") }} {{ submit_button("Search") }} {{ endForm() }} ``` ``` Phalcon also provides a [*form builder*](#) to create forms in an object-oriented manner. ### 使用助手生成表单控件（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). ``` <pre class="calibre14">``` <?php echo $this->tag->textField("username") ?> <?php echo $this->tag->textArea(array( "comment", "This is the content of the text-area", "cols" => "6", "rows" => 20 )) ?> <?php echo $this->tag->passwordField(array( "password", "size" => 30 )) ?> <?php echo $this->tag->hiddenField(array( "parent_id", "value"=> "5" )) ?> ``` ``` Volt syntax: ``` <pre class="calibre14">``` {{ 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 [*Phalcon\\Mvc\\Model*](#), while Phalcon\\Tag::selectStatic() can with PHP arrays. ``` <pre class="calibre14">``` <?php // Using data from a resultset echo $this->tag->select( array( "productId", Products::find("type = 'vegetables'"), "using" => array("id", "name") ) ); // Using data from an array echo $this->tag->selectStatic( array( "status", array( "A" => "Active", "I" => "Inactive", ) ) ); ``` ``` The following HTML will generated: ``` <pre class="calibre14">``` <select id="productId" name="productId"> <option value="101">Tomato</option> <option value="102">Lettuce</option> <option value="103">Beans</option> </select> <select id="status" name="status"> <option value="A">Active</option> <option value="I">Inactive</option> </select> ``` ``` You can add an “empty” option to the generated HTML: ``` <pre class="calibre14">``` <?php // Creating a Select Tag with an empty option echo $this->tag->select( array( "productId", Products::find("type = 'vegetables'"), "using" => array("id", "name"), "useEmpty" => true ) ); ``` ``` Produces this HTML: ``` <pre class="calibre14">``` <select id="productId" name="productId"> <option value="">Choose..</option> <option value="101">Tomato</option> <option value="102">Lettuce</option> <option value="103">Beans</option> </select> ``` ``` ``` <pre class="calibre14">``` <?php // Creating a Select Tag with an empty option with default text echo $this->tag->select( array( 'productId', Products::find("type = 'vegetables'"), 'using' => array('id', "name"), 'useEmpty' => true, 'emptyText' => 'Please, choose one...', 'emptyValue' => '@' ) ); ``` ``` ``` <pre class="calibre14">``` <select id="productId" name="productId"> <option value="@">Please, choose one..</option> <option value="101">Tomato</option> <option value="102">Lettuce</option> <option value="103">Beans</option> </select> ``` ``` Volt syntax for above example: ``` <pre class="calibre14">``` {# Creating a Select Tag with an empty option with default text #} {{ select('productId', products, 'using': ['id', 'name'], 'useEmpty': true, 'emptyText': 'Please, choose one...', 'emptyValue': '@') }} ``` ``` ### 设置 HTML 属性（Assigning HTML attributes） All the helpers accept an array as their first parameter which can contain additional HTML attributes for the element generated. ``` <pre class="calibre14">``` <?php $this->tag->textField( array( "price", "size" => 20, "maxlength" => 30, "placeholder" => "Enter a price" ) ) ?> ``` ``` or using Volt: ``` <pre class="calibre14">``` {{ text_field("price", "size": 20, "maxlength": 30, "placeholder": "Enter a price") }} ``` ``` The following HTML is generated: ``` <pre class="calibre14">``` <input type="text" name="price" id="price" size="20" maxlength="30" placeholder="Enter a price" /> ``` ``` ### 设置助手的值（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 hasa name that matches the preloaded value, it will use it, unless a value is directly assigned on the helper in the view. ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Controller; class ProductsController extends Controller { public function indexAction() { $this->tag->setDefault("color", "Blue"); } } ``` ``` At the view, a selectStatic helper matches the same index used to preset the value. In this case “color”: ``` <pre class="calibre14">``` <?php echo $this->tag->selectStatic( array( "color", array( "Yellow" => "Yellow", "Blue" => "Blue", "Red" => "Red" ) ) ); ``` ``` This will generate the following select tag with the value “Blue” selected: ``` <pre class="calibre14">``` <select id="color" name="color"> <option value="Yellow">Yellow</option> <option value="Blue" selected="selected">Blue</option> <option value="Red">Red</option> </select> ``` ``` ### 通过请求（From the Request） A special feature that the [*Phalcon\\Tag*](#) helpers have is that they keep the valuesof 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） [*Phalcon\\Tag*](#) offers helpers to change dynamically the document title from the controller.The following example demonstrates just that: ``` <pre class="calibre14">``` <?php use Phalcon\Mvc\Controller; class PostsController extends Controller { public function initialize() { $this->tag->setTitle("Your Website"); } public function indexAction() { $this->tag->prependTitle("Index of Posts - "); } } ``` ``` ``` <pre class="calibre14">``` <html> <head> <?php echo $this->tag->getTitle(); ?> </head> <body> </body> </html> ``` ``` The following HTML will generated: ``` <pre class="calibre14">``` <html> <head> <title>Index of Posts - Your Website</title> </head> <body> </body> </html> ``` ``` ### 静态内容助手（Static Content Helpers） [*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） ``` <pre class="calibre14">``` <?php // Generate <img src="/your-app/img/hello.gif"> echo $this->tag->image("img/hello.gif"); // Generate <img alt="alternative text" src="/your-app/img/hello.gif"> echo $this->tag->image( array( "img/hello.gif", "alt" => "alternative text" ) ); ``` ``` Volt syntax: ``` <pre class="calibre14">``` {# Generate <img src="/your-app/img/hello.gif"> #} {{ image("img/hello.gif") }} {# Generate <img alt="alternative text" src="/your-app/img/hello.gif"> #} {{ image("img/hello.gif", "alt": "alternative text") }} ``` ``` ### 样式表（Stylesheets） ``` <pre class="calibre14">``` <?php // Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css"> echo $this->tag->stylesheetLink("http://fonts.googleapis.com/css?family=Rosario", false); // Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css"> echo $this->tag->stylesheetLink("css/styles.css"); ``` ``` Volt syntax: ``` <pre class="calibre14">``` {# Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css"> #} {{ stylesheet_link("http://fonts.googleapis.com/css?family=Rosario", false) }} {# Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css"> #} {{ stylesheet_link("css/styles.css") }} ``` ``` ### 脚本（Javascript） ``` <pre class="calibre14">``` <?php // Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script> echo $this->tag->javascriptInclude("http://localhost/javascript/jquery.min.js", false); // Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script> echo $this->tag->javascriptInclude("javascript/jquery.min.js"); ``` ``` Volt syntax: ``` <pre class="calibre14">``` {# Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script> #} {{ javascript_include("http://localhost/javascript/jquery.min.js", false) }} {# Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script> #} {{ javascript_include("javascript/jquery.min.js") }} ``` ``` ### HTML5 对象（HTML5 elements - generic HTML helper） 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. ``` <pre class="calibre14">``` <?php // Generate // <canvas id="canvas1" width="300" class="cnvclass"> // This is my canvas // </canvas> echo $this->tag->tagHtml("canvas", array("id" => "canvas1", "width" => "300", "class" => "cnvclass"), false, true, true); echo "This is my canvas"; echo $this->tag->tagHtmlClose("canvas"); ``` ``` Volt syntax: ``` <pre class="calibre14">``` {# Generate <canvas id="canvas1" width="300" class="cnvclass"> This is my canvas </canvas> #} {{ tag_html("canvas", ["id": "canvas1", width": "300", "class": "cnvclass"], false, true, true) }} This is my canvas {{ tag_html_close("canvas") }} ``` ``` ### 标签服务（Tag Service） [*Phalcon\\Tag*](#) is available via the ‘tag' service, this means you can access it from any partof the application where the services container is located: ``` <pre class="calibre14">``` <?php echo $this->tag->linkTo('pages/about', 'About') ?> ``` ``` You can easily add new helpers to a custom component replacing the service ‘tag' in the services container: ``` <pre class="calibre14">``` <?php use Phalcon\Tag; class MyTags extends Tag { // ... // Create a new helper static public function myAmazingHelper($parameters) { // ... } // Override an existing method static public function textField($parameters) { // ... } } ``` ``` Then change the definition of the service ‘tag': ``` <pre class="calibre14">``` <?php $di['tag'] = function () { return new MyTags(); }; ``` ``` ### 创建助手（Creating your own helpers） You can easily create your own helpers. First, start by creating a new folder within the same directory as your controllers and models. Give it a title that is relative to what you are creating. For our example here, we can call it “customhelpers”. Next we will create a new file titled `MyTags.php` within this new directory. At this point, we have a structure that looks similar to : `/app/customhelpers/MyTags.php`. In `MyTags.php`, we will extend the [*Phalcon\\Tag*](#) and implement your own helper. Below is a simple example of a custom helper: ``` <pre class="calibre14">``` <?php use Phalcon\Tag; class MyTags extends Tag { /** * Generates a widget to show a HTML5 audio tag * * @param array * @return string */ static public function audioField($parameters) { // Converting parameters to array if it is not if (!is_array($parameters)) { $parameters = array($parameters); } // Determining attributes "id" and "name" if (!isset($parameters[0])) { $parameters[0] = $parameters["id"]; } $id = $parameters[0]; if (!isset($parameters["name"])) { $parameters["name"] = $id; } else { if (!$parameters["name"]) { $parameters["name"] = $id; } } // Determining widget value, // \Phalcon\Tag::setDefault() allows to set the widget value if (isset($parameters["value"])) { $value = $parameters["value"]; unset($parameters["value"]); } else { $value = self::getValue($id); } // Generate the tag code $code = '<audio id="'.$id.'" value="'.$value.'" '; foreach ($parameters as $key => $attributeValue) { if (!is_integer($key)) { $code.= $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. ``` <pre class="calibre14">``` <?php use Phalcon\Loader; use Phalcon\Mvc\Application; use Phalcon\DI\FactoryDefault(); use Phalcon\Exception as PhalconException; try { $loader = new Loader(); $loader->registerDirs(array( '../app/controllers', '../app/models', '../app/customhelpers' // Add the new helpers folder ))->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); echo $application->handle()->getContent(); } catch (PhalconException $e) { echo "PhalconException: ", $e->getMessage(); } ``` ``` Now you are ready to use your new helper within your views: ``` <pre class="calibre14">``` <body> <?php echo MyTags::audioField( array( 'name' => 'test', 'id' => 'audio_test', 'src' => '/path/to/audio.mp3' ) ); ?> </body> ``` ``` In next chapter, we'll talk about [*Volt*](#) a faster template engine for PHP, where you can use amore friendly syntax for using helpers provided by Phalcon\\Tag. | - [索引](# "总目录") - [下一页](# "资源文件管理（Assets Management）") | - [上一页](# "使用视图（Using Views）") |