視圖助手（標簽） · Phalcon 3.4中文手冊

[TOC] # 視圖助手（標簽）由于命名約定和必須考慮的眾多屬性，編寫和維護HTML標記很快就會變成一項繁瑣的任務。Phalcon通過提供Phalcon \ Tag組件來處理這種復雜性，而 `Phalcon\Tag` 組件又提供視圖助手來生成HTML標記。此組件可用于純HTML + PHP視圖或`Volt`模板。 >[warning] 本指南并非旨在提供可用幫助程序及其參數的完整文檔。請訪問API中的`Phalcon\Tag`頁面以獲取完整參考。 ## 文檔內容類型 Phalcon提供 `Phalcon\Tag::setDoctype()` 幫助器來設置內容的文檔類型。文檔類型設置可能會影響其他標記幫助程序生成的HTML輸出。例如，如果您設置XHTML文檔類型系列，則返回或輸出HTML標記的幫助程序將生成自動關閉標記以遵循有效的XHTML標準。 `Phalcon\Tag` 命名空間中的可用文檔類型常量是： | 常量 | 文檔類型 | | -------------------- | ---------------------- | | 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 | 設置文檔類型。 ```php <?php use Phalcon\Tag; $this->tag->setDoctype(Tag::HTML401_STRICT); ``` 獲取文檔類型。 ```php <?= $this->tag->getDoctype() ?> <html>  </html> ``` 將生成以下HTML。 ```html <!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01//EN' 'http://www.w3.org/TR/html4/strict.dtd'> <html>  </html> ``` Volt語法： ```twig {{ get_doctype() }} <html>  </html> ``` ## 生成鏈接任何Web應用程序或網站中的一個真正常見任務是生成允許我們從一個頁面導航到另一個頁面的鏈接。當它們是內部URL時，我們可以通過以下方式創建它們： ```php  <?= $this->tag->linkTo('products/search', 'Search') ?>  <?= $this->tag->linkTo(['products/edit/10', 'Edit', 'class' => 'edit-btn']) ?>  <?= $this->tag->linkTo([['for' => 'show-product', 'title' => 123, 'name' => 'carrots'], 'Show']) ?> ``` 實際上，所有生成的URL都是由 `Phalcon\Mvc\Url` 組件生成的。使用Volt可以生成相同的鏈接： ```twig  {{ 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') }} ``` ## 創建表單 Web應用程序中的表單在檢索用戶輸入方面起著至關重要的作用。以下示例顯示如何使用視圖助手實現簡單搜索表單： ```php  <?= $this->tag->form('products/search') ?> <label for='q'>Search:</label> <?= $this->tag->textField('q') ?> <?= $this->tag->submitButton('Search') ?> <?= $this->tag->endForm() ?>  <?= $this->tag->form(['products/search', 'method' => 'get']); ?> <label for='q'>Search:</label> <?= $this->tag->textField('q'); ?> <?= $this->tag->submitButton('Search'); ?> <?= $this->tag->endForm() ?> ``` 最后一個代碼將生成以下HTML： ```html <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> ``` 在Volt中生成相同的表單： ```twig  {{ form('products/search', 'method': 'get') }} <label for='q'>Search:</label> {{ text_field('q') }} {{ submit_button('Search') }} {{ endForm() }} ``` Phalcon還提供了一個表單構建器，以面向對象的方式創建表單。 ## 助手生成表單元素 Phalcon提供了一系列幫助程序來生成表單元素，如文本字段，按鈕等。每個幫助程序的第一個參數始終是要生成的元素的名稱。提交表單時，名稱將與表單數據一起傳遞。在控制器中，您可以使用請求對象上的`getPost()`和`getQuery()`方法（`$this->request`）使用相同的名稱獲取這些值。 ```php <?php echo $this->tag->textField('username') ?> <?php echo $this->tag->textArea( [ 'comment', 'This is the content of the text-area', 'cols' => '6', 'rows' => 20, ] ) ?> <?php echo $this->tag->passwordField( [ 'password', 'size' => 30, ] ) ?> <?php echo $this->tag->hiddenField( [ 'parent_id', 'value' => '5', ] ) ?> ``` Volt語法： ```twig {{ 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') }} ``` ## 制作選擇框生成選擇框（選擇框）很容易，特別是如果相關數據存儲在PHP關聯數組中。選擇元素的助手是`Phalcon\Tag::select()`和`Phalcon\Tag::selectStatic()`。`Phalcon\Tag::select()`一直是專門設計用于Phalcon模型（`Phalcon\Mvc\Model`），而`Phalcon\Tag::selectStatic()`可以用PHP數組。 ```php <?php $products = Products::find("type = 'vegetables'"); // Using data from a resultset echo $this->tag->select( [ 'productId', $products, 'using' => [ 'id', 'name', ] ] ); // Using data from an array echo $this->tag->selectStatic( [ 'status', [ 'A' => 'Active', 'I' => 'Inactive', ] ] ); ``` 將生成以下HTML： ```html <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> ``` 您可以為生成的HTML添加一個`空`選項： ```php <?php $products = Products::find("type = 'vegetables'"); // Creating a Select Tag with an empty option echo $this->tag->select( [ 'productId', $products, 'using' => [ 'id', 'name', ], 'useEmpty' => true, ] ); ``` 生成此HTML： ```html <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> ``` ```php <?php $products = Products::find("type = 'vegetables'"); // Creating a Select Tag with an empty option with default text echo $this->tag->select( [ 'productId', $products, 'using' => [ 'id', 'name', ], 'useEmpty' => true, 'emptyText' => 'Please, choose one...', 'emptyValue' => '@', ] ); ``` ```html <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語法： ```twig {# 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屬性所有幫助程序都接受一個數組作為它們的第一個參數，該參數可以包含生成的元素的其他HTML屬性。 ```php <?php $this->tag->textField( [ 'price', 'size' => 20, 'maxlength' => 30, 'placeholder' => 'Enter a price', ] ) ?> ``` 或使用Volt： ```twig {{ text_field('price', 'size': 20, 'maxlength': 30, 'placeholder': 'Enter a price') }} ``` 生成以下HTML： ```html <input type='text' name='price' id='price' size='20' maxlength='30' placeholder='Enter a price' /> ``` ## 設置助手值 ### 來自控制器對于MVC框架來說，為視圖中的表單元素設置特定值是一個很好的編程原則。您可以使用 `Phalcon\Tag::setDefault()`直接從控制器設置這些值。此幫助程序為視圖中存在的任何幫助程序預加載值。如果視圖中的任何幫助程序具有與預加載值匹配的名稱，則它將使用它，除非在視圖中的幫助程序上直接分配值。 ```php <?php use Phalcon\Mvc\Controller; class ProductsController extends Controller { public function indexAction() { $this->tag->setDefault('color', 'Blue'); } } ``` 在視圖中，selectStatic助手匹配用于預設值的相同索引。在這種情況下`color`： ```php <?php echo $this->tag->selectStatic( [ 'color', [ 'Yellow' => 'Yellow', 'Blue' => 'Blue', 'Red' => 'Red', ] ] ); ``` 這將生成以下選擇標記，并選擇值“Blue”： ```html <select id='color' name='color'> <option value='Yellow'>Yellow</option> <option value='Blue' selected='selected'>Blue</option> <option value='Red'>Red</option> </select> ``` ### 來自請求 `Phalcon\Tag` 幫助程序具有的一個特殊功能是它們可以在請求之間保留表單幫助程序的值。這樣，您可以輕松顯示驗證消息，而不會丟失輸入的數據。 ### 直接指定值每個表單助手都支持參數'value'。有了它，您可以直接為助手指定值。如果存在此參數，則將忽略使用`setDefault()`或通過請求的任何預設值。 ## 動態更改文檔標題 `Phalcon\Tag` 提供幫助程序以動態更改控制器中的文檔標題。以下示例演示了： ```php <?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 - '); } } ``` ```php <html> <head> <?php echo $this->tag->getTitle(); ?> </head> <body> </body> </html> ``` 將生成以下HTML： ```php <html> <head> <title>Index of Posts - Your Website</title> </head> <body> </body> </html> ``` ## 靜態內容助手 `Phalcon\Tag` 還提供幫助程序來生成腳本，鏈接或img等標記。它們有助于快速輕松地生成應用程序的靜態資源 ### 圖片 ```php <?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( [ 'img/hello.gif', 'alt' => 'alternative text', ] ); ``` Volt語法： ```twig {# 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') }} ``` ### 樣式表 ```php <?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語法： ```twig {# 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 ```php <?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語法： ```twig {# 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元素 - 通用HTML幫助器 Phalcon提供了一個通用的HTML幫助程序，允許生成任何類型的HTML元素。開發人員可以為幫助程序生成有效的HTML元素名稱。 ```php <?php // Generate // <canvas id='canvas1' width='300' class='cnvclass'> // This is my canvas // </canvas> 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語法： ```php {# 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') }} ``` ## 標簽服務 `Phalcon\Tag` 可通過標簽服務獲得，這意味著您可以從服務容器所在??的應用程序的任何部分訪問它： ```php <?php echo $this->tag->linkTo('pages/about', 'About') ?> ``` 您可以輕松地將新助手添加到自定義組件中，替換服務容器中的服務`tag`： ```php <?php use Phalcon\Tag; class MyTags extends Tag { // ... // Create a new helper public static function myAmazingHelper($parameters) { // ... } // Override an existing method public static function textField($parameters) { // ... } } ``` 然后更改服務`tag`的定義： ```php <?php $di['tag'] = function () { return new MyTags(); }; ``` ## 創建自己的助手工具您可以輕松創建自己的幫助程序。首先，首先在與控制器和模型相同的目錄中創建一個新文件夾。給它一個與你正在創建的相關的標題。對于我們這里的例子，我們可以稱之為'customhelpers'。接下來，我們將在這個新目錄中創建一個名為`MyTags.php`的新文件。此時，我們的結構看起來類似于：`/app/customhelpers/MyTags.php`。在`MyTags.php`中，我們將擴展`Phalcon\Tag`并實現您自己的幫助器。以下是自定義幫助程序的簡單示例： ```php <?php 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 (!is_array($parameters)) { $parameters = [$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; } } ``` 在創建自定義幫助程序之后，我們將從位于公共目錄中的`index.php`中自動加載包含我們的幫助程序類的新目錄。 ```php <?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(); $response->send(); } catch (PhalconException $e) { echo 'PhalconException: ', $e->getMessage(); } ``` 現在，您已準備好在視圖中使用新助手： ```php <body> <?php echo MyTags::audioField( [ 'name' => 'test', 'id' => 'audio_test', 'src' => '/path/to/audio.mp3', ] ); ?> </body> ``` 您還可以查看Volt一個更快的PHP模板引擎，在這里您可以使用更友好的開發人員語法來幫助`Phalcon\Tag`提供幫助程序。