Re: [templates] Listing pages

On Thu, Dec 6, 2012 at 5:08 AM, Scott Rowe <scottrowe@google.com> wrote:

> 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.
>

Unfortunately I won't be at the doc sprint next week, but I'd be happy to
work through this with you one of the other days next week.

>
> *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.
>

This makes a lot of sense, especially since people are already using it
this way. The actual table should be some template, and the API_Listing
page template should be re-implemented to primarily just use precisely that
template.Also, we'll need to think about where and how we handle the form
part of the table. It's probably best to define a
Concept_Listing_Form_Section template and use that in any form that needs a
concept listing. Incidentally, Template:Single_Example,
Template:Inline_Example, and Template:Examples_Section collectively follow
this basic pattern where the "heavy lifting" is done by an inner template.

>
> *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.
>

This change sounds reasonable to me (again, on the API_Listing page
template, not the Concept_listing *inner *template discussed above).

>
>
> 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).
>

I don't think this is a good idea. The Applies_to machinery is very
specifically suited to members of an interface, where each member is part
of one interface. The API_Listing pages allow more rich queries that permit
you to have a single leaf page easily show up in multiple category listings
without the leaf page having to know anything about where else it's being
included.

>
> *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.
>

Sounds reasonable. We should make sure the naming of this section is
consistent across its uses in API_Listing, API_Object, etc. Main_Content
sounds reasonable, I think.

>
> 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
>
>