OpenAjax Metadata 1.0 Specification Futures

From MemberWiki

Jump to: navigation, search

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


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


Contents

Appendix B: Futures

Introduction

This appendix lists features that the IDE Working Group at OpenAjax Alliance has postponed out of the version 1.0 OpenAjax Metadata Specification. These features might or might not be included in future versions of the OpenAjax Metadata Specification, and if included in the future, there might be significant changes to the descriptions provided below. The main motivation for including this appendix is to provide starting point feature definitions in case people in the industry find that they need to extend OpenAjax Metadata to meet particular requirements.

The features listed below have had various degrees of discussion within the IDE Working Group. Some of the features have had extensive discussion, and were postponed from the version 1.0 specification only because no products were implementing the given feature in time for version 1.0 approval. Other features are more speculative and had limited discussion.

If products find a need to implement any of the features below, those features SHOULD be implemented as extensions and therefore SHOULD use appropriate namespacing techniques. Markup extensions SHOULD use XML namespaces (with a namespace URI different than the one used by this specification) for any of the elements and attributes described in this chapter. For example, if a product decides to implement support for the <include> element described below, then that element SHOULD have a different XML namespace than the approved features found in this specification:

<widget id="http://example.com/widget2"
        name="Widget2" spec="1.0" width="208" height="148"
        xmlns="http://openajax.org/metadata"
        xmlns:abc="http://mydomain/abc">
  <abc:include src="abc_oam.xml"/>
  <content>Hello, world</content>
</widget>

The sections below describe the various features that were postponed out of OpenAjax Metadata 1.0.


Library Metadata

This would be a simple XML file that might exist in the root folder of an Ajax library distribution and provides a small amount of general metadata about the given library, such as its prefix, namespaceURI, and version, all of which are expected to align with entries in the OpenAjax Registry and the parameters that are passed to OpenAjax.hub.registerLibrary().

For example:

<library xmlns="http://openajax.org/metadata"
  prefix=""
  namespaceURI=""
  version="" 
  ...probably other things such as pointers to the website...

  <eventHandlersPatterns>
    <addEventHandlerPattern pattern="...string with variables..." />
    <removeEventHandlerPattern pattern="...string with variables..." />
  </eventHandlersPatterns>
/>

Under consideration were sub-elements <eventHandlersPatterns>/{<addEventHandlerPattern>,<removeEventHandlerPattern>} that specified pattern naming conventions for the add/remove subscriber methods, such as {token} = OpenAjax.hub.subscribe({name}, {handler}).

Schema

library_element = element library {
  library_content  &  library_attributes  &  foreign_nodes
}
library_content = (
  eventHandlerPatterns_element*  & 
  pattern_attribute  & 
  descriptive_elements 
)
library_attributes = (
  prefix?  &  namespaceURI?  &  version?
)


Inclusion

This section describes a metadata inclusion feature using the <include> element.


<include>

Schema

include_element = element include {
  include_content  &  include_attributes  &  foreign_attributes
}
include_content = (
  empty 
)
include_attributes = (
  src
)

Additional notes

The <include> element references an external file whose content is to be transcluded into the current document.

The referenced document MUST be a well-formed XML file with a <fragment> root element. If the referenced document does not meet the criteria, the reference file MUST be ignored and null content should be used to replace the <include> element.

If the referenced document is satisfactory, then the infoset of the metadata file MUST be modified such that the <include> element is replaced by the set of child nodes of the root <fragment> element from the referenced file.

It is incumbent on metadata authors to ensure that the post-transclusion document is valid against the metadata language schema.

The src attribute specifies the URI of the file whose content is to be transcluded into this document.


<fragment>

The <fragment> element is the root element for files that are referenced by the <include> element.

fragment_element = element fragment {
  anything
}


openajaxmetadata: protocol for referencing

The custom protocol handler "openajaxmetadata:foo" indicates a reference to other objects that are described by OpenAjax Metadata, where you would specify such a reference using an <a> element, as in see <a href="openajaxmetadata:foo">foo</a>


Localization via file substitution

With this proposed feature, authors can localize particular files by placing alternate, localized versions of those files inside a folder named 'locales/' that is located in the same folder as the metadata file. Particular localizations must be located within a sub-folder whose name follows the Language Tag conventions set forth in BCP47, such as "en-us", "en-gb", and so on. For example, localization files for the French as used in Canada locale would be located in the locales/fr-CA folder.

For each localized file, the file name and relative path from the original file to the folder containing the OpenAjax Metadata file must be the same as the file name and relative path from the localized file to the root folder for the given locale. For example, assume there is a widget that requires an original image file located at "images/family.jpg" (the original target file), and assume there is an alternative image file for the French Canadian locale. For this case, the folder hierarchy should be as follows:

mywidget_oam.xml
images/
  family.jpg
locales/
  fr-CA/
    images/
      family.jpg

File substitution algorithm

For all file references within an OpenAjax Metadata file, the developer tool must first check for to see if there is an alternate, localized version of that file that corresponds to the current system locale. If a localized version is found, the developer tool MUST use the appropriate localized version instead of the referenced file.

The following is the algorithm that developer tools MUST use when determining which localized file to use as the localized replacement for a given target file. The algorithm makes use of the lookup mechanism as defined in section 3.4 of RFC4647 (part of BCP47). The aim is to match, in order, one of the language ranges found in the current system locale to a localized folder in the widget resource. For illustrative discussion for this algorithm, assume that the target file is "images/family.jpg":

  • If the system locale consists of a list (e.g., "fr-CA,fr,de"), then apply the following steps on the first locale in the list (e.g., "fr-CA"). If a localized file match is found corresponding to that locale, then stop; otherwise, continue with the next locale on the list until either a match is found or the list is exhausted. For example, if file "locales/fr-CA/images/family.jpg" exists, since "fr-CA" is the first locale in the list, then a localized file would exist for the first locale. Therefore, use that file and quit the algorithm. Otherwise, continue looking for files that match the other locales (i.e., "fr" and "de").
  • For each of the locales in the list:
    • If the given locale is a single "*" or begins with a "*", then use the original target file
    • If the given locale contains any intermediate subtags "*", then remove that subtag (e.g., "en-*-US" becomes "en-US")
    • Look for a file match in the folder that matches the locale string. For example, if the locale is "fr-CA" and the target file is "images/family.jpg", look for file "locales/fr-CA/images/family.jpg". If found, then use that file and quit the algorithm.
    • Otherwise, remove the last subtag and look for a file match. For example, if the locale is "fr-CA" but there was no file at "locales/fr-CA/images/family.jpg", then drop the "-CA" and look for a file at "locales/fr/images/family.jpg". If found, then use that file and quit the algorithm. If not found, repeat this step until all subtags are exhausted.
    • If no match was found for this locale, continue with the next locale in the list
  • If no match was found for any of the locales, then use the original target file


Standard JSON representation of OpenAjax Metadata

OpenAjax Alliance might define a normative definition of the JSON representation of the OpenAjax Metadata infoset. Such a JSON representation would allow pure JavaScript implementations to be interoperable without requiring those implementations to deal with the XML DOM, thereby allowing lighterweight and smaller implementations. In many workflows, the conversion from XML into JSON might happen at design-time or via a server preprocessor.


Inline API commenting conventions

OpenAjax Alliance might produce specification and/or open source that includes a set of inline commenting rules, probably using JSDoc. Two key objectives might be: (1) infoset alignment between the inline commenting conventions and API XML metadata found in OpenAjax Metadata, and (2) minimally lossy transformations between the inline comments and the XML metadata format.



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