舊文件

此處文件僅供參考,請自行考量時效性與適用程度,其他庫藏文件請參考文件頁面
我們亟需您的協助,進行共筆系統搬移、及文件整理工作,詳情請查閱參與我們

「套件開發指南 - Googlebar Lite」修訂間的差異

出自 MozTW Wiki

話說在開始之前 (Before We Start)
Chrome 清單 (Chrome Manifest)
行 196: 行 196:
 
       +- content/
 
       +- content/
 
</pre>
 
</pre>
與早先使用的 contents.rdf (通常超過20行) 比較,現在的方式變得非常簡單!第一行使用你指定的封裝名稱來登錄,並指明放置在 content 目錄。這將允許 chrome 資源識別字串(Uniform Resource Identifier,簡稱 URI) ,如 '''chrome://myextension/content/''',在我們的套件層級中指向適當的地方。注意到,content 目錄的位置是相對於套件的根目錄。在這份指南,我們使用 tuttoolbar 當作封裝名稱。
+
與早先使用的 contents.rdf (通常超過20行) 比較,現在的方式變得非常簡單!第一行使用你指定的封裝名稱來登錄,並指明放置在 content 目錄。這將允許 chrome 資源識別字串(Uniform Resource Identifier,簡稱 URI) ,如 '''chrome://myextension/content/''',在我們的套件層級中指向適當的地方。
  
第二行登錄 '''chrome://browser/content/browser.xul''' 的覆載(overlay)。這允許你新增或修改 Firefox 主視窗的使用者介面(user interface)。
+
注意到,'''content''' 目錄的位置是相對於套件的根目錄。在這份指南,我們使用 '''tuttoolbar''' 當作封裝名稱。
在上面的範例,'''chrome://myextension/content/overlay.xul''' 指定了覆載(overlay)的XUL 檔案。換句話說,位於套件中 content 目錄的 overlay.xul 檔案,是我們將要新增的使用者介面(工具列)。在這個部份,我們要使用的值為 '''chrome://tuttoolbar/content/tuttoolbar.xul''' 。
+
 
 +
第二行登錄 '''chrome://browser/content/browser.xul''' 的覆載(overlay),這允許你新增或修改 Firefox 主視窗的使用者介面(user interface)。
 +
 
 +
在上面的範例,'''chrome://myextension/content/overlay.xul''' 指定了覆載(overlay)的XUL 檔案。
 +
 
 +
換句話說,位於套件中 content 目錄的 overlay.xul 檔案,是我們將要新增的使用者介面(工具列)。在這個部份,我們要使用的值為 '''chrome://tuttoolbar/content/tuttoolbar.xul''' 。
 
下一行說明地區化如何建立(how a locale can be created)。在這份指南中,我們不設計地區化(雖然過程很簡單),這將在未來再做討論。
 
下一行說明地區化如何建立(how a locale can be created)。在這份指南中,我們不設計地區化(雖然過程很簡單),這將在未來再做討論。
  

於 2006年3月17日 (五) 02:08 的修訂

翻譯進度:2/6

排版有點亂,請幫忙調整!--chkuya 00:14 2006年三月17日 (CST)

原文: Creating a Firefox Toolbar Extension (Firefox 1.5)

前言 (Instruction)

這份指南將說明如何建立 Firefox 的工具列套件(支援 1.5 或更新的版本)。這份文件提供套件如何開發的概要、必要的工具、以及建立工具列的細節。

套件開發是不難的,儘管必須具備某些基礎的程式設計知識。

有三種技術是我建議你必須稍微熟悉的:XML、JavaScript、CSS。這三個技術學習起來都不難,而且網路上有許多不錯的教學。

Firefox 1.5 版在套件開發上有很大的改善,這個版本比先前的版本更容易建立套件。 這份指南利用了改善的部份,必要時,我會指出變動的部份。

如果你發現錯誤的地方,或是有任何建議,請聯絡作者

第一章:準備開始 (Getting Started)

在我們開始製作第一份工具列套件之前,有一些非常有用的東西是你必須要先知道的。

下載指南 (Tutorial Downloads)

在這份指南的最後,我們將建立一個 Googlebar Lite 的簡化版本。為了幫助過程的學習,你可以下載這個工具列的開發版本。兩份可得到的版本:

  • Example Toolbar XPI : 這是我們將要建立的套件的安裝版本。
  • Example Toolbar Source Code (即將完成): 這份 zip 檔案包含建立工具列的原始碼。

注意到這份 xpi 檔案也包含了原始碼。技術上而言,你只要下載 xpi 的檔案,並用 zip 的解壓縮程式解開 xpi 檔,以及其中的 jar 檔。第二份檔案只是為了方便而已。

有用的參考文獻 (Useful References)

我強烈建議你將下列的網址加入書籤,在我學習套件開發的過程,這些網頁對我非常的有幫助,我相信對你來說也是。(前四項為原作者提供)

必需先學習的 (Learning the Prerequisites)

如我之前所提到的,Firefox 套件開發需要先知道一點關於 XML、JavaScript、及CSS 的技術。這三個主題都是相當容易了解的,我也會提供了一些關於這三項技術的說明。

你將會需要的工具 (Tools You Will Need)

為了設計套件,你需要幾個工具軟體,這些軟體都是免費可取得的。我們要設計的幾個檔案都是標準文字檔。因此,你需要一個不錯的文字編輯器。我強烈反對使用類似 Microsoft Word 的程式。網路上有一些傑出的免費程式設計文字編輯器,這些編輯器對你有非常大的幫助,例如自動縮排、強調語法等等。幾個受歡迎的編輯器包含 Crimson EditorTextPad、及 JCreator

第二個你會用到的工具是 zip 檔的壓縮軟體。雖然有其他需多有用的工具,像是 7-Zip、及 WinRAR,但我個人是使用 WinZip。當封裝套件時,我們會用到這個工具。如果你打算做很多套件的開發,我建議你找有命令列介面的壓縮工具。使用命令列可以輕易地將封裝過程自動化,也省下你大量的時間。

檔案結構佈局 (File Structure Layout)

套件開發需要特定的內部結構,所以我們必須確定這一步是正確的。否則,將不會發生作用。首先,為我們的套件建立最上層的目錄。在這份指南,我們會使用 TutToolbar 當作目錄名稱(避免使用空白文字)。在這個新建立好的 TutToolbar 目錄裡,我們需要再建立第二個目錄。這個目錄命名為 chrome (使用小寫) 。既然我們這麼喜歡建立目錄,那就再來建立第三個吧!這次在 chrome 目錄裡建立一個名稱為 content 的目錄(使用小寫)。這裡是我們的目錄結構看起來的樣子:

+- TutToolbar/
   +- chrome/
      +- content/

或者是

TutToolbar/
TutToolbar/chrome/
TutToolbar/chrome/content/

第二章:建立架構(Creating the Framework)

套件的架構是用來告訴 Firefox 套件是如何被延伸的:檔案的結構、被誰建立、或是套件的全球唯一代號(GUID)。在 Firefox 1.5 這個版本,套件開發在這個部份有很大的變化。原本在 1.0.x 版是很沈重的技巧,在 1.5 版已經變得更整潔、更簡單。

安裝清單 (Installer Manifest)

這份清單是用來提供 Firefox 關於套件的細節。有一些重要的項目放置在這個檔案,所以我們必須確定這部份是正確的。在你的最上層目錄裡,建立一個檔案 install.rdf 。當你建立好這個檔案,你會看到這樣的結構:

+- TutToolbar/
   +- install.rdf
   +- chrome/
      +- content/

在我們開工前,讓我們看看這個範例。所有我們必須編輯的部份已經被突顯出來了,沒有被突顯的部份是不可以修改的。接著,我們來看這份檔案的內容,我將會解釋每個部份的細節,而且可以開始編輯屬於自己的套件。

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="http://www.mozilla.org/2004/em-rdf#">

<Description about="urn:mozilla:install-manifest">

<!-- Required Items -->
<em:id>yourextension@yoursite.com</em:id>
<em:name>Your Extension's Name</em:name>
<em:version>1.0</em:version>

<em:targetApplication>
    <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>1.5.0.*</em:maxVersion>
    </Description>
</em:targetApplication>

<!-- Optional Items -->
<em:creator>Your Name</em:creator>
<em:description>A description of the extension</em:description>
<em:homepageURL>http://www.yoursite.com/</em:homepageURL>

</Description>
</RDF>

在最上面第一行表示這是一份 XML 格式的檔案。第二行,以 <RDF> 開頭的,是這份文件的基本元素(root element)。它的責任是辨別這部份是 RDF (Resource Description Framework) 格式。下一個標籤(Tag) <Description> 同樣地是用來辨別為安裝清單。現在,乏味的東西都結束了,讓我們看看第一部份必須要編輯的:

<em:id>yourextension@yoursite.com</em:id>
<em:name>Your Extension's Name</em:name>
<em:version>1.0</em:version>

第一個我們需要擔心的是套件的識別號碼。在 Firefox 1.5 之前的版本,必須使用全球唯一代號(globally unique identifier),即 GUID。儘管 GUID 還是被支援的,新的格式卻更容易使用。僅僅需要使用你的套件名稱,@ 符號,再加上你的網站的最上層網址。在這份指南中,我們為這個工具列使用這個值 tuttoolbar@borngeek.com

接著是套件的名稱(這會顯示在套件管理員裡)。在我們的範例裡,使用 Toolbar Tutorial 為這個套件的名稱。確定這個名稱不包含版本編號,因為版本編號有它自己專屬的標籤。我們要編輯的這個標籤就在下一行。既然這是我們試圖要做的第一個工具列套件,讓這個值為 1.0 。要注意到,在真實的情況裡,當你發表新版本的套件時,必須更新這個值,描述解譯程式(Scripter)在自動更新過程才不會發生問題。在我的套件裡,我利用了描述語法 (以 Perl 寫成)。在這份指南的第七章,我將會告訴你我如何使用。

下一個區塊也是這個安裝清單重要的一部分,接著來看看這部份:

<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>1.5.0.*</em:maxVersion>
</Description>
</em:targetApplication>

這個區塊是用來指示套件要用在哪個程式。在這個例子,我們要開發 Firefox 的套件。因此,<em:id> 這個元素指定了 Firefox 的 GUID 。你不應該改變這個值,否則,會讓你的套件無法被正確地安裝。

唯一兩個我們需要變動的,是這兩個元素:<em:minVersion><em:maxVersion> 。這兩個元素指明套件適合用在 Firefox 的哪個版本 ( minVersion 是最低支援版本,而 maxVersion 是最高支援版本) 。 在我們的範例,我們會使用 1.5 (minVersion) 與 1.5.0.* (maxVersion)。因為我們利用 Firefox 1.5 的開發環境,所以不可以把 minVersion 設定的比 1.5 還小。

注意到,你所使用的版本編號必須遵守標準協定。舉個例子,「1.5 Release Candidate 1」是不行的。目前 Firefox 的版本結構是相當嚴謹的,在 Mozilla Developer Center 的文章 Toolkit Version Format 有詳細的描述。我建議你讀這篇文章,以了解怎樣的字串是被允許的。

在安裝清單的最後,是用來描述套件的資料定義,或稱中繼資料(meta-data):

<!-- Optional Items -->
<em:creator>Your Name</em:creator>
<em:description>A description of the extension</em:description>
<em:homepageURL>http://www.yoursite.com/</em:homepageURL>

就如註釋一樣,這些元素是非必要的。<em:creator> 允許套件作者指明自己的名字,這樣別人就知道是誰製作這個套件。下一個,<em:description> 允許我們對我們的套件做一些說明,這個說明會顯示在套件管理員中的套件名稱底下。最後,<em:homepageURL> 允許我們指明別人可以在哪裡找到我們的套件。

注意到,這些不是唯一的資料定義,同時也有許多其他可選用的項目。舉個例子,有個元素可以在套件管理員中使用我們自己的圖示(icon)。 另一個元素允許我們指定自訂選項的位置或是「關於」的對話視窗。全部可用的元素(也叫做屬性 properties ),可以看看在Mozilla Developer Center 中的文章 Installer Manifests 。最後一點要注意的,所有的元素是不需要按照順序的。也就是說,你可以將它們放在檔案中任何地方,僅僅要注意的是,將它們放置在 <Description></Description> 之間。

現在,我們了解了安裝清單,讓我們來看看最後的樣子,這個版本將被使用在這份指南中。你可以直接將下面的部份,複製在 install.rdf 中。

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="http://www.mozilla.org/2004/em-rdf#">

<Description about="urn:mozilla:install-manifest">

 <!-- Required Items -->
 <em:id>tuttoolbar@borngeek.com</em:id>
 <em:name>Tutorial Toolbar</em:name>
 <em:version>1.0</em:version>

 <em:targetApplication>
     <Description>
         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
         <em:minVersion>1.5</em:minVersion>
         <em:maxVersion>1.5.0.*</em:maxVersion>
     </Description>
 </em:targetApplication>

 <!-- Optional Items -->
 <em:creator>Jonah Bishop</em:creator>
 <em:description>An example toolbar extension.</em:description>
 <em:homepageURL>http://www.borngeek.com/firefox/</em:homepageURL>

</Description>
</RDF>

Chrome 清單 (Chrome Manifest)

Chrome 清單是 Firefox 1.5 才開始有的。在之前,所有的資料被設定在兩個地方:安裝清單(installer manifest)、及 contents.rdf 。而現在,新的格式顯得更簡單。再次在最上層目錄建立另外一個檔案 chrome.manifest 。下面是檔案結構看起來的樣子:

+- TutToolbar/
   +- install.rdf
   +- chrome.manifest
   +- chrome/
      +- content/

與早先使用的 contents.rdf (通常超過20行) 比較,現在的方式變得非常簡單!第一行使用你指定的封裝名稱來登錄,並指明放置在 content 目錄。這將允許 chrome 資源識別字串(Uniform Resource Identifier,簡稱 URI) ,如 chrome://myextension/content/,在我們的套件層級中指向適當的地方。

注意到,content 目錄的位置是相對於套件的根目錄。在這份指南,我們使用 tuttoolbar 當作封裝名稱。

第二行登錄 chrome://browser/content/browser.xul 的覆載(overlay),這允許你新增或修改 Firefox 主視窗的使用者介面(user interface)。

在上面的範例,chrome://myextension/content/overlay.xul 指定了覆載(overlay)的XUL 檔案。

換句話說,位於套件中 content 目錄的 overlay.xul 檔案,是我們將要新增的使用者介面(工具列)。在這個部份,我們要使用的值為 chrome://tuttoolbar/content/tuttoolbar.xul 。 下一行說明地區化如何建立(how a locale can be created)。在這份指南中,我們不設計地區化(雖然過程很簡單),這將在未來再做討論。

最後一行設定了面板(skin),我們將使用這個技巧來美化我們的工具列。現在,先略過它,我們將在第五章再回來討論這點。 一切都很簡單,不是嘛?下面是我們將會使用的 chrome 清單,這只是半成品,之後我們將會加入面板的資訊。再一次,將下面的程式碼複製到我們剛剛建立的 chrome.manifest

content tuttoolbar chrome/content/
overlay chrome://browser/content/browser.xul chrome://tuttoolbar/content/tuttoolbar.xul

現在架構已經可以了,接著讓我們來做些有趣的事吧!

個人工具