Bugzilla – Bug 20128
clarify structure for API members that supplement core DOM interfaces
Last modified: 2013-03-14 17:18:14 UTC
Part architecture, part infrastructure. Bug relates to a topic in
11/18 site-content conf-call & earlier unresolved discussion in
"URL structure sanity check" public email thread. Here's the
canonical URL structure for non-core APIs:
Good for new interfaces, but API packages often add members to core
interfaces (e.g. Document, Window, Navigator). Two examples:
* DeviceOrientation API adds a few events to the Window object. It
does not add any new API interfaces.
* CSS Regions API (apis/css-regions) adds 'getNamedFlows' member to
the Document interface. It's common to add such members simply to
access specialized APIs. (In this case, I placed it here:
Question: should these members be added to /dom tree, or supplement
the existing /apis URL structure? E.g.:
Arguments in favor of the latter:
* Placing them directly on /dom interface page would otherwise list
core members & more specialized members all jumbled together, and
the distinction is info webdevs might find useful when viewing each
* Maybe there's an opportunity to use templates to import
supplementary members from /api to populate appropriate /dom
interface. Page could be separated into core & non-core members.
* There's a benefit to being able to scan each /apis/<package> page
and be able to view all relevant members from any interface,
analogous to the everything-you-need-to-know structure of W3C specs.
* Relates to bug #20103: would like <package> pages to generate nested
list allowing users to drill down directly to any member.
* What if users land on /apis/<package>/Document page? We're not going to
re-doc it. Is a redirect to appropriate location under /dom possible?
This makes sense to me Mike. I suggest we go with this, if there are no dissenters. Update the hierarchy information at http://docs.webplatform.org/wiki/WPD:Content/Topic_Hierarchy ?
OK, as a test case I moved
& kept the interface name Initcap to stay consistent with rest of
Ideally at some point, dom/apis/document should dynamically list
getNamedFlows, perhaps in a separate list of supplementary members.
Also ideally, the new interim apis/css-regions/Document page should
redirect to dom/apis/document, or else dynamically reflect its content.
Requiring it to be created by hand would invite fragmented out-of-context
Sounds good, but shouldn't we be using all lower case for URLs, like we agreed a while ago?
Think this needs clarification. From discussion over the /apis tree I took away this convention:
New location: http://project.webplatform.org/ia/issues/9