視圖助手 · Phalcon3中文文檔

# 視圖助手 (Tags)（View Helpers (Tags)）因為HTML標簽的命名方式和很多標簽屬性，讓書寫HTML標簽變成一項超級沉悶的工作。Phalcon提供[Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)類來處理這些復雜而無趣的事情。 > 這個簡單的指導不是一個完整的關于視圖助手的文檔，請查看[Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)以獲得視圖助手的完整說明。 ## 文檔類型（Document Type of Content） Phalcon 提供`Phalcon\Tag::setDoctype()`方法可以設置輸出內容的文檔類型。此類型設置可能被其他的tag方法影響。 | 常量 | 對應的文檔類型 | | --- | --- | | HTML32 | HTML 3.2 | | HTML401\_STRICT | HTML 4.01 嚴格模式 | | HTML401\_TRANSITIONAL | HTML 4.01 過渡模式 | | HTML401\_FRAMESET | HTML 4.01 Frameset | | HTML5 | HTML 5 | | XHTML10\_STRICT | XHTML 1.0 嚴格模式 | | XHTML10\_TRANSITIONAL | XHTML 1.0 過渡模式 | | XHTML10\_FRAMESET | XHTML 1.0 Frameset | | XHTML11 | XHTML 1.1 | | XHTML20 | XHTML 2.0 | | XHTML5 | XHTML 5 | 設置文檔類型: ~~~ <?php use Phalcon\Tag; $this->tag->setDoctype(Tag::HTML401_STRICT); ?> ~~~ 獲取文檔類型: ~~~ <?= $this->tag->getDoctype() ?> <html>  </html> ~~~ 如下的html代碼將被生成: ~~~ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html>  </html> ~~~ Volt 語法: ~~~ {{ get_doctype() }} <html>  </html> ~~~ ## 生成鏈接（Generating Links）每一個普通的web應用都需要生成超鏈接去讓我們在不同的頁面之間進行導航。我們可以使用如下的方法創建指向我們站內的超鏈接： ~~~  <?= $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](http://docs.iphalcon.cn/reference/url.html)生成的。使用Volt生成超鏈接的例子: ~~~  {{ 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）在Web應用中，表單是獲取用戶輸入的重要工具，下面的例子顯示了使用視圖助手(tag)如何去生成一個簡單的form表單。 ~~~  <?= $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: ~~~ <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生成表單: ~~~  {{ form("products/search", "method": "get") }} <label for="q">Search:</label> {{ text_field("q") }} {{ submit_button("Search") }} {{ endForm() }} ~~~ Phalcon也提供了[form builder](http://docs.iphalcon.cn/reference/forms.html)類去以面向對象的風格去生成這樣的表單。 ## 使用助手生成表單控件（Helpers to Generate Form Elements） Phalcon 提供了一系列的方法去生成例如文本域(text)，按鈕(button)和其他的一些form表單元素。提供給所有方法(helper)的第一個參數都是需要創建的表單元素的名稱(name屬性)。當提交表單的時候，這個名稱將被和form表單數據一起傳輸。在控制器中，你可以使用request對象 (`$this->request`) 的`getPost()`和`getQuery()`方法結合之前定義的名字(name屬性)來獲取到這些值。 ~~~ <?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 的語法: ~~~ {{ 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）生成選擇框(select)很簡單,特別是當你已經把相關的數據存儲在了PHP的關聯數組中。生成select的方法是`Phalcon\Tag::select()`和`Phalcon\Tag::selectStatic()`。方法`Phalcon\Tag::select()`與[Phalcon\\Mvc\\Model](http://docs.iphalcon.cn/reference/models.html)一起使用會更好。當然`Phalcon\Tag::selectStatic()`也可以和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代碼將會被生成: ~~~ <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> ~~~ 你可以添加一個空的選項(option)到被生成的HTML頁面中: ~~~ <?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如下: ~~~ <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 $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" => "@", ] ); ~~~ ~~~ <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的語法生成以上的select選擇框 ~~~ {# 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）所有的方法的第一個參數可以是一個數組，這個數組包含了這個被生成的HTML元素額外的屬性。 ~~~ <?php $this->tag->textField( [ "price", "size" => 20, "maxlength" => 30, "placeholder" => "Enter a price", ] ) ?> ~~~ Volt語法: ~~~ {{ text_field("price", "size": 20, "maxlength": 30, "placeholder": "Enter a price") }} ~~~ 以下的HTML代碼將被生成。 ~~~ <input type="text" name="price" id="price" size="20" maxlength="30" placeholder="Enter a price" /> ~~~ ## 設置助手的值（Setting Helper Values） ### 通過控制器（From Controllers）使用MVC框架編程時的一個好習慣是給form元素在視圖中設定一個明確的值。你可以直接使用`Phalcon\Tag::setDefault()`在控制器中設置這個值。這個方法為所有的視圖助手的方法預先設定了一個值，如果任意一個視圖助手方法有一個和此預設值相匹配的名字，這個值將會被使用，除非那個視圖方法明確的指定了這個值。 ~~~ <?php use Phalcon\Mvc\Controller; class ProductsController extends Controller { public function indexAction() { $this->tag->setDefault("color", "Blue"); } } ~~~ 例如，在視圖中一個選擇框助手方法(select helper)匹配到了這個之前被預設的值”color” ~~~ <?php echo $this->tag->selectStatic( [ "color", [ "Yellow" => "Yellow", "Blue" => "Blue", "Red" => "Red", ] ] ); ~~~ 當這個選擇框被生成的時候，”Blue”將被默認選中。 ~~~ <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） > [Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)助手有一個特性，它可以在用戶請求的時候保持表單的值。這個特性讓你在不損失任何輸入數據的情況下顯示一些確認信息。 ### 直接設置值（Specifying values directly）所有的表單方法都支持參數”value”。你可以直接設置一個明確的值給表單方法。當這個值被明確設定的時候，任何通過 setDefault() 或者通過請求(request) 所設置的值將被直接忽略。 ## 動態設置文檔標題（Changing dynamically the Document Title） [Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)類提供了一些方法，讓我們可以在控制器中動態地設置HTML文檔的標題(title)。 ~~~ <?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 - "); } } ~~~ ~~~ <html> <head> <?php echo $this->tag->getTitle(); ?> </head> <body> </body> </html> ~~~ 以下的HTML代碼將會被生成: ~~~ <html> <head> <title>Index of Posts - Your Website</title> </head> <body> </body> </html> ~~~ ## 靜態內容助手（Static Content Helpers） [Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)也提供一些其他的方法去生成一些其他的標簽，例如腳本(script),超鏈接(link)或者圖片(img)。它可以幫助你很快的生成一些你應用中的靜態資源 ### 圖片（Images） ~~~ <?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 語法: ~~~ {# 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） ~~~ <?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 語法: ~~~ {# 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 // 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 語法： ~~~ {# 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 提供了一個通用的方法去生成任何HTML的元素。在這個方法中，需要開發者將有效的HTML元素標簽傳給此方法。 ~~~ <?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 語法： ~~~ {# 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](http://docs.iphalcon.cn/api/Phalcon_Tag.html)類可以通過 ‘tag’ 服務來使用，這意味著你可以在服務容器被加載的任何地方訪問到它。 ~~~ <?php echo $this->tag->linkTo("pages/about", "About") ?> ~~~ 在服務容器中我們可以很容易的添加一個新的組件去替換’tag’組件。 ~~~ <?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 $di["tag"] = function () { return new MyTags(); }; ~~~ ## 創建助手（Creating your own helpers）你可以簡單地創建你自己的方法。首先，在你的控制器和模型的同級目錄下創建一個新的文件夾，給此文件夾起一個和它功能相關的名字。在這里，叫它”customhelpers”好了。接下來我們在此文件夾下創建一個新的文件命名為`MyTags.php`這時，我們有一個類似于`/app/customhelpers/MyTags.php`的結構，我們將擴展(extend)[Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)并且實現(implement)這個類。下面是一個自定義的助手(helper)類： ~~~ <?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; } } ~~~ 在我們創建了自定義的助手(helper)類之后，我們要在我們的public目錄下的”index.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(); } ~~~ 現在，你就可以在你的視圖中使用你的新助手類了。 ~~~ <body> <?php echo MyTags::audioField( [ "name" => "test", "id" => "audio_test", "src" => "/path/to/audio.mp3", ] ); ?> </body> ~~~ 在下一節中，我們將討論關于[Volt](http://docs.iphalcon.cn/reference/volt.html)的內容，它是PHP的一個速度很快的模板引擎，在[Phalcon\\Tag](http://docs.iphalcon.cn/api/Phalcon_Tag.html)中你將得到更多關于視圖助手的友好的提示。