Widget包的封裝格式定義

W3C Working Draft 5 中譯版 March 2011

原版本(This version):
http://www.w3.org/TR/2010/WD-widgets-20101005/
原主編(Editor):
Marcos Cáceres, Opera Software ASA
譯者(Translator)
Jing Fung Chen (Grace) @ III

Valid XHTML 1.0 Transitional

前言

實際上,Widget就是一個由HTML/CSS/DOM/JavaScript所組成的本地網頁應用,使用者使用其擁有的設備(如: STB或智慧型手機)僅需要下載widget一次,此時這個本地網頁應用便儲存在使用者的設備內。

Widget使用開放式網頁技術(open web technique),最大優點就是可運行於各種系統,如: iPhone、Android、Blackberry、Window Mobile以及很多系統,Widget遵守編譯一次,隨處運行(write once, run anywhere)的原則,容易建立且網路連結方面僅使用數據通信。

關於Widget相關使用的規格方面,MPEG-U(ISO/IEC 23007)豐富多彩媒體使用者介面的目前標準表格的第一部分就是Widgets,由於目前MPEG-U尚未有任何公開文獻,因此以下是翻譯W3C Widget封裝與配置(2010/10/5),此外還兼顧本翻譯文件的完整性,每個章節保留些的原文的英文字,可連結到對照的原Widget packaging and configuration規格,翻譯文字間也建立有連結,因此可互相參照。

翻譯者:Jing Fung Chen (Grace) @ III (update: 2011.03)

目錄

摘要

1. 簡介

1.1 設計目標與需求

1.2 如何閱讀此文件

1.3 版面相關使用用語

1.4 widget家族規格

2. 一致性

3. 定義

3.1 字元定義

4. 用戶代理

4.1 選用Zip規格的層面

5. Zip檔案

5.1 壓縮法

5.2 Zip版本需提取的檔案項目

5.3 Zip關聯路徑

5.4 互通性考量

6 . Widget封裝法

6.1 無效Widget包

6.2 檔案和資料夾

6.3 保留檔和資料夾名稱

6.4 數位簽章

6.5 起始檔

6.6 圖像

6.7 媒體類型

6.8 延伸檔名

7. 配置文件

7.1 配置文件範例

7.2 命名空間

7.3 專用擴展

7.4 屬性類型

7.5 全域屬性

7.6 widget成員屬性

7.7 name成員屬性

7.8 description成員屬性

7.9 author成員屬性

7.10 license成員屬性

7.11 icon成員屬性

7.12 content成員屬性

7.13 feature成員屬性

7.14 param成員屬性

7.15 preference成員屬性

7.16 span成員屬性

8. 國際化與本地化

8.1 雙向文本

8.2 本地化模型

8.3 資料夾為主的本地化

8.4 成員為主的本地化

8.5 本地化使用範例

9. 處理Widget包步驟

9.1 處理規則

        +

實施步驟1-9

附錄

媒體類型登錄

HTML文件連結Widget包

成員與其屬性對照表

參考文獻

摘要

此規格是標準化Widget軟體封裝格式,Widgets就是客戶端(client-side)應用,其撰寫採用網頁(Web)標準,如:HTML5,但其內容也同時鑲入網頁文件中。本規格採用PKWare的ZIP存檔格式、XML的配置文件格式(configuration document format)和一連串步驟,隨著運行時處理和驗證封裝時的不同面向,此封裝格式扮演一個使用widget的檔案容器(container),且這個Widget配置文件是XML詞彙(vocabulary)其聲明詮釋資料(metadata)和配置參數(configuration parameters)。另外,處理widget封裝的步驟是描述期望的行為,和運行處理封裝格式、配置文件與其他相關檔案時,錯誤控制處理的辦法。

本規格翻譯Widget封裝與配置(2010/10/5)的前半部網頁,其組成為封裝格式配置文件保留檔案、預設頭像本地資料夾,此網頁僅描述定義 ;而整個封裝配置的處理過程則放置於處理widget包的規則與步驟網頁,皆隸屬於Widget家族規格書的一部分。

1. 簡介(Introduction)

此章節為非規範性的。

Widget是完全合格的客戶端應用,其撰寫採用HTML5網頁標準,且打包配送(packaged for distribution),就是典型的下載和安裝到客戶端機器或設備,這些機器或設備運行就如同單機(stand-alone)版的應用。Widget可鑲入到網頁(Web pages)和運行於網站瀏覽器(Web browser),其種類繁多,從簡單時鐘、股票行情、新聞播報、遊戲和氣象預報的widget應用,到複雜混搭(mashed-up)應用 – 從複合來源取得的數據資料,並使用些趣味和有用方式呈現給用戶(參考Widgets-Landscape可獲得更多資訊)。

為了說明方便,此規格以HTML5作為特定的網站平台(Web platform)。

1.1 設計目標和需求(Design Goals and Requirements)

此章節為非規範性的。

本規格設計目標與需求,是來自Widgets-Requirements文件,並標出25個需求與2009/4/30 Widgets需求文件工作草案(working Draft)封裝配置文件相關聯之處。

2009/4/30 Widgets 1.0需求文件

本翻譯文件(2010/10/5 Widget封裝和配置文件)

1

封裝格式(Packaging Format)

封裝格式(packaging format)

2

媒體類型(Media Type)

有效widget媒體類型 (valid widget media type)

3

延伸檔案(File Extension)

widget延伸檔(widget file extension)

4

內部抽象結構(Internal Abstract Structure)

Zip檔案(Zip archive)和widget包(widget package)

5

保留資源名稱(Reserved Resource Names)

保留檔名表(reserved file names table)

6

編址方案(Addressing Scheme)

有效路徑(valid path

7

多語檔名(Multilingual File Names)

Zip關聯路徑(Zip relative path),特別指支援UTF-8的部分

8

本地指南(Localization Guidelines)

成員為主的本地化(element-based localization)、資料夾為主的本地化(folder-based localization)

9

自動本地化(Automatic Localization)

成員為主的本地化(element-based localization)、資料夾為主的本地化(folder-based localization)

10

設備無關發行(Device Independent Delivery)

本文件各方面的發展皆考慮此需求(all aspects of this document where developed with this requirement in mind)

11

資料壓縮(Data Compression)

有效壓縮法(valid compression methods)

12

取得媒體類型資源(Derive the Media Type of Resources)

識別媒體類型檔的規則(rule for identifying the media type of a file)

13

格式與方案(Format and Schema)

配置文件(configuration document)、預設組態表(table of configuration defaults)和供配置文件的下一代鬆綁Widget方案([Widgets-Relax NG Schema] for configuration document)

14

Widget詮釋資料(Widget Metadata)

配置文件-特別是成員(configuration document - particularly the elements) 

15

原著資料(Authorship Metadata)

author成員 (author element)

16

版權註記與許可證資料(Copyright Notice and License Metadata)

license成員 (license element)

17

可視呈現維度(Visual Rendering Dimensions)

widget成員 (widget element)

18

宣告輔助程序(Declarative Bootstrap)

content成員 (content element)

19

自動輔助程序(Automated Bootstrap)

預設起始檔(default start file)

20

頭像呈現(Iconic Representations)

icon成員 (icon element)、預設頭像表(default icons table)和客製頭像(custom icons)

21

組態參數(Configuration Parameters)

param成員 (param element),其結合使用feature成員 (used in conjunction with the feature element)

22

作者定義啟用數值 - 偏好 (Author-defined Start-up Values - Preference)

preference成員 ( preference element)

23

功能跨越聲明(Feature Access Declarations)

feature成員 (feature element)

24

獨立配置文件(Configuration Document Independence)

配置文件 (configuration document)

25

偏好顯示模式(Preferred Display Mode)

widget成員viewmodes屬性 (the viewmode attribute of widget element)

1.2 如何閱讀此文件(How this document is Organized)

此章節為非規範性的

本翻譯文件分成widget包的封裝與配置之定義處理widget包的規則與步驟兩個網頁說明 ,在閱讀此兩份文件時,期間相關聯的地方有相互引用的連結可參考:

這個widget包的封裝與配置之定義網頁,其組成為封裝格式配置文件保留檔案、預設頭像本地資料夾。此網頁僅描述定義,而整個封裝配置的處理過程則放置於另一網頁。

第二部分為處理widget包的規則與步驟網頁 ,其定義處理widget包需要的步驟和用戶代理處理封裝格式配置文件、和試圖尋找本地內容等之預期行為相同。另外,也包含錯誤事件的控制方式,例如:用戶代理遇到未支援、或遺失檔案、或配置文件內的DOM節點錯誤(in error)。

1.3 版面相關使用用語(Typographic Conventions)

此章節為非規範性的

此章節定義本規格的版面相關用語(Typographic conventions),本規格內有些文字是非規範性的,非規範性(non-normative)的文字包含:

此外的文字皆為規範性的(normative)。

這裡採用簡單界定術語(simple defined term),比如:這個簡單界定術語,就提供個連結回到此名詞之原始定義處。

採用RFC2119規範的用語維持一致性條款(conformance clause)或可測試聲明(testable assertion),其中本規範使用的關鍵字有must, must not, should, recommended, mayoptional

變數(Variables)是使用特定的表示方式:variable。編碼(Code)的格式為code

斜體字表示其定義於延伸規範。

此為使用範例之顯示方式,用來展示和說明如何使用功能的概念,因此使用範例視為非規範性的。

註釋 此為註釋,通常包含有用額外的資訊。為非規範的形式。

創作指南 此為創作指南,其目的是提供作者最佳練習編寫的技術。創作指南亦為非規範性的。

1.4 widget家族規格(The Widget Family of Specifications)

此章節為非規範性的

本翻譯的規範是Widget家族規格(Widgets family of specifications)的一部分,Widget家族規格就是聚集標準化widget的整體,其中諸多相關之widget家族規格,可在widget家族規格工作小組的wiki上找到。

2. 一致性(Conformance)

只有用戶代理(user agent)這類的產品需要符合本規格(conformance to this specification)。

註釋 創建者可檢查其符合本規格的程度,透過順利通過P&C-Test-Suite的測試案例,然而通過測試套件(test suite)提供的所有測試並不意味著完全符合本規範;只能說明該實施符合測試套件設計的測試方向,也就是說:測試套件提供的測試並沒有包含符合本條款的所有選項。

3. 定義(Definitions)

蒐集使用於本規格各處的術語集中解釋陳列於下,還有一些遺落的術語則散落於本規格的其他處。

任意(Arbitrary)就是一個字元(character)、或文本串(text string)、或file-name、或folder-name保留任何本規格的目的。

作者(Author)就是建立widget包(widget package)的人或產生一個widget包的創作工具(authoring tool)。

初始化(Initialization)表示用戶代理(user agent)照著widget包處理步驟(steps for processing a widget package)正常運作。

語言標籤(language tag)是個文本串,其比對Language-Tag的作業過程定義於BCP47規格。

媒體類型(media type)定義於MIME規格。

保留(Reserved)表示一個字元(character)、或文本串(text string)、或file-name、或folder-name有特定目的和語意,其使用於本規格或在一些其他規格或系統,當這術語被使用時,其預期目的為保留任何預定。

支援(Supported)表示用戶代理實現了提及規格(mentioned specification),或一致性條款(conformance clause),或能夠處理以其他方式展示的媒體類型(media type)。

未支援(Unsupported)表示用戶代理沒有實現提及規格、或功能(feature)、或不能展示處理和/或其他提及的展示媒體類型(media type)。

widget透過Widgets-Landscape定義,如:最終用戶(end-user)的概念於單一互動應用訴求,提供顯示和/或更新本地數據或網頁數據,包裝法允許單一下載和安裝到用戶機(user's machine)、行動電話(mobile phone)、或上網設備(Internet-enabled device)。封裝widget的優點就是可以在用戶間共享widget包,而不需仰賴HTTP

3.1 字元定義(character definitions)

本節聚集了適用於本規格之常見的Unicode編碼組。

空白字元(space characters)編碼:

Unicode空白字元(Unicode white space characters)編碼是標註於Unicode規格中,為空白(White_Space)的性質,包含有:

Zip禁止字元(Zip forbidden characters)編碼:

4. 用戶代理(user agents)

用戶代理(user agent)就是本widget規格的實施,支援XMLXMLNSUTF-8UnicodeDOM3CoreSNIFFZIP(參考選用Zip規格的規格),除Widget包(widget package)外,用戶代理may(可能)支援其他傳統和專用應用封裝格式(application packaging formats) ,且用戶代理optional(可選用)支援選用ZIP規格的觀點(optional aspects of the Zip specification)。

註釋 不須特別使用"widget user agent"這麼長的字串表示用戶代理,是因為用戶代理就是實踐所有定義在widgets family of specification的規範和依存關係。用戶代理在描述widget封裝配置方面,只要考慮如何處理ZIP檔案配置文件

4.1 選用Zip規格的觀點 (Optional Aspects of the Zip Specification)

選用Zip規格的觀點並沒有使用ZIP規格定義的泛用功能,而採用下列項目:

5. Zip檔案(Zip Archive)

Zip檔案(Zip archive)格式使用ZIP規格的定義,也就是widget包封裝格式(packaging format)。

檔案項(file entry)是由本地檔頭(local file header),檔案數據(file data)和(選用的)檔案描述(file descriptor)所構成,提供Zip檔案內的實體檔或資料夾使用,其定義如同ZIP規格。

潛在Zip檔案(potential Zip archive)為一個數據物件(data object),其要求為Zip檔案,但未驗證有效Zip檔案

有效Zip檔案 (valid Zip archive)為一個數據物件(data object),其經過用戶代理驗證,符合定義於zip檔案格式規格[ZIP]的.zip檔案且其符合本規格的需求(參考實施步驟1)。

Zip檔的魔術字串 (magic numbers for a Zip archive) byte sequence:50 4B 03 04

5.1 壓縮法 (compression methods)

壓縮法(compression method)就是壓縮演算法或儲存法則,其使用在zip檔案(zip archive)建立時,對檔案項file data編碼,是透過識別數值(numeric value)是否來自ZIP規格定義的壓縮法領域(compression method field)。

有效壓縮法(valid compression methods),如同透過compression method field 給的檔案項

8
資料壓縮使用Deflate
0
資料未壓縮儲存(Stored),如同ZIP規格定義

創作指南為確保互通性(interoperability),壓縮檔案項zip檔案內部,使用Deflate或未壓縮儲存,或其他壓縮法,可能導致zip檔案被視為無效widget包。另外,在有效壓縮法則裡是以Deflate為首選之壓縮法。

5.2 Zip版本需提取的檔案項目(Version of Zip Needed to Extract a File Entry)

版本需求取得(version needed to extract)為提取2位元組(2-byte),從檔案項local file header,指向最低支援之ZIP的規格,此2-byte為需要取出的檔案數據

有效版本取得(valid versions needed to extract)數值如下所示,每個數值由ZIP規格分配一個或數個含意。

1.0

預設值指定於ZIP規格

2.0

檔案數據使用Deflate法,或檔案數據為一個資料夾,或檔案使用傳統PKWARE加密

註釋:Zip檔案使用傳統PKWARE加密,則用戶代理Zip檔案視為一個無效widget包 ,參考實施步驟2

5.3 Zip關聯路徑(Zip relative path)

Zip關聯路徑(Zip relative path)是可變長度字串(variable-length string) ,其來自檔名域(file name field)的檔案項目local file header

註釋: Zip關聯路徑據說與其儲存字串,其描述檔案和資料夾名稱相關於Zip檔案 創建在檔案系統(file system)的位置,比如:images/bg.png,相對於絕對儲存位置(c:\images\bg.png)。當Zip檔案在設備內被創建時,Zip關聯路徑的數值通常類似於檔案(或資料夾)名稱字串數值,但路徑若使用 U+002F Solidus斜線分隔符號(/)字元,則為異常路徑。還需要注意的是Zip關聯路徑不是URI參考URI reference,Zip關聯路徑需要使用這個打造使用的URIs的文本(context)前,轉換成URI reference。

有效Zip關聯路徑 (valid Zip relative path)為一個匹配Zip-rel-path的產品,其使用到相關ABNF規格如下所示:

Zip-rel-path   = [locale-folder] *folder-name file-name /
                 [locale-folder] 1*folder-name
locale-folder  = %x6C %x6F %x63 %x61 %x6C %x65 %x73
                 "/" language-range "/"
folder-name    = file-name "/"
file-name      = 1*allowed-char
allowed-char   = safe-char / zip-UTF8-char
zip-UTF8-char  = UTF8-2 / UTF8-3 / UTF8-4
safe-char      = ALPHA  / DIGIT / SP  / "$" / "%" / 
                 "'"    / "-"   / "_" / "@" / "~" /
                 "("    / ")"   / "&" / "+" / "," /
                 "="    / "["   / "]" / "."
UTF8-2         = %xC2-DF UTF8-tail
UTF8-3         = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
                 %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
UTF8-4         = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
                 %xF4 %x80-8F 2( UTF8-tail )
UTF8-tail      = %x80-BF
language-range = (1*8low-alpha / "*") *("-" (1*8alphanum / "*"))
alphanum       = low-alpha  / DIGIT
low-alpha      = %x61-71

ALPHADIGITSP(空白字元, space character)皆定義於ABNF規格,但有基本字母字符字元(alphanumerical characters)與U+0020 SPACE編碼的差別。

5.4 互通性考量(Interoperability Considerations)

此章節為非規範性的。

一些爭議可能會產生字元編碼與檔案名稱、Zip關聯路徑長度、和確定使用字串(如:檔名)。此章節旨在幫助創建者避開有可能的互通性爭議。

創作指南

此指南為非規範性的。

以下列出路徑長度、字元組與檔案名稱的設計方向:

路徑長度(Paths Lengths)

此規格沒有設定限制Zip關聯路徑之byte長度,所以用戶代理需能處理大於250 bytes長的Zip關聯路徑,由於有些作業系統(operating systems)設限路徑長度有多長,故創建者須保留關聯路徑長度低於250 bytes。然而Unicode之code points不需只使用1個byte對一個字元(character)一對一的編碼,導致對路徑長度本身而言是低於250字元(character),但是經編碼後,整體的長度卻大於250 bytes。

字元組(character sets)

創作者需察覺發佈時間會有互通性爭議,就是當運用作業系統綁定(bundle)的ZIP打包(zipping tool)時,關於Zip檔檔案資料夾,使用的字元超過safe-chars的範圍,因此跨不同作業系統執行Zip檔,將產生不一致(non-conforming)ZIP規格之互通性爭議:所幸此情況很少發生,若有的話,應正確採用Unicode編碼的檔案名稱。

使用UTF-8編碼的Zip關聯路徑,要設定language encoding flag (EFS)

若創建者選用utf8-chars,則在分發到各種平台之前需要徹底的測試他們的widgets,否則建議限定檔案和資料夾名稱長度於safe-chars範圍內(即US-ASCII範圍內的字元),另外,有過長路徑名稱(如:超過120字元)也可能導致某些作業系統產生互通性問題。

檔案名稱(file names)

創建者為widget檔案命名時,應避免使用Zip禁止字元,這些保留字元是維持跨不同檔案系統和使用URIs之互通性。

創建者須避免用到下列英文字,對Zip關聯路徑其中的資料夾個別檔名命名,如同保留名稱於有些作業系統是沒有大小寫區別的(case-insensitive):CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, CLOCKS$。舉例來說,"CON-tact.txt"、"printer.lpt1"、"DCOM1.pdf"這樣的檔名是可用的,但若命名為"com3.txt"、"Lpt1"、"CoM9.gif"則不被允許。

另外,創建者需要避免用到"." U+002E FULL STOP於檔案資料夾名稱的最後一個字元, 正如某些作業系統在處理解壓縮Zip檔到該設備時,是會主動移除此字元( . )。更進一步,避免空白字元於檔名開始或結束的地方,且謹慎使用"+" U+002B PLUS SIGN,因為它可能導致某些作業系統產生問題。

6. Widget封裝法 (Widget Packages)

Widget包就是一個有效ZIP檔案其內含的檔案如下,

註釋:參見實施步驟1 - 依照如何處理widget包的操作步驟,獲取潛在Zip檔案

6.1 無效Widget包(invalid Widget package)

在施行處理Widget包步驟期間,含有錯誤條件的ZIP檔案,將導致無效Widget包產生,一個無效Widget包(invalid Widget package)存在的條件,可能是ZIP檔案或位於ZIP檔案內的檔案,其中有檔案毀壞(corrupt),導致無法復原或不符合要求或不被W3C widget目前規範所支持,不能讓用戶代理繼續處理。

6.2 檔案和資料夾(Files and Folders)

根widget包(root of widget package)是位於ZIP檔案內最上層路徑,根widget包含有檔案和資料夾,其中有些是預定保留的檔名與存放路徑,參見保留檔名表(reserved file names table)。

檔案(file)就是檔案依照原檔案項目解壓縮(檔案型式跟它壓縮前加入ZIP檔案的格式相同)。

資料夾(folder) 是一個檔案項目(file entry),其file name field 對照有效Zip關聯路徑folder-name,這個file name field 的最後一個字元=U+002F SOLIDUS且版本需求為2.0。

可處理檔案(processable file)之檔案條件:

6.3 保留檔和資料夾名稱(Reserved File and Folder Names)

下面的保留檔名表(reserved file names table),包含本規格為某些目保留的檔名,保留檔名表的首行列出大小寫皆須吻合(case-sensitive)的檔名列表,隨後二行指出保留檔案類型與目的。

保留檔名表
檔名(file name) 類型(Type) 保留目的(reserved for purpose)
config.xml 檔案 配置文件

icon.png/icon.gif/icon.jpg/

icon.ico/icon.svg

檔案 (副檔名含有.png, .gif, .jpg, .ico, .svg) 預設頭像
index.svg/index.xhml/index.xht 檔案 (副檔名含有.html, .htm, .svg, .xhtml, .xht) 預設起始檔
locales 資料夾 本地內容容器

                                                                                                (資料來源:W3C,資策會整理)

本規格採用檔名包含有兩個簽章,分發簽章之通用命名widget作者簽名,如同widget數位簽章[Widgets-DigSig]規格書的定義。

創作指南除保留檔和本地內容容器外,建議封裝所有檔案於單一子目錄名,這設計是為了避免解壓縮後檔案散落到用戶(end-user)目前工作的目錄內,如下圖所示,此規格的進階版包含的規則,可到index.html與config.xml內查找相對應的目錄。

介紹封裝widget最佳練習範例:

  • widget file: boat.wgt
    • file: index.html
    • configuration document: config.xml
    • folder: boat/
      • folder: scripts/
        • script: engine.js
      • folder: images/
        • icon: header.png
    • folder: locales/
      • folder: en-gb/
        • folder: boat/
          • folder: images/
            • icon: hearder.png

6.4 數位簽章(Digital Signature)

Widget包包含數位簽章(digital signature),表示此widget包內含有1個或數個檔案皆符合Widgets-DigSig規格之數位簽定(digitally signed)。

6.5 起始檔(start files)

每個Widget包內至少需含有一個起始檔(start file),當用戶代理widget包實體化時,此widget包內所需要被載入到用戶代理的檔案就是起始檔。本規格定義兩種類型的起始檔:客製起始檔預設起始檔

客製起始檔(custom start file) – widget包內部之可處理檔案,使用content成員src屬性作為鑑別。

預設起始檔(default start file) – 為位於根widget包或根本地資料夾(root of a locale folder)之保留起始檔 ,需注意檔名需依預設起始檔名表(default start files table )的命名方式,且有大小寫的區別(case-sensitively),其中媒體類型依照MIME的定義,也可選擇(optional)使用用戶代理支援的媒體類型,如下表,

預設起始檔名表
檔名 (file name) 媒體類型 (media type)
index.htm text/html
index.html text/html
index.svg image/svg+xml
index.xhtml application/xhtml+xml
index.xht application/xhtml+xml

用戶代理對照檔名,發現預設的起始檔位於任意資料夾,此時用戶代理必須把此檔案視為任意檔,如:參考測試範例ta-RRZxwTFHx

舉例來說:把index.html檔案放置"foo/bar/index.html"到此目錄夾下,此index.html便視為任意檔。

註釋: 參見實施步驟8 - 如何尋找預設起始檔的指南。

創作指南widget包中,永遠包含至少一個起始檔

6.6 圖像(icons)

圖像(icon)是個檔案,用來 展現widget於不同種類的應用文本,舉例來說,讓使用者看到有widget可使用,或者圖像可用於對接(dock)、或任務條(task bar)、或其他可視文本(visual context);圖像幫助使用者瀏覽各種視覺化的widget套件,介紹兩種圖像的定義:客製頭像預設頭像

客製頭像(custom icons) – 明確宣告icon成員於配置文件檔,其位於根widget包或根本地資料夾或任意資料夾。

預設頭像(default icon) – 就是保留圖像,位於根widget包或根本地資料夾,檔名的設計有大小寫的區別(case-sensitively),其中預設圖像檔案之檔名與類型,如下表;另外,用戶代理可選擇(optional)其支援 的媒體類型皆列於下面的預設頭像表(default icons table)。

預設頭像檔名表
檔名 (file name) 媒體類型 (media type)
icon.svg image/svg+xml
icon.ico image/vnd.microsoft.icon
icon.png image/png
icon.gif image/gif
icon.jpg image/jpeg

6.7 媒體類型(Media Type)

有效widget媒體類型(valid widget media type),為application/widget字串。

創作指南Widget包協議傳輸支持MIME規範,則確保widget都標有application/widget媒體類型,若未能正確標示,將導致widget包被認定為無效widget包

6.8 延伸檔名(file extension)

widget延伸檔案(widget file extension)之檔名字串是不考慮大小寫的區別(case-insensitively),只要副檔名符合".wgt"(如:.wgt,.WGt ,.WgT等等字串)都有效。

例如:看到widget.WGT,這個".WGT"就是個延伸副檔名。

創作指南 若預期要分發的widget缺乏MIME支援,則宣告此為widget的延伸檔案(file extension),這個widget延伸檔運行於HTTP服務時,不需在widget包標示application/widget,此widget延伸檔只需在widget包,標示系統特有的檔案名稱,包含檔案延伸標誌(symbolizes)或關聯的媒體類型

7. 配置文件 (configuration document)

配置文件(configuration document)是個XML文件檔,內有位於Widget命名空間root的widget成員,一個widget包就有搭配一個配置文件,其位於根widget包

註釋: 參見實施步驟7:說明如何透過用戶代理處理配置文件成員的細節。

有效配置文件之檔名(valid configuration document file name)為config.xml字串,其可供widget設計者選用(optional)成員屬性。

用戶代理必定(must)把放置於任意資料夾(arbitrary folder)或本地資料夾(locale folder)的config.xml檔案,視為任意檔,如:參考測試範例 - ta-dxzVDWpaWg

創作指南 Widget包需要個位於根widget包配置文件config.xml,這個config.xml檔名字串為小寫型式(lowercase form) ;為確保其互通性,這個配置文件config.xml應採用UTF-8的編碼。

7.1 配置文件範例 (Example Configuration Document)

使用配置文件是為了鼓勵分享相關資訊給用戶,而使用視覺化資料(visual metadata)製作配置文件,下面為一個典型的配置文件格式,是源自W3C提供的配置文件範例:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns       = "http://www.w3.org/ns/widgets"
        id          = "http://example.org/exampleWidget"
        version     = "2.0 Beta"
        height      = "200"
        width       = "200"
        viewmodes   = "fullscreen">

 
  <name short="Example 2.0">
    The example Widget!
  </name>

  <feature name="http://example.com/camera">
    <param name="autofocus" value="true"/>

  </feature>

  <preference name     = "apikey"
              value    = "ea31ad3a23fd2f"
              readonly = "true" />

  <description>
    A sample widget to demonstrate some of the possibilities.
  </description>

  <author href  = "http://foo-bar.example.org/"
          email = "foo-bar@example.org">Foo Bar Corp</author>

  <icon src="icons/example.png"/>
  <icon src="icons/boo.png"/>
  <content src="myWidget.html"/>

  <license>
  Example license (based on MIT License)
  Copyright (c) 2008 The Foo Bar Corp.
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  </license>
</widget>

註釋: 鼓勵創建widget者揭露相關資料的配置文件提供給用戶,這個visual metadata就是鼓勵作者充分使用配置文件格式(configuration document format)。參見實施步驟7,說明如何處理配置文件

創作指南 配置文件widget成員內唯一強制性的配置,其他 所有成員和各自的屬性都是可選的,以下的例子顯示用戶代理能處理的最基本文件配置文件形式,之所以要包含這為一個成員,目的就是明確的告訴用戶代理或一致性檢查(conformance checker),此Zip檔是符合本規範。


     <!-- example of the smallest possible conforming configuration document -->
     <widget xmlns="http://www.w3.org/ns/widgets"/>
     

7.2 命名空間(Namespace)

Widget命名空間(widget namespace)的URL位於配置文件內,其XMLNS語法為http://www.w3.org/ns/widgets

註釋: 確保widget命名空間為widget成員的一部分,若缺乏此命名空間,則這個widget對用戶代理而言,就是非法的widget包

7.3 專用擴展(Proprietary Extensions)

此章節為非規範性的。

倘若創建者或作者(Implementers or authors)意圖延伸配置文件格式於自訂的XML成員和屬性(或其他規格的定義),便可以使用分離XMLNS語法的命名空間,本文件沒有定義widget命名空間以外的XML處理模型,因此在處理期間,可簡單略過。

舉例說明延伸的配置文件格式,

<widget xmlns="http://www.w3.org/ns/widgets"
   xmlns:ex="http://example.org/">
       <icon src="idle.png"  ex:role="inactive"/>

       <icon src="big.png" ex:role="big"/>
       <ex:datasource>{'a':'b','c':'d'}</ex:datasource>

       <content src="widget.html"/>
</widget>

 

7.4 屬性類型(Types of Attributes)

此章節定義使用在配置文件中之不同屬性類型(attribute types)和構成其他屬性類型之有效數值。若為此屬性為無效(invalid)屬性,表示輸入的數值不符合此屬性類型,也就是屬性數值的處理規則為錯誤

布林屬性(Boolean attribute)

就是關鍵字屬性僅提供使用有效的布林數值,有效布林數值(valid boolean value)需注意關鍵字輸入字元的大小寫(case-sensitively),並對照truefalse,除了另有規定外,預設的行為就是當忽略屬性或有一個其他的數值則顯示false

用戶代理依屬性定義解釋布林屬性,如:feature成員required屬性

可顯示字串屬性(Displayable-string attribute)

此屬性為基本轉換可讀資訊,如:name成員short屬性widget成員version屬性

關鍵字屬性(keyword attribute)

於此規範目的為此規格保留之字串,關鍵字屬性數值就是一個keyword,其為根據屬性定義指定一個有限集合(finite set)。

關鍵字列表屬性(keyword list attribute)

此定義為取得一個或數個關鍵字數值,藉由空白字元分隔

媒體類型屬性 (Media type attribute)

符合有效的媒體類別的定義,有效媒體類型(valid media type)是參照ABNF的規定:

valid-MIME-type = type "/" subtype *(";" parameter)

其中typesubtypeparameter皆依照個別的MIME定義。

語言屬性(language attribute)

此屬性數值定義包含有效的語言標籤(valid language tag),由Language-Tag所產生的字串,其定義參照BCP47

數值屬性(Numeric attribute)

此值為數值屬性,包含有效非負整數(valid non-negative integer),其組成為一個或多個編碼,範圍從 U+0030 數字零(0)到 U+0039 數字九(9)。 舉例來說:字串類型有”002”, “323”, “23214”等等

路徑屬性(Path attribute)

包含有效路徑(valid path),就是由Zip-rel-pathZip-abs-path所壓制生成的路徑。

創作指南 有效路徑非一個URL,這個有效路徑是指Zip檔案內部的檔案而言,為一個層級式的路徑,需正確的對照本地檔頭檔案項目file name field,這表示有效路徑不必要為URL編碼。

國際資源鑑定屬性(IRI attribute)

需包含有效IRI(valid IRI),其必須對照IRI的規格使用IRI代幣(IRI token)。

創作指南由於IRI內混和著風險,因此要廢棄時,使用%-escaped characters(%-洩漏字元)於功能名稱,表示強烈反對。

版本屬性(version attribute)

屬於可顯示字串之屬性,其數值為任意字串(可能為空的),其規範允許XML屬性的限制,此版本屬性格式並不強制任何特定格式、語法或特殊處理版本屬性之規則。

創作指南 版本屬性格式本身並沒有特別的限制,可以是任意字串(例如:'1.0'不小於'2.0',但具簡單差異),因此為了保持一致性,在此還是參照ABNF的規定

rec-version-tag = 1*DIGIT "."  1*DIGIT [ "." 1*DIGIT]
*[ 1*ALPHA / SP / 1*DIGIT ]
以版本標籤(version tag)為例:
  • Version 1.0 Beta
  • 1.0 RC1
  • 1.0-Build/1580
  • Joey the dog [5.1.2100]
rec-version-tag為例:
  • 1.0
  • 1.10.1 beta1
  • 1.02.12 RC1

7.5 全域屬性(Global Attributes)

此章節定義描述行為(behavior)和預期使用其他關連屬性,使用部分XML規範,為所謂的全域屬性(global attributes),可用於配置文件中的任何成員。

創作指南 設計widget程式,在適當的時候可選用(optional)任何適合的全域屬性,例如:在語言中做宣告是有助於易讀性(legibility)和定向信息(directional information),將協助用戶代理呈現正確的文本(render text correctly)。

xml:lang屬性(The xml:lang Attribute) – 為語言屬性,是透過語言標籤傳遞,包含XML成員之內容和屬性數值(參考IANA 語言子標籤登記),此為XML規格的xml:lang屬性且影響子節點(child node)。

創作指南

透過BCP47的建議,將所有語言標籤皆轉為大寫(case-folded)可在特定的時候顯現,但此轉換對語言標籤而言沒有意義,因此提醒widget的創作者用戶代理對照所有的語言標籤皆為小寫(lowercase),本文件的所有範例都是使用小寫,參考資料夾為主的本地化,其需要使用的語言標籤為小寫形式表示資料夾名稱。

避免子標籤(IANA 語言子標籤登記)過時(deprecated)、溯及過往(grandfathered)或造成多餘(redundant),此xml:lang屬性宣告主要成員、屬性、後代節點(descendent notes),由於文字於用戶代理沒有任何方向性,因此指定方向的文字,可參考dir屬性

dir屬性(The dir Attribute) – 為關鍵字屬性用於指定方向性(specify the directionality),人類可讀(human-readable)的文本於用戶代理呈現 (如:文本內容使用name成員description成員license成員)。該方向性設定即為dir屬性使用是應用文本內容(text content)和任何顯示字串屬性的成員(displayable string attributes of the element where it is used)以及其子成員內容,除非複寫另一個dir實例,例如:本規格中的dir屬性只影響name成員short屬性widget成員version屬性

dir屬性可能數值為有效定向指標(valid directional indicators):

ltr

左到右文字,要求Unicode BIDI演算法,處理成員字元,從左到右鑲入。

rtl

右到左文字,要求Unicode BIDI演算法,處理成員字元,從右到左鑲入。

lro

左到右覆蓋,強迫Unicode BIDI演算法,處理成員字元,為左到右字元。

rlo

右到左覆蓋,強迫Unicode BIDI演算法,處理成員字元,為右到左字元。

註釋: 基於安全考量,參考UTR36的安全建議,在配置文件檔中可看到實踐的IRIsIDNA地址,例如:dir屬性行為是沒有影響任何IRI屬性path屬性和位於author成員email屬性

dir屬性的基本方向性就是為明確設定為最接近父成員(parent element)使用,或者當沒有屬性符合前者時,基本方向就是指向繼承預設文件方向(default direction of the document),由左到右(ltr)。

使用範例1 – 於配置文件使用dir屬性


    <widget xmlns="http://www.w3.org/ns/widgets" dir="rtl" xml:lang="fa">
    <name short="آب و هوا">‎
    آب و هوا برنامه</name>
       <description> 
    این نرم افزار به شما اجازه می دهد تا برای دیدن آب و هوا در منطقه محلی تان.
       </description>
    </widget>

使用範例2 – 本地內容使用dir屬性

<widget xmlns="http://www.w3.org/ns/widgets">

   <name short="Weather">
    Weather Application
   </name>

   <name short="آب و هوا" xml:lang="fa" dir="rtl"> 
    آب و هوا برنامه
   </name>

</widget>

使用範例3 – 將dir屬性使用於混合語言內容(mixed language content),


    <widget xmlns="http://www.w3.org/ns/widgets">
      <name short="Weather">
       Weather! a totally awesome application!
      </name>

      <name short="آب و هوا" xml:lang="fa" dir="rtl">
      <span dir="ltr" xml:lang="en">Weather!</span> برنامه واقعا بزرگ
      </name>

    </widget>

7.6 widget 成員與屬性(The widget Element and its Attributes)

widget成員服務就像一個容器(container)提供配置文件其他成員使用。

背景(Context in which this element is used):
widget成員就是配置文件的根成員
資源指引(Occurrences)
位於XML文件的根成員
預期子節點 (在任何次序){Expected children (in any order)}
name: 零或多個 (每種語言允許一個成員)
description: 零或多個 (每種語言允許一個成員)
author: 零或多個
license: 零或多個 (每種語言允許一個成員)
icon: 零或多個
content: 零或多個
feature: 零或多個
preference: 零或多個
本地化(透過xml:lang)
無(No); 屬性數值繼承透過author, preference, iconcontent,在實施步驟7處理過程中是沒有作用的,例如:成員沒有支援xml:lang表示xml:lang沒有被繼承。
屬性(Attributes):
Global屬性, id, version, height, width, viewmodes
 

id屬性 - 為IRI屬性,指向widget識別

創作指南 可選擇(optional)使用id屬性widget成員

version屬性 - 為version屬性指特定的widget版本

創作指南 可選擇(optional)使用version屬性widget成員

height屬性 - 為非負整數的numeric屬性(大於0),可指定檢視區(viewport)範圍的高度,使用CSS像素(CSS pixels [CSS])實體化呈現客製起始檔

創作指南 可選擇(optional)使用height屬性widget成員

width屬性 - 為數值(numeric)屬性(大於0),可指定檢視區(viewport)範圍的寬度,使用CSS像素(CSS pixels [CSS])實體化呈現客製起始檔

創作指南 可選擇(optional)使用width屬性widget成員

viewmodes屬性 - 關鍵字列表(Keyword list)屬性,表示首要偏好的視圖模式(view mode),其次是下個考量的視圖模式,以此類推。當該屬性遺失或為空的,意味著作者期待用戶代理為該widget選擇一個近似的viewmode。

Viewport概念定義於[CSS],但基本上是一個窗口(window)或其他螢幕顯示區域(viewing area),其定義可參考[CSS]9.1.1 The viewport章節,其中這個view mode的概念,可參考View-Modes的定義。

創作指南 可選擇(optional)使用viewmodes屬性widget成員

使用範例 – 使用widget成員的範例

<widget xmlns     = "http://www.w3.org/ns/widgets"
        id        = "http://example.org/exampleWidget"
        version   = "2.0 Beta"
        height    = "200"
        width     = "200"
        viewmodes = "windowed floating"/>

7.7 name 成員與屬性(The name Element and its Attributes)

name成員widget使用時,呈現是全部人類可讀(human-readable)的名字,例如:一個應用功能選單或其他文本(contexts)。

背景(Context in which this element is used):
屬於widget成員
內容模組(Content model)
任何 (Any)
資源指引(Occurrences)
零或多個 (每種語言允許一個成員)
預期子節點(Expected children)
span: 零或多個
本地化(透過xml:lang)
有(Yes)

創作指南xml:lang屬性之數值對任何子序列成員類別是唯一的

屬性(Attributes):
Global屬性, short

short屬性 – 為可視字串屬性用表示widget縮寫的名字,例如:名字可用於文本中只能獲得有限空間,就像底下的圖像(icon)。

創作指南optional(選擇)使用short屬性name成員

使用範例 – 使用name成員的範例

<widget xmlns="http://www.w3.org/ns/widgets">

   <name short="Weather">
    The Ultimate Weather Widget
   </name>

   <name short="Boletim" xml:lang="pt">
    Boletim Metereológico
   </name>

</widget>

7.8 description 成員與屬性(The description Element and its Attributes)

description成員呈現是人類可讀(human-readable)的widget描述。

背景(Context in which this element is used):
屬於widget成員
內容模組(Content model)
任何 (Any)
資源指引(Occurrences)
零或多個 (每種語言允許一個成員)
預期子節點(Expected children)
span: 零或多個
本地化(透過xml:lang)
有(Yes)

創作指南xml:lang屬性之數值對任何子序列成員類別是唯一的,若有兩個或多個成員有相同的xml:lang屬性數值,則用戶代理對第一個成員比對,忽略(ignore)其他所有成員,詳情參見實施步驟7

屬性(Attributes):
Global屬性

使用範例 – 使用description成員的範例

<widget xmlns="http://www.w3.org/ns/widgets">
  <name>Dahut Chaser</name>
  <description>
  Combining the latest weather info with your GPS position,
  this widget alerts you of any significant dahut activity in your
  area. When a big one walks by, the widget plots the best route on a map based
  on the dahut's trajectory so you can chase it! With support for
  built-in cameras, you can quickly upload all the Alpine action to
  your blog or to the insane dahut chaser web site! Awesome!
  </description>
</widget>

7.9 author 成員與屬性(The author Element and its Attributes)

author成員呈現創建widget時候的人(people)或組織(organization)狀態。

背景(Context in which this element is used):
屬於widget成員
內容模組(Content model)
任何(Any)
資源指引(Occurrences)
零或多個
預期子節點(Expected children)
span: 零或多個
本地化(透過xml:lang)
無(No)。 只有這個成員的第一個實例於文件次序(document order)使用,不管任何的xml:lang數值
屬性(Attributes):
Global屬性, href, email

href屬性 – 為IRI屬性(IRI attribute),用IRI表示與作者關聯或相連結於作者的首頁(homepage)、社群網路簡介(profile)等資訊;

創作指南 可選擇(optional)使用href屬性author成員

email屬性 – 為關鍵字屬性(keyword attribute)顯示作者的email地址;

創作指南 可選擇(optional)使用email屬性author成員

使用範例 – 使用author成員的範例


	<widget xmlns="http://www.w3.org/ns/widgets">
        	<name>Café Finder</name>
        	<author href  = "http://dahut.example.org/developers/"
        	        email = "cafefinder@example.org">
        	  Mr. Jo and Julia Bacalhau
        	</author>
	</widget>

7.10 license 成員與屬性(The license Element and its Attributes)

license成員呈現軟體許可(software license),如:使用協議(usage agreement)、再版聲明(redistribution statement)和/或著作權許可期限(copyright license term),讓創建此widget包內容受到保護。

背景(Context in which this element is used):
屬於widget成員的子項
內容模組(Content model)
任何(Any)
資源指引(Occurrences)
零或多個 (每種語言允許一個成員)
預期子節點(Expected children)
span: 零或多個
本地化(透過xml:lang)
有(Yes)

創作指南 xml:lang屬性的值,對子序列成員類別必須是唯一的,本地化內容license成員不該使用不同版本(version)的許可證(license),只能採用相同許可證的翻譯版。

屬性(Attributes):
Global屬性, href

href – 為有效IRI(valid IRI)或有效路徑(valid path)用來呈現軟體和內容的許可證(license);

創作指南 可選擇(optional)使用href屬性license成員

使用範例1 – 使用license成員href屬性之範例

<widget xmlns="http://www.w3.org/ns/widgets">
  <license href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231">
Distributed under the W3C Software License.
  </license>
</widget>

使用範例2 – 使用license成員,刪掉href屬性之範例

<widget xmlns="http://www.w3.org/ns/widgets">
  <license>
	... 
   3.3.1 Widgets can use any APIs or libraries, prescribed by anyone.
   Widgets a are a free and open Web technology, so can be produced for free 
   and sold anywhere. Widgets can be written in JavaScript 
   so can run on any conforming engine (without the annoying restrictions of 
   C, C++, or Objective-C). You can even "cross-compile" them, if you want.  
	...  
  </license>
</widget>

7.11 icon 成員與屬性(The icon Element and its Attributes)

icon成員呈現widget的客製頭像(custom icon)。

背景(Context in which this element is used):
屬於widget成員的子項
內容模組(Content model)
空(Empty)
資源指引(Occurrences)
零或多個
本地化(透過xml:lang)
無(No)。依靠資料夾本地化(folder-based localization)。
屬性(Attributes):
Global屬性, src, width, height

src屬性 - 為路徑屬性(path attribute)指widget包內的檔案。

創作指南 當使用icon成員就需要指定src屬性

width屬性 – 為數值屬性(numeric attribute)大於0,使用CSS2內定義的CSS像素,可指定頭像(icon)的寬度,為呈現文本(rendering context)或容易達到的理由(accessibility reason),改變頭像高度同時,用戶代理可能(may)忽略width屬性設定的值;

創作指南 可選擇(optional)使用width屬性icon成員

height屬性 - 為數值屬性(numeric attribute)大於0,使用CSS2內定義的CSS像素,可指定頭像(icon)的高度,為呈現文本(rendering context)或容易達到的理由(accessibility reason),去改變頭像高度,用戶代理可能(may)忽略height屬性設定的值;

創作指南 可選擇(optional)使用height屬性icon成員

使用範例 – 使用icon成員,包含三個頭像成員,其中兩個為顯示器產生的光域(raster),一個就是SVGTiny檔,這個raster圖顯示文本(context)小於256x256像素,另外,此成員與文件次序(document order)無關。
<widget xmlns="http://www.w3.org/ns/widgets">
  <icon src="icons/medium.png"/>
  <icon src="icons/big.svg" width="256" height="256"/>
  <icon src="icons/tiny.png"/>
</widget>

7.12 content 成員與屬性(The content Element and its Attributes)

content成員由作者於客製起始檔(custom start file)宣告,用戶代理預計使用時,content成員於widget顯示。

背景(Context in which this element is used):
屬於widget成員的子項
內容模組(Content model)
空(Empty)
資源指引(Occurrences)
零或多個
本地化(透過xml:lang)
無(No)。依靠資料夾本地化(folder-based localization)。
屬性(Attributes):
Global屬性, src, type, encoding

src屬性 - 為路徑屬性(path attribute)指widget包內的檔案

創作指南 當使用content成員就需要指定src屬性

type屬性 - 為媒體類型(media type)包含檔案的媒體類別,可參考src屬性

創作指南 可選擇(optional)使用type屬性content成員,當此數值不存在,用戶代理就會認定此數值為text/html

encoding屬性 - encoding屬性關鍵字屬性(keyword attribute)就是檔案字元編碼識別採用src屬性,此數值可以是"name"或任何"Character Set"的別名(alias),參考IANA-Charsets列表。

創作指南 可選擇(optional)使用encoding屬性content成員,給定IANA-Charsets註冊的別名(alias),可使用"preferred MIME name"任何註冊的值。

預設編碼(default encoding)是[UTF-8],其為IANA-Charsets註冊表內的"UTF-8"。此外,用戶代理可選擇(optional)支援的其他字元編碼。

使用範例1 – 使用content成員的範例

<widget xmlns="http://www.w3.org/ns/widgets">
  <content src="myWidget.html"/>

</widget>

使用範例2 – content成員使用encoding屬性,將預設encoding屬性值="UTF-8"換成簡體中文編碼"GB2312"。

<widget xmlns="http://www.w3.org/ns/widgets">
  <name xml:lang="zh-cn">古老瓷地图</name>
  <name>Ancient Chinese Maps</name>
  <content src="china-maps.html" encoding="GB2312"/>
</widget>

使用範例3 – content成員使用type屬性,當widget運作時,建立專屬的媒體類型(media type)。

<widget xmlns="http://www.w3.org/ns/widgets">
  <name>Location-Based Games Finder</name>
  <content src="lbg-maps.swf" type="application/x-shockwave-flash"/>
  <feature name="http://example.org/api.geolocation"

           required="false"/>
</widget>

7.13 feature 成員與屬性(The feature Element and its Attributes)

feature為一個URI識別運行元件(identifiable runtime component),如:應用程式介面(Application Programming Interface, API)或視訊解碼(video decoder),feature成員標準化的服務,就是要求widget運行時結合IRI識別運行元件,存取feature其識別透過feature成員name屬性用戶代理使用feature是靠著安全政策,因此feature的活動(activation)與授權(authorization)不在本規範內。一個feature相關聯有零或數個parameters

背景 (Context in which this element is used):
widget成員的子項
內容模組 (content model):
零或多個param成員
資源指引 (Occurrences):
零或多個
本地化 (透過xml:lang)
無(No)
屬性 (Attributes):
Global屬性, name, required

name屬性 – 為IRI屬性認定的feature需要透過widget運行(如:一個API)。

創作指南 當使用feature成員就需要指定name屬性

required屬性 – 為布林屬性,widget運行時可獲得此屬性。當required屬性設為true,表示feature與widget功能正確有絕對相關,且沒有feature則表示widget服務沒有達到目的或不能正確執行;當required屬性設為false,表示widget正確運作不需要feature支援或其他用戶代理提供的可行方式。

創作指南 可選擇(optional)使用required屬性feature成員;另外,需要通知用戶代理的情況,就是當required屬性設定為truerequired屬性遺失;也就是widget運行時可獲得feature或者此widget為無效Widget包

使用範例 – widget使用地理位置(geo-location)的API,但feature不能由用戶代理取得。

<widget xmlns="http://www.w3.org/ns/widgets">
   <feature name     = "http://example.org/api/geolocation"
            required = "false"/> 
</widget>

7.14 param 成員與屬性(The param Element and its Attributes)

param成員定義餵給一個feature的一個parameter參數(parameter)為數值名稱對(name-value pair)關聯於相對應的feature,創建者建立parameterfeature間的聯繫,即param成員feature成員的直接子項,是根據文件序列(document order)的定義。

背景(Context in which this element is used):
屬於feature成員的子項
內容模組(Content model)
空(Empty)
資源指引(Occurrences)
零或多個
本地化(透過xml:lang)
無(No)。
屬性(Attributes):
Global屬性, name, value

name屬性 – 為keyword屬性表示parameter名字;

創作指南 當使用param成員就需要指定name屬性

value屬性 – 為keyword屬性表示該parameter數值;

創作指南 當使用param成員就需要指定value屬性

使用範例 – widget使用虛構地理位置(geo-location)功能,透過準確的設定param成員數值為"low"。

<widget xmlns="http://www.w3.org/ns/widgets">
   <feature name="http://example.org/api/geolocation">
      <param name="accuracy" value="low"/> 
   </feature>
</widget>

7.15 preference 成員與屬性(The preference Element and its Attributes)

preference成員允許創建者宣告一個或數個偏好(preferences),preference是個持續儲存的名稱數值對(name-value pair),就是關聯首次啟動的widget。

註釋: 用戶代理支援這個Widgets-APIs規格,表示widget運行時,揭露其宣告的preference,在Widgets-APIs規格的行為描述。

背景(Context in which this element is used):
屬於widget成員的子項
資源指引(Occurrences)
零或多個
預期子節點(Expected children)
無(none)
本地化(透過xml:lang)
無(No)
屬性(Attributes):
Global屬性, name, value, readonly

name屬性 – 為表示preference名稱的字串;

創作指南 當使用preference成員就需要指定name屬性

value屬性 - 為preference數值的字串;

創作指南 當使用preference成員,可選擇(optional)使用的value屬性

readonly屬性 - 為boolean屬性,在widget運行時,不管該preference能或不能透過作者設計的腳本(author script)複寫。設定方式為:當readonly屬性設定為true,表示preference不能複寫(overwritten);反之,當preference設定為false,則此preference可複寫。

創作指南 作者可選擇(optional)使用preference成員readonly屬性,若缺少readonly屬性用戶代理便會將readonly屬性設為false,表示這個preference在運行時,可複寫。

使用範例 – 顯示widget兩個preference的設定,若第二個preference透過readonly屬性,設為唯讀("read only"),表示preference數值在運行時,不能被更改。

<widget xmlns="http://www.w3.org/ns/widgets">
   <preference name     = "skin"
               value    = "alien"/>

   <!-- The preference below will be protected
        from modification and deletion at runtime -->

   <preference name     = "api-key"
               value    = "f6d3a312f9d742"
               readonly = "true"/>
</widget>

7.16 span 成員與屬性(The span Element and its Attributes)

span成員為文字內容的包裝,其本身擁有跟服務沒有用的功能。作者使用span成員做為全域屬性(global attribute),當span成員dir屬性合併時,span成員可指名文本內容本身的方向性,換句話說,span成員員允許作者設定Unicode雙向演算法(unicode bidirectional algorithm, [BIDI])之基本方向,當span成員xml:lang屬性合併,這個span成員指向另外一個成員文本內容的子集合,並使用特殊語言。

背景(Context in which this element is used):
name, author, license 和/或description成員的子項
資源指引(Occurrences)
零或多個
預期子節點(Expected children)
任何(Any)
本地化(透過xml:lang)

無(No),表示宣告xml:lang位於span成員的父成員(如:name成員),其不影響成員為主的本地化(element-based localization)之行為(參考下方的使用範例,觀察如何應用此成員);

創作指南 也就是使用span成員xml:lang指名文本內容的語言資訊。(詳情參考使用範例)

屬性(Attributes):
Global屬性

本節內容相當豐富(informative)

使用範例 – 顯示span成員用來直接指向文本就像語言資訊,注意,name成員xml:lang屬性設定空字串,允許使用預設內容(default content)於成員為主的本地化(element-based localization)處理。

<widget
 xmlns="http://www.w3.org/ns/widgets"
 xml:lang="he" dir="rtl">
 <name xml:lang="" dir="ltr">
  <span xml:lang="en">GPS Weather!</span>
 </name>
 <description>
  יישומון ה-
  <span dir="ltr" xml:lang="en">GPS Weather!</span> מאפשר
 לך לבדוק את מזג הא
וויר בכל נקודת GPS ברחבי העולם.
 </description>

<description xml:lang="" dir="ltr">
   <span xml:lang="en">The GPS Weather! widget lets you check
   the weather at any point around the world with GPS.</span>
</description>
</widget>

8. 國際化與本地化(Internationalization and localization)

國際化(Internationalization)或i18n就是設計發展產品、應用或文件內容,其能夠為了不同文化、區域或語言的觀眾,客製化本地化工作。本地化(Localization)是指適應性的調整產品、應用或文件內容,讓語言、文化或其他需求符合特定區域市場("locale")。

註釋: 參考相關定義本地化名詞(the term locale)的文件,如:Web Services Internationalization Usage ScenariosUnicode Locale Data Markup Language

本地化內容(localized content)就是作者確定完成本地化(localized),也就是widget包含有本地內容,是使用資料夾為主的本地化,或者是配置文件透過成員為主的本地化囊括本地內容。

預設內容(default content)就是包含widget包內或配置文件內的內容來說,其沒有明確的本地化。對widget包而言,表示內容不在本地內容容器內;對配置文件而言,任何成員沒有明確聲明或繼承xml:lang屬性

本地檔(localized file)就是任何檔案放至本地資料夾內(如:本地內容使用資料夾為主的本地化)。一個widget包含有零或數個本地資料檔案,除了數位簽章配置文件以外,所有檔案資料夾都可透過資料夾為主的本地化達到本地化的功能。

舉例來說:一個本地資料夾 "locales/ja/" (Japanese) 可能包含一個HTML日語翻譯文件。

創作指南 本地資料夾需要放在本地內容容器,若本地資料夾不位在本地內容容器內,表示其為任意資料夾。此外,作者在給定的locale製做本地功能,可經由製作可用的翻譯、本地化或其它本地內容,以及完整測試該widget。

8.1 雙向文本(bidirectional text)

用戶代理運作在雙向文本的授權是採用Unicode,本規格提供dir屬性span成員作為標記(markup-based)影響雙向Unicode文本(bidirectional Unicode text, BIDI),參考配置文件章節dir屬性span成員的使用範例。

8.2 本地化模型(Localization Model)

兩種方法可使用明確本地化widget內容,

  1. 設置本地檔案內容至本地資料夾,整個過程指向資料夾為主的本地化
  2. 配置文件內明確標記XML成員達到本地化,整個過程指向成員為主的本地化

綜合討論這兩個本地化的描述,資料夾為主(folder-based)和成員為主(element-based)的本地化仰賴用戶代理,去比對widget的配置文件內的本地相關之語言範圍,從user agent locales到相近之本地資料夾和/或本地的XML成員。

8.3 資料夾為主的本地化(folder-based localization)

定義資料夾為主的本地化(folder-based localization)的概念,處理方法就是在資料夾內放置檔案,此資料夾命名方法遵守language-rangeABNF規則。換而言之,資料夾命名使用IANA Language Subtag Registry規定的小寫(lower-case)用法,如:"en-us", "en-gb"等等,且避免子標籤標註deprecated(棄用)、grandfathered(溯及過往)、或redundant(冗餘)。這些本地資料夾皆放置於本地內容容器

創作指南 雖然BCP47建議一個特定大小寫折疊(case-folding)慣例,但使用大寫(upper)或小寫(lowercase)字對語言標籤皆是無意義的,因為widget包內的資料夾是透過用戶代理做區分大小寫(case-sensitive),在'locale'資料夾內部資料夾名稱必須全部都是小寫(lowercase),所有語言標籤(不管出現在配置檔案或其他地方)皆為了顯示相對應的目的而使用小寫。

本地內容容器(container for localized content)是個保留資料夾,位於根widget包,其folder-name有大小寫區別的(case-sensitive)與字串'locales'相匹配,一個本地內容容器(container for localized content)包含零或數個本地資料夾

本地資料夾(locale folder)是個資料夾,其file name field匹配locale-folder製作和一個直接後代的本地內容容器,如:"/locales/en-us","/locales/fr",等等,本地資料夾包含零或數個任意資料夾和/或檔案

創作指南

需要避免地區(region)、腳本(script)或其他子標籤(subtags),除非他們能增加有用之鑑別資訊到本地資料夾;另外,避免widget包內有空的本地資料夾,除非有非常好的理由。

使用範例 – 顯示widget使用資料夾為主的本地化之用法。

widget.wgt
 locales/zh-hans-cn/a.gif
 locales/zh-hans-cn/f.gif
 locales/zh-hans/a.gif
 locales/zh-hans/b.gif
 locales/zh/a.gif
 locales/zh/b.gif
 locales/zh/c.gif
 a.gif
 b.gif
 c.gif
 d.gif
 index.html
 config.xml

為了進一步促進本地化處理,是透過比對群組檔案內部之子標籤組成的層次結構資料夾,分析以下的使用範例 – 假設widget的locale是"zh-hans-cn":

此適用於所有子層(sub-levels),只要父標籤匹配子標籤,例如:"cn" 結尾區域可使用"zh-hans" 資料夾的本地檔、"zh" 資料夾和非本地化檔案(unlocalized files)是位於根widget包用戶代理永遠優先使用位在子資料夾之檔案,就是包含所有本地資料夾接近根widget包內的檔案;相反的,若widget的locale為"en-us",引用 a.gif,b.gif,c.gif和d.gif將解析檔案到根widget包

另請注意用戶代理處理外部的本地內容容器,是採預設內容處理方式,包含任何檔案資料夾

8.4 成員為主的本地化(element-based localization)

定義成員為主的本地化(element-based localization)的概念,允許使用xml:lang屬性明確指出配置文件本地XML成員。

使用範例 – 顯示widget使用成員為主的本地化之用法。

<widget xmlns="http://www.w3.org/ns/widgets">
   <name short="Weather">
   The Ultimate Weather Widget
   </name>

   <name short="Boletim" xml:lang="pt">
    Boletim Metereológico
   </name>
</widget>

Widget命名空間的一些成員定義:"yes"或"no", 是透過xml:lang達到本地化(localizable via xml:lang),如:name成員定義,當成員設定為"yes",表示運用xml:lang完成直接或間接之成員為主的本地化,其數值是透過直接或間接的繼承xml:lang而來,詳細步驟請參考實施步驟7

註釋: xml:lang屬性可用任何成員指定成員內容(content)使用的語言(language)與屬性數值(attribute values),在指定的XML中,xml:lang的數值是繼承來的,正如擁有xml:lang屬性的成員,其所有的後代皆建議使用相同語言;除非個別指定擁有的xml:lang屬性,注意成員可經由設定xml:lang為空字串(不論任何祖先 的xml:lang屬性,用來表示沒有特定語言。

使用範例 - 假設使用widget成員xml:lang屬性,表示所有子成員皆繼承這個xml:lang數值(xml:lang="en")。設定第一個name成員xml:lang,其下所有子孫皆套用此設定,倘若第二個name成員是採用自行宣告的xml:lang(xml:lang="pt"),覆蓋了原先xml:lang,則最後的name成員xml:lang設定為空字串,則此最後成員透過用戶代理使用預設內容

<widget xmlns="http://www.w3.org/ns/widgets"
 xml:lang="en">

   <name short="I'm in english, though not explicitly marked as such!">
    Behaves as if xml:lang="en"
   </name>

   <name xml:lang="pt">
    The declaration of xml:lang="pt" overrides
    xml:lang="en" inherited from the widget element. 
   </name>
   
   <name xml:lang="">
    The user agent will treat this as unlocalized content. 
   </name>

</widget>

若標註某成員為本地化是透過設定xml:lang為"yes",表示只有每種語言允許一個成員(one element is allowed per language)。

一個成員接受每種語言就是只有允許一個成員類型,例如:雖然很多name成員可在配置文件出現,只有一個name成員透過用戶代理選定英語(English),於是用戶代理於處理過程中(參考實施步驟7),比對文件順序(document order)的第一個成員,其比對語言範圍落在user agent locales忽略任何子成員序列重複包含比對的xml:lang數值,即便成員內容是不同的。

使用範例 – 假設user agent locales為"en-us"表示語言範圍只包含美國的英文,允許每種語言只實踐一個description成員。下面的程式碼中,用戶代理比對第一個description成員,但忽略第二與第三的description成員


<widget xmlns="http://www.w3.org/ns/widgets">

   <description xml:lang="en">
      This element would be used.
   </description>

   <description xml:lang="en">
      This element would be ignored because there is already
      a description element that uses xml:lang="en".
   </description>

   <description>
      This element is unlocalized, and would be used if the user agent's
      locale does not match any localized description elements.
   </description>

	 <description xml:lang="">
		This element would be ignored because there is already an unlocalized 
      description element! Using xml:lang="" makes this element behave as if
      it is unlocalized.
	 </description>

</widget>

user agent locales只包含 "*" 或不比對任何本地description成員,則用戶代理比對第三層以上的description成員

根據前段敘述,若不能使用xml:lang屬性和沒有特定屬性成員使用xml:lang比對user agent locales用戶代理使用預設內容位於文件次序(document order)的成員,比對找到的成員類別。

使用範例 – 假設user agent locales只包含"jp" (日語),由於只透過一個description成員實踐此語言,下面的例子是說明用戶代理忽略前兩個description成員,比對第三個非本地description成員


<widget xmlns="http://www.w3.org/ns/widgets">

   <description xml:lang="en">
       This element would be ignored.
   </description>

   <description xml:lang="en">
      This element would be ignored.
   </description>

   <description>
      In this case, this unlocalized element would be used.
   </description>

</widget>

8.5 本地化使用範例(Localization Examples)

此章節為非規範性。

本章節以三個例子呈現如何使用widget實現本地化,每個例子展示不同的本地化演算法。

簡單本地化範例(Simple Example) – 此範例是使用widget表現user agent locales持有的以每周日數計算為基準的語言範圍(the days of week based on language range),若用戶代理不能比對任意本地資料夾的語言範圍,則該widget在根widget包顯示/index.html

config: config.xml

<widget xmlns="http://www.w3.org/ns/widgets">
<name>What day is it?</name>
<description>
 This widget highlights the current day
 of the week.
</description>
</widget> 

file: locale/es/index.html

<!doctype html>
<title>¿Qué día es?</title>
<script src="scripts/dayfinder.js"></script>
<body>
<p>Hoy es: lunes, martes, miércoles,
   jueves, viernes, sábado,
   domingo

複雜本地化範例(Complex Example) – 下面的範例是本地widget具備複雜本地化的頭像起始檔配置文件,本例子呈現一些需要注意的事情:

config: /config.xml

<widget xmlns="http://www.w3.org/ns/widgets">
  <name xml:lang="ko">웃기는 고양이</name>
  <content src="cats.html"/>
</widget> 

file: /locales/en-au/cats.html

<!doctype html>
<title>G'day! LOL Cats!</title>
<script src="scripts/engine.js">
...

file: /locales/es/cats.html

<!doctype html>
<title>Gatos Graciosos!</title>
<script src="scripts/engine.js">
...

備援行為範例(Fallback Behavior Example) – 此規格允許作者置換檔案資料夾,期待本地化不位於根widget包;在運行時,若用戶代理本地資料夾尋找檔案失敗,其僅能永遠在根widget包尋找遺失檔案。這個備援(fallback)模型設計目的為減少widget包內需要創建的本地檔案數目。

本範例展示用戶代理嘗試本地化檔案,但本地檔案不存在這個本地方案(localized scenario)中,假設用戶代理的區域設置為 'en-gb'且Zip關聯路徑為 "images/mast.png"。

  1. 首先用戶代理找尋個資料夾,期望找到與用戶代理的區域設置盡可能接近的檔案,在此範例中,用戶代理試圖本地相關路徑將 'images/mast.png' 放置於 '/locales/en-gb/' ,但將會失敗。

  2. 接著,若檔案不存在(absent),用戶代理將到語言區(language range)的本地資料夾,遍尋任意其他子資料夾(sub-folder),因此用戶代理下個位置將在 'en/' 底下看到,且與Zip關聯路徑 'images/mast.png' 是一致的。

  3. 最後,若上述失敗,用戶代理則在根widget包尋找遺失檔案,所以如果用戶代理的區域設置在Zip關聯路徑下,找不到任何本地資料夾,則比對位於根widget包的 'images/mast.png' 檔且使用這個預設內容

考慮各種變體中文(various Chinese variants): 'zh-hans-cn' 、 'zh-hans' 和 'zh' 如下所示,在這個例子中,尋找 'flag.png' 檔供簡體中文(Mainland Chinese) 'zh-hans-cn' 於簡單腳本 使用,用戶代理先看到 'zh-hans-cn' ,隨後是 'zh-hans' ,最後是本地檔'zh' 。

找 'mast.png' 檔,用戶代理的找法是從 'zh-hans-cn' 找起,隨後是 'zh-hans' ,接著 'zh' ,且最後到根widget包尋找,發現接找不到此不存在檔的實際位置(actually located)。

file: /index.html

<!doctype html>
<title>Patriotic Boat</title>
<script src="scripts/engine.js">
</script>
<body>
  <img src="flag.png">
  <img src="mast.png">

Valid XHTML 1.0 Transitional

參考文獻 [back]

[ABNF]
Augmented BNF for Syntax Specifications: ABNF. RFC5234. D. Crocker and P. Overell. January 2008.
[BIDI]
Unicode Standard Annex #9: Unicode Bidirectional Algorithm. Unicode 5.2.0. M. Davis. 22 September 2009.
[BCP47]
Tags for Identifying Languages, A. Phillips and M. Davis, Editors, September 2009.
[CSS2]
Cascading Style Sheets Level 2 Specification. B. Bos, I. Hickson, T. Çelik, H. Wium Lie. W3C Candidate Recommendation 23 April 2009.
[Deflate]
DEFLATE Compressed Data Format Specification version 1.3. P. Deutsch, The Internet Society, May 1996.
[DOM3Core]
Document Object Model (DOM) Level 3 Core Specification. A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. W3C Recommendation 07 April 2004.
[HTML5]
HTML5, I. Hickson and D. Hyatt. W3C Working Draft. (Work in Progress)
[HTTP]
Hypertext Transfer Protocol -- HTTP/1.1. RFC 2616, R. Fielding, et al. June 1999.
[IRI]
Internationalized Resource Identifiers (IRIs). RFC3987, M. Duerst, M. Suignard. January 2005.
[MIME]
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. RFC2045, N. Freed and N. Borenstein, IETF, November 1996.
Multipurpose Internet Mail Extensions(MIME) Part Two: Media Types. RFC2046, N. Freed and N. Borenstein, IETF, November 1996.
[P&C-Test-Suite]
Test Suite for Widget Packaging and Configuration. Work in Progress.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. RFC2119, S. Bradner. March 1997.
[SNIFF]
Media Type Sniffing. A. Barth and I. Hickson. IETF (Work in Progress).
[SVGTiny]
Scalable Vector Graphics (SVG) Tiny 1.2 Specification. O. Andersson, R. Berjon, E. Dahlström, A. Emmons, J. Ferraiolo, A. Grasso, V. Hardy, S. Hayman, D. Jackson, C. Lilley, C. McCormack, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear. W3C Recommendation, 22 December 2008.
[Unicode]
The Unicode Standard.
[URI]
Uniform Resource Identifier (URI): Generic Syntax. RFC 3986, T. Berners-Lee, R. Fielding and L. Masinter. January 2005.
[UTF-8]
UTF-8: A Transformation format of ISO 1064. RFC 3629, F. Yergeau. IETF, November 2003.
[UTR36]
UTR #36: Unicode Security Considerations, M. Davis, M. Suignard. Unicode Consortium.
[Widgets-APIs]
The Widget Interface. M. Cáceres, R. Berjon, and A. Bersvendsen. (Work in progress).
[Widgets-DigSig]
Digital Signatures for Widgets. M. Cáceres, F. Hirsch, and M. Priestley. (Work in Progress).
[Widgets-Landscape]
The Widget Landscape (Q1 2008). M. Cáceres. W3C Working Draft. 14 April 2008. (Work in Progress)
[Widgets-Requirements]
Widgets Requirements, M. Cáceres and M. Priestley. W3C Working Draft, 30 April 2009. (Work in Progress)
[Widgets-Relax NG Schema]
Relax NG Schema for the Widgets Family of Specifications. Håsäther, David. (Work in Progress).
[Widgets-URI]
Widget URI Scheme. R. Berjon. (Work in progress).
[WS-i18n]
Web Services Internationalization Usage Scenarios. D. Banerjee, M. J. Dürst, M. McKenna, A. Phillips, T. Suzuki, T. Texin, M. Trumble, A. Vine and K. Noji. W3C Working Group Note 30 July 2004.
[View-Modes]
The 'view-mode' Media Feature. R. Berjon. W3C. (Work in Progress).
[XML]
Extensible Markup Language (XML) 1.0 (Fifth Edition). T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau. W3C, November 2008.
[XML-MIME]
XML Media Types. RFC3023. M. Murata, S. St. Laurent, D. Kohn. IETF. January 2001.
[XMLNS]
Namespaces in XML (Second Edition). T. Bray, D. Hollander, A. Layman, R. Tobin. W3C Recommendation, August 2006.
[ZIP]
.Zip File Format Specification. PKWare Inc, Version 6.3.2, September 28, 2007.
[ZIP-MIME]
IANA Media Type Assignment.