Difference between revisions of "Layout Overrides in Joomla/zh-tw"

Latest revision as of 02:31, 5 February 2021

Other languages:

English • ‎español • ‎français • ‎中文（台灣）‎

This tutorial is for Joomla! CMS Version(s)

關於替代版面的功能介紹

Joomla 有個精巧的功能設計，讓網站管理員能從佈景主題中，對所有的 html 顯示能有更多控制。有五種類型的替代版面：

模組
元件
分類
選單項目
JLayouts

替代版面類似於佈景主題功能覆蓋，但是允許您有更多的選項以及控制。以下針對每一種類別討論：

模組替代版面

建立模組的替代版面(alternative layout)，類似於建立模組的覆蓋版型(template override)。上述兩個動作，您都需要建立一個名為templates/<your template>/html/<module name>的資料夾。例如，要在beez3佈景主題中，建立 templates/beez3/html/mod_login/資料夾，來完成 "mod_login" 的替代版面或是覆蓋版型。

替代版面和覆蓋版型有兩個主要差異。首先是檔案名稱。對覆蓋版型而言，您會把檔案命名為default.php ，來符合Joomla! 核心中使用的檔名；但對替代版型而言，您必需使用不同的名稱。唯一的規則是 檔名不可以有任何的下底線。這樣您可以使用多個檔案，擁有更複雜的版型規劃。起頭的檔案命名不能有下底線，而由這個起頭檔案呼叫的其他的檔案，則在檔案名中有下底線。例如，您可以把起頭檔案命名為mynewlogin.php ，在其中呼叫 mynewlogin_1.php。

另一個重要的差異是，不像覆蓋版型的檔案，會在模組出現在佈景主題的時候自動套用；替代性版型只有在您從模組管理介面中設定為使用的時候，才會套用。在之後，請於進階頁籤中的「替代版面」設定。

這個項目會列出您放在佈景主題資料夾模組路徑中，所有(沒有下底線)的檔案。您也可以使用佈景主題的系統語言檔案，來翻譯檔案名稱。 (請注意，範例使用的是便宜行事的作法，最好的實踐方法是使用 Joomla 的語言覆蓋工具來建立字串，而不要修改佈景主題語言檔案)。例如，如果您新增了一行

TPL_BEEZ3_MOD_LOGIN_LAYOUT_NOLOGIN="Alt Login Layout"

到檔案 en-GB.tpl_beez3.sys.ini中，將會翻譯nologin.php 的名稱為 "Alt Login Layout"。

It is important to understand that if specified in the Module Manager screen, an alternative layout file for a module will be used for that module regardless of what template is used to display the page where the module is shown. It is therefore the administrator's responsibility to make sure that the layout file will work as desired in any templates where this module may be shown.

外掛替代版面(覆蓋外掛)

是的，外掛也可以覆蓋，這相當有用，尤其是對於內容外掛而言。然而，您只有在外掛允許被覆蓋的情形下，才可以進行。

A Tip!

目前，可以被覆蓋的的核心外掛是「頁面導覽」，就是顯示上一頁/下一頁文章連結那個。第三方擴充套件可能提供了一些可以被覆蓋的外掛，未來也會有更多核心外掛會提供可覆蓋功能。

如果您有看到/tmpl/資料夾，表示這個外掛是可以被覆蓋版面的。請見 https://github.com/joomla/joomla-cms/tree/staging/plugins/content/pagenavigation (開發者請注意：這個外掛使用了 JPluginHelper::getLayoutPath() )

外掛覆蓋範例

要在「beez3」版型中覆蓋 Pagenavigation content plugin外掛，請建立名為templates/beez3/html/plg_content_pagenavigation/ 的資料夾，並複製原始的版面檔案(plugins/content/pagenavigation/tmpl/default.php) 到新的資料夾中。

現在，您可以更改這個版面檔案來完成覆蓋外掛。

重要的是要知道，您需要建立資料夾路徑，來完成覆蓋。

templates/TEMPLATE-NAME/html/plg_PLUGIN-GROUP_PLUGIN-NAME/

範例： templates/beez3/html/plg_content_pagenavigation/

當中的 PLUGIN-GROUP 是外掛所屬的群組 (也就是外掛所處路徑的上一層名稱，請參閱 https://github.com/joomla/joomla-cms/tree/staging/plugins. 更多關於事件群組的文章在外掛/事件(event))。

元件替代版面

元件的覆蓋版面類似於上面講過的模組版面。再一次，檔案要放在佈景主題路徑中相對位置。例如，要在beez3中建立文章版面的覆蓋，要把檔案放到templates/beez3/html/com_content/article/中。一如模組的版面，檔案不要使用與模組名稱相同的，並且不要在檔名中使用下底線。另外，資料夾中不要有 XML 檔案 (底下講到選單項目覆蓋版面時，我們會討論 XML 檔案)

在文章的選項視窗中，您可以設定套用到全站的值。例如，在文章管理員選項視窗中，有參數是給替代版面用的，如下：

這會建立全站設定值，讓個別元件 - 文章、內容、新聞聯播(news feed)以及網站連結(web link) - 可以繼承。

與模組版面相同，元件的版面在編輯介面中，也有參數可以設定。例如，文章元件的參數設定畫面如下：

「--從全站選項--」設定會套用您在選項中使用的設定。「--從元件--」設定則會套用元件預設的版面，您所建立於不同的佈景主題中的版面，也會出現在下拉清單當中。

檔案名稱也是可以翻譯的，請參考以下程式碼：

TPL_BEEZ3_COM_CONTENT_ARTICLE_LAYOUT_MYLAYOUT="Title Only No XML"

會把名為 "mylayout.php" 的檔案翻譯為"Title Only No XML"。

一個版面可能有超過一個檔案。起頭的檔案名稱必需不要有下底線，而其他的檔案則有下底線。

元件的替代版面必需用於文章、元件或是新聞聯播。網站連結(web link)並沒有獨立的元件版面，所以沒有替代版面可以用。

只有在以下兩個條件符合時，才會使用元件的替代版面：(1) 被指定於元件的參數設定中，並且 (2) 沒有選單項目使用這個元件。例如，如果您有一或是多個選單項目使用「單一文章」並且指定了一篇文章，您將看不到這個文章的替代版面效果。反之，會使用選單項目所指定的版面。這和元件選項作用的方式是一致的，也就是比較特定的 (本案例來說，就是單一文章選單項目) 會覆蓋較不特定的 (本案例來說，就是文章的選項設定)。

分類替代版面

分類替代版面作用的方式和元件版面一模一樣。指定分類版面檔案的方式和規則一樣。唯一的差異是，資料夾是分類資料夾，而不是元件資料夾。例如，beez3佈景主題中，聯絡人分類頁面的替代版面檔案要放在在路徑 templates/beez3/html/com_contact/category。

您可以在每一個元件的選項頁面設定全站的分類版面，以下範例是設定聯絡人管理的畫面。

Contact component options category alternative layout j3 en.png

當您在分類管理介面中的基本選項新增或編輯分類，分類替代版面會出現。畫面如下：

Category options alternative layout j3 en.png

分類替代版面可以被用於文章、內容、新聞聯播(news feed)以及網站連結(web link)。

如同元件版面，分類版面只會在以下條件下顯示：(1) 被指定於分類的參數設定中，並且 (2) 有選單項目使用這個分類 (例如，分類聯絡人列表、分類新聞聯播列表、分類網站連結列表、分類列表、分類部落格)。

假如有選單項目設定為特定分類，將會使用版面，而非替代版面。

Drill Down to Blog or List

對文章而言，我們有兩個核心的版面可以用：部落格(Blog)和條列(List)。這兩個的選項都會顯示於名為「--從元件--」下拉選單中。所以，如同其他的版面選項，您可以為文章分類選擇部落格或是條列頁面作為全站設定(如下圖，文章選項介面)；或是在編輯單一文章分類。

Article manager category blog alternative layout j3 en.png

這是說，如同其他的版面選項一樣，您可以控制文章分類中的頁面是部落格或是條列。很重要的是要知道，如同其他的版面參數，這個設定選項只會在沒有單一分類選單項目設定為此分類時，才會生效。

替代選單項目

和其他替代版面相比，選單項目替代版面有個重要的差異。要建立選單項目替代版面，您必需要包含一個 XML 檔案，檔案名稱與替代版面的起頭檔案相符。例如，在beez3佈景主題中，要為文章建立名為「myarticle」的選單項目替代版面，您需要在templates/beez3/html/com_content/article 資料夾中建立兩個檔案，分別是 myarticle.php 以及 myarticle.xml。如果您要包含更多的版面檔案，您會需要新增檔名帶有下底線的檔案。

XML 檔案使用的格式和 Joomla核心選單 XML 檔案相同。這可以讓您不僅建立自訂的選單項目替代版面，還允許您建立自訂的參數。例如，您考以隱藏或是新增一些參數。

選單項目替代版面會在您選擇一個選單項目類型時出現，如下圖：

選單項目替代版面使用就和標準的選單項目一樣，由於他們已經是在自訂版面的基礎上建立，佈景主題覆蓋並不會作用於選單項目替代版面。

如同上述所說明的，選單項目版面的順序會高於元件或是分類替代版面。

Translation of alternative menu items is done with the following tags in the XML files. The format is "TPL_"<template name>_<component>_<view>_<menu item name>_<tag type>。例如，下面的程式碼會翻譯名為 "catmenuitem" 的選單項目帶替代版面的「標題」、「選項」、「描述」。

TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="Beez3 Custom Category Layout"
TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="Beez3 Custom"
TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for beez3 custom category layout."

加入字串到 language/en-GB/en-GB.tpl_beez3.sys.ini檔案

catmenuitem.xml 開頭會這樣：

<?xml version="1.0" encoding="utf-8"?>
<metadata>
   <layout title="TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
      <help
         key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
      />
      <message>
         <![CDATA[TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
      </message>
   </layout>

控制選單項目替代版面的模版

如同上面所討論過的， XML 檔案可以使替代版面出現為選單項目。XML 檔案的格式和 Joomla! 核心的選單項目 XML 檔案一樣。有了這個XML 檔案，您可以新增您想要的參數到這個選單項目中。它們可以和核心選單項目的一樣，您也可以新增或是修改核心的選項。請注意如果您新增了選項，它們將可以被用在版面檔案中，但無法用在核心的 model或是 view 檔案中。

也可以覆蓋核心所提供的選項。一個例子，控制選單項目的版面要使用哪個佈景主題。在某些狀況中，您也許會想要自訂選單項目可以在任何佈景主題中都能使用；但是在某些情況下，您可能想要限制選單項目只能使用特定版面。如果是後者，您可以新增底下的一段語法到該選單項目的XML檔案：

<fields>
  <field
    name="template_style_id"
    type="templatestyle"
    label="COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"
    description="COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"
    filter="int"
    template="beez3"
    class="inputbox">
  </field>
 </fields>

這會覆寫核心的 template_style_id 參數，設定佈景主題為"beez3" ，這樣一來會限制用戶只能選擇佈景主題為 "beez3"。

JLayout 微型版面(Micro-Layout )覆蓋

JLayouts 是 Joomla! 強大的功能。JLayouts 提供鬆散定義的微型版面( micro-layouts)。它們是組成 Joomla! 頁面的個別元素。例如，閱讀更多的按鈕、摘要圖片、全文圖片都是屬於各自 JLayout 控制的元素。

如果我們在分類部落格頁面的檔案上鑽研更深入，會發現程式碼呼叫了文章的標題、摘要圖片、摘要文字，以及其他相關的頁面組成元素。這就是我們使用 JLayout 來呼叫元素造成的結果。

<?php echo JLayoutHelper::render('joomla.content.blog_style_default_item_title', $this->item); ?>

這一段程式碼會在 Joomla! 分類部落格中呼叫文章標題。

為了幫助您了解這個元素的檔案位置，我們來看命名如何轉換為檔案位置。看看joomla.content.blog_style_default_item_title 中的點，試著用路徑的斜線 /來取代，您就知道檔案路徑。所有的 JLayouts 都可以在 JOOMLAROOT/layouts 路徑下找到。改換一下命名結構您就會知道，檔案位於JOOMLAROOT/layouts/joomla/content/blog_style_default_item_title.php。

用範例來說明吧。假使我們想要搬動摘要圖片到標題之上，如果您想要的話您還可以新增一些其他東西。

您應該不要直接編輯 JLayout 檔案，因為以後系統更新，您的檔案就會被蓋掉了。正確的作法應該是，找到您要覆蓋的元素(比方說intro_image) ，複製那個檔案到您的佈景主題中，例如templates/YOUR_TEMPLATE/html/。您只需要複製您需要的，以免檔案太多太大，而且也減少造成問題的機會。

範例中，可以在以下路徑找到原始的摘要圖片 intro_image 檔案： JOOMLAROOT/layouts/joomla/content/intro_image.php

複製的檔案將會是：templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image.php

範例中，我們新增一個響應式圖片class 到摘要圖片。首先，我們開啟複製的JLayout 檔案，放在路徑templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image.php。

尋找以下內文

<div class="pull-<?php echo htmlspecialchars($imgfloat); ?> item-image">

我們新增響應式的圖片class img-responsive到現有的class

<div class="pull-<?php echo htmlspecialchars($imgfloat); ?> item-image img-responsive">

好的，我們新增了我們要的class了，現在儲存並關閉檔案。確認檔案上傳到我們網站上。現在如果我們重新整理頁面。我們會看到class img-responsive 被加到摘要圖片上了。您剛剛使用了JLayout，試著想想看您可以使用JLayout做哪些很棒的事情吧！

Creating a new JLayout that only appears on some pages

您甚至可以建立新的JLayout檔案。它們不需要現存的元素作為基礎。您只需要直接將它們加到YOUR_TEMPLATE/html/layouts/ ，Joomla! 就會找到它們。然後您需要在您的程式碼中參照新的JLayout。為了方便展示，範例中我們複製既有的元素並改成我們想要的版本。

我們從標準的部落格版面的HTML覆蓋開始(而非JLayout覆蓋)。您可以了解要如何進一步修改頁面。要完成佈景主題覆蓋，會需要新增一些檔案到templates/YOUR_TEMPLATE/html路徑。我會建立新的 JLayout，並且希望它「只被」用在我的部落格頁面上。假如我僅僅只是修改 intro_image 的 JLayout ，將會影響到所有的intro_image，但是我希望只修改我的分類部落格檢視中的intro_image。

我要使用的檔案是templates/YOUR_TEMPLATE/html/com_content/category/blog_item.php。在當中我們找到 <?php echo JLayoutHelper::render('joomla.content.intro_image', $this->item); ?> ，是用來呼叫 JLayout 元素的。而且特定的程式碼用於 intro_image 元素。

基於簡要說明的目的，我們複製檔案JOOMLAROOT/layouts/joomla/content/intro_image.php。我們將之放在 templates/YOUR_TEMPLATE/html/layouts/joomla/content/ 路徑下，並且重新命名為 intro_image_blog.php。

現在我們打開佈景主題覆蓋檔案templates/YOUR_TEMPLATE/html/com_content/category/blog_item.php。我們會發現參照的. I find the reference to <?php echo JLayoutHelper::render('joomla.content.intro_image', $this->item); ?>，我們把它移除，重新指定 JLayout 的位置到標題之上。接著我們使用剛剛建立的 JLayout templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image_blog.php .

現在已經使用了我們新的 JLayout ，而且位置調動到標題之上。如果需要的話，我們可以做更多的修改，像是新增響應式圖片之類的，改變會出現在分類部落格頁面上。

@@ Line 162: / Line 162: @@
 </source>
-This will override the core <tt>template_style_id</tt> parameter. Setting the template equal to "beez3" in this case will limit the user to only selecting template styles for the "beez3" template.
+這會覆寫核心的 <tt>template_style_id</tt> 參數，設定佈景主題為"beez3" ，這樣一來會限制用戶只能選擇佈景主題為 "beez3"。
 === JLayout 微型版面(Micro-Layout )覆蓋 ===

J3.x