blob: 40afef30b6cf41e7552ee213242ccdf00c8362d6 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
---
title: 製作即時摘要
slug: Archive/Mozilla/Creating_a_microsummary
tags:
- 即時摘要
translation_of: Archive/Mozilla/Creating_a_microsummary
---
<p>
即時摘要來源（microsummary generator）內含一組從網頁中製出即時摘要的指令，而網頁能在 <code><head></code> 元素中放入 <code><link rel="microsummary"></code> 以指定適用的摘要來源。即時摘要來源檔案中如含有適用頁面列表，則也可以獨立安裝。</p>
<p>
在這份教學文件中，我們將建立 <a class="external" href="http://www.spreadfirefox.com/">Spread Firefox 首頁</a>的即時摘要來源，藉以顯示目前 Firefox 的總下載數。 (例： <cite>Fx 下載數: 174475447</cite>)。</p>
<p>
接下來我們會用一份 XSLT 樣式表將該網頁轉換為即時摘要、指定此摘要來源的適用頁面並了解摘要來源傳佈方式，讓使用者能下載及安裝。在這份文件中每階段新增的程式碼會以粗體顯示，方便您辨識。</p>
<h2 id=".E9.96.8B.E5.A7.8B" name=".E9.96.8B.E5.A7.8B">
開始</h2>
<p>
摘要來源是 XML 文件的一種，而其根元素為 <code><generator></code>、名稱空間 (namespace) 需指定為 <cite><a class="external" href="http://www.mozilla.org/microsummaries/0.1" rel="freelink">http://www.mozilla.org/microsummaries/0.1</a></cite>，所以要建立一份摘要來源就先得在空的純文字檔中放入 XML 宣告及空的 <code><generator></code> 標籤：</p>
<pre class="eval"><b><?xml version="1.0" encoding="UTF-8"?></b>
<b><generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"></b>
<b></generator></b>
</pre>
<h2 id=".E5.91.BD.E5.90.8D" name=".E5.91.BD.E5.90.8D">
命名</h2>
<p>
每個即時摘要來源都必須有個名字，該名稱以 <code>name</code> 屬性記載、明確說明此摘要來源所建立的摘要主題。由於我們要建立的摘要來源將顯示 Firefox 總下載數，所以便命名為「Firefox 下載計數」：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
<b>name="Firefox 下載計數"</b>>
</generator>
</pre>
<h2 id=".E5.8A.A0.E4.B8.8A_XSLT_.E6.A8.A3.E5.BC.8F.E8.A1.A8" name=".E5.8A.A0.E4.B8.8A_XSLT_.E6.A8.A3.E5.BC.8F.E8.A1.A8">
加上 XSLT 樣式表</h2>
<p>
即時摘要來源檔案中必須含有一份 XSLT 樣式表，以便將網頁依樣式表設定轉換為即時摘要。同一份資料碰上不同的 XSLT 樣式便能轉換為「相貌」不同的文件，這便是 XSLT 威力所在。</p>
<p>
以下示範以 <code><template></code> 元素在摘要來源中添加 XSLT 樣式表：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<b><template></b>
<b><transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0"></b>
<b></transform></b>
<b></template></b>
</generator>
</pre>
<p>
即時摘要來源中可以放任何形式的 XSLT，設定為產生超文件也行，但 Firefox 目前只會顯示純文字內容。</p>
<h2 id=".E8.A8.AD.E5.AE.9A.E8.BC.B8.E5.87.BA.E6.A0.BC.E5.BC.8F" name=".E8.A8.AD.E5.AE.9A.E8.BC.B8.E5.87.BA.E6.A0.BC.E5.BC.8F">
設定輸出格式</h2>
<p>
由於 XSLT 樣式表會產岀文字摘要，所以 XSLT 的 <code><output></code> 元素需設定如下：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<template>
<transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0">
<b><output method="text"/></b>
</transform>
</template>
</generator>
</pre>
<h2 id=".E4.BD.BF.E7.94.A8_XSLT_.3Ctemplate.3E" name=".E4.BD.BF.E7.94.A8_XSLT_.3Ctemplate.3E">
使用 XSLT <code><template></code></h2>
<p>
XSLT 處理器會分別比對 XSLT 樣式表中每組 <code><template></code> 元素及文件中的節點。當 <code><template></code> 的 <code>match</code> 屬性設定與節點相符，處理器便依設定轉換文件。</p>
<p>
這種處理方式可以循序檢查網頁中每個節點，依據設定條件顯示內容，非常有用。不過本例只是要顯示 Spread Firefox 網站上的即時摘要，僅用一個 <code><template></code> 元素來找一回根元素下的內容即可：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<template>
<transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0">
<output method="text"/>
<b><template match="/"></b>
<b></template></b>
</transform>
</template>
</generator>
</pre>
<h2 id=".E5.8A.A0.E4.B8.8A.E4.B8.8B.E8.BC.89.E6.AC.A1.E6.95.B8" name=".E5.8A.A0.E4.B8.8A.E4.B8.8B.E8.BC.89.E6.AC.A1.E6.95.B8">
加上下載次數</h2>
<p>
若想將下載次數放到 XSLT 輸出的文件中，我們得在 XSLT 中的 <code>template</code> 元素加上 <code><value-of></code> 元素，而此 <code>template</code> 元素的 <code>select</code> 屬性中指定的 XPath 必須指向涵括計數器的節點。</p>
<p>
XPath 是用來指定 HTML/XML 文件節點的語言，也有基本的節點內容處理函式。要得知能指向此節點的 XPath 陳述式，最輕鬆的方法就是使用 <a class="link-https" href="https://addons.mozilla.org/firefox/1095/">XPath Checker 擴充套件</a>。</p>
<p>
安裝 XPath Checker 並重新啟動 Firefox 之後，先到 <a class="external" href="http://www.spreadfirefox.com/">Spread Firefox 首頁</a>去，找到 Firefox 下載次數（網頁右邊欄最下方的數字)，在上頭按下右鍵，於快捷選單中選擇 <cite>View XPath</cite>。此時 XPath Checker 會開啟一個新視窗，其中 <cite>XPath</cite> 欄位包含方才所選節點的 XPath 陳述式： <cite>id('download-count')</cite> 。</p>
<p>
在 XSLT 的 <code><template></code> 元素中加上一個 <code><value-of></code> 元素，其中 <code>select</code> 屬性便設為此 XPath 陳述式，如下：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<template>
<transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0">
<output method="text"/>
<template match="/">
<b><value-of select="id('download-count')"/></b>
</template>
</transform>
</template>
</generator>
</pre>
<h2 id=".E5.8A.A0.E4.B8.8A.E6.96.87.E5.AD.97" name=".E5.8A.A0.E4.B8.8A.E6.96.87.E5.AD.97">
加上文字</h2>
<p>
為了在即時摘要中加上 <cite>Fx 下載數:</cite> 這段文字，我們必須將 <code><text></code> 元素放到 <code><template></code> 元素中文字該出現的地方。以下範例便放進一個內容為 <cite>Fx 下載數:</cite> 的 <code><text></code> 元素：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<template>
<transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0">
<output method="text"/>
<template match="/">
<b><text>Fx 下載數: </text></b>
<value-of select="id('download-count')"/>
</template>
</transform>
</template>
</generator>
</pre>
<p>
此處須留心 XSLT 標籤之間的空白字元並不會出現在輸出結果中，不像 HTML 會合併顯示為一個空格，所以要在字串後多加上一個空白以便區隔下載次數及字串。</p>
<p>
這麼一來，這個轉換 Spread Firefox 首頁為即時摘要的 XSLT 樣式便完成了。</p>
<h2 id=".E6.8C.87.E5.AE.9A.E6.91.98.E8.A6.81.E4.BE.86.E6.BA.90.E7.9A.84.E9.81.A9.E7.94.A8.E7.AF.84.E5.9C.8D" name=".E6.8C.87.E5.AE.9A.E6.91.98.E8.A6.81.E4.BE.86.E6.BA.90.E7.9A.84.E9.81.A9.E7.94.A8.E7.AF.84.E5.9C.8D">
指定摘要來源的適用範圍</h2>
<p>
摘要來源的轉換樣式已大工告成，接下來要指定此樣式適用的網頁。如果我們是 Spread Firefox 的網站管理員，可以在網頁上的 <code><head></code> 元素中直接加入 <code><link rel="microsummary"></code> 標籤，以便指定此網頁對應的摘要來源：</p>
<pre class="eval"><head>
...
<b><link rel="microsummary" href="path/to/our/generator.xml"></b>
</head>
</pre>
<p>
不過，由於我們並非該站網管，所以就得在檔案中規定此摘要來源的適用網頁，然後把摘要來源檔放到網路上供人下載。為了要指定適用網頁範圍，我們在 <code><generator></code> 元素中放上 <code><pages></code> 元素：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<template>
<transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0">
<output method="text"/>
<template match="/">
<text>Fx 下載數: </text>
<value-of select="id('download-count')"/>
</template>
</transform>
</template>
<b><pages></b>
<b></pages></b>
</generator>
</pre>
<p>
<code><pages></code> 元素中可以放進多個 <code><include></code> 及 <code><exclude></code> 元素。元素正如其名，<code><include></code> 元素能以規則運算式(regular expression)指定適用網頁，而 <code><exclude></code> 元素則以規則運算式指定不適用網頁。</p>
<p>
若無另加規定，則摘要來源預設不適用所有網頁。也就是說，你必須明確指定摘要來源之適用範圍，但如無必要可不必以 <code><exclude></code> 排除其他網頁。</p>
<p>
此處加上個 <code><include></code> 元素指定 Spread Firefox 首頁為適用範圍：</p>
<pre class="eval"><?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="<span class="nowiki">http://www.mozilla.org/microsummaries/0.1</span>"
name="Firefox 下載計數">
<template>
<transform xmlns="<span class="nowiki">http://www.w3.org/1999/XSL/Transform</span>" version="1.0">
<output method="text"/>
<template match="/">
<text>Fx 下載數: </text>
<value-of select="id('download-count')"/>
</template>
</transform>
</template>
<pages>
<b><include><span class="nowiki">http://(www\.)?spreadfirefox\.com/(index\.php)?</span></include></b>
</pages>
</generator>
</pre>
<p>
不熟悉規則運算式的話，可以參考<a href="zh_tw/%e5%bb%ba%e7%ab%8b%e5%8d%b3%e6%99%82%e6%91%98%e8%a6%81%e7%9a%84%e8%a6%8f%e5%89%87%e9%81%8b%e7%ae%97%e5%bc%8f">建立即時摘要的規則運算式</a>一文。</p>
<h2 id=".E5.AE.89.E8.A3.9D.E5.8D.B3.E6.99.82.E6.91.98.E8.A6.81.E4.BE.86.E6.BA.90" name=".E5.AE.89.E8.A3.9D.E5.8D.B3.E6.99.82.E6.91.98.E8.A6.81.E4.BE.86.E6.BA.90">
安裝即時摘要來源</h2>
<p>
現在萬事俱備，只差讓人能下載此摘要來源的機制。我們得先將摘要來源檔上傳到網路，接著再以一段 JavaScript 連結呼叫 Firefox 的 <cite>window.sidebar.addMicrosummaryGenerator()</cite> 方法以便下載安裝。</p>
<p>
舉例而言，如果摘要來源檔的位置在 <a class="external" href="http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml" rel="freelink">http://people.mozilla.com/~myk/micro...-generator.xml</a>，而我們希望使用者能從 <a class="external" href="http://people.mozilla.com/~myk/microsummaries/tutorial/index.html" rel="freelink">http://people.mozilla.com/~myk/micro...ial/index.html</a> 上下載安裝，就應該在 <cite>index.html</cite> 網頁上加上此段程式碼：</p>
<pre class="eval"> <strong><button onclick="window.sidebar.addMicrosummaryGenerator('<span class="nowiki">http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml</span>')">安裝 SpreadFirefox 首頁即時摘要來源！</button></strong>
</pre>
<p>
不過，如果是不支援即時摘要的瀏覽器，按下此按鈕之後會產生 JavaScript 錯誤，所以我們應該幫使用者點忙、檢查他們的瀏覽器是否支援即時摘要，若不支援則顯示說明訊息：</p>
<pre class="eval"><strong><script></strong>
<strong> const warning = "不好意思ㄋㄟ，你得用支援即時摘要的瀏覽器 (如 Firefox 2.0) 才能安裝這玩意喔！";</strong>
<strong> function addGenerator(url) {</strong>
<strong> if (typeof window.sidebar == "object" &&</strong>
<strong> typeof window.sidebar.addMicrosummaryGenerator == "function")</strong>
<strong> window.sidebar.addMicrosummaryGenerator(url);</strong>
<strong> else</strong>
<strong> alert(warning);</strong>
<strong> }</strong>
<strong></script></strong>
<strong><button onclick="</strong><strong><strong>addGenerator</strong></strong><strong>('<span class="nowiki">http://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml</span>')">安裝 SpreadFirefox 首頁即時摘要來源！</button></strong>
</pre>
<p>
附帶一提：</p>
<ul>
<li>
由於 {{ Bug(341283) }} 的關係，目前 <cite>addMicrosummaryGenerator()</cite> 無法支援相對位置的 URL。</li>
<li>
如果存放摘要來源檔的伺服器無法送出正確的 MIME Type (例： Google Pages 的空間)，則摘要來源將無效，您可以在網址列輸入 javascript: 來查閱錯誤。</li>
<li>
如果摘要來源檔案中的 XML 或 XSLT 格式有誤，則摘要來源將無效，一樣可以在網址列輸入 javascript: 來查閱錯誤。</li>
</ul>
<h2 id=".E7.B5.90.E8.AA.9E" name=".E7.B5.90.E8.AA.9E">
結語</h2>
<p>
現在你應該瞭解怎麼製作能顯示 Firefox 下載次數的即時摘要了。試著將 Spread Firefox 首頁存為書籤，然後在<cite>新增書籤</cite>對話方塊中按下<cite>名稱</cite>下拉式選單、選擇<cite>即時標題</cite>之後的項目即可。</p>
<p>
其他關於即時摘要的相關資訊，可以參考 <a class="external" href="http://wiki.mozilla.org/Microsummaries">Microsummaries 主題頁</a>。</p>
|
