製作即時摘要
出自 MozTW Wiki
本文編譯自 http://developer.mozilla.org/en/docs/Creating_a_Microsummary
即時摘要來源 (microsummary generator) 內含一組從網頁中製出即時摘要的指令，而網頁能在 <head> 元素中放入 <link rel="microsummary"> 以指定適用的摘要來源。即時摘要來源檔案中如含有適用頁面列表，則也可以獨立安裝。
在這份教學文件中，我們將建立 Spread Firefox 首頁的即時摘要來源，藉以顯示目前 Firefox 的總下載數。 (例： 174475447 Fx downloads)。
接下來我們會用一份 XSLT 樣式表將該網頁轉換為即時摘要、指定此摘要來源的適用頁面並了解摘要來源傳佈方式，讓使用者能下載及安裝。在這份文件中每階段新增的程式碼會以粗體顯示，方便您辨識。
內容大綱
開始
摘要來源是 XML 文件的一種，而其根元素為 <generator>、名稱空間 (namespace) 需指定為 http://www.mozilla.org/microsummaries/0.1，所以要建立一份摘要來源就先得在空的純文字檔中放入 XML 宣告及空的 <generator> 標籤：
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="http://www.mozilla.org/microsummaries/0.1"> </generator>
命名
每個即時摘要來源都必須有個名字，該名稱以 name 屬性記載、明確說明此摘要來源所建立的摘要主題。由於我們要建立的摘要來源將顯示 Firefox 總下載數，所以便命名為「Firefox Download Count」：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
</generator>
加上 XSLT 樣式表
即時摘要來源檔案中必須含有一份 XSLT 樣式表，以便將網頁依樣式表設定轉換為即時摘要。同一份資料碰上不同的 XSLT 樣式便能轉換為「相貌」不同的文件，這便是 XSLT 威力所在。
以下示範以 <template> 元素在摘要來源中添加 XSLT 樣式表：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
</transform>
</template>
</generator>
即時摘要來源中可以放任何形式的 XSLT，設定為產生超文件也行，但 Firefox 目前只會顯示純文字內容。
設定輸出格式
由於 XSLT 樣式表會產岀文字摘要，所以 XSLT 的 <output> 元素需設定如下：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<output method="text"/>
</transform>
</template>
</generator>
使用 XSLT <template>
XSLT 處理器會分別比對 XSLT 樣式表中每組 <template> 元素及文件中的節點。當 <template> 的 match 屬性設定與節點相符，處理器便依設定轉換文件。
這種處理方式可以循序檢查網頁中每個節點，依據設定條件顯示內容，非常有用。不過本例只是要顯示 Spread Firefox 網站上的即時摘要，僅用一個 <template> 元素來找一回根元素下的內容即可：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<output method="text"/>
<template match="/">
</template>
</transform>
</template>
</generator>
加上下載次數
To include the download count in the output of the XSLT transform sheet, we need to add an XSLT <value-of> element to the template whose select attribute contains an XPath expression that points to the node containing the count.
XPath is a language for identifying nodes in HTML/XML documents. It also contains basic functions for manipulating those nodes and their content. The easiest way to get an XPath expression that points to the node in question is to use the XPath Checker 擴充套件.
安裝並重新啟動 Firefox 之後，先到 Spread Firefox 首頁去，找到 Firefox 下載次數（網頁右邊欄最下方的數字)，在上頭按下右鍵，於快捷選單中選擇 View XPath。此時 XPath Checker 會開啟一個新視窗，其中 XPath 欄位包含方才所選節點的 XPath 陳述式： id('download-count') 。
在 XSLT 的 <template> 元素中加上一個 <value-of> 元素，其中 select 屬性便設為此 XPath 陳述式，如下：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<output method="text"/>
<template match="/">
<value-of select="id('download-count')"/>
</template>
</transform>
</template>
</generator>
Adding Text
To include the label Fx downloads in the microsummary, we need to add an XSLT <text> element to the XSLT <template> element whose content is the text we want to add.
Add a <text> element to the XSLT template with the content Fx downloads:
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<output method="text"/>
<template match="/">
<value-of select="id('download-count')"/>
<text> Fx downloads</text>
</template>
</transform>
</template>
</generator>
Note that white space between XSLT tags is not included in the XSLT output, unlike in HTML where that white space is collapsed to a single space, so make sure to prepend a space to the phrase in order to separate it from the download count.
With this addition, we've finished writing the XSLT transform sheet that converts the Spread Firefox home page to its microsummary.
指定摘要來源的適用範圍
摘要來源的轉換樣式已大工告成，接下來要指定此樣式適用的網頁。如果我們是 Spread Firefox 的網站管理員，可以在網頁上的 <head> 元素中直接加入 <link rel="microsummary"> 標籤，以便指定此網頁對應的摘要來源：
<head> ... <link rel="microsummary" href="path/to/our/generator.xml"> </head>
不過，由於我們並非該站網管，所以就得在檔案中規定此摘要來源的適用網頁，然後把摘要來源檔放到網路上供人下載。為了要指定適用網頁範圍，我們在 <generator> 元素中放上 <pages> 元素：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<output method="text"/>
<template match="/">
<value-of select="id('download-count')"/>
<text> Fx downloads</text>
</template>
</transform>
</template>
<pages>
</pages>
</generator>
<pages> 元素中可以放進多個 <include> 及 <exclude> 元素。元素正如其名，<include> 元素能以規則運算式(regular expression)指定適用網頁，而 <exclude> 元素則以規則運算式指定不適用網頁。
若無另加規定，則摘要來源預設不適用所有網頁。也就是說，你必須明確指定摘要來源之適用範圍，但如無必要可不必以 <exclude> 排除其他網頁。
此處加上個 <include> 元素指定 Spread Firefox 首頁為適用範圍：
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1" name="Firefox Download Count">
<template>
<transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<output method="text"/>
<template match="/">
<value-of select="id('download-count')"/>
<text> Fx downloads</text>
</template>
</transform>
</template>
<pages>
<include>http://(www\.)?spreadfirefox\.com/(index\.php)?</include>
</pages>
</generator>
Making the Generator Available for Download
Now that the generator applies to the Spread Firefox home page, the only thing left to do is to make it downloadable. To do so, we need to put it up on the web and then create a JavaScript link on some web page that calls Firefox's window.sidebar.addMicrosummaryGenerator() method to download and install the generator.
For example, if we put the generator file on the web at http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml, and we wanted users to be able to install it from http://people.mozilla.com/~myk/microsummaries/tutorial/index.html, we might add the following code to the index.html page:
<a href="javascript:window.sidebar.addMicrosummaryGenerator('http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Install the Spread Firefox home page microsummary!</a>
Clicking that link will generate a JavaScript error on browsers that don't support microsummaries, however, so to improve the experience for those users, we should check to see if the user is using a microsummaries-enabled browser and display an explanatory message if not. We might do so via the following code:
<script>
const warning = "Sorry, you need a microsummary-enabled browser like Firefox 2.0 to install and use microsummary generators.";
function addGenerator(url) {
if (typeof window.sidebar == "object" &&
typeof window.sidebar.addMicrosummaryGenerator == "function")
window.sidebar.addMicrosummaryGenerator(url);
else
alert(warning);
}
</script>
<a href="javascript:addGenerator('http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Install the Spread Firefox home page microsummary!</a>
Conclusion
You should now have a microsummary generator that displays the current Firefox download count when you install it, bookmark the Spread Firefox home page, and select the microsummary from the Summary drop-down menu in the Add Bookmark dialog.
For more information about Microsummaries, see the Microsummaries home page.
譯者註：這個功能目前在非 UTF-8 的網頁部分有點問題，已提報 bug 345016
