舊文件

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

「製作即時摘要」修訂間的差異

出自 MozTW Wiki

 
範例
 
(未顯示由 1 位使用者於中間所作的 20 次修訂)
行 1: 行 1:
A microsummary generator is a set of instructions for creating a microsummary from the content of a page.  Web pages can reference generators via <code><link rel="microsummary"></code> elements in their <code><head></code> elements.  Generators can also be independently downloaded and installed by users if they include a list of pages to which they apply.
+
{{MDC|製作即時摘要}}
  
In this tutorial we're going to create a microsummary generator for the [http://www.spreadfirefox.com/ Spread Firefox home page] that displays the current Firefox download count along with the label <cite>Fx downloads</cite>; for example: <cite>174475447 Fx downloads</cite>.
+
----
  
We'll build the XSLT transform sheet that converts that page into its microsummary, learn how to specify that the generator applies to that page, and find out how to make the generator available for download and installation.
+
即時摘要來源 (microsummary generator) 內含一組從網頁中製出即時摘要的指令,而網頁能在 <code><head></code> 元素中放入 <code><link rel="microsummary"></code> 以指定適用的摘要來源。即時摘要來源檔案中如含有適用頁面列表,則也可以獨立安裝。
  
In each step of revising the transform sheet and other code in this tutorial, new material added will be shown in '''boldface''' so you can follow along more easily.
+
在這份教學文件中,我們將建立 [http://www.spreadfirefox.com/ Spread Firefox 首頁]的即時摘要來源,藉以顯示目前 Firefox 的總下載數。 (例: <cite>Fx 下載數: 174475447</cite>)。
  
= Beginnings =
+
接下來我們會用一份 XSLT 樣式表將該網頁轉換為即時摘要、指定此摘要來源的適用頁面並了解摘要來源傳佈方式,讓使用者能下載及安裝。在這份文件中每階段新增的程式碼會以粗體顯示,方便您辨識。
  
Generators are expressed as XML documents whose root element is the <code><generator></code> element in the  <cite>http://www.mozilla.org/microsummaries/0.1</cite> namespace.  To begin building the generator, create a new empty text file and add an XML declaration and empty <code><generator></code> tag to it:
+
= 開始 =
 +
 
 +
摘要來源是 XML 文件的一種,而其根元素為 <code><generator></code>、名稱空間 (namespace) 需指定為 <cite>http://www.mozilla.org/microsummaries/0.1</cite>,所以要建立一份摘要來源就先得在空的純文字檔中放入 XML 宣告及空的 <code><generator></code> 標籤:
  
 
  '''<?xml version="1.0" encoding="UTF-8"?>'''
 
  '''<?xml version="1.0" encoding="UTF-8"?>'''
行 15: 行 17:
 
  '''</generator>'''
 
  '''</generator>'''
  
= Giving it a Name =
+
= 命名 =
  
Generators should have <code>name</code> attributes which are arbitrary descriptions of the microsummaries the generator creates.  Names should be descriptive enough to give users a good idea what information the microsummaries will provide.  Since our generator will be creating microsummaries displaying the Firefox download count, let's give it the name "Firefox Download Count":
+
每個即時摘要來源都必須有個名字,該名稱以 <code>name</code> 屬性記載、明確說明此摘要來源所建立的摘要主題。由於我們要建立的摘要來源將顯示 Firefox 總下載數,所以便命名為「Firefox 下載計數」:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             '''name="Firefox Download Count"'''>
+
             '''name="Firefox 下載計數"'''>
 
  </generator>
 
  </generator>
  
= Adding an XSLT Transform Sheet =
+
= 加上 XSLT 樣式表 =
  
Generators must include an XSLT transform sheet (also known as an XSLT stylesheet) which transforms the page content into its microsummary.  XSLT is a powerful language for transforming documents into different representations of the same information.
+
即時摘要來源檔案中必須含有一份 XSLT 樣式表,以便將網頁依樣式表設定轉換為即時摘要。同一份資料碰上不同的 XSLT 樣式便能轉換為「相貌」不同的文件,這便是 XSLT 威力所在。
  
Add the XSLT transform sheet to the generator by including it within a <code><template></code> element:
+
以下示範以 <code><template></code> 元素在摘要來源中添加 XSLT 樣式表:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             name="Firefox Download Count">
+
             name="Firefox 下載計數">
 
   '''<template>'''
 
   '''<template>'''
 
     '''<transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">'''
 
     '''<transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">'''
行 39: 行 41:
 
  </generator>
 
  </generator>
  
Note that while microsummary generators can include arbitrary XSLT, including XSLT that produces rich text output, Firefox currently only displays the text version of the XSLT output.
+
即時摘要來源中可以放任何形式的 XSLT,設定為產生超文件也行,但 Firefox 目前只會顯示純文字內容。
  
= Specifying the Output Type =
+
= 設定輸出格式 =
  
Since the XSLT transform sheet will generate a text microsummary, we should indicate this with the XSLT <code><output></code> element:
+
由於 XSLT 樣式表會產岀文字摘要,所以 XSLT <code><output></code> 元素需設定如下:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             name="Firefox Download Count">
+
             name="Firefox 下載計數">
 
   <template>
 
   <template>
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
行 55: 行 57:
 
  </generator>
 
  </generator>
  
= Using a Simple XSLT <code><template></code> =
+
= 使用 XSLT <code><template></code> =
  
The XSLT processor transforms documents by comparing each XSLT <code><template></code> element in the transform sheet to a set of nodes in the document.  When a <code><template></code>'s <code>match</code> attribute matches a node, the processor performs the transformations specified by the content of the element.
+
XSLT 處理器會分別比對 XSLT 樣式表中每組 <code><template></code> 元素及文件中的節點。當 <code><template></code> <code>match</code> 屬性設定與節點相符,處理器便依設定轉換文件。
  
This mechanism is powerful, because it lets you traverse the node tree of a document, recursively generating output based on the contents of the document.  But for the purposes of generating a microsummary for the Spread Firefox page, we only need to use a single <code><template></code> element that matches the root node of the document and is processed once:
+
這種處理方式可以循序檢查網頁中每個節點,依據設定條件顯示內容,非常有用。不過本例只是要顯示 Spread Firefox 網站上的即時摘要,僅用一個 <code><template></code> 元素來找一回根元素下的內容即可:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             name="Firefox Download Count">
+
             name="Firefox 下載計數">
 
   <template>
 
   <template>
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
行 73: 行 75:
 
  </generator>
 
  </generator>
  
= Including the Download Count =
+
= 加上下載次數 =
  
To include the download count in the output of the XSLT transform sheet, we need to add an XSLT <code><value-of></code> element to the template whose <code>select</code> attribute contains an XPath expression that points to the node containing the count.
+
若想將下載次數放到 XSLT 輸出的文件中,我們得在 XSLT 中的 <code>template</code> 元素加上 <code><value-of></code> 元素,而此 <code>template</code> 元素的 <code>select</code> 屬性中指定的 XPath 必須指向涵括計數器的節點。
  
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 [https://addons.mozilla.org/firefox/1095/ XPath Checker extension].
+
XPath 是用來指定 HTML/XML 文件節點的語言,也有基本的節點內容處理函式。要得知能指向此節點的 XPath 陳述式,最輕鬆的方法就是使用 [https://addons.mozilla.org/firefox/1095/ XPath Checker 擴充套件]
  
Install the extension (restarting Firefox to complete installation) then go to the [http://www.spreadfirefox.com/ Spread Firefox home page], find the Firefox download count (a large number at the bottom of the right-hand column), context click on the number, and select <cite>View XPath</cite> from the context menu.
+
安裝 XPath Checker 並重新啟動 Firefox 之後,先到 [http://www.spreadfirefox.com/ Spread Firefox 首頁]去,找到 Firefox 下載次數(網頁右邊欄最下方的數字),在上頭按下右鍵,於快捷選單中選擇 <cite>View XPath</cite>。此時 XPath Checker 會開啟一個新視窗,其中 <cite>XPath</cite> 欄位包含方才所選節點的 XPath 陳述式: <cite>id('download-count')</cite> 。
  
XPath Checker will open a new window.  The new window will include an <cite>XPath</cite> field that contains this XPath expression pointing to the download count node: <cite>id('download-count')</cite>.
+
在 XSLT 的 <code><template></code> 元素中加上一個 <code><value-of></code> 元素,其中 <code>select</code> 屬性便設為此 XPath 陳述式,如下:
 
 
Add a <code><value-of></code> element to the XSLT <code><template></code> element whose <code>select</code> attribute contains that XPath expression:
 
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             name="Firefox Download Count">
+
             name="Firefox 下載計數">
 
   <template>
 
   <template>
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
行 98: 行 98:
 
  </generator>
 
  </generator>
  
= Adding Text =
+
= 加上文字 =
  
To include the label <cite>Fx downloads</cite> in the microsummary, we need to add an XSLT <code><text></code> element to the XSLT <code><template></code> element whose content is the text we want to add.
+
為了在即時摘要中加上 <cite>Fx 下載數:</cite> 這段文字,我們必須將 <code><text></code> 元素放到 <code><template></code> 元素中文字該出現的地方。以下範例便放進一個內容為 <cite>Fx 下載數:</cite> <code><text></code> 元素:
 
 
Add a <code><text></code> element to the XSLT template with the content <cite>Fx downloads</cite>:
 
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             name="Firefox Download Count">
+
             name="Firefox 下載計數">
 
   <template>
 
   <template>
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
       <output method="text"/>
 
       <output method="text"/>
 
       <template match="/">
 
       <template match="/">
 +
        '''<text>Fx 下載數: </text>'''
 
         <value-of select="id('download-count')"/>
 
         <value-of select="id('download-count')"/>
        '''<text> Fx downloads</text>'''
 
 
       </template>
 
       </template>
 
     </transform>
 
     </transform>
行 118: 行 116:
 
  </generator>
 
  </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.
+
此處須留心 XSLT 標籤之間的空白字元並不會出現在輸出結果中,不像 HTML 會合併顯示為一個空格,所以要在字串後多加上一個空白以便區隔下載次數及字串。
  
With this addition, we've finished writing the XSLT transform sheet that converts the Spread Firefox home page to its microsummary.
+
這麼一來,這個轉換 Spread Firefox 首頁為即時摘要的 XSLT 樣式便完成了。
  
= Specifying the Page to which the Generator Applies =
+
= 指定摘要來源的適用範圍 =
  
Now that we've written the transform sheet, we have to specify the page to which it applies.  If we were the Spread Firefox webmasters, we might simply reference the generator within the page itself by adding a <code><link rel="microsummary"></code> tag to its <code><head></code> element:
+
摘要來源的轉換樣式已大工告成,接下來要指定此樣式適用的網頁。如果我們是 Spread Firefox 的網站管理員,可以在網頁上的 <code><head></code> 元素中直接加入 <code><link rel="microsummary"></code> 標籤,以便指定此網頁對應的摘要來源:
  
 
  <head>
 
  <head>
行 131: 行 129:
 
  </head>
 
  </head>
  
Since we're not that site's webmasters, however, we can specify the page to which the generator applies within the generator itself and then make the generator available for download and installation.  To specify pages to which a generator applies, we use a <code><pages></code> element within the <code><generator></code> element:
+
不過,由於我們並非該站網管,所以就得在檔案中規定此摘要來源的適用網頁,然後把摘要來源檔放到網路上供人下載。為了要指定適用網頁範圍,我們在 <code><generator></code> 元素中放上 <code><pages></code> 元素:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
             name="Firefox Download Count">
+
             name="Firefox 下載計數">
 
   <template>
 
   <template>
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
       <output method="text"/>
 
       <output method="text"/>
 
       <template match="/">
 
       <template match="/">
 +
        <text>Fx 下載數: </text>
 
         <value-of select="id('download-count')"/>
 
         <value-of select="id('download-count')"/>
        <text> Fx downloads</text>
 
 
       </template>
 
       </template>
 
     </transform>
 
     </transform>
行 149: 行 147:
 
  </generator>
 
  </generator>
  
The <code><pages></code> element can contain a sequence of <code><include></code> and <code><exclude></code> elements specifying the pages to which a generator does and doesn't apply, respectively.
+
<code><pages></code> 元素中可以放進多個 <code><include></code> <code><exclude></code> 元素。元素正如其名,<code><include></code> 元素能以規則運算式(regular expression)指定適用網頁,而 <code><exclude></code> 元素則以規則運算式指定不適用網頁。
  
To make a generator apply to a page, add an <code><include></code> element whose content is a regular expression matching the page.  To make the generator not apply to a page, add an <code><exclude></code> element whose content is a regular expression matching the page.
+
若無另加規定,則摘要來源預設不適用所有網頁。也就是說,你必須明確指定摘要來源之適用範圍,但如無必要可不必以 <code><exclude></code> 排除其他網頁。
  
By default, generators don't apply to any page, so you have to explicitly list the pages they apply to, and you don't have to exclude any pages unless you've previously included them.
+
此處加上個 <code><include></code> 元素指定 Spread Firefox 首頁為適用範圍:
 
 
Add an <code><include></code> element matching the Spread Firefox home page:
 
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>" name="Firefox Download Count">
+
  <generator xmlns="<nowiki>http://www.mozilla.org/microsummaries/0.1</nowiki>"
 +
            name="Firefox 下載計數">
 
   <template>
 
   <template>
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
     <transform xmlns="<nowiki>http://www.w3.org/1999/XSL/Transform</nowiki>" version="1.0">
 
       <output method="text"/>
 
       <output method="text"/>
 
       <template match="/">
 
       <template match="/">
 +
        <text>Fx 下載數: </text>
 
         <value-of select="id('download-count')"/>
 
         <value-of select="id('download-count')"/>
        <text> Fx downloads</text>
 
 
       </template>
 
       </template>
 
     </transform>
 
     </transform>
行 173: 行 170:
 
  </generator>
 
  </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 <cite>window.sidebar.addMicrosummaryGenerator()</cite> method to download and install the generator.
+
現在萬事俱備,只差讓人能下載此摘要來源的機制。我們得先將摘要來源檔上傳到網路,接著再以一段 JavaScript 連結呼叫 Firefox <cite>window.sidebar.addMicrosummaryGenerator()</cite> 方法以便下載安裝。
  
For example, if we put the generator file on the web at [http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml 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 http://people.mozilla.com/~myk/microsummaries/tutorial/index.html], we might add the following code to the <cite>index.html</cite> page:
+
舉例而言,如果摘要來源檔的位置在 [http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml],而我們希望使用者能從 [http://people.mozilla.com/~myk/microsummaries/tutorial/index.html http://people.mozilla.com/~myk/microsummaries/tutorial/index.html] 上下載安裝,就應該在 <cite>index.html</cite> 網頁上加上此段程式碼:
  
  '''<a href="javascript:window.sidebar.addMicrosummaryGenerator('<nowiki>http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml</nowiki>')">Install the Spread Firefox home page microsummary!</a>'''
+
  '''<a href="javascript:window.sidebar.addMicrosummaryGenerator('<nowiki>http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml</nowiki>')">安裝 Spread Firefox 首頁即時摘要來源!</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:
+
不過,如果是不支援即時摘要的瀏覽器,按下此連結之後會產生 JavaScript 錯誤,所以我們應該幫使用者點忙、檢查他們的瀏覽器是否支援即時摘要,若不支援則顯示說明訊息:
  
 
  '''<script>'''
 
  '''<script>'''
  '''  const warning = "Sorry, you need a microsummary-enabled browser like Firefox 2.0 to install and use microsummary generators.";'''
+
  '''  const warning = "不好意思ㄋㄟ,你得用支援即時摘要的瀏覽器 (如 Firefox 2.0) 才能安裝這玩意喔!";'''
 
  '''  function addGenerator(url) {'''
 
  '''  function addGenerator(url) {'''
 
  '''    if (typeof window.sidebar == "object" &&'''
 
  '''    if (typeof window.sidebar == "object" &&'''
行 193: 行 190:
 
  '''  }'''
 
  '''  }'''
 
  '''</script>'''
 
  '''</script>'''
  '''<a href="javascript:addGenerator('<nowiki>http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml</nowiki>')">Install the Spread Firefox home page microsummary!</a>'''
+
  '''<a href="javascript:addGenerator('<nowiki>http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml</nowiki>')">安裝 Spread Firefox 首頁即時摘要來源!</a>'''
 +
<!--
 +
這個即時摘要來源的安裝已經放在[http://bobchao.googlepages.com/microsummary 柏強雜碎頁: Firefox 2 即時摘要來源]中,可以安裝試試結果。
 +
-->
 +
= 範例 =
 +
*[http://shyangs.110mb.com/microsummary/tw-weather-V7.html 中央氣象局目前天氣即時標題]
  
= 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 <cite>Summary</cite> drop-down menu in the <cite>Add Bookmark</cite> dialog.
+
現在你應該瞭解怎麼製作能顯示 Firefox 下載次數的即時摘要了。試著將 Spread Firefox 首頁存為書籤,然後在<cite>新增書籤</cite>對話方塊中按下<cite>名稱</cite>下拉式選單、選擇<cite>即時標題</cite>之後的項目即可。
  
For more information about Microsummaries, see the [http://wiki.mozilla.org/Microsummaries Microsummaries home page].
+
其他關於即時摘要的相關資訊,可以參考 [http://wiki.mozilla.org/Microsummaries Microsummaries 主題頁]
  
[[fr:Création d'un microrésumé]]
+
----
[[it:Creare un Microsommario]]
+
註:
 +
*這個功能目前在非 UTF-8 的網頁部分有點問題,已提報 bug [https://bugzilla.mozilla.org/show_bug.cgi?id=345016 345016]
 +
*如果存放摘要來源檔的伺服器無法送出正確的 MIME Type (例: Google Pages 的空間),則摘要來源將無效,您可以在網址列輸入 javascript: 來查閱錯誤。
 +
*如果摘要來源檔案中的 XML 或 XSLT 格式有誤,則摘要來源將無效,一樣可以在網址列輸入 javascript: 來查閱錯誤。

於 2011年8月6日 (六) 18:58 的最新修訂

本文已經移往 Mozilla 開發者中心,請前往目前網址參考最新資訊。

即時摘要來源 (microsummary generator) 內含一組從網頁中製出即時摘要的指令,而網頁能在 <head> 元素中放入 <link rel="microsummary"> 以指定適用的摘要來源。即時摘要來源檔案中如含有適用頁面列表,則也可以獨立安裝。

在這份教學文件中,我們將建立 Spread Firefox 首頁的即時摘要來源,藉以顯示目前 Firefox 的總下載數。 (例: Fx 下載數: 174475447)。

接下來我們會用一份 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 下載計數」:

<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
           name="Firefox 下載計數">
</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 下載計數">
  <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 下載計數">
  <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 下載計數">
  <template>
    <transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
      <output method="text"/>
      <template match="/">
      </template>
    </transform>
  </template>
</generator>

加上下載次數

若想將下載次數放到 XSLT 輸出的文件中,我們得在 XSLT 中的 template 元素加上 <value-of> 元素,而此 template 元素的 select 屬性中指定的 XPath 必須指向涵括計數器的節點。

XPath 是用來指定 HTML/XML 文件節點的語言,也有基本的節點內容處理函式。要得知能指向此節點的 XPath 陳述式,最輕鬆的方法就是使用 XPath Checker 擴充套件

安裝 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 下載計數">
  <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>

加上文字

為了在即時摘要中加上 Fx 下載數: 這段文字,我們必須將 <text> 元素放到 <template> 元素中文字該出現的地方。以下範例便放進一個內容為 Fx 下載數:<text> 元素:

<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="http://www.mozilla.org/microsummaries/0.1"
           name="Firefox 下載計數">
  <template>
    <transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
      <output method="text"/>
      <template match="/">
        <text>Fx 下載數: </text>
        <value-of select="id('download-count')"/>
      </template>
    </transform>
  </template>
</generator>

此處須留心 XSLT 標籤之間的空白字元並不會出現在輸出結果中,不像 HTML 會合併顯示為一個空格,所以要在字串後多加上一個空白以便區隔下載次數及字串。

這麼一來,這個轉換 Spread Firefox 首頁為即時摘要的 XSLT 樣式便完成了。

指定摘要來源的適用範圍

摘要來源的轉換樣式已大工告成,接下來要指定此樣式適用的網頁。如果我們是 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 下載計數">
  <template>
    <transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
      <output method="text"/>
      <template match="/">
        <text>Fx 下載數: </text>
        <value-of select="id('download-count')"/>
      </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 下載計數">
  <template>
    <transform xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
      <output method="text"/>
      <template match="/">
        <text>Fx 下載數: </text>
        <value-of select="id('download-count')"/>
      </template>
    </transform>
  </template>
  <pages>
    <include>http://(www\.)?spreadfirefox\.com/(index\.php)?</include>
  </pages>
</generator>

安裝即時摘要來源

現在萬事俱備,只差讓人能下載此摘要來源的機制。我們得先將摘要來源檔上傳到網路,接著再以一段 JavaScript 連結呼叫 Firefox 的 window.sidebar.addMicrosummaryGenerator() 方法以便下載安裝。

舉例而言,如果摘要來源檔的位置在 http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml,而我們希望使用者能從 http://people.mozilla.com/~myk/microsummaries/tutorial/index.html 上下載安裝,就應該在 index.html 網頁上加上此段程式碼:

<a href="javascript:window.sidebar.addMicrosummaryGenerator('http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">安裝 Spread Firefox 首頁即時摘要來源!</a>

不過,如果是不支援即時摘要的瀏覽器,按下此連結之後會產生 JavaScript 錯誤,所以我們應該幫使用者點忙、檢查他們的瀏覽器是否支援即時摘要,若不支援則顯示說明訊息:

<script>
  const warning = "不好意思ㄋㄟ,你得用支援即時摘要的瀏覽器 (如 Firefox 2.0) 才能安裝這玩意喔!";
  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')">安裝 Spread Firefox 首頁即時摘要來源!</a>

範例

結語

現在你應該瞭解怎麼製作能顯示 Firefox 下載次數的即時摘要了。試著將 Spread Firefox 首頁存為書籤,然後在新增書籤對話方塊中按下名稱下拉式選單、選擇即時標題之後的項目即可。

其他關於即時摘要的相關資訊,可以參考 Microsummaries 主題頁


註:

  • 這個功能目前在非 UTF-8 的網頁部分有點問題,已提報 bug 345016
  • 如果存放摘要來源檔的伺服器無法送出正確的 MIME Type (例: Google Pages 的空間),則摘要來源將無效,您可以在網址列輸入 javascript: 來查閱錯誤。
  • 如果摘要來源檔案中的 XML 或 XSLT 格式有誤,則摘要來源將無效,一樣可以在網址列輸入 javascript: 來查閱錯誤。
個人工具