組件 · October Cms 筆記

# 組件 ## 組件 ### 組件說明 - 組件文件所在目錄 /plugins/用戶名/插件名/components - 每個組件都有一個定義組件類的PHP文件和一個可選的組件partials目錄。 - 組件的partials目錄名稱與以小寫形式編寫的組件類名稱匹配。 - 組件目錄結構的示例： ``` plugins/ 用戶名/ myplugin/ components/ componentname/ <=== Component partials directory default.htm <=== Component default markup (optional) ComponentName.php <=== Component class file Plugin.php ``` 必須使用該方法將組件[注冊在Plugin注冊類中](https://octobercms.com/docs/plugin/components#component-registration)`registerComponents`。 ### 組件注冊 - 必須通過重寫`Plugin注冊類中`的`registerComponents`方法來注冊組件。 - 注冊組件的示例：這將使用默認別名名稱**demoTodo**注冊Todo組件類 ``` public function registerComponents() { return [ 'October\Demo\Components\Todo' => 'demoTodo' ]; } ``` ### 組件類定義 - **組件類文件**定義了組件功能和組件的屬性 - 組件類文件名應與組件類名匹配 - 組件類應繼承擴展`\Cms\Classes\ComponentBase`該類。 - 定義組件詳情的`componentDetails`方法是必需的。該方法應返回帶有兩個鍵的數組：`name`和`description`。名稱和描述顯示在CMS后端用戶界面中。 - 示例： `componentDetails`定義屬性，`posts`定義方法 ``` namespace Acme\Blog\Components; class BlogPosts extends \Cms\Classes\ComponentBase { public function componentDetails() { return [ 'name' => 'Blog Posts', 'description' => 'Displays a collection of blog posts.' ]; } // This array becomes available on the page as {{ component.posts }} public function posts() { return ['First Post', 'Second Post', 'Third Post']; } } ``` - 當組件附加到頁面或布局時，類屬性和方法將通過component變量在頁面上可用，該變量與組件的短名稱或別名匹配。例如，如果示例中的BlogPost組件是在其短名稱頁面上定義的： ``` url = "/blog" [blogPosts] == ``` 您將可以`posts`通過`blogPosts`變量訪問其方法。請注意，Twig支持方法的屬性表示法，因此您無需使用方括號。 ``` {% for post in blogPosts.posts %} {{ post }} {% endfor %} ``` ### 組件屬性 - 將組件添加到頁面或布局時，可以使用屬性對其進行配置 - 這些屬性是使用`defineProperties`組件類的方法定義的。下一個示例顯示如何定義組件屬性： ``` public function defineProperties() { return [ 'maxItems' => [ 'title' => 'Max items', 'description' => 'The most amount of todo items allowed', 'default' => 10, 'type' => 'string', 'validationPattern' => '^[0-9]+$', 'validationMessage' => 'The Max Items property can contain only numeric symbols' ] ]; } ``` - 該方法應返回一個數組，其中屬性鍵為索引，屬性參數為值。 - 屬性鍵用于訪問組件類內部的組件屬性值。使用帶有以下鍵的數組定義屬性參數： | 鍵 | 描述 | | --- | --- | | **title** | 必填屬性標題，由CMS后端中的組件檢查器使用。 | | **description** | 必需的屬性描述，由CMS后端中的組件檢查器使用。 | | **default** | 可選，將組件添加到CMS后端中的頁面或布局時使用的默認屬性值。 | | **type** | 可選，指定屬性類型。類型定義了屬性在檢查器中的顯示方式。當前支持的類型是**字符串**，**復選框**，**下拉列表**和**設置**。默認值：**字符串**。（**string**,**checkbox**,**dropdown**and**set**. Default:**string**.） | | **validationPattern** | 用戶在檢查器中輸入屬性值時使用的可選正則表達式。驗證只能與**字符串**屬性一起使用。 | | **validationMessage** | 驗證失敗時顯示的可選錯誤消息。 | | **required** | 可選，強制填寫字段。留空時使用validationMessage。 | | **placeholder** | 字符串和下拉列表屬性的可選占位符。 | | **options** | 下拉屬性的可選選項數組。 | | **depends** | 下拉屬性所依賴的屬性名稱數組。請參閱下面的[下拉屬性](#dropdown-properties)。 | | **group** | 可選的組名。小組在Inspector中創建部分，以簡化用戶體驗。在多個屬性中使用相同的組名將它們組合在一起。 | | **showExternalParam** | 指定檢查器中屬性的“外部參數”編輯器的可見性。默認值：**true**。在組件內部，您可以使用以下`property`方法讀取屬性值： | ``` $this->property('maxItems'); ``` 如果未定義屬性值，則可以提供默認值作為方法的第二個參數`property`： ``` $this->property('maxItems', 6); ``` 您還可以將所有屬性加載為數組： ``` $properties = $this->getProperties(); ``` 要從Twig局部訪問組件的屬性，請使用`__SELF__`引用Component對象的變量： `{{ __SELF__.property('maxItems') }}` ### 下拉菜單和設置屬性 - 下拉菜單和設置屬性的選項列表可以是靜態的或動態的 - 靜態選項是使用`options`屬性定義的元素定義的。例： ``` public function defineProperties() { return [ 'units' => [ 'title' => 'Units', 'type' => 'dropdown', 'default' => 'imperial', 'placeholder' => 'Select units', 'options' => ['metric'=>'Metric', 'imperial'=>'Imperial'] //定義靜態選項 ] ]; } ``` - 如果上面方法返回數組沒有`options`鍵，則選項列表被視為動態列表。 - 組件類必須定義一個返回選項列表的方法。該方法的名稱應采用以下格式：`get*Property*Options``get屬性名Options` - 如：`getCountryOptions`該方法返回一個選項數組，其中選項值作為鍵，選項標簽作為值 - 示例： ``` public function defineProperties() { return [ 'country' => [ 'title' => 'Country', 'type' => 'dropdown', 'default' => 'us' ] ]; } public function getCountryOptions() { return ['us'=>'United states', 'ca'=>'Canada']; } ``` 動態下拉列表和設置列表可能取決于其他屬性。例如，州列表可能取決于所選國家。依賴項`depends`在屬性定義中用參數聲明。下一個示例定義了兩個動態下拉列表屬性，狀態列表取決于國家/地區： ``` public function defineProperties() { return [ 'country' => [ 'title' => 'Country', 'type' => 'dropdown', 'default' => 'us' ], 'state' => [ 'title' => 'State', 'type' => 'dropdown', 'default' => 'dc', 'depends' => ['country'], 'placeholder' => 'Select a state' ] ]; } ``` 為了加載狀態列表，您應該知道檢查器中當前選擇的國家。檢查器將所有屬性值POST到`getPropertyOptions`處理程序，因此您可以執行以下操作： ``` public function getStateOptions() { $countryCode = Request::input('country'); // Load the country property value from POST $states = [ 'ca' => ['ab'=>'Alberta', 'bc'=>'British columbia'], 'us' => ['al'=>'Alabama', 'ak'=>'Alaska'] ]; return $states[$countryCode]; } ``` ### 頁面列表屬性 - 有時組件需要創建指向網站頁面的鏈接。例如，博客文章列表包含指向博客文章詳細信息頁面的鏈接 - October包含一個用于創建動態下拉列表的幫助器 - 下一個示例定義了postPage屬性，該屬性顯示頁面列表： ``` public function defineProperties() { return [ 'postPage' => [ 'title' => 'Post page', 'type' => 'dropdown', 'default' => 'blog/post' ] ]; } public function getPostPageOptions() { return Page::sortBy('baseFileName')->lists('baseFileName', 'baseFileName'); } ``` ### 路由參數 - 組件可以直接訪問頁面URL中定義的路由參數值。 ``` // Returns the URL segment value, eg: /page/:post_id $postId = $this->param('post_id'); ``` - 在某些情況下，組件屬性可以充當硬編碼值或從URL引用該值。 - 這個硬編碼示例顯示了使用標識符的博客帖子`2`： ``` url = "/blog/hard-coded-page" [blogPost] id = "2" ``` - 也可以使用外部屬性值從頁面URL動態引用該值 ``` url = "/blog/:my_custom_parameter" [blogPost] id = "{{ :my_custom_parameter }}" ``` - 在這兩種情況下，都可以使用以下`property`方法來檢索值： ``` $this->property('id'); ``` - 如果需要訪問路由參數名稱： ``` $this->paramName('id'); // Returns "my_custom_parameter" ``` ### 處理頁面執行周期通過重寫`onRun`組件類中的方法，組件可以參與Page執行周期事件。每次加載頁面或布局時，CMS控制器都會執行此方法。在方法內部，您可以通過`page`屬性將變量注入頁面： ``` public function onRun() { // This code will be executed when the page or layout is // loaded and the component is attached to it. $this->page['var'] = 'value'; // 向頁面中注入一些變量 } ``` ### 頁面執行生命周期處理程序頁面加載時，October執行可以在布局和頁面PHP部分以及組件類中定義的處理程序函數。處理程序的執行順序如下： 1. 布局`onInit()`功能。 2. 頁面`onInit()`功能。 3. 布局`onStart()`功能。 4. 布局組件`onRun()`方法。 5. 布局`onBeforePageStart()`功能。 6. 頁面`onStart()`功能。 7. 頁面組件`onRun()`方法。 8. 頁面`onEnd()`功能。 9. 布局`onEnd()`功能。 ### 組件初始化 - 初始化方法是在首次實例化組件類時執行代碼。 - 重寫`init`組件類中的方法以處理任何初始化邏輯，都將在AJAX處理程序之前和頁面執行生命周期之前執行。 - 此方法可用于將另一個組件動態附加到頁面。 ``` public function init() { $this->addComponent('Acme\Blog\Components\BlogPosts', 'blogPosts'); } ``` ### 停止回應 - 如果`onRun`組件中的方法返回一個值，后停止該周期并將響應返回給瀏覽器。可以使用`Response`返回拒絕訪問的消息： ``` public function onRun() { if (true) { return Response::make('Access denied!', 403); } } ``` 您還可以從`onRun`方法返回404響應： ``` public function onRun() { if (true) { $this->setStatusCode(404); return $this->controller->run('404'); } } ``` ### AJAX處理程序 - 組件托管AJAX事件處理程序與在頁面或布局代碼中定義的方式完全相同 - 在組件類中定義的示例AJAX處理程序方法： ``` public function onAddItem() { $value1 = post('value1'); $value2 = post('value2'); $this->page['result'] = $value1 + $value2; } ``` - 如果此組件的別名為\*demoTodo，\*則可以通過訪問此處理程序`demoTodo::onAddItem`。 - 有關將AJAX與組件一起使用的詳細信息，請參見[在組件](https://octobercms.com/docs/ajax/handlers#calling-handlers)文章中[定義](https://octobercms.com/docs/ajax/handlers#calling-handlers)的“[調用AJAX處理程序”](https://octobercms.com/docs/ajax/handlers#calling-handlers)。 ### 默認標記 - 所有組件都可以帶有默認標記，默認標記是將其包含在帶有`{% component %}`標簽的頁面上時使用的 - 默認標記保存在**組件partials目錄中**，該**目錄**與小寫的組件類同名。 - 默認組件標記應放置在名為**default.htm**的文件中。 - 例如，在文件\*\*/plugins/october/demo/components/todo/default.htm中\*\*定義了Demo ToDo組件的默認標記。然后可以使用`{% component %}`標簽將其插入頁面上的任何位置： ``` url = "/todo" [demoTodo] == {% component 'demoTodo' %} ``` 默認標記還可以采用在渲染[組件](https://octobercms.com/docs/plugin/components#component-properties)時覆蓋[組件屬性的](https://octobercms.com/docs/plugin/components#component-properties)參數。 ``` {% component 'demoTodo' maxItems="7" %} ``` 這些屬性將在`onRun`方法中不可用，因為它們是在頁面循環完成之后建立的。相反，可以通過重寫`onRender`組件類中的方法來處理它們。CMS控制器在呈現默認標記之前執行此方法。 ``` public function onRender() { // This code will be executed before the default component // markup is rendered on the page or layout. $this->page['var'] = 'Maximum items allowed: ' . $this->property('maxItems'); } ``` ### 零件：入分頁 - 分頁目錄：**/plugins/october/demo/components/todo/pagination.htm中，** - 使用以下命令在頁面上顯示： ``` {% partial 'demoTodo::pagination' %} ``` - 如果在組件局部內部調用，它將直接引用自身 - 如果在主題部分中調用，它將掃描頁面/布局上使用的所有組件以查找匹配的部分名稱并使用該名稱。 ``` {% partial '@pagination' %} ``` - 多個組件可以通過將部分文件放置在名為**components / partials**的目錄中來共享**部分**。 - 如果找不到常用的組件零件，則在此目錄中找到的局部用作備用。 - 例如，任何組件都可以使用以下命令在頁面上顯示\*\*/plugins/acme/blog/components/partials/shared.htm中\*\*的共享部分： ``` {% partial '@shared' %} ``` ### 引用“自我” 組件可以使用該`__SELF__`變量在自己的部分中引用自己。默認情況下，它將返回組件的簡稱或[別名](https://octobercms.com/docs/cms/components#aliases)。 ``` <form data-request="{{__SELF__}}::onEventHandler"> [...] </form> ``` 組件也可以引用自己的屬性。 ``` {% for item in __SELF__.items() %} {{ item }} {% endfor %} ``` 如果在部件局部內部，則需要渲染另一個部件局部`__SELF__`，以部分名稱連接變量： ``` {% partial __SELF__~"::screenshot-list" %} ``` ### 唯一標識符如果在同一頁面上兩次調用相同的組件，`id`則可以使用屬性來引用每個實例。 ``` {{__SELF__.id}} ``` 每次顯示組件時，ID都是唯一的。 ```  {% component 'demoTodo' %}  {% component 'demoTodo' %} ``` ### 渲染主鍵 - `renderPartial`方法渲染組件，渲染后將結果作為字符串返回 - 第一個方法：組件文件`component-partial.htm` - 第二個參數用于傳遞視圖變量。 ``` $content = $this->renderPartial('component-partial.htm'); $content = $this->renderPartial('component-partial.htm', [ 'name' => 'John Smith' ]); ``` 例如，將部分渲染為對[AJAX處理程序](https://octobercms.com/docs/ajax/handlers)的響應： ``` function onGetTemplate() { return ['#someDiv' => $this->renderPartial('component-partial.htm')]; } ``` 另一個示例可能是通過返回`onRun`渲染頁面的結果來覆蓋整個頁面視圖響應。這段代碼將使用`Response`Facade專門返回XML響應： ``` public function onRun() { $content = $this->renderPartial('default.htm'); return Response::make($content)->header('Content-Type', 'text/xml'); } ``` ### 向頁面注入組件 - 組件可以將資源（CSS和JavaScript文件）注入到它們所附著的頁面或布局中 - 使用控制器的`addCss`和`addJs`方法將資產添加到CMS控制器。 - 可以用組件的`onRun`方法完成 - 例： ``` public function onRun() { $this->addJs('/plugins/acme/blog/assets/javascript/blog-controls.js'); } ``` - 如果`addCss`and`addJs`方法參數中指定的路徑以斜杠（/）開頭，則它將相對于網站根目錄。如果資源路徑不是以斜杠開頭，則它是相對于組件目錄的。 - `addCss`和`addJs`方法提供了您的注入資源的屬性定義為一個陣列的第二個參數。有一個特殊的屬性--`build`可以為您注入的資源添加指定版本的當前插件后綴。插件升級后，可用于刷新緩存的資產。 ``` public function onRun() { $this->addJs('/plugins/acme/blog/assets/javascript/blog-controls.js', [ 'build' => 'Acme.Test', 'defer' => true ]); } ``` 您也可以使用字符串作為第二個參數，然后默認使用字符串值作為`build`： ``` public function onRun() { $this->addJs('/plugins/acme/blog/assets/javascript/blog-controls.js', 'Acme.Test'); } ```