w3c package

http://www.w3.org/TR/widgets/

http://www.w3.org/TR/2009/CR-widgets-20090723/

 

 

The following is an example of a typical configuration document:

<?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 NONINFRINGEMENT.
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>

Note: Implementers are encouraged to expose relevant information provided by the configuration document to the user. Having "visual metadata" encourages authors to make full use of the configuration document format. See Step 7 for instructions on how to process a configuration document.

 

 

 

7.3 Proprietary Extensions

This section is non-normative.

Implementers or authors intending to extend the configuration document format with their own [XML] elements and attributes (or those defined in other specifications) can do so by using a separate [XMLNS] namespace. This specification does not define a model for processing [XML] elements outside the widget namespace (they are simply ignored during processing).

Example of extending the configuration document format:

<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

This section defines the different attribute types used in the configuration document and what constitutes valid values for those attribute types.

An attribute is invalid if its value does not conform to its said attribute type; that is, if the value of the attribute is in error given the processing rules for that type of attribute.

Boolean attribute

A boolean attribute is a keyword attribute that can only be used with a valid boolean value. A valid boolean value is a keyword that case-sensitively matches true or false. Unless specified otherwise, the default behavior, which is used when the attribute is omitted or has a value other than the two allowed values, is false. The way a user agent interprets a boolean attribute is defined as part of an attribute's definition (see, for example, the feature element's required attribute).

String attribute

The value of a string attribute is any string that conforms to [XML] as a valid string for an XML attribute. The purpose of this attribute type is to classify strings that are not affected by the dir attribute, such as the email attribute (i.e., these attributes will not treated as displayable-strings during Step 7).

Displayable-string attribute

An attribute whose primary purpose is to convey human readable information, such as the name element's short attribute and the widget element's version attribute.

Keyword attribute

A keyword is a string that is reserved for the purpose of this specification. The value of a keyword attribute is a keyword that is one of a finite set specified in the attribute's definition in the case given in this specification.

Keyword list attribute

An attribute defined as taking one or more keywords as a value, which are separated by space characters.

Media type attribute

An attribute whose value is defined as containing a valid media type. A valid media type is string that matches the production for valid-MIME-type in the following [ABNF]:

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

The type, subtype, and parameter tokens are defined in the [MIME] specification.

Language attribute

An attribute whose value is defined as containing a valid language tag (see the IANA Language Subtag Registry for an authoritative list of possible values, see also the Maintenance Agency for ISO 3166 country codes). A valid language tag is a string that conforms to the production of a Language-Tag, as defined in the [BCP47] specification.

Numeric attribute

The value of a numeric attribute is a string containing a valid non-negative integer. A valid non-negative integer is a string that consists of one or more code points in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). For example, the strings "002", "323", "23214", and so on.

Path attribute

An attribute defined as containing a valid path. A valid path is one that matches the production of a Zip-rel-path or a Zip-abs-path.

Authoring Guidelines: A valid path is not a URI: a valid path represents a hierarchical path to a file inside a Zip archive, which exactly matches the value of a file name field of a local file header of a file entry. This means that valid paths need not be URL encoded.

IRI attribute

An attribute defined as containing a valid IRI. A valid IRI is one that matches the IRI token of the [IRI] specification.

Authoring Guidelines: Because of the risk of confusion between IRIs that would be equivalent if dereferenced, the use of %-escaped characters in feature names is strongly discouraged.

Version attribute

A displayable-string attribute whose value is any arbitrary string value (possibly empty) within the constraints allowed for [XML] attributes. This specification does not mandate any specific format, semantics, or special processing rule for the format of a version attribute.

Authoring Guidelines: For the purpose of this specification, the structure of version tags has no semantics; they are just treated as arbitrary strings (e.g. '1.0' is not less than '2.0', but is simply different). However, for the sake of consistency, one can choose to use the following [ABNF]:

rec-version-tag = 1*DIGIT "."  1*DIGIT [ "." 1*DIGIT]
                  *[ 1*ALPHA / SP / 1*DIGIT ]
Example version tags:
  • Version 1.0 Beta
  • 1.0 RC1
  • 1.0-Build/1580
  • Joey the dog [5.1.2100]
Example of rec-version-tag:
  • 1.0
  • 1.10.1 beta1
  • 1.02.12 RC1

7.5 Global Attributes

This section describes the behavior and expected usage of other relevant attributes that are part of the [XML] specification and this specification. In this specification, these attributes are referred to as global attributes because they can be used on any element in a configuration document.

Although global attributes can be used on any element in this specification, they sometimes have no effect on the element on which they are used. For example, applying dir attribute on an icon element will have no effect on the icon elements or any of its attributes. What effect specifying a global attribute has on an elements is determined by Step 7 of this specification.

Authoring Guidelines: Although it is optional for an author to use any global attributes, their usage is recommended when appropriate (e.g., when declaring the language will help with legibility and when directional information will assist the user agent render text correctly).

7.5.1 The xml:lang Attribute

A language attribute that specifies, through a language tag, the language of the contents and attribute values of XML elements (see the IANA Language Subtag Registry). The [XML] specification specifies the xml:lang attribute and its influence on child nodes.

Authoring Guidelines: Although [BCP47] recommends that language tags be casefolded in a particular way for presentation, case has no meaning in a language tag. As a reminder to authors that user-agents map all language tags to lowercase, all examples in this document use lowercase. See also folder-based localization, which also requires authors to use language tags in lowercase form as the names of folders.

Avoid subtags from the IANA Language Subtag Registry marked as deprecated, grandfathered, or redundant. The intended purpose of the xml:lang attribute is to declare the primary language of an element, its attributes, and its descendant nodes; as such, it has no implication with regards to the directionality of the text in the user agent. To specify the directionality of text, see the dir attribute.

7.5.2 The dir Attribute

A keyword attribute used to specify the directionality in which human-readable text is to be represented by a user agent (e.g., the text content of the name element, the description element, and the license element). The directionality set by the dir attribute applies to the text content and any displayable string attributes of the element where it is used, and to child elements in its content unless overridden with another instance of dir (i.e., in this specification, the dir attribute only affects the short attribute of the name element and to the version attribute of the widget element).

The possible value of a dir attribute is one of the valid directional indicators:

ltr

Left-to-right text. Request that the Unicode [BIDI] algorithm treat characters within an element as embedded left-to-right.

rtl

Right-to-left text. Request that the Unicode [BIDI] algorithm treat characters within an element as embedded right-to-left.

lro

Left-to-right override. Forces the Unicode [BIDI] algorithm to treat characters within an element as strong left-to-right characters.

rlo

Right-to-left override. Forces the Unicode [BIDI] algorithm to treat characters within an element as strong right-to-left characters.

Note:For security reasons, implementations intending to display IRIs and IDNA addresses found in the configuration document are strongly encouraged to follow the security advice given in [UTR36]. This could include, for example, behaving as if the dir attribute had no effect on any IRI attributes, path attributes, and the author element's email attribute.

The base direction of a dir attribute is either set explicitly by the nearest parent element that uses the dir attribute; or, in the absence of such an attribute, the base direction is inherited from the default direction of the document, which is left-to-right ("ltr").

7.5.3 Examples of Usage

The following example demonstrates the dir attribute being applied globally to a configuration document.

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

The following example shows the dir attribute applied to localized content.

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

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

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

</widget>

The following example shows the dir attribute used with 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 The widget Element and its Attributes

The widget element serves as a container for the other elements of the configuration document.

Context in which this element is used:
The widget element is the root element of a configuration document.
Occurrences:
Exactly one, at the root element of the [XML] document.
Expected children (in any order):
name: zero or more (one element is allowed per language).
description: zero or more (one element is allowed per language).
author: zero or one.
license: zero or more (one element is allowed per language).
icon: zero or more.
content: zero or one.
feature: zero or more.
preference: zero or more.
Localizable via xml:lang:
No. Inheritance of the value of this attribute by author, preference, icon, and content will have no effect during processing in Step 7.
Attributes:
Global attributes, id, version, height, width, viewmodes.

7.6.1 The id Attribute

An IRI attribute that denotes an identifier for the widget.

Authoring Guidelines: It is optional for authors to use the id attribute with a widget element.

7.6.2 The version Attribute

A version attribute that specifies the version of the widget.

Authoring Guidelines: It is optional for authors to use the version attribute with a widget element.

7.6.3 The height Attribute

A numeric attribute greater than 0 that indicates the preferred viewport height of the instantiated custom start file in CSS pixels [CSS].

Authoring Guidelines: It is optional for authors to use the height attribute with a widget element.

7.6.4 The width Attribute

A numeric attribute greater than 0 that indicates the preferred viewport width of the instantiated custom start file in CSS pixels [CSS].

Authoring Guidelines: It is optional for authors to use the width attribute with a widget element.

7.6.5 The viewmodes Attribute

A keyword list attribute that denotes the author's preferred view mode, followed by the next most preferred view mode and so forth. When the attribute is missing, or is left empty, it implies that the author expects the user agent to select an appropriate viewmode for the widget.

The concept of a viewport is defined in [CSS], but is essentially a window or other viewing area on the screen (see section 9.1.1 The viewport of [CSS]). The concept of a view mode is defined in the [View-Modes] specification.

Authoring Guidelines: It is optional for authors to use the viewmodes attribute with a widget element.

7.6.6 The defaultlocale attribute

A language attribute that specifies, through a language tag, the author's preferred locale for the widget. Its intended use is to provide a fallback in case the user agent cannot match any of the widget's localized content to the user agent locales list or in case the author has not provided any unlocalized content.

Authoring Guidelines: It is optional for authors to use the defaultlocale attribute with a widget element.

7.6.7 Example of Usage

The following example shows how the widget element can be used.

<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.6.8 Example of Usage of the defaultlocale attribute

The following example shows how the widget element's defaultlocale attribute can be used:

<widget xmlns = "http://www.w3.org/ns/widgets"
        defaultlocale = "en-us">

   <name short="Weather" xml:lang="en-us">
    The Ultimate Weather Widget
   </name>

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

</widget>

7.7 The name Element and its Attributes

The name element represents the full human-readable name for a widget that is used, for example, in an application menu or in other contexts.

Context in which this element is used:
In a widget element.
Content model:
Any.
Occurrences:
Zero or more (one element is allowed per language).
Expected children:
span: zero or more.
Localizable via xml:lang:
Yes.

Authoring Guidelines: The value of the xml:lang attribute needs to be unique for any subsequent element of this type.

Attributes:
Global attributes, short.

7.7.1 The short Attribute

A displayable-string attribute intended to represent a condensed name for a widget (e.g., a name that could be used in context were only limited space is available, such as underneath an icon).

Authoring Guidelines: It is optional for authors to use the short attribute with an name element.

7.7.2 Example of Usage

The following example shows the usage of the name element.

<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 The description Element and its Attributes

The description element represents a human-readable description of the widget.

Context in which this element is used:
In a widget element.
Content model:
Any.
Occurrences:
Zero or more (one element is allowed per language).
Expected children:
span: zero or more.
Localizable via xml:lang:
Yes.

Authoring Guidelines: The value of the xml:lang attribute needs to be unique for any subsequent element of this type. If two or more elements with the same xml:lang attribute value are encountered, the user agent will ignore all but the matching first element. See Step 7 for more details.

Attributes:
Global attributes.

7.8.1 Example of Usage

An example usage of the description element.

<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 The author Element and its Attributes

An author element represents people or an organization attributed with the creation of the widget.

Context in which this element is used:
As a child of the widget element.
Content model:
Any.
Occurrences:
Zero or one.
Expected children:
span: zero or more.
Localizable via xml:lang:
No. Only the first instance of this element in document order will be used, regardless of the value of xml:lang (if any).
Attributes:
Global attributes, href, email.

7.9.1 The href Attribute

An IRI attribute whose value represents an IRI that the author associates with himself or herself (e.g., a homepage, a profile on a social network, etc.).

Authoring Guidelines: It is optional for authors to use the href attribute with an author element.

7.9.2 The email Attribute

A string attribute that represents an email address associated with the author.

Authoring Guidelines: It is optional for authors to use the email attribute with an author element.

7.9.3 Example of Usage

The following example shows the expected usage of the author element.

<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 The license Element and its Attributes

The license element represents a software license, which includes, for example, a usage agreement, redistribution statement, and/or a copyright license terms under which the content of the widget package is provided.

Context in which this element is used:
As a child of the widget element.
Content model:
Any.
Expected children:
span: zero or more.
Occurrences:
Zero or more (one element is allowed per language).
Localizable via xml:lang:
Yes.

Authoring Guidelines: The value of the xml:lang attribute needs to be unique for any subsequent element of this type. The content of localized license elements shouldn't be used to present different versions of a license, just translations of the same license.

Attributes:
Global attributes, href.

7.10.1 The href Attribute

A valid IRI or a valid path that points to a representation of a software and/or content license.

Authoring Guidelines: It is optional for authors to use the href attribute with a license element.

7.10.2 Example of Usage

This example shows the expected usage of the license element's href attribute.

<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>

This example shows the expected usage of the license element when the href attribute is omitted.

<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 The icon Element and its Attributes

The icon element represents a custom icon for the widget.

Context in which this element is used:
As a child of the widget element.
Content model:
Empty.
Occurrences:
Zero or more.
Localizable via xml:lang:
No. Relies on folder-based localization.
Attributes:
Global attributes, src, width, height.

7.11.1 The src Attribute

A path attribute that points to a file inside the widget package.

Authoring Guidelines: When an icon element is used, it is required for authors to use the src attribute.

7.11.2 The width Attribute

A numeric attribute greater than 0 that represents, in CSS pixels [CSS], the author's preferred width for the icon. A user agent may ignore this value when changing the height icon to fit a rendering context or for accessibility reasons.

Authoring Guidelines: It is optional for authors to use the width attribute of an icon element.

7.11.3 The height Attribute

A numeric attribute greater than 0 that represents, in CSS pixels [CSS], the author's preferred height for the icon. A user agent may ignore this value when changing the height icon to fit a rendering context or for accessibility reasons.

Authoring Guidelines: It is optional for authors to use the height attribute of an icon element.

7.11.4 Example of Usage

This example shows the expected usage of the icon element. The example declares three icon elements, two of which are raster and one of which is an [SVGTiny] file. The raster graphics would be used for display contexts smaller than 256x256 pixels. Document order of the elements is irrelevant.

<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 The content Element and its Attributes

The content element is used by an author to declare which custom start file the user agent is expected to use when it instantiates the widget.

Context in which this element is used:
As a child of the widget element.
Content model:
Empty.
Occurrences:
Zero or one.
Localizable via xml:lang:
No. Relies on folder-based localization.
Attributes:
Global attributes, src, type, encoding.

7.12.1 The src Attribute

A path attribute that allows an author to point to a file within the widget package.

Authoring Guidelines: When a content element is used, it is required for authors to use the src attribute.

7.12.2 The type Attribute

A media type attribute that indicates the media type of the file referenced by the src attribute.

Authoring Guidelines: It is optional for authors to use the type attribute with a content element. When the value is absent, the user agent will assume the value text/html.

7.12.3 The encoding Attribute

A keyword attribute that denotes the character encoding of the file identified by the src attribute. The value is the "name" or "alias" of any "Character Set" listed in [IANA-Charsets].

Authoring Guidelines: It is optional for authors to use the encoding attribute with a content element. Where aliases are given by the [IANA-Charsets] registry, authors are encouraged to use the value of the "preferred MIME name" (if any) from the registry.

The default encoding is [UTF-8], which has the name "UTF-8" in the [IANA-Charsets] registry.

Aside from the default encoding, it is optional for a user agent to support other character encodings.

7.12.4 Example of Usage

This example shows the expected usage of the content element:

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

</widget>

This example shows the content element being used with a encoding attribute to override the default value of the encoding attribute (UTF-8) with the GB2312 character set, which the author has used to encode simplified Chinese characters:

<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>

This example shows the content element being used with a type attribute to instantiate a widget created with a proprietary 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 The feature Element and its Attributes

A feature is a URI identifiable runtime component (e.g. an Application Programming Interface or video decoder). The act of a an author requesting the availability of a feature through a feature element is referred to as a feature request. The feature element serves as a standardized means to request the binding of an IRI identifiable runtime component to a widget for use at runtime. Using a feature element denotes that, at runtime, a widget can attempt to access the feature identified by the feature element's name attribute. How a user agent makes use of features depends on the user agent's security policy, hence activation and authorization requirements for features are beyond the scope of this specification. A feature has zero or more parameters associated with it.

Context in which this element is used:
As a child of the widget element.
Content model:
Zero or more param elements.
Occurrences:
Zero or more.
Localizable via xml:lang:
No.
Attributes:
Global attributes, name, required.

7.13.1 The name Attribute

An IRI attribute that identifies a feature that is needed by the widget at runtime (such as an API).

Authoring Guidelines: When the feature element is declared, it is required for authors to use the name attribute.

7.13.2 The required Attribute

A boolean attribute that indicates whether or not this feature has to be available to the widget at runtime.

When set to true, the required attribute denotes that a feature is absolutely needed by the widget to function correctly, and without the availability of this feature the widget serves no useful purpose or won't execute properly.

When set to false, the required attribute denotes that a widget can function correctly without the feature being supported or otherwise made available by the user agent.

Authoring Guidelines: It is optional for authors to use the required attribute with an feature element. However, authors need to be aware that a user agent will behave as if the required attribute had been set to true when the required attribute is absent, meaning that the named feature needs to be available at runtime or the widget will be treated as an invalid widget package.

7.13.3 Example of Usage

This example demonstrates a widget that would like to use a fictional geo-location API feature, but would still be able to function if the feature cannot be made available to the widget by the user agent.

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

7.14 The param Element and its Attributes

The param element defines a parameter for a feature. A parameter is a name-value pair that is associated with the corresponding feature for which the parameter is declared for. A author establishes the relationship between a parameter and feature by having a param element as a direct child of a feature element in document order.

Context in which this element is used:
As a child of the feature element.
Content model:
Empty.
Occurrences:
Zero or more.
Localizable via xml:lang:
No.
Attributes:
Global attributes, name, value.

7.14.1 The name Attribute

A string attribute that denotes the name of this parameter.

Authoring Guideline:When a param element is declared, it is required for authors to use the name attribute.

7.14.2 The value Attribute

A string attribute that denotes the value of this parameter.

Authoring Guidelines: When a param element is used, it is required for authors to use the value attribute.

7.14.3 Example of Usage

This example demonstrates a widget that makes use of a fictional geo-location feature where by its accuracy is set to "low" via a param element.

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

7.15 The preference Element and its Attributes

The preference element allows authors to declare one or more preferences: a preference is a persistently stored name-value pair that is associated with the widget the first time the widget is initiated.

Note: A user agent that supports the [Widgets-APIs] specification will expose any declared preference at runtime in the manner described in the [Widgets-APIs] specification.

Context in which this element is used:
As a child of the widget element.
Occurrences:
Zero or more.
Expected children:
none.
Localizable via xml:lang:
No.
Attributes:
Global attributes, name, value, readonly.

7.15.1 The name Attribute

A string that denotes the name of this preference.

Authoring Guidelines: When a preference element is used, it is required for authors to use the name attribute.

7.15.2 The value Attribute

A string that denotes the value of this preference.

Authoring Guidelines: It is optional for authors to use the value attribute with a preference element.

7.15.3 The readonly Attribute

A boolean attribute indicating whether this preference can, or cannot, be overwritten at runtime (e.g., via an author script). When set to true, it means that the preference cannot be overwritten. When set to false, it means that the preference can be overwritten.

Authoring Guidelines: It is optional for authors to use the readonly attribute with a preference element. If the readonly attribute is absent, the user agent will act as if the readonly attribute had been set to false (meaning that the preference can be overwritten at runtime).

7.15.4 Example of Usage

This example shows a widget where two preferences are set. The second preference is set as "read only" via the readonly attribute, which means the values of that preference cannot be changed at runtime.

<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 The span Element and its Attributes

The span element is a wrapper for text content; on its own it serves no useful function.

It is expected that authors will use the span element with the global attributes. When combined with the dir attribute, the span element can indicate the textual directionality of text content. In other words, it allows authors to set the base direction for the Unicode bidirectional algorithm [BIDI]. When combined with the xml:lang attribute, the span element allows the author to indicate the particular language used for a subset of text content within another element.

Context in which this element is used:
As a child of the name, author, license, and/or description element.
Occurrences:
Zero or more.
Expected children:
Any.
Localizable via xml:lang:

No, meaning that declaring xml:lang on a span element within a parent element (e.g., a name element) will not affect the behavior of element-based localization (see Example of Usage below to see how this works).

Authoring Guidelines: Authors are encouraged to use xml:lang to indicate the language information for text content contained within a span element. See Example of Usage for more information.

Attributes:
Global attributes.

7.16.1 Example of Usage

This section is informative.

This example shows the span elements being used to indicate directionality of text as well as language information. Note that the name element's xml:lang attribute is set to an empty string to allow it to be used as default content in the process of 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>
posted @ 2014-09-10 14:28  alxe_yu  阅读(192)  评论(0)    收藏  举报