Re: A categorization/placing problem - event/property pages

When I posted about this (among other issues) a few months ago, I think the
initial conclusion was that we should only have event pages (abort) and
have a check box in the event template in order to specify whether it may
function as a property (onabort) and another check box in the event
template in order to specify whether it may function as a standard event
listener (object.addEventListener("abort", handler, false)).

I think having two (or more, if you include the dreadful inline HTML event
listeners) pages for most events is wasteful.
Perhaps we should also have a check box for its inline HTML event listeners
attribute and a field for the HTML element, I do not know.

☆*PhistucK*


On Wed, Feb 13, 2013 at 8:39 PM, Julee <julee@adobe.com> wrote:

> Is there any place where we are drawing the relationship between html
> element attributes (onerror), object properties (onerror), events (error),
> and event listeners (error, handler)?
>
> Or are we planning on separating out each manifestation and documenting
> them separately?
>
> Thanks much.
>
> Julee
> ----------------------------
> julee@adobe.com
> @adobejulee
>
> From: Scott Rowe <scottrowe@google.com>
> Date: Wednesday, February 13, 2013 9:48 AM
> To: Chris Mills <cmills@opera.com>
> Cc: "public-webplatform@w3.org" <public-webplatform@w3.org>
> Subject: Re: A categorization/placing problem - event/property pages
>
> Hi Chris,
>
> Let me lend some perspective to this, in line...
> +Scott
>
>
> On Wed, Feb 13, 2013 at 9:03 AM, Chris Mills <cmills@opera.com> wrote:
>
>> Hi all,
>>
>> I am mailing to discuss a consistency problem we have come up against in
>> the properties/events pages on webplatform.org; I have been discussing
>> this with Frederic Hemberger, who took part in the Berlin doc sprint. The
>> question is, how to categorise properyy and event pages.
>>
>> Crawling through the properties list (
>> http://docs.webplatform.org/w/index.php?title=Category:API_Object_Properties)
>> we have 40 event related properties:
>>
>> apis/file/properties/onabort
>> apis/indexeddb/IDBTransaction/onabort
>> apis/webrtc/RTCPeerConnection/onaddstream
>> apis/webrtc/MediaStreamTrackList/onaddtrack
>> apis/webaudio/ScriptProcessorNode/onaudioprocess
>> apis/indexeddb/IDBOpenDBRequest/onblocked
>> apis/indexeddb/IDBVersionChangeRequest/onblocked
>> apis/appcache/ApplicationCache/oncached
>> apis/appcache/ApplicationCache/onchecking
>> apis/indexeddb/IDBTransaction/oncomplete
>> apis/webrtc/RTCPeerConnection/ondatachannel
>> apis/appcache/ApplicationCache/ondownloading
>> apis/webrtc/MediaStream/onended
>> etc.
>>
>
> First, to level-set here, these are termed "event handlers" and treated in
> the specifications as properties. We've followed suit in the API docs.
>
>
>>
>> (Also, the File API is the only API listing those as
>> "apis/file/properties/<propertyName>" instead of
>> "apis/file/<propertyName>".)
>>
>
> This was a mistake. This property belongs to the msStreamReader object,
> and it's page is now located properly at apis/file/MSStreamReader/onabort<http://docs.webplatform.org/wiki/apis/file/MSStreamReader/onabort>
> .
>
> However, it may be argued that all of the Microsoft-proprietary
> documentation should be removed from WPD as it is not standard. But that's
> an issue for a separate thread.
>
>
>>
>> On the other hand, the event page lists 54 API (61 if you include SVG)
>> and 107 DOM event pages, rather than their related properties.
>>
>> The questions is, how should we make these more consistent?
>>
>
> DOM events and API object events are treated differently. Consistency
> would confuse the issue rather than clarify.
>
>
>>
>> 1. We could list these as event pages primarily, but then have another
>> page for the event property in each case. So for example
>>
>> http://docs.webplatform.org/wiki/apis/file/events/onabort could be the
>> main page, with all the info on the event and its related property (but
>> we'd be best changing onabort to abort)
>>
>
> No. Under no circumstance should we change the names of API object
> properties. These are defined in the spec. The event is "abort," the event
> handler is "onabort."
>
> Incidentally, the "abort" event has yet to be documented. We're on it.
>
>
>>
>> http://docs.webplatform.org/wiki/apis/file/properties/onabort could just
>> have a minimum of information on it, but point to the above page
>>
>> 2. We could do basically the same, but have the property pages as the
>> main pages, and point the event pages to those.
>>
>> 3. We could just have the event pages, and make them cover both the
>> properties and events:
>>
>> http://docs.webplatform.org/wiki/apis/file/events/abort
>>
>> And maybe have a silent redirect on the similar property page.
>>
>> We (myself and Frederic) would rather go with moving the 40odd existing
>> property pages to the Events listing and not treat them as "real"
>> properties for the sake of documentation consistency (although this might
>> be less precise from an implementation point of view).
>>
>
> The way we are currently representing events and event handlers in the API
> documentation is correct. We maintain the structure prescribed in the
> specifications.
>
>
>>
>> Otherwise, we'd need to move all API events to properties (if you think
>> of DOM events as a "special breed"), and/or make duplicate (or at least
>> very similar) pages. We are more interested here in what is most
>> implementable/findable, rather than what is most technically correct.
>>
>
>
> DOM events, on the other hand, do appear to warrant a different treatment,
> particularly because they are shared across many different objects.
>
>
>
>>
>> Thoughts?
>>
>> Chris Mills
>> Opera Software, dev.opera.com
>> W3C Fellow, web education and webplatform.org
>> Author of "Practical CSS3: Develop and Design" (http://goo.gl/AKf9M)
>>
>>
>>
>