Re: More compact display for inherited properties and methods in DOM object pages

Thanks for the feedback Julee, Phistuck, and Rob.  Here is my perspective
on the feasibility of the suggestions:

*Suggestion #1: Remove the examples section or move it before the
property/methods lists*
I wouldn't want to remove the examples completely from the template; these
pages might not need it, but others could have useful examples. We already
have the "Example not needed" option to suppress the "Needs examples"
warning.

I like the idea of moving the examples section farther up in the page
(after the Overview but before the Properties and Methods).  The problem is
that Overview, Properties, Methods, etc. are all currently generated by the
same template, while the example section is a separate template.  I'm not
certain, but I think that if we moved the example template *inside* the API
Object template, we would then have to change the forms so that the data
was passed through as well.

Can Eliezer, Eliot, or someone else with plenty of template know-how
comment on this?

Another option would be to split the API Object template into two, so that
the main template just prints the overview, and the listings are printed by
a separate template, and then change the forms to inject the second
template into all pages in the category.  However, that separate template
would have to use an #ask query to grab the "Subclass of" property that is
set by the main template, which causes problems with preview mode.

All in all, a lot of mucking around, but it is probably feasible if people
think it's important.  Something to leave for later, I think.


*Suggestion #2: Keep all the essential information on one page*
Phistuck didn't like the idea of forcing people to click through to get the
basic idea about the properties and methods.  That's a valid concern, but
needs to be balanced against putting so much content on one page that it is
impossible to get any sort of overview.

Rob suggested a good compromise: use the "title" attribute to make the
summaries to show up as a tooltip.  I thought this was a great idea, and I
*thought* it would be easy to implement, so I started monkeying around with
the templates this morning.

It turned out to *not* be easy at all, but I managed to get it working.
 Mediawiki has no way to override their automatic title attribute on links,
and no way to create link markup yourself, but I was able to include a span
with a title attribute *inside* the link markup, and testing it in Chrome,
Firefox and IE11 shows that the span title overrides the link title to
become the displayed tooltip.

It should be working now, e.g. on
http://docs.webplatform.org/test/dom/HTMLTableElement
"classList", "innerHTML" and "focus" have values for the summary field,
everything else displays the default tooltip.



*Suggestion #3:  Avoid "More" links, or if they are necessary, avoid
redirecting to search page*
I agree that the "More" links should be avoided.  One of the benefits of
the compact display is that we can display *all* the methods instead of
cutting off the tables after 50 entries.  (I've got limit=400 on the
"cloud" display, so it is unlikely to ever have a "more..." link).

There are only a small number of pages (HTMLElement, Element) that will
have "More..." links on the main (non-inherited) tables.  We could avoid
the links altogether by also using arbitrarily large limits on the table
queries, and accept that those pages will have giant tables.

This currently would mean more than 300 rows in the properties table for
HTML Element, although that number will come down when the rest of the
database is cleaned up -- many of those "Properties" are non-standard,
associated with more specific interfaces than HTMLElement, or not even
valid DOM properties (e.g. aria attributes).

Long term, I would like to exclude all non-standard methods from the main
tables.  They could be displayed in their own cloud after the inherited
values.  However, currently this is not practical because most API
Method/Property pages don't have the "Standardization Status" property set.

>From a design and UX perspective, I like Phistuck's suggestion that the
"More..." link should trigger a script that adds more entries to the table
instead of redirecting to a separate page.  However, that would be a lot of
custom code which (with the compact design for inherited members) would
only affect a couple pages.

So my proposed solution would be
(a) use the compact "cloud" display, with tooltips, for the inherited
members
(b) set a large limit on the main tables to avoid "More..." on the few
pages that have >50 properties or methods,
(c) make cleaning up the DOM pages a suggested task for DocSprints or new
contributors!


*Suggestion #4:  Use the issue tracker to organize these types of
discussions*
Great idea Julee!  Let us know when it's ready to go!

I'll leave this open for more comments for a week, and if there are no
objections roll it out next weekend.