原文: [http://www.borngeek.com/firefox/toolbar-tutorial/ Creating a Firefox Toolbar Extension (Firefox 1.5)][已授權]

作者 [http://www.borngeek.com/about/ Born Geek]

= 前言 (Instruction) =

這份指南將說明如何建立 Firefox 的工具列套件(支援 1.5 或更新的版本)。

Firefox 1.5 版在套件開發上有很大的改善，這個版本比先前的版本更容易建立套件。 這份指南利用了改善的部份，必要時，我會指出變動的部份。如果你發現錯誤的地方，或是有任何建議，請[http://www.borngeek.com/contact/ 聯絡作者]。

= 第一章：準備開始 (Getting Started) =

== 開始之前 (Before We Start)==

=== 下載指南 (Tutorial Downloads) ===

在這份指南的最後，我們將建立一個 [http://www.borngeek.com/firefox/googlebarlite/ Googlebar Lite] 的簡化版本。為了對過程的學習有所幫助，你可以下載這個工具列的開發版本。兩份可得到的版本：

* [http://www.borngeek.com/firefox/toolbar-tutorial/samples/tuttoolbar.xpi Example Toolbar XPI] : 這是我們將要建立的套件的安裝版本。

* [http://www.borngeek.com/firefox/toolbar-tutorial/samples/tuttoolbar.zip Example Toolbar Source Code]: 這份 zip 檔案包含建立工具列的原始碼。

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

=== 有用的參考文獻 (Useful References) ===

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

* [http://xulplanet.com/references/elemref/ XUL Planet Element Reference](英)

* [http://forums.mozillazine.org/viewforum.php?f=19 MozillaZine Extension Development Forum](英)

* [http://lxr.mozilla.org/mozilla1.8.0/ Search the Firefox Source Code](英)

* [http://roachfiend.com/archives/2004/12/08/how-to-create-firefox-extensions/ roachfiend.com Extension Tutorial](英)

* [http://developer.mozilla.org/en/docs/Building_an_Extension Building an Extension - Mozilla Developer Center](英)

* [http://marvel.hit.edu.cn:8080/text/firefox/Hello%20World%20Firefox.htm 劉文懋 » Hello World——開發你的第一個Firefox擴展](簡)

* [http://blog.donews.com/limodou/category/35193.aspx?PageNumber=4 limodou的學習記錄 - XUL](簡)

* [http://itart.wordpress.com/mozilla-ext/ The Art of IT » 基於 Mozilla 的擴展開發](簡)

=== 必需先學習的 (Learning the Prerequisites) ===

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

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

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

== 檔案結構佈局 (File Structure Layout) ==

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

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

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

== 安裝清單 (Installer Manifest) ==

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

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

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

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

這個區塊是用來指示套件要用在哪個程式。在這個例子，我們要開發 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 的文章 [http://developer.mozilla.org/en/docs/Toolkit_version_format Toolkit Version Format] 有詳細的描述。我建議你讀這篇文章，以了解怎樣的字串是被允許的。

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

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

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

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

== Chrome 清單 (Chrome Manifest) ==

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

Chrome 清單是用來告訴 Firefox ，我們的套件提供的封裝(package)與覆載(overlay)。在我們開始建立之前，先看個範例：

與早先使用的 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''' 。

= 第三章：建構工具列 (Structuring the Toolbar) =

Firefox 套件的使用者介面部份是使用 XUL 技術 (音：zool)，這是一種用來設計使用者介面的標示語言。XUL 可以想成是一種 XML 的調味料(意旨有附加功能的)， 它不過是使用預設元素的 XML (也叫做 widgets)。使用 XUL 的好處，是因為它使用了'''動態覆載(dynamic overlays)'''的技術。動態覆載技術可以讓開發者'''不需要'''改變原本介面的程式碼的情況下，去修改視窗的使用者介面。在不需更動原始程式碼的情況下，可以讓我們專注於設計我們的套件，而不用擔心需要重複開發的問題。在這個章節，我們要來看看設計工具列的 XUL 必要標示。記住，XUL 僅僅是用來建構工具列而已。為了讓工具列可以運作，我們必須使用 JavaScript ，這部份將在第六章提到。

在 '''content''' 目錄裡，建立一個檔名為 '''tuttoolbar.xul''' 的檔案。在你建立好之後，目錄的結構會是這樣：

因為 XUL 只是一種 XML 的調味料，所以第一行必須是使用 XML 的宣告：

現在，宣告這是一個 XML 的檔案之後，我們就可以開始藉由 '''overlay''' 元素設計覆載了。這個元素將會是這整份文件的根元素。換句話說，所有其他的元素必須在 <overlay> 與 </overlay> 之間。這是 '''overlay''' 看起來的樣子：

這個元素有兩個屬性：'''id''' 與 '''xmlns''' 。這跟 HTML 類似，'''id''' 的值'''必須是唯一'''的。更重要的是，這也必須是'''整個瀏覽器'''唯一的值。這裡有一個可以讓你確定所使用的 ID 是唯一的方法。例如，上面的範例。你可以注意到我使用了 '''TutTB''' 開頭的字眼來定義 id 屬性的值。使用符合你的套件名稱開頭的字眼，這會使 ID 是唯一的可能性提高。並且注意到，實際的值是不需要包含 overlay 的字眼，我這麼做是方便我追蹤所使用的名稱是做什麼用的。

第二個屬性：'''xmlns'''，用來指定使用於覆載的命名空間。既然這是 XUL 文件，我們必須定義 XUL 的命名空間，這是你會'''一直'''用到的值。

== 工具箱與工具列 (The Toolbox and Toolbar) ==

所有的工具列應該被集中在工具箱中。我們使用 '''toolbox''' 元素來指定一個工具箱(記住，這個元素必須被放置在 '''overlay''' 之間。)：

注意到，這個 id 屬性有一個預設值：'''navigator-toolbox''' 。 這個特定的值表示為 Firefox 視窗中主要的工具箱元素，跟瀏覽工具列、選單列、網址列，或是其他類似的控制選項一樣。藉由指定這個特別的工具列，我們可以確定這個工具列會與其他的工具列靠攏在一起。我建議你總是讓你的工具列放在這個特定的工具箱中，這不只讓你有看起來一致的工具列，也可以讓你在 「檢視>工具列」 中，快速地將你的工具列隱藏或是顯示。

讓我們將注意力放回到 '''toolbar''' 元素，我們會將這個元素放在 '''toolbox''' 之中。看看這個範例：

* '''toolbarname''' - 這個元素指定套件的名稱(這會是你在「檢視>工具列」看到的文字)。

* '''accesskey''' - 給這個工具列指定字母，用來當作快速鍵使用。在這個工具列指南中，我們使用大寫的 T 。雖然這是非必要的屬性，還是強烈建議你使用它，這能讓使用者只要用快速鍵就能開啟或關閉你的工具列。

* '''class''' - 為工具列指定特定的樣式類別。預設值 '''chromeclass-toolbar''' 是用來規範工具列顯示模式的類別，同樣地，這是建議使用的非必要屬性。

* '''context''' - 指定當在工具列上按右鍵時，所顯示的工具列選單(context menu)。你可以提供你的選單 ID 值，或是使用 '''toolbar-context-menu''' 來將選單放置在「檢視 > 工具列」。

* '''hidden''' - 指定工具列是否隱藏。預設的情況下，我們要讓使用者看見我們的工具列，所以設定這個值為 false (相反為 ture )。

* '''persist''' - This attribute is a space separated list of attributes that should persist across browser sessions. 在上面的範例，我使用 hidden ，用來告訴 Firefox 在 sessions 記住工具列的隱藏狀態。注意到，如果你的工具列沒有使用 id 屬性，則 persist 屬性不會發生作用！所以要確定你有為你的工具列指定 id 元素。

你可以在 XUL Planet [http://xulplanet.com/references/elemref/ref_toolbar.html toolbar element's attributes] 看到完整的參考文獻。

現在，讓我們來看看建立好的覆載檔案[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-a.txt View XUL Overlay Revision 1]]：

== 工具列按鈕 (Toolbar Buttons) ==

在 Firefox 中，工具列按鈕有三種：一般、選單、按鈕選單。這些都是用 '''toolbarbutton''' 來建立的，讓我們來分別看看。記住，這些元素必須放在 '''toolbar''' 元素之中。

=== 一般按鈕 (Normal Buttons) ===

* '''tooltiptext''' - 當滑鼠移動到按鈕上時出現的說明。

* '''label''' - 工具列按鈕顯示的文字。

* '''oncommand''' - 當 '''oncommand''' 事件觸發時(按下按鈕)，你所指定的程式碼。在這個範例，使用 '''TutTB_Search()'''函式，我們將在第六章詳細說明。

你可以在 XUL Planet [http://xulplanet.com/references/elemref/ref_toolbarbutton.html toolbarbutton element's attributes] 找到完整的參考文獻。

=== 選單按鈕 (Menu Buttons) ===

當點擊按鈕選單時，會出現下拉式選單。 儘管這個按鈕標記類似一般按鈕標記，我們還是必須加入 '''menupopup''' 元素，讓選單以我們想要的樣子出現。為了簡潔點，下面的範例只包含兩個選單項目。

'''toolbarbutton''' 有兩個要注意的變化。第一，'''type''' 屬性指定了 menu 的值，說明了這是個選單按鈕，而不是一般按鈕。第二，你會注意到這裡面沒有 '''oncommand''' 屬性。因為選單按鈕的唯一目的是為了顯示跳出式選單，並不需要執行任何程式碼，而顯示選單的動作會由 Firefox 自動完成。

也請注意到 '''menupopup''' ，'''menuitem''' ，'''menuseparator''' 這三個元素。'''menupopup''' 所有選單項目的容器，用來建立與顯示選單。在這個範例裡，這個元素沒有屬性。同樣地，'''menuseparator''' 也很簡單，在下拉式選單中放置水平分隔線，用來分隔不同的選單。

'''menuitem''' 稍微有點複雜。在上面的範例，我們指定的屬性：

* '''label''' - 指定選單項目的文字。

* '''tooltiptext''' - 這個屬性就像是我們在 '''toolbarbutton''' 看到的，但是有一點要警告的。由於 Firefox 的 bug ([https://bugzilla.mozilla.org/show_bug.cgi?id=147670 bug #147670])，這個屬性是必要的。如果你決定從 '''menuitem''' 中刪掉這個屬性，當使用者將滑鼠移動到選單項目時，會看不到提示說明。選單不會顯示工具提示，這真是個令人不滿意的「特色」！

你可以在 XUL Planet [http://xulplanet.com/references/elemref/ref_menuitem.html menuitem element's attributes] 找到完整的參考文獻。

=== 按鈕選單 (Button-Menu Buttons) ===

有兩個值得注意的變化：在 '''toolbarbutton''' 的 '''type''' 屬性指定了值 '''menu-button''' ，而且有另外一行程式碼 '''oncommand''' ，我會在第六章解釋這額外的程式碼。接著注意到，這裡有跟「一般按鈕」一樣的 '''toolbarbutton''' 有 '''oncommand''' 屬性，以及在「選單按鈕」裡的巢狀元素 '''menupopup''' 與 '''menuitem''' 。

現在，我們討論完不同的按鈕，來看看程式碼的樣子[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-b.txt View XUL Overlay Revision 2]]：

== 下拉式編輯列 (Drop-Down Edit Box) ==

下一個我們要在工具列加入的是下拉式編輯列。這是用 '''menulist''' 來建立的，讓我們來看看程式碼：

注意到，我們把 '''menulist''' 放在 '''toolbaritem''' 之中。任何一個在 '''toolbar''' 的項目都不是工具列按鈕，在 '''toolbaritem''' 裡頭的才是。也請注意到，我們為 '''toolbaritem''' 指定了 '''id''' ，且設定了寬度(藉由利用了 '''persist''' 屬性)。

'''menulist''' 才是真正用來建立下拉式編輯列的。有幾個在這個元素出現的新屬性：

* '''editable''' - 當設定為 true 時，使用者可以在編輯列中打字。

* '''flex''' - 使這個元素是可變動的。這是個整數值，相對於其他可變動工具列元素，指定其大小。設定值 2 代表著設定值 1 的兩倍寬，0 則是不能變動的固定寬度。

* '''minwidth''' - 最小寬度，單位為像素。

* '''width''' - 初始寬度，單位為像素。

* '''onkeypress''' - 當使用者輸入文字時，用來執行的程式碼。

你可以在 XUL Planet [http://xulplanet.com/references/elemref/ref_menulist.html menulist element's attributes] 看到完整的參考文獻。

跟我們之前看到的「選單按鈕」一樣，在 '''menulist''' 裡的 '''menupopup''' 包含了 menuitem 元素。'''onpopupshowing''' 這個事件會在編輯列的選單項目顯示前觸發，其中指定一個能動態寫入選單項目的函式，這個函式我們稍後會提及。你也可以加入靜態的選單，過程跟「選單按鈕」是一樣的。

現在，這個套件已經變得更具體一點了，讓我們來看看程式碼[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-c.txt View XUL Overlay Revision 3]]：

== 可調整的移駐標記 (Resizing Gripper) ==

還記得之前包含在 '''menulist''' 中 '''toolbaritem''' 元素所提到的 '''persist''' 屬性嗎？設定這個屬性以讓我們在瀏覽器使用期間，可以儲存搜尋列的寬度。為了讓使用者可以改變寬度，我們要提供 '''移駐標記''' 。用來做這件事的元素是 '''splitter''' ，讓我們來看看程式碼：

這是 '''splitter''' 的屬性：

* '''state''' - 指定切割標記是否摺疊(隱藏)內容， open 值指定不管是否有內容皆顯示。

* '''collapse''' - 決定哪邊的 splitter 被隱藏。我們使用 none ，不讓任何一邊的 splitter 被隱藏。

* '''resizebefore''' - 當 splitter 改變時，指定 splitter 左邊的哪個元素必須被重新調整。當 splitter 移動時，使用 closest 來重新調整最靠近 splitter 左邊的編輯列。

* '''resizeafter''' - 當 splitter 改變時，指定 splitter 右邊的哪個元素必須被重新調整。在這個範例裡，我們使用 farthest 來重新調整最右邊的彈性空間。

vbox 是用來設定樣式的，我們會在第五章討論面板時，提到這點。

你可以在 XUL Planet [http://xulplanet.com/references/elemref/ref_splitter.html splitter element's attributes] 看到更完整的參考文獻。

讓我們來看看包含 '''splitter''' 與 '''toolbaritem''' 的覆載程式碼[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-d.txt View XUL Overlay Revision 4]]：

為了避免移駐標記討厭的細微顯示問題，我們還需要建立額外的 '''toolbaritem''' ，這與我們剛剛在「選單按鈕」中的搜尋按鈕所做的一樣。 再一次確定 flex 屬性的值為 0，這將會避免，當我們的選單按鈕被拖曳到左邊時被移除。

接著，讓我們再來增加兩個項目。首先，將 '''toolbarseparator''' 放置在最後兩個按鈕中，此目的是為了裝飾。再來，將 '''toolbarspring''' 放置在最後的 toolbaritem 元素之後。This spring will allow us to drag the resizer all the way to the right, so that we can see the full resizing effect in action. 這兩個標示是很簡單的，像是這樣：

讓我們來看看完整的覆載範例[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-e.txt View XUL Overlay Revision 5]]：

= 第四章：動態開發 (Dynamic Development) =

(譯者：如果不想用此開發環境，可以略過此章，並用第七章的方式測試套件。)

在 Firefox 1.5 中，動態套件開發是新的技術，對開發者而言，這是最有用的附加功能。這項技術可以讓你在開發套件時，即時地看到結果。當你要測試 XUL 覆載或是 JavaScript 程式碼時，不用每次再重新封裝套件。這不只節省了你的時間，也讓你能更快速地除錯。

那麼，這項特色是如何運作的呢？這就要感謝我們在第二章建立的 chrome 清單了。直到現在為止，我都還沒跟你說 chrome 清單試作甚麼用途。在這個指南中，我們一開始建立的版本就是'''特別'''為動態開發而設計的。換言之，我們不必重新封裝那份版本的套件，但還是有些改變需要完成，才可以封裝。有幾個用來「啟動」套件動態開發的步驟，在那之前，我要先給你幾個建議。

== 注意事項 (A Word of Warning) ==

套件開發有時會有點危險，尤其是設計 XUL 覆載檔案時。我'''強烈建議'''你要避免開發套件跟平常瀏覽網頁共用一個設定檔(profile)。換言之，'''你必須為你的開發環境建立一個新的設定檔'''。這可以避免你失去一些關鍵的資料，如：儲存的密碼、cookies、書籤或是其他你不想遺失的東西。

我希望能儘快 Born Geek 在發表關於如何建立與使用設定檔的教學。在那之前，你可以先看看在 Mozilla.org 的[http://www.mozilla.org/support/firefox/profile 設定檔文件]。建立與使用設定檔是很簡單的，這會避免讓你頭痛的情況發生。

== 如何動態開發 (How to Develop Dynamically) ==

最主要的工作，我們已經在 chrome 清單完成(即使你還不了解我們那時做了什麼)。現在，我們需要的，是一個將 Firefox 指向硬碟上套件位置的檔案，我們將藉由 pointer 檔案來完成。

首先，在你的電腦的隨便一個地方，以我們在安裝清單(install manifest)中所使用的 GUID 名稱，建立一個文字檔。在這份指南中，我們使用 '''tuttoolbar@borngeek.com''' 作為檔名。不幸的是，在微軟視窗環境裡，「.com」的檔案是被用來當作執行檔，而我們需要的是文字檔。你可以把「.com」拿掉，但也記得去修改在安裝清單的 GUID，確保兩個名稱是一樣的。

在這個檔案裡，我們將要輸入一行文字：套件儲存的絕對位置，也就是存放 '''install.rdf''' 與 '''chrome.manifest''' 檔案的目錄。在我的例子，儲存路徑如下：

現在，我們必須將這個檔案移動到跟開發環境的設定檔(profile)同一個目錄(如：C:\Documents and Settings\Administrator\Application Data\Mozilla\Firefox\Profiles)。我剛剛提到的[http://www.mozilla.org/support/firefox/profile 設定檔文件]會討論到設定檔目錄的位置。當你找到設定檔目錄時，將我們剛剛建立的 pointer 檔案移動到該目錄的 extensions 目錄下。這是我的例子：

你可以看到我的設定檔最上層目錄，我使用以「Nightly」為名的設定檔，來作為我的套件開發環境。一旦你把 pointer 檔案放在適當的位置，開啟 Firefox，確定你使用的是套件開發的設定檔(再次提醒，剛剛提到的設定檔文件會告訴你如何這樣做)。 到目前為止，如果你每樣都做的正確，你會看到沒有面板的灰色工具列。

== 開發週期 (The Development Cycle) ==

#編輯你的套件檔案

#重新開啟已更改檔案所套用的視窗，或是使用 [http://ted.mielczarek.org/code/mozilla/extensiondev/index.html Extension Developer's Extension] 的重新整理('''Reload Chrome''')。

*如果你改變了 '''chrome.manifest''' 檔案，你必須重新開啟 Firefox (這個檔案只有在程式啟動時會發生作用)。

*如果你改變了 '''install.rdf''' 檔案，你必須改變 pointer 檔案所指向目錄的修改時間。在 Linux 中，你只要使用 '''touch''' 指令。而在 Windows 裡就有點難度，除非你安裝了可以使用 '''touch''' 指令的 [http://www.cygwin.com/ Cygwin] 工具。唯一要做的，就是在套件最上層目錄建立一個新目錄，然後刪除新目錄以改變目錄的「上一次修改」時間。

你可以看到，我們有了方便的開發與除錯工具。這勝過於，在 1.5 版之前的標準過程，就是每次在套件開發過程都要封裝檔案。

= 第五章：面板製作 (Skinning the Toolbar) =

== 更新檔案結構 (Updating the File Structure) ==

設計面板的第一步就是建立一個目錄，用來存放關於面板的檔案。在 '''chrome''' 目錄下建立一個 '''skin''' 目錄。檔案結構會像這樣：

現在我們有存放面板檔案的地方了，之後必須要在 chrome 裡註冊這個位置。

== 更新 Chrome 清單 (Updating the Chrome Manifest) ==

還記得我們在第二章建立的 chrome 清單嗎？我們必須在這個檔案加入一行程式碼，用來註冊我們的面板。新加入的位置(第三行)：

新加入的這一行相當簡單，而且只有四個部份。第一部份，skin 說明這一行要註冊面板的資訊。接著是套件的名稱，這裡使用 '''tuttoolbar''' 當作我們的套件名稱。第三部份，說明我們將會擴展的已安裝套件名稱，「classic/1.0」是你會一直用到的值。最後，也是最重要的部份，就是包含面板檔案的目錄路徑。注意到這個路徑後面的斜線(/)，這個斜線是'''必要的'''，確定你有輸入。

== 建立圖片檔案 (Creating the Image Files) ==

我們會讓每個工具列按鈕使用各自的圖像。注意到，這不是最有效率或是精緻的作法，但是可以讓人更容易了解。更好的方式是使用'''圖像樣式表'''，但是那超出這份指南的範圍。

我們需要五個圖像供工具列的組合選單使用：主要選單、綜合搜尋按鈕、網頁搜尋按鈕、圖片搜尋選單以及可調整的移駐標記。在下面的列表中，有五個我用在這個套件的圖像。注意， 這些圖像都是透明的 PNG 格式檔案，如果你使用 IE 或是其他瀏覽器，可能不能正確地顯示。

主要選單圖示 Main Menu Icon (main.png): http://wiki.moztw.org/uimages/b/b7/Borngeek_main.png

綜合搜尋圖示 Combined Search Icon (combined.png): http://wiki.moztw.org/uimages/3/36/Borngeek_combined.png

網頁搜尋圖示 Web Search Icon (web.png): http://wiki.moztw.org/uimages/9/9c/Borngeek_web.png

圖片搜尋圖示 Images Search Icon (images.png): http://wiki.moztw.org/uimages/6/61/Borngeek_images.png

可調整移駐標記圖示 Resizing Gripper Icon (gripper.png): http://wiki.moztw.org/uimages/5/50/Borngeek_gripper.png

將這些圖像儲存在我們剛剛建立的 '''skin''' 目錄裡，檔案結構會像這樣：

== 藉由串接樣式表套用圖片 (Applying the Images with CSS) ==

現在，有這些圖像可以使用，面板目錄也已經註冊，我們可以開始把圖像套用在工具列按鈕上了。我們將會藉由 CSS 來完成。就如我在指南一開始提到的，如果你對 CSS 不熟悉，可以參考 W3Schools 的 [http://www.w3schools.com/css/css_intro.asp excellent CSS tutorial] 。

讓我們開始建立 CSS 檔案吧！在 '''skin''' 目錄下，建立一個檔名為 '''tuttoolbar.css''' 的檔案，把這個檔案跟圖像放在一起。檔案結構如下：

第一項規則是指定該圖像給「主要選單」按鈕使用。回顧一下第三章，我們給了該按鈕一個 ID 值：'''TutTB-MainMenu'''，我們用該值來設定按鈕顯示的圖像。在前面的井號(#)是 '''ID 選取器'''(ID selector)，也就是用來指定 CSS 元素規則的特定識別值。在工具列按鈕裡，我們使用 CSS 屬性的 '''list-style-image''' 來指定圖像。注意到我們使用的是 chrome 路徑，也就是套件檔案結構中的圖像路徑，常用的格式如下：

在我們的範例裡，封裝名稱(package name)是 '''tuttoolbar'''，而主要選單使用的圖像名稱為 '''main.png'''。你可以看到，所有的工具列按鈕使用類似的規則，在綜合搜尋按鈕的選單項目也是一樣。There's one caveat to handling menu item icons, however. 回想一下，在綜合搜尋選單中，我們為選單項目使用了一個特別的類別值：'''menuitem-iconic'''，這是 Firefox 內建的。這個值「啟動」圖示支援使用它的每個選單項目。

這個特別的 CSS 屬性在這裡使用 '''-moz-box-orient'''，這指定按鈕的標籤該如何顯示：水平或是垂直顯示。工具列按鈕標籤的預設值是垂直顯示，也就是顯示在圖示下方。在這個範例，不使用這樣的方式，所以我們改為水平顯示，以使標籤顯示在圖示之後。

在處理可調整的移駐標記(resizing gripper)時，有兩條樣式表的規則。還記得在第四章裡，我們在分離的元素(splitter element)使用的 '''vbox''' 元素嗎？我們為移駐標記使用了 '''vbox''' 來顯示背景圖像。這次，我們使用 '''background-image''' 屬性。我們必須藉由 '''min-height''' 與 '''min-width''' 屬性，提供最小高度與最小寬度，以讓移駐標記顯示出來。'''vbox''' 與 '''hbox''' 屬性的預設值可能是依內容大小判定。由於 '''vbox''' 是空的，預設值就是 0，這也避免我們會看到背景圖像。

我們也為分離的元素提供一條規則。 我們讓背景是透明的，而且不使用邊框(分離元素的預設值是會使用邊框的)。現在，CSS 檔案已經完成，我們要設定覆載(overlay)以使用它。

== 使用樣式表 (Using the Style Sheet) ==

只有一行程式碼是需要被加入在 XUL 覆載的，這用來啟動我們剛剛建立的樣式表。這必須放置在 XML 宣告指令的下方，以及覆載(overlay)元素之前。下面，我列出覆載檔案的前幾行需要更動的地方：

就像我們在樣式表中看到的圖像一樣，chrome 路徑被用來指定位置。而 '''type''' 屬性只是指明這是 CSS 的檔案。現在讓我們看看覆載檔案在加入這一行後的完整內容[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-f.txt View XUL Overlay Revision 6]]：

別忘記要測試！用[http://wiki.moztw.org/index.php/%E5%A5%97%E4%BB%B6%E9%96%8B%E7%99%BC%E6%8C%87%E5%8D%97_-_Googlebar_Lite#.E7.AC.AC.E5.9B.9B.E7.AB.A0.EF.BC.9A.E5.8B.95.E6.85.8B.E9.96.8B.E7.99.BC_.28Dynamic_Development.29 動態開發]的 Firefox 副本開啟，然後看看套件的樣子。接下來，我們要為工具列注入生命。

= 第六章：主程式 (Scripting the Toolbar) =

套件通常是用 JavaScript 執行的，這是一種簡單易學的程式語言。你將會發現，我們的工具列套件的程式碼是非常簡單的。我們將會大量使用文件物件模型(DOM)，這可以讓我們處理單獨的元素。

在我們開始前，你要先知道一個重點。'''id''' 屬性必須是整個瀏覽器唯一的，而 JavaScript 的變數及函式也是。在瀏覽器覆載中的JavaScript 是全域性的，因此才會有這個限制。我們將會使用跟 XUL 元素一樣的技巧：所有的變數及函式的名稱，將會有以我們套件為名起始名稱。我們使用 '''TutTB_''' 當作起始名稱，所以我們的搜尋函式會是 '''TutTB_Search()'''。

現在，讓我們建立 JavaScript 檔案。在 '''content''' 目錄中，建立一個 '''tuttoolbar.js''' 的文字檔。目錄結構如下：

在建立任何程式碼前，先告訴 XUL 檔案該如何使用 JavaScript 檔案。

== 連結 XUL 與 JavaScript (Tying XUL to JavaScript) ==

我們的 XUL 檔案 '''tuttoolbar.xul''' 需要被告知相對應的 JavaScript 檔，我們可以使用下面的描述：

這必須放置在 '''overlay''' 元素之中。'''type''' 屬性是指定使用 JavaScript，'''src''' 屬性是指定剛剛建立的 JavaScript 檔。內容如下[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/xul-g.txt View XUL Overlay Revision 7]]：

== 為按鈕加上功能 (Adding Functionality to the Buttons) ==

還記得我們為工具列按鈕提供的 '''oncommand''' 屬性嗎？這個屬性是指定程式碼執行的事件。我們也可以使用 '''onclick''' 代替 '''oncommand'''，但是 '''onclick''' 對鍵盤無效，而 '''oncommand''' 可以同時回應鍵盤與滑鼠的動作。讓我們回顧一下搜尋按鈕：

這個值呼叫 '''TutTB_Search()''' 函式，其中包含兩個值：這個函式呼叫的事件(event)，以及搜尋的網頁(web)。

程式碼如下[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/js-a.txt View JavaScript Revision 1]]：

// TutTB_Search() 函式會為我們完成搜尋。event 參數會觸發函式的呼叫，type 參數

// 為搜尋的類型。

     // 將要瀏覽的網址

     // 辨別搜尋欄位是否為空值

     // 處理搜尋欄位 ( <menulist> 元素)

     // 從搜尋欄位取出字串，整理必要的空白

     // 可以在下面看看 TutTB_TrimString() 函式運作的細節

     // 選擇搜尋的類型

     // 如果欄位是空白的，我們會引導使用者到 Google 網頁中適當的地方。

     // 否則，搜尋輸入的文字。

     // 建立圖片搜尋的網址

     // 建立網頁搜尋的網址

     // 使用 TutTB_LoadURL 函式在瀏覽視窗中載入網址

// TutTB_TrimString() 函式會修剪字串的前後空白部份，然後將所有的空白部份轉換成

// 單一個空白，然後傳回修改後字串。

     // 如果傳入的字串無效，或是沒有東西，則傳回空值

     // 將所有空白部份用單一空白代替

     return string; // 傳回改變後的值

// TutTB_ConvertTermsToURI() 函式將傳入的搜尋字串轉換為安全的網址

     // 建立陣列存放每個搜尋字串

     // 用空白字元切割字串

     // 用來存放安全的網址

     // 在字串中遞迴

         // 在第一個字串後的所有的字串會用加號(+)隔開

         // 使用 Firefox 內建的 encodeURIComponent() 函式加密

     return result; // 傳回結果

// TutTB_LoadURL() 函式在瀏覽器中載入特定的網址

     // 在網址列設定傳入的網址

開啟你的 Firefox 開發版本，在我們的工具列套件輸入搜尋的值，然後按下網頁搜尋按鈕。程式碼應該會執行，然後會出現搜尋結果。這個動態開發版本確實是相當便利的吧！

== 按鈕選單的注意事項 (A Special Note About Button-Menu Buttons) ==

在我們進入下一張章節之前，有一點關於按鈕選單所要注意的。回想一下，這類型的按鈕提供可以點擊的按鈕與彈出式選單(主要範例為往前與向後瀏覽)。也想一下，toolbarbutton 以及包含 oncommand 的 menuitem 元素。當工具列按鈕的一部分被啟動，toolbarbutton 元素的 oncommand 程式碼如你所期望的被執行。但是，當使用者啟動了menuitem 元素的其中一個時，會發生什麼事？

不只是 menuitem 元素的 oncommand 事件執行，toolbarbutton 元素的事件也被執行。所以兩個事件是同時執行的，儘管你只是想要其中一件被執行。因為 toolbarbutton 事件是最後發生的，所以實際執行的是 toolbarbutton 事件。換句話說，menuitem 事件沒有機會執行。那我們要怎樣解決這個問題呢？事實上，是有辦法的。讓我們往前看看 menuitem 元素：

藉由使用 DOM 函式 preventBubble()，我們可以避免 oncommand 被執行。為了避免夜長夢多，記住一件事，當你建立按鈕選單時，記得在 menuitem 元素的 oncommand 屬性加入 '''event.preventBubble()'''。

== 為搜尋列加入功能 (Adding Functionality to the Search Box) ==

這次，我們使用 onkeypress 代替 oncommand。這個事件會在使用者在搜尋列按下按鍵時觸發。在這個範例，我們建立一個相當簡單的 '''TutTB_KeyHandler()'''函式：

這個函式只不過是要檢查「Enter」是否被按下。如果是，TutTB_Search()會被呼叫。否則，不做任何事。讓我們來看看加入此函式的 JavaScript 檔案[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/js-b.txt View JavaScript Revision 2]]：

// TutTB_Search() 函式會為我們完成搜尋。event 參數會觸發函式的呼叫，type 參數

// 為搜尋的類型。

     // 將要瀏覽的網址

     // 辨別搜尋欄位是否為空值

     // 處理搜尋欄位 ( <menulist> 元素)

     // 從搜尋欄位取出字串，整理必要的空白

     // 可以在下面看看 TutTB_TrimString() 函式運作的細節

     if(searchTerms.length == 0) // 搜尋欄位是空白的嗎？

         isEmpty = true;        // 是，設定 isEmpty 為 true

     else                        // 不，轉換為安全的網址

     // 選擇搜尋的類型

     // 如果欄位是空白的，我們會引導使用者到 Google 網頁中適當的地方。

     // 否則，搜尋輸入的文字。

     // 建立圖片搜尋的網址

     // 建立網頁搜尋的網址

     // 使用 TutTB_LoadURL 函式在瀏覽視窗中載入網址

// TutTB_TrimString() 函式會修剪字串的前後空白部份，然後將所有的空白部份轉換成

// 單一個空白，然後傳回修改後字串。

     // 如果傳入的字串無效，或是沒有東西，則傳回空值

     // 將所有空白部份用單一空白代替

     return string; // 傳回改變後的值

// TutTB_ConvertTermsToURI() 函式將傳入的搜尋字串轉換為安全的網址

     // 建立陣列存放每個搜尋字串

     // 用空白字元切割字串

     // 用來存放安全的網址

     // 在字串中遞迴

         // 在第一個字串後的所有的字串會用加號(+)隔開

         // 使用 Firefox 內建的 encodeURIComponent() 函式加密

     return result; // 傳回結果

// TutTB_LoadURL() 函式在瀏覽器中載入特定的網址

     // 在網址列設定傳入的網址

// TutTB_KeyHandler() 檢查「Enter」是否被輸入。是的話，就執行搜尋

     // [ENTER]被按下了嗎？如果是，執行搜尋

在一次，執行你的 Firefox 開發版本，在搜尋列輸入搜尋字串，然後按下「Enter」。就像是按下搜尋按鈕一樣，搜尋結果應該會出現。現在，我們的套件已經有了生命！

== 動態置入選單 (Dynamically Populating a Menu) ==

注意到，在 menupopup 元素的 onpopupshowing 屬性。我們指定 TutTB_Populate()函式在每次「彈出式選單」即將顯示時被執行，這個函式將會建立我們的動態選單項目。讓我們來看看函式的程式碼[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/js-populate.txt View TutTB_Populate() Code]]：

// TutTB_Populate() 函式在工具列欄位的下拉式選單放置動態產生的選單項目。

// 雖然這不是非常實用的，但是藉由這個範例，我們可以看看動態選單置入的運作方式。

     // 取得彈出選單元素

     // 移除在彈出選單目前的項目

     // 指定要在選單增加的項目數量

         // 建立要增加的新選單項目

         // 設定新選單項目的標籤

         // 在選單中新增項目

這個函式範例不會命令每個 menuitem 元素去執行選擇的指令。為了讓每個 menuitem 知道應該執行的指令，我們僅僅只要加入 setAttribute()函式來處理事件及執行程式碼。這是處理 oncommand 事件的範例：

加入 TutTB_Populate()函式後的 JavaScript 檔案[[http://www.borngeek.com/firefox/toolbar-tutorial/samples/js-c.txt View JavaScript Revision 3]]：

// TutTB_Search() 函式會為我們完成搜尋。event 參數會觸發函式的呼叫，type 參數

// 為搜尋的類型。

     // 將要瀏覽的網址

     // 辨別搜尋欄位是否為空值

     // 處理搜尋欄位 ( <menulist> 元素)

     // 從搜尋欄位取出字串，整理必要的空白

     // 可以在下面看看 TutTB_TrimString() 函式運作的細節

     if(searchTerms.length == 0) // 搜尋欄位是空白的嗎？

         isEmpty = true;        // 是，設定 isEmpty 為 true

     else                        // 不，轉換為安全的網址

     // 選擇搜尋的類型

     // 如果欄位是空白的，我們會引導使用者到 Google 網頁中適當的地方。

     // 否則，搜尋輸入的文字。

     // 建立圖片搜尋的網址

     // 建立網頁搜尋的網址

     // 使用 TutTB_LoadURL 函式在瀏覽視窗中載入網址

// TutTB_TrimString() 函式會修剪字串的前後空白部份，然後將所有的空白部份轉換成

// 單一個空白，然後傳回修改後字串。

     // 如果傳入的字串無效，或是沒有東西，則傳回空值

     string = string.replace(/^\s+/, ''); // 移除前面空白

     string = string.replace(/\s+$/, ''); // 移除後面空白

     // 將所有空白部份用單一空白代替

     return string; // 傳回改變後的值

// TutTB_ConvertTermsToURI() 函式將傳入的搜尋字串轉換為安全的網址

     // 建立陣列存放每個搜尋字串

     // 用空白字元切割字串

     // 用來存放安全的網址

     // 在字串中遞迴

         // 在第一個字串後的所有的字串會用加號(+)隔開

         // 使用 Firefox 內建的 encodeURIComponent() 函式加密

     return result; // 傳回結果

// TutTB_LoadURL() 函式在瀏覽器中載入特定的網址

     // 在網址列設定傳入的網址

// TutTB_KeyHandler() 檢查「Enter」是否被輸入。是的話，就執行搜尋

     // [ENTER]被按下了嗎？如果是，執行搜尋

// TutTB_Populate() 函式在工具列欄位的下拉式選單放置動態產生的選單項目。

// 雖然這不是非常實用的，但是藉由這個範例，我們可以看看動態選單置入的運作方式。

     // 取得彈出選單元素

     // 移除在彈出選單目前的項目

     // 指定要在選單增加的項目數量

         // 建立要增加的新選單項目

         // 設定新選單項目的標籤

         // 在選單中新增項目

== 動態加入工具列按鈕 (Dynamically Adding Toolbar Buttons) ==

加入動態工具列按鈕就跟動態置入選單一樣簡單，而且還非常相似。首先，我們需要一個包含動態按鈕的容器。在這兒， toolbaritem 元素是不錯的選擇，標記如下：

現在，容器已經可以利用了，我們可以使用它，來加入動態 toolbarbutton 元素，讓我們來看一下可以讓我們加入動態按鈕的函式範例：

     // 取得我們在 XUL 描述中增加的工具列項目「容器」

     // 移除所有存在的按鈕

     // 增加五個動態按鈕

'''Optional Programming Exercise'''：試著用這個概念來增加「搜尋字串按鈕(search word buttons)」到工具列。當使用者在搜尋字串按鈕鍵入文字時，動態地增加按鈕到工具列的最後，一個按鈕一個字。這兒有幾個提示：

# 你需要增加 toolbaritem 容器到 XUL 描述檔的最後(right before the toolbarspring element is a good choice)。確定 ID 是唯一的。

# 在 menulist 元素中使用 oninput 事件，這個事件會在使用者輸入文字時觸發。