OpenAjax Metadata 1.0 Specification Descriptive

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.


<--previous       contents--^       next-->


Contents

Chapter 9: Descriptive elements and attributes

Introduction

This chapter describes the elements and attributes that provide descriptive metadata.

This chapter defines the following attribute collection:

  • descriptive_elements: a collection of descriptive elements that are available as child elements for many elements in the OpenAjax Metadata language

and the following elements and attributes:

  • <aboutMe> element: supplemental text information about an author
  • <author> element: information about one or more authors
  • <description> element: text description
  • <directoryTitle> element: short text string that can be displayed within a widget directory or catalog
  • <example> element: one or more illustrative examples
  • <icon> element: a small image (child element to <widget>)
  • <license> element: textual information about licensing
  • <quote> element: a quotation that a person associates with his signature
  • <reference> element: indicates a reference to other related documentation
  • <remarks> element: supplemental textual comment beyond the information found in the <description>
  • <shortDescription> elements: short text description (presumably shorter than <description>)
  • <title> element: short descriptive text suitable as a label or title bar
  • 'type' attribute: indicates whether an element's textual content is plain text (i.e., text/plain) or HTML rich text (i.e., text/html)


descriptive_elements

The following is the schema definition for descriptive_elements, which is referenced by other elements defined in other chapters:

descriptive_elements = (
  authors_element*  &  author_element*  &  description_element?  &
  examples_element*  &  example_element*  &  remarks_element?  &
  references_element*  &  reference_element*  &  shortDescription_element?  &  
  title_element?
)


<aboutMe>

The <aboutMe> is a child element of <author> and can be used to provide arbitrary supplemental textual information about the author beyond the information found in the <author> element's attributes and other sub-elements.

Schema

aboutMe_element = element aboutMe {
  aboutMe_content  &  aboutMe_attributes  &  foreign_attributes
}
aboutMe_content = (
  plain_text_or_html
)
aboutMe_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <aboutMe> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


Example

<widget xmlns="http://openajax.org/metadata">
  <authors>
    <author name="Charlie Chaplin">
      <aboutMe>I have many skills</aboutMe>
    </author>
  </authors>
  ...
</widget>


<author>

The <author> element describes one of the authors of the given widget or API. Supplemental information about the author beyond what is expressed in the various attributes can be supplied in either the <aboutMe> or <quote> sub-elements.

Schema

author_element = element author {
  author_content  &  author_attributes  &  foreign_attributes
}
author_content = (
  aboutMe_element?  &  quote_element?
)
author_attributes = (
  email?  &  location?  &  name  &  organization?  &  
  photo?  &  website?
)

Child content

The <author> element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Author's name. The name MUST be globally unique within the context of current container object. String yes none
email Author's email address String no none
location Author's primary geographical location, such as "Paris, France" String no none
organization Organization (e.g., company) name with which the author is associated String no none
photo URI where there is a picture of the person URI no none
website URI of the author's website URI no none


<description>

The <description> element provides a textual description for its parent.

Schema

description_element = element description {
  description_content  &  description_attributes  &  foreign_attributes
}
description_content = (
  plain_text_or_html
)
description_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <description> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


Example

In the following example, the <description> element provides a textual description for the <widget> element (its parent).

<widget ...>
   <description>Bar chart widget with configurable title and axis labels.</description>
   ...
</widget>

Additional information

If the <description> element is not provided for a given parent element, but other similar descriptive metadata is provided (e.g., <shortDescription> or <title>), then developer tools SHOULD use the value of the other descriptive metadata as the value for the (missing) <description> element.


<directoryTitle>

The <directoryTitle> element provides a text string that can be used as the widget's "display name" in a widget directory or catalog. This element SHOULD be provided if it is possible that the widget will be submitted into an online widget catalog.

Schema

directoryTitle_element = element directoryTitle {
  directoryTitle_content  &  directoryTitle_attributes  &  foreign_attributes
}
directoryTitle_content = (
  text
)
directoryTitle_attributes = ( 
  lang?  &  locid? 
)

Child content

The <directoryTitle> element contains a short plain text string.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.


<example>

The <example> element provides a single illustrative example (often, source code) for its parent element (or, when the <example> is a child of an <examples> element, its grandparent element).

Schema

example_element = element example {
  example_content  &  example_attributes  &  foreign_attributes
}
example_content = (
  plain_text_or_html
)
example_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <example> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


Example

<api ... >
  ...
  <method name="setStateColor">    
    <example>
<![CDATA[
var a = myobject.setStateColor(2008,"California","blue");    
]]> 
    </example>
    ...
  </method>
...
</widget>


<icon>

The <icon> element specifies the URI for a graphical representation of its parent (or grandparent if the parent element is the plural <icons> element).

Schema

icon_element = element icon {
  icon_content  &  icon_attributes  &  foreign_attributes
}
icon_content = (
  empty
)
icon_attributes = ( 
  width?  &  height?  &  src 
)

Child content

The <icon> element must be an empty element (i.e., no child content).

Attribute summary

AttributeDescriptionTypeRequiredDefault
height Height of the icon in pixels Positive integer no none
src URI that provides the Web address for the icon's graphics file URI yes none
width Width of the icon in pixels Positive integer no none


Example

<widget ... >
  ...
  <icons>                
    <icon width="36" height="36" src="lightwindow_pi.gif" />
    <icon width="16" height="16" src="lightwindow.gif" />
  </icons>
...
</widget>

Additional information

When multiple <icon> elements appear in the widget metadata file, the developer tool MAY select an icon that appears to be the closest match to its needs and rescale as necessary.

Developer tools MAY use image size information included within the referenced image file instead of the values specified in the width and height attributes.

If the width and/or height attributes are not provided, the default value is implementation-dependent.


<license>

The <license> element describes license information about this widget. The textual content might contain the actual license text or might include a URL where the license text can be found.

Schema

license_element = element license {
  license_content  &  license_attributes  &  foreign_attributes
}
license_content = (
  plain_text_or_html
)
license_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <license> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


<quote>

The <quote> element provides a quotation that a person associates with his signature, in either plain text or HTML.

Schema

quote_element = element quote {
  quote_content  &  quote_attributes  &  foreign_attributes
}
quote_content = (
  plain_text_or_html
)
quote_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <quote> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


<reference>

The <reference> element indicates a reference to other related documentation. The content of the element provides the text that describes the reference.

Schema

reference_element = element reference {
  reference_content  &  reference_attributes  &  foreign_attributes
}
reference_content = (
  plain_text_or_html
)
reference_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <reference> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


<remarks>

The <remarks> element provides optional supplemental textual comments about its parent element. It is assumed that the primary descriptive text is contained in the <description> element.

Schema

remarks_element = element remarks {
  remarks_content  &  remarks_attributes  &  foreign_attributes
}
remarks_content = (
  plain_text_or_html
)
remarks_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <remarks> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


<shortDescription>

The <shortDescription> element provides a short textual description for its parent.

Schema

shortDescription_element = element shortDescription {
  shortDescription_content  &  shortDescription_attributes  &  foreign_attributes
}
shortDescription_content = (
  plain_text_or_html
)
shortDescription_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <shortDescription> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


Example

The following example shows the expected usage of the <description> and <shortDescription> elements. The <description> element provides the longer textual description for the <widget> element (its parent), and the <shortDescription> element provides the shorter description.

<widget ...>
   <description>
     Bar chart widget with configurable title and axis labels.
     The title can be up to 3 lines of text.
     The vertical axis label can be rendered on its side or as stacked characters.
   </description>
   <shortDescription>Bar chart widget with configurable title and axis labels.</shortDescription>
   ...
</widget>

Additional information

If the <shortDescription> element is not specified on a given parent element, but other similar descriptive metadata is provided (e.g., <title> or <description>), then developer tools SHOULD use the value of the other descriptive metadata as the value for the (missing) <shortDescription> element.


<title>

The <title> element contains short descriptive text suitable as a label or title bar.

Schema

title_element = element title {
  title_content  &  title_attributes  &  foreign_attributes
}
title_content = (
  plain_text_or_html
)
title_attributes = ( 
  lang?  &  locid?  &  type? 
)

Child content

The <title> element can contain either plain text or HTML markup.

Attribute summary

AttributeDescriptionTypeRequiredDefault
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
locid Lookup key into the message bundle files. Defined in Localization chapter.
type Whether the content is plain text or HTML markup. Defined in Plain text or HTML section.


Content that can be plain text or HTML

Several elements within the OpenAjax Metadata specification, such as the <description> element, allow content that can be either "plain text or HTML". Each of these elements has a type attribute that specifies a MIME type for the element's content.

This specification defines behavior for two possible values for the type attribute:

  • text/plain: (the default) for plain text that SHOULD be presented "as is" to the user
  • text/html: for rich text expressed as an HTML snippet that SHOULD be suitable as the innerHTML of an HTML <div> element and that SHOULD be processed and rendered by an engine that can parse and render HTML

text/plain

If the type attribute has the value text/plain, then the content of the element SHOULD be presented "as is" to the user. For example:

<description>A small amount of text (i.e., "plain text")</description>

SHOULD result in the user seeing the following:

A small amount of text (i.e., "plain text")

With text/plain, newlines and white space SHOULD be preserved. For example:

<description>This is line 1
 This is line 2
   This is line 3</description>

SHOULD result in the user seeing the following:

This is line 1
 This is line 2
   This is line 3

Because the OpenAjax Metadata file is expressed in XML, the metadata author SHOULD enclose the plain text content in a CDATA construct if the content contains any of the special literal markup characters that have special meaning to an XML parser, such as "&", "<" and ">". For example, if you want a description that will present this string to the user: "where N is an integer & N > 0 & N < 20", then you could use a CDATA construct as follows:

<description>
<![CDATA[
where N is an integer & N > 0 & N < 20
]]>
</description>

One possible detailed processing model for plain text content is as follows:

  1. From the original source metadata file, extract the complete string of characters between the start element tag and the end element tag, including any white space and newlines. For <description type="text/plain">Here is the description </description> (notice the trailing space character), the extracted text would be "Here is the description " (again, notice the trailing space character).
  2. Strip out all CDATA constructs. For example, with <description type="text/plain">PPP <![CDATA[-bbb-]]> QQQ</description>, the result text string would be "PPP -bbb- QQQ".
  3. If rendering the text using an HTML engine, perform the following substitutions:
    • '&' (ampersand) characters are converted into '&amp;'
    • '"' (double quote) characters are converted into '&quot;'
    • ''' (single quote) characters are converted into '&#039;'
    • '<' (less than) characters are converted into '&lt;'
    • '>' (greater than) characters are converted into '&gt;'
    • Newlines are converted into '<br />'
    • White space characters become '&nbsp;'

text/html

If the type attribute has the value text/html, then the content of the element SHOULD be an HTML snippet that is presented to the user as rich text.

Here are examples using the <description type="text/html"> element:

[1] <description type="text/html">Text that is to be rendered as HTML but contains no markup</description>

[2] <description type="text/html">A small amount of text with <b>limited use</b> of HTML markup</description>

[3] <description type="text/html">
      <p>This is an example that shows two HTML paragraphs</p>
      <p>This is the second paragraph</p>
    </description>

[4] <description type="text/html">
    <![CDATA[
      <p>Some HTML text that is not well-formed XML</p>
      <ul>
        <li>A bullet without a proper end element
        <li>A second bullet
      </ul>
    ]]>
    </description>
  • Example [1] SHOULD be rendered as "Text that is to be rendered as HTML but contains no markup".
  • Example [2] SHOULD render the words "limited use" using boldface.
  • Example [3] SHOULD render as two paragraphs.
  • Example [4] illustrates the use of the CDATA construct to bracket content that is not proper XML (because the </li> end tags are missing) and SHOULD render as a paragraph followed by two bulleted items.

Developer tools SHOULD support the ability to render formatted HTML content as rich text; however, if unable to render HTML rich text, the developer tool SHOULD still render the content somehow, such as stripping out the markup. For example:

<description type="html">
this word is <b>bold</b>.
</description>

which might render as (after stripping out the markup):

this word is bold.

or alternatively the developer tool might simply render the original markup exactly as is (but for security reasons replacing < and > with entities &lt; and &gt;, which produce the same visual result):

this word is <b>bold</b>.

(Note: Metadata authors may want to format their content such that the content is still readable if a developer tool chooses to strip out the markup.)

Because the HTML content is meant to be suitable for inclusion within an HTML <div> element, the content SHOULD not contain any of the following HTML elements: <base>, <body>, <iframe>, <frame>, <frameset>, <head>, <html>, or <title>, and most of the time also SHOULD not contain <link>, <meta>, <style>, or <script>.

Metadata authors need to be aware that different developer tools will support different subsets of HTML. Therefore, for common cases, metadata authors are advised to use a simple common subset of HTML for any rich text content to maximize portability.

Developer tools SHOULD take appropriate measures to prevent malicious HTML content from executing unwanted JavaScript logic, such as cross-site scripting (XSS) attacks due to JavaScript logic secretly embedded within the content. (See discussion of security considerations in the Introduction chapter and discussion of cross-site scripting at: "Ajax and Mashup Security"). Note that there are several advanced ways to include executable content within HTML, such as

<a href="javascript:alert('hi')">press me</a>

The detailed processing model for the HTML descriptive content is as follows:

  1. From the original source metadata file, extract the complete string of characters between the start element tag and the end element tag. For example, for <description type="text/html"><b>Here</b> is the description </description>, the extracted text would be "<b>Here</b> is the description".
  2. Strip out all CDATA constructs. For example, with <description type="text/html">PPP <[CDATA[-bbb-]]> QQQ</description>, the result text string would be "PPP -bbb- QQQ".
  3. Take appropriate measures such as entity encoding and whitelisting to filter out potentially malicious HTML constructs.
  4. Render the result of the previous steps using an engine capable of parsing and rendering rich text HTML content.

<--previous       contents--^       next-->
Personal tools