建立一個基本的 Joomlaǃ 佈景主題

From Joomla! Documentation

This page is a translated version of the page Creating a basic Joomla! template and the translation is 87% complete.
Other languages:
Deutsch • ‎English • ‎Nederlands • ‎Türkçe • ‎español • ‎français • ‎русский • ‎中文（台灣）‎
This tutorial is for Joomla! CMS Version(s) Joomla 1.5 Joomla 2.5 Joomla 3.1
Split-icon.png
Split Page into Specific Joomla! Versions - J2.5 and 3.x

It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 3 years ago.

介紹

這篇教學的主要用意是作為一個創建 Joomla! 佈景主題的介紹。將會包含建立基本佈景主題所需要的基本檔案以及程式碼。所展示的程式碼可以複製、貼上來使用，但是也許會需要一些些的修改。

設置資料夾架構

要創建最「基本」的佈景主題，在 templates 裡面 新增一個資料夾。將資料夾名稱取為和你的佈景主題名稱相同，這裡取為 mynewtemplate。

使用你最喜歡的編輯器來新增 index.php 以及 templateDetails.xml 檔案。 為了方便整理，新增 2 個資料夾，將他們命名為 images 以及 css。 在 css 資料夾裡面新增一個叫作 template.css的檔案。

雖然可以將你所有的 CSS 直接放在 index.php 檔案的開頭，但是很多的網頁開發員都習慣將他們的CSS分開至別的檔案，這樣可以使用 link 標籤來將它們連接到多個頁面裡。將CSS放置分開的檔案也可以被新增到快取裡，這樣可以縮短讀取網頁的時間。

這是最基本所需要的設置。資料夾以及檔案的架構如下： 

* mynewtemplate/
** css/
*** template.css
** images/
** index.php
** templateDetails.xml


新增一個基本的 templateDetails.xml 檔案

templateDetails.xml 檔案是必要的，沒有它的話，Joomla! 將會找不到你的佈景主題。關於佈景主題檔案裡的關鍵 元資料(metadata)。

檔案的語法在每個版本的 Joomla 都不一樣。

Joomla 1.5 版的語法如下： 

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
	<name>mynewtemplate</name>
	<creationDate>2008-05-01</creationDate>
	<author>John Doe</author>
	<authorEmail>john@example.com</authorEmail>
	<authorUrl>http://www.example.com</authorUrl>
	<copyright>John Doe 2008</copyright>
	<license>GNU/GPL</license>
	<version>1.0.2</version>
	<description>My New Template</description>
	<files>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<folder>images</folder>
		<folder>css</folder>
	</files>
	<positions>
		<position>breadcrumb</position>
		<position>left</position>
		<position>right</position>
		<position>top</position>
		<position>user1</position>
		<position>user2</position>
		<position>user3</position>
		<position>user4</position>
		<position>footer</position>
	</positions>
</install>

Joomla 2.5版之後的語法如下。version="2.5" 更改了你安裝的 Joomla 的版本。 

<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="template">
	<name>mynewtemplate</name>
	<creationDate>2008-05-01</creationDate>
	<author>John Doe</author>
	<authorEmail>john@example.com</authorEmail>
	<authorUrl>http://www.example.com</authorUrl>
	<copyright>John Doe 2008</copyright>
	<license>GNU/GPL</license>
	<version>1.0.2</version>
	<description>My New Template</description>
	<files>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<folder>images</folder>
		<folder>css</folder>
	</files>
	<positions>
		<position>breadcrumb</position>
		<position>left</position>
		<position>right</position>
		<position>top</position>
		<position>user1</position>
		<position>user2</position>
		<position>user3</position>
		<position>user4</position>
		<position>footer</position>
	</positions>
</extension>

所以，你可以發現我們在標籤之中有一整套資訊 (在 <element> 中)。最簡單的方式就是複製貼上到你的 templateDetails.xml 檔案裡來進行修改 (例如 <name> 以及 <author>)。

<files> 部分應該要包含所有您會用到的檔案 - 此時，您可能不知道要怎麼列出全部，不過沒關係，晚一點再來做這一塊。<folder> 部分會用來定義資料夾。

先保留讓 position 這一塊 - 這是一些共用項目，這樣您可以更輕鬆地從標準佈景主題移轉過來。

新增基本的 index.php 檔案

The index.php file becomes the core of every page that Joomla! delivers. Essentially, you make a page (like any HTML page) but place PHP code where the content of your site should go. The template works by adding Joomla code into module positions and the component section in your template. Anything added to the template will appear on all pages unless it is added to one of these sections via the Joomla CMS (or customised code).

This page will show the bare-bones code ready for you to cut and paste into your own design.

Begin

A Joomla template begins with the following lines: 

<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" 
   xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >

The first line stops naughty people looking at your coding and getting up to bad things.

The second line is the Document Type Declaration (DOCTYPE), which tells the browser (and web crawlers) which flavor of HTML the page is using. The doctype used above is HTML5, a newer version of HTML that is largely backwards compatible, but contains many new features. You should be aware that this will not work well in Internet Explorer 8 or earlier without a hack. You might want to investigate this situation and your clients' wishes before deciding on which doctype you want to use. However this is used in Joomla Joomla 3.0 and higher.

The third line begins our HTML document and describes what language the website is in. A html document is divided into two parts, head and body. The head will contain the information about the document and the body will contain the website code which controls the layout.


Head

<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/css/template.css" type="text/css" />
</head>

The first line gets Joomla to put the correct header information in. This includes the page title, meta information as well as system JavaScript. The rest creates links to two system style sheets and to your own style sheet (if it's named template.css and is located in the css folder of your template directory. So if your template is in http://www.mysite.com/templates/my_template/ then the css files will go in http://www.mysite.com/templates/my_template/css/).

Body Section

<body>
<jdoc:include type="modules" name="top" /> 
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>

Amazingly, this will suffice! Yes, it's a very basic layout, but it will do the job. Everything else will be done by Joomla!. These lines, usually called jdoc statements, tell Joomla to include output from certain parts of the Joomla system. Note: you will need to ensure your menu is set to go into the "top" module position.

Module Positions

Above, the line which says name="top" adds a module position called top and allows Joomla to place modules into this section of the template. The type="component" line contains all articles and main content (actually, the component) and is very important. It goes in the centre of the template.

Note: You can add your own module lines anywhere you want in the body, but you have to add a corresponding line to the templateDetails.xml file which sits alongside the index.php of your template.

End

Finish it off - one last bit: 

</html>

Custom Images

If you want to add any images to the template you can do so like this: 

<img src="<?php echo $this->baseurl; ?>/templates/<?php echo $this->template; ?>/images/myimage.png" alt="Custom image" class="customImage" />

Here the template variable will fill in the name of your template.

Custom CSS

You can add custom css like this: 

<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template;?>/css/styles.css" type="text/css" />

Every file which is added must have a line in the templateDetails.xml file for the template, unless it resides in a sub-folder (which can be included in a <folder> element).


最後檔案長得像這樣子： 

<?php defined('_JEXEC') or die('Restricted access');?>
<!DOCTYPE html>
<html xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template ?>/css/template.css" type="text/css" />
</head>
<body>
<jdoc:include type="modules" name="top" /> 
<jdoc:include type="component" />
<jdoc:include type="modules" name="footer" />
</body>
</html>

測試佈景主題

從佈景主題管理中找到你的佈景主題，選取它並且按下「預設」來將它設置成目前的佈景主題。

Joomla 1.5 在 Joomla! 1.5，你的新佈景主題將會直接在 Template Manager 中出現，可以在擴充 -> 佈景主題管理中找到。

Joomla 2.5+ In the Joomla! 2.5 series and later, you first need to tell Joomla! that you have created a new template. This feature is called Discover Extensions and can be accessed via Extensions -> Extension Manager -> Discover (i.e. the Discover tab). Click Discover (i.e. the Discover button) to discover your template, then select it and click Install to install it. Now your template should show up in the Template Manager (Styles), accessible via Extensions -> Template Manager.

Note you can create your template outside of Joomla and simply install it like any regular extension.

HINT: there are a couple of ways you can preview your index page as you put it together, either insert the styles into the head of the index page or directly link it to the style sheet you will be using temporarily. You can remove these links before packaging the file.

將佈景主題封裝成安裝包

A directory with several loose files is not a convenient package for distribution. So the final step is to make a package. This is a compressed archive containing the directory structure and all the files. The package can be in ZIP format (with a .zip extension), in TAR-gzip format (with a .tar.gz extension), or in TAR-bz2 format (with a .tar.bz2 extension).

If your template is in a directory mytemplate/ then to make the package you can connect to that directory and use commands like:

  • tar cvvzf ../mytemplate.tar.gz *
  • zip -r ..\mytemplate.zip *.*

Note to Mac OS X users

Note to template developers using Mac OS X systems: the Finder's "compress" menu item produces a usable ZIP format package, but with one catch. It stores the files in AppleDouble format, adding extra files with names beginning with "._". Thus it adds a file named "._templateDetails.xml", which Joomla 1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4: Empty document". The workaround is to compress from the command line, and set a shell environment variable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See the AppleDouble article for more information.

To set an environment variable on a Mac, open a terminal window and type: 

export COPYFILE_DISABLE=true

Then in the same terminal window, change directories into where your template files reside and issue the zip command. For instance, if your template files have been built in a folder in your personal directory called myTemplate, then you would do the following: 

cd myTemplate
zip -r myTemplate.zip *


結論

You should now have created a template that works. It won't look like much yet. The best thing to do now is start experimenting with the layout.

Retrieved from "https://docs.joomla.org/index.php?title=Creating_a_basic_Joomla!_template/zh-tw&oldid=781596"