User:Dantman/Output Metadata/Namespace API

This page describes the idea or a MWXMLScope class for the support of an XML/RDFa api. (RDFa prefixes and CURIEs are somewhat different than XML namespaces. MWXMLScope is a terrible name. MWXMLNamespaceScope might be better. But atm we don't even intend to use it for actual XML namespaces but instead for RDFa prefixes so using that name seems a little foolish.)

The goal of this class is to provide a way to use XML/RDFa namespaces using prefixes with a guarantee that you will not end up with conflicts caused by accidentally using the same prefix that something else is already using.

For example our element would have one MWXMLScope tied to it, and we'd query that instance's interfaces to get what curie (ie: og:title, etc...) we would use inside elements in the, etc...

A MWXMLScope instance has the following api:
 * $scope->namespace( $preferredPrefix, $uri/$iri, [$keepPrefixIfPossible = false] );
 * Example:
 * Given a preference for the prefix and a uri for the namespace, defines the namespace on the MWXMLScope and returns an MWXMLScope_Namespace instance that can be used to build things using that namespace.
 * The prefix is a preference and it's not guaranteed that the resulting namespace will use the exact same prefix. For example if two extensions ask for a namespace on the same scope using two different namespace URIs and both ask for the prefix 'asdf', only the first uri will get associated with the prefix, the other will be given a different automatically generated prefix.
 * If a previous call has used the same $uri and already registered a prefix this method will typically return that namespace so it doesn't have to wastefully register redundant namespace attributes. If you pass true to $keepPrefixIfPossible this behaviour will be disabled and as long as the prefix preference you provide has not already been used it will return a namespace using your prefix preference even if that means that it has to define two prefixes with the same URI.


 * $scope->namespaceMap;
 * Returns an array mapping prefixes to URIs containing the currently registered namespaces.


 * $scope->xmlnsAttrs;
 * Returns an array mapping xmlns:prefix keys to the URI which can be used in an attributes array when building an element.


 * $scope->prefixAttr;
 * Returns the value for a RDFa Core 1.1 prefix="" attribute

The MWXMLScope_Namespace class returned by MWXMLScope::namespace has the following api:
 * $ns->prefix;
 * Return the prefix used in this namespace. Note that it is preferred that you use ->gname( $name ) instead of taking return of ->prefix and concatenating it with something like "$prefix:$name";


 * $ns->qname( $name );
 * Return a qname (eg: "foo:bar") suitable of being used in an XML/XHTML tag name, etc...


 * $ns->curie( $name );
 * Return a CURIE (eg: "og:title") suitable of being used in an RDFa property, etc...


 * $ns->expand( $name );
 * Return the fully expanded URI for a given name in the namespace.

Examples and expectations defined as a run of test code with assertions: