[templates] Listing pages

For the Template Corps, I would like to propose the following changes. I'd
also like to do these changes myself - as a learning exercise - with the
guidance of a TC member, and I'm sure there are others who would like to
learn to do these. If a member is planning on attending the Doc Sprint in
Mountain View next week, that would give us the opportunity to hold a small
session in which we could use these changes as learning exercises.

*Concepts listing template*

We need a concepts listing template, like an API listing page, but without
the dependency on the API listing form. Consider the
concepts/mobile_web<http://docs.webplatform.org/wiki/concepts/mobile_web>
page
where someone simply included the API_Listing template call over the extant
basic page - which is innovative, to be sure, but not a neat solution. It
causes more than one default form to be defined for the page, and the
listing table to be displayed first, before the main content.

A "Concepts_Listing" template could be dropped on any basic or concepts
page and create the same Page/Summary table as that for API listings. It
would "Use page title instead of API_Name" - which currently doesn't seem
to be working, by the way.

*API_Listing changes*

Speaking of API_Listing, I'd like to make these more capable of including
overview content as well as listing their API_Object sub pages the same way
API_Object pages list API_Object_Properties, _Methods, and _Events.

Currently, the API_Listing pages present the Summary, followed by the
listing table, which can either be query-based or sub page-based. See the
apis/webrtc <http://docs.webplatform.org/wiki/apis/webrtc> page for an
example.

I'd like to make it so that the page first provides a Main Content section
- to allow for an elaborate description (the example is using the Usage
section of the Notes form). The Main Content section would appear after the
Summary.

Following the Main Content, the page would display a listing table of
Objects using the same mechanism that the API_Object page uses to pull
together tables of Properties, Methods, and Events - with the "Applies to"
field of those pages. This Object/Summary table could replace the
query-based or sub page-based table, or we could allow for that table to
appear at the end of the page (which would require moving it down in the
form).

*API_Object changes*

Like listing pages, the API_Object pages need a Main Content section to
provide an explanation about using the object. This would appear after the
Summary section, and it would be followed by the Examples section. So, all
of this would have to be reordered.

Also, per the above, the API_Object page would need an "Applies to" field
that would allow the API_Listing page to pull the API_Object page Name and
Summary into a table on the API_Listing page.

What do you think?

+Scott

Received on Wednesday, 5 December 2012 18:08:42 UTC