[whatwg] OUTPUT tag: clarify purpose in spec?

[Ian Hickson]

On Tue, 3 Dec 2013, Jukka K. Korpela wrote:
> 2013-12-03 2:24, Ian Hickson wrote:
> > On Thu, 26 Sep 2013, Jukka K. Korpela wrote:
> > > 2013-09-26 21:41, Ian Hickson wrote:
> > > > 
> > > > There's a lot of <output> examples in the spec; do they help at 
> > > > all?
> > > 
> > > There are indeed several examples, but they are scattered around; 
> > > the section that specifically deals with the <output> element, 
> > > 4.10.15, has only one example.
> > 
> > I've added a second.
> 
> I can't find it - I just see the calculator example, at 
> http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-output-element

You may have looked before the multipage version got pushed. The single 
page version is updated before I check in, the multipage version is 
updated some time later.


> > <output> elements are never submitted, actually. They're not 
> > submittable.
> 
> Thank you for the clarifications. I may have been stuck to an idea of a 
> submittable element, possibly adopted from some earlier version or 
> proposal. I think an explicit short note like "The output element is not 
> submittable" would be useful.

I am reluctant to add that kind of comment for a couple of reasons. First, 
there's the problem of determining when one would add these notes. Should 
the spec be explicit about everything it doesn't say? That way lies 
madness, obviously, since it doesn't say an infinite number of things. 
Second, it can lead readers to assume that anything that the spec doesn't 
explicitly call out as not being true is in face true (as in "it says 
<output> is not submittable, but it doesn't say <aside> is not 
submittable, so clearly <aside> is submittable").

What I would rather do is clarify whatever led to the confusion in the 
first place. Do you have any idea what it is in the <output> section that 
might lead you to think that it would be submittable?


> (A submittable output element would a natural thing to have in many 
> cases, e.g. in showing some calculated total to the user and submitting 
> it along with form data, for checking purposes.)

Can you elaborate on this use case? I'm not sure how it would work.

The main reason for not submitting it so far has been that it would risk 
authors relying on the client's computation and thus not doing it on the 
server, opening the server up to data integrity attacks (e.g. if a 
purchase total was submitted, an attacker could list a long series of 
expensive products to buy, but submit the "total" as $0).


> I think the definition of the @name content attribute needs revision. It 
> now says: "Name of form control to use for form submission and in the 
> form.elements API." Apparently, form submission should be omitted.

Aah, interesting. Yeah, that's confusing. The attribute is a generic one 
used by multiple elements for both those purposes, but in the case of 
<output> and <fieldset>, it can never be used for form submission, since 
those aren't submittable, so it should use a different description.

Fixed.


> And I think it would be better to drop the @name attribute entirely; if 
> a page uses it in <output>, it's probably a mistake (the author assumes 
> that <output> is submittable.

Without name="", the main purpose of <output> -- making it easy to update 
non-form-control values in script -- is lost.

Consider what this would look like without the form.elements API:

  <form name="main">
   Result: <output name="result"></output>
   <script>
    document.forms.main.elements.result.value = 'Hello World';
   </script>
  </form>


> > > The question then arises why <output> is used, instead of just 
> > > showing the result in a <span> or <div> element as usual.
> > 
> > Indeed. Often the benefit to using a more appropriate element rather 
> > than just using <span> everywhere is not immediately obvious.
> 
> I don't quite see why <output> would be more appropriate.

Well, more or less by definition, of <output> is appropriate for 
something, it's more appropriate than <span> would be, since <span> is 
more generic. <span> is like the "fall back" element, it has essentially 
no semantics at all.


> > In the particular case of the calculator example, the main benefit is 
> > that the snippets of script become much simple:
> > 
> >     oninput="o.value = a.valueAsNumber + b.valueAsNumber"
> > 
> > ...rather than:
> > 
> >     oninput="document.getElementById('o').textArea = a.valueAsNumber +
> > b.valueAsNumber"
> 
> I suppose you mean .textContent instead of .textArea.

Right, my bad.


> References like document.getElementById('o') or their jQuery counterpart 
> $('o') are extremely common, so why bother simplifying things in a very 
> specific case?

I think the improvement of "o" relative to "document.getElementById('o')" 
should be self-evident; that libraries like jQuery feel the need to do 
exactly this kind of simplification is exactly the kind of evidence we use 
when trying to work out what needs simplifying.


> And anyone who does not like the length of document.getElementById() and 
> does not want to load jQuery can write his own function for the purpose.

It's hard to simulate the simplicity achieved by <output>, even with a 
function.


> I think it is unnecessary to have an element for output when this means 
> that writing to the element is different from normal manipulation of 
> elements (via document.getElementById() or via 
> document.getElementsByTagName() or other general methods)

Why? The HTML API has lots of special-purpose accessors like this, e.g. 
the rest of the form API, the HTML table API, etc. Adding one for output 
in forms seems to make sense, since doing the same for input is already 
possible. Especially given the low cost of doing this.


> > The output element represents the result of a calculation or user 
> > action. That's what the spec says. I'm not sure what more you want it 
> > to say.
> 
> Well, what it really means. Is <output>4</output> OK just because I got 
> 4 from calculating 2 + 2?

Probably. It's hard to say for sure without more context. I mean, if 
you're just writing a paragraph that starts like:

   <p>I bought two apples, then I bought two more, and now I have

...then I would say that <output> is probably unnecessary, but if you find 
it useful to use here, it wouldn't be _wrong_ per se.


> You contrasted <output> with <samp>, which clarified this to some 
> extent, but there is no statement like that in the description.

I've added similar prose to the specification. Let me know what you think.


> So shouldn't "calculation" be clarified by saying that it is a 
> calculation performed on the page, i.e. the result of executing some 
> client-side script?

Well, it could be the result of a calculation done by a remote host based 
on user input, too. Or the result of a calculation done by remote host C 
based on data from remote hosts A and B. The second example in the 
<output> section shows an example of that.


> This would probably cover "user action" too - it now looks odd, since 
> the element content is not supposed to change directly due to user 
> action, the way e.g. <input type=text> works.

It can change directly based on user action (indeed the first example of 
<output> in the <output> element's section does just that), it's just not 
an actual input control itself.


> > > I still don't quite see *why* <output> has been introduced. I can 
> > > understand it as a purely logical creation, but what is the 
> > > practical gain expected to be?
> > 
> > The main practical gain is that it makes outputting data from script 
> > in a form easier, since <output> is a listed form-associated element.
> 
> That statement, in some formulation, might be a useful addition to the 
> description of <output>.

I have made a conscious choice to not include rationales in the 
specification, to keep the document manageable. However, I encourage you 
(anyone reading this) to add this kind of information to this Wiki page:

   http://wiki.whatwg.org/wiki/Rationale


> I don't find <output> useful in outputting data from a script, since it 
> requires a special approach for something that can well be handled using 
> a general approach, and compactness of code is not that relevant, 
> especially if it makes the code less readable.

I think it makes the code significantly more readable in form situations, 
but as mentioned earlier, there's nothing wrong with not using it. It's 
just a tool available for those who want it.


> I think the benefits of <output> do not justify the added complexity it 
> brings into the language and the time that would be spent by authors, 
> trying to understand the concept and to decide whether to use <output> 
> or <span> or <input> or something else for results of computation.

I can understand that. This kind of judgement call is what this is all 
about. In this instance, I happen to disagree, on the whole; I think the 
added complexity is small and justified given the additional benefits 
(which are admittedly also small).


> P.S. I haven't seen a description of what the @for attribute of <output> 
> might be useful for. Presumably, it is meant to act as a documentation 
> tool, with some automated checking by validators (they check that the 
> referenced @id attributes exist in the document). If this is relevant, 
> the same can be achieved without a dedicated element, e.g. by adding a 
> general attribute @from that specifies that the content of the element 
> will (normally) be changed by a script that uses certain other elements 
> (listed in the attribute value) as data.

Yeah, the <output for> attribute maybe should be dropped. It was initially 
intended to allow UAs and ATs to let users jump to the relevant controls 
from the output; in non-visual situations in particular, this can in 
theory be quite helpful. If nobody implements it, I imagine we'll drop it.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'