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

1. I think moving the Examples (and Usage and Notes, maybe) section into
the API Object (and the rest of the API templates) makes a lot of sense.
The member reference should not be at the top of the page - it is
overwhelming (and ugly, those tables), even with only several members.

2. The title solution is not optimal, to say the least. People sift through
the content quickly to find what they need, a title makes you hover the
member for a second at least and is not searchable using Control + F. I am
not sure regarding the SEO situation, too. The "more" option is much better
(still not optimal, because it is less searchable than having everything
revealed up front).
Also, If it only affects a couple of pages, I would leave the giant tables
in these pages as well. The cloud (and/or title) solution is really bad in
my opinion.


☆*PhistucK*


On Sun, Jul 27, 2014 at 8:42 PM, Amelia Bellamy-Royds <
amelia.bellamy.royds@gmail.com> wrote:

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