Skip to content

Commit

Permalink
[] (0) Include some advice on how to do experimental non-standard att…
Browse files Browse the repository at this point in the history 
…ributes.

Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=9239

git-svn-id: http://svn.whatwg.org/webapps@4939 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Apr 1, 2010
1 parent 7c1d73b commit 07d7c25
Show file tree
Hide file tree
Showing 3 changed files with 338 additions and 77 deletions.
134 changes: 108 additions & 26 deletions complete.html
View file
Expand Up @@ -3202,24 +3202,106 @@ <h4 id=dependencies><span class=secno>2.2.1 </span>Dependencies</h4>



<div class=impl>

<h4 id=extensibility><span class=secno>2.2.2 </span>Extensibility</h4>

<p>Vendor-specific proprietary extensions to this specification are
strongly discouraged. Documents must not use such extensions, as
doing so reduces interoperability and fragments the user base,
allowing only users of specific user agents to access the content in
question.</p>

<p>If vendor-specific markup extensions are needed, they should be
done using XML, with elements or attributes from custom
namespaces. If such DOM extensions are needed, the members should be
prefixed by vendor-specific strings to prevent clashes with future
versions of this specification. Extensions must be defined so that
the use of extensions neither contradicts nor causes the
non-conformance of functionality defined in the specification.</p>
<!-- thanks to QA Framework -->
<p>HTML has a wide number of extensibility mechanisms that can be
used for adding semantics in a safe manner:</p>

<ul><li>Authors can use the <code title=attr-class><a href=#classes>class</a></code>
attribute to extend elements, effectively creating their own
elements, while using the most applicable existing "real" HTML
element, so that browsers and other tools that don't know of the
extension can still support it somewhat well. This is the tack used
by Microformats, for example.</li>

<li>Authors can include data for inline client-side scripts or
server-side site-wide scripts to process using the <code title=attr-data-*><a href=#attr-data-*>data-*=""</a></code> attributes. These are
guaranteed to never be touched by browsers, and allow scripts to
include data on HTML elements that scripts can then look for and
process.</li>

<li>Authors can use the <code title=meta><a href=#meta>&lt;meta name=""
content=""&gt;</a></code> mechanism to include page-wide metadata by
registering <a href=#concept-meta-extensions title=concept-meta-extensions>extensions to the
predefined set of metadata names</a>.</li>

<li>Authors can use the <code title=attr-hyperlink-rel><a href=#attr-hyperlink-rel>rel=""</a></code> mechanism to annotate
links with specific meanings by registering <a href=#concept-rel-extensions title=concept-rel-extensions> extensions to the predefined set of
link types</a>. This is also used by Microformats.</li>

<li>Authors can embed raw data using the <code title=script><a href=#script>&lt;script type=""&gt;</a></code> mechanism with a custom
type, for further handling by a inline or server-side scripts.</li>

<li>Authors can create <a href=#plugin title=plugin>plugins</a> and
invoke them using the <code><a href=#the-embed-element>embed</a></code> element. This is how Flash
works.</li>

<li>Authors can extend APIs using the JavaScript prototyping
mechanism. This is widely used by script libraries, for
instance.</li>

<li>Authors can use the microdata feature (the <code title=attr-item>item=""</code> and <code title=attr-itemprop><a href=#names:-the-itemprop-attribute>itemprop=""</a></code> attributes) to embed
nested name-value pairs of data to be shared with other
applications and sites.</li>

</ul><div class=impl>

<hr><p>Vendor-specific proprietary user agent extensions to this
specification are strongly discouraged. Documents must not use such
extensions, as doing so reduces interoperability and fragments the
user base, allowing only users of specific user agents to access the
content in question.</p>

<p>If such extensions are nonetheless needed, e.g. for experimental
purposes, then vendors are strongly urged to use one of the
following extension mechanisms:</p>

<p>For markup-level features that can be limited to the XML
serialization and need not be supported in the HTML serialization,
vendors should use the namespace mechanism to define custom
namespaces in which the non-standard elements and attributes are
supported.</p>

<p>For markup-level features that are intended for use with
<a href=#syntax>the HTML syntax</a>, extensions should be limited to new
attributes of the form "<code title="">_<var title="">vendor</var>-<var title="">feature</var></code>", where
<var title="">vendor</var> is a short string that identifies the
vendor responsible for the extension, and <var title="">feature</var> is the name of the feature. New element names
should not be created. Using attributes for such extensions
exclusively allows extensions from multiple vendors to co-exist on
the same element, which would not be possible with elements. Using
the "<code title="">_<var title="">vendor</var>-<var title="">feature</var></code>" form allows extensions to be made
without risk of conflicting with future additions to the
specification.</p>

<div class=example>

<p>For instance, a browser named "FerretBrowser" could use "ferret"
as a vendor prefix, while a browser named "Mellblom Browser" could
use "mb". If both of these browsers invented extensions that turned
elements into scratch-and-sniff areas, an author experimenting with
these features could write:</p>

<pre>&lt;p&gt;This smells of lemons!
&lt;span -ferret-smellovision -fetter-smellcode="LEM01"
-mb-outputsmell -mb-smell="lemon juice"&gt;&lt;/span&gt;&lt;/p&gt;</pre>

</div>

<p>Attribute names starting with a U+005F LOW LINE character (_) are
reserved for user agent use and are guaranteed to never be formally
added to the HTML language.</p>

<p class=note>Pages that use such attributes are by definition
non-conforming.</p>

<p>For DOM extensions, e.g. new methods and IDL attributes, the new
members should be prefixed by vendor-specific strings to prevent
clashes with future versions of this specification.</p>

<p>All extensions must be defined so that the use of extensions
neither contradicts nor causes the non-conformance of functionality
defined in the specification.</p> <!-- thanks to QA Framework -->

<div class=example>

Expand All @@ -3234,16 +3316,6 @@ <h4 id=extensibility><span class=secno>2.2.2 </span>Extensibility</h4>

</div>

<p>When support for a feature is disabled (e.g. as an emergency
measure to mitigate a security problem, or to aid in development, or
for performance reasons), user agents must act as if they had no
support for the feature whatsoever, and as if the feature was not
mentioned in this specification. For example, if a particular
feature is accessed via an attribute in a Web IDL interface, the
attribute itself would be omitted from the objects that implement
that interface &mdash; leaving the attribute on the object but
making it return null or throw an exception is insufficient.</p>

<hr><p>When vendor-neutral extensions to this specification are needed,
either this specification can be updated accordingly, or an
extension specification can be written that overrides the
Expand All @@ -3260,6 +3332,16 @@ <h4 id=extensibility><span class=secno>2.2.2 </span>Extensibility</h4>
processors), and styling them according to CSS (for CSS processors),
but not inferring any meaning from them.</p>

<p>When support for a feature is disabled (e.g. as an emergency
measure to mitigate a security problem, or to aid in development, or
for performance reasons), user agents must act as if they had no
support for the feature whatsoever, and as if the feature was not
mentioned in this specification. For example, if a particular
feature is accessed via an attribute in a Web IDL interface, the
attribute itself would be omitted from the objects that implement
that interface &mdash; leaving the attribute on the object but
making it return null or throw an exception is insufficient.</p>

</div>


Expand Down
134 changes: 108 additions & 26 deletions index
View file
Expand Up @@ -3100,24 +3100,106 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d



<div class=impl>

<h4 id=extensibility><span class=secno>2.2.2 </span>Extensibility</h4>

<p>Vendor-specific proprietary extensions to this specification are
strongly discouraged. Documents must not use such extensions, as
doing so reduces interoperability and fragments the user base,
allowing only users of specific user agents to access the content in
question.</p>

<p>If vendor-specific markup extensions are needed, they should be
done using XML, with elements or attributes from custom
namespaces. If such DOM extensions are needed, the members should be
prefixed by vendor-specific strings to prevent clashes with future
versions of this specification. Extensions must be defined so that
the use of extensions neither contradicts nor causes the
non-conformance of functionality defined in the specification.</p>
<!-- thanks to QA Framework -->
<p>HTML has a wide number of extensibility mechanisms that can be
used for adding semantics in a safe manner:</p>

<ul><li>Authors can use the <code title=attr-class><a href=#classes>class</a></code>
attribute to extend elements, effectively creating their own
elements, while using the most applicable existing "real" HTML
element, so that browsers and other tools that don't know of the
extension can still support it somewhat well. This is the tack used
by Microformats, for example.</li>

<li>Authors can include data for inline client-side scripts or
server-side site-wide scripts to process using the <code title=attr-data-*><a href=#attr-data-*>data-*=""</a></code> attributes. These are
guaranteed to never be touched by browsers, and allow scripts to
include data on HTML elements that scripts can then look for and
process.</li>

<li>Authors can use the <code title=meta><a href=#meta>&lt;meta name=""
content=""&gt;</a></code> mechanism to include page-wide metadata by
registering <a href=#concept-meta-extensions title=concept-meta-extensions>extensions to the
predefined set of metadata names</a>.</li>

<li>Authors can use the <code title=attr-hyperlink-rel><a href=#attr-hyperlink-rel>rel=""</a></code> mechanism to annotate
links with specific meanings by registering <a href=#concept-rel-extensions title=concept-rel-extensions> extensions to the predefined set of
link types</a>. This is also used by Microformats.</li>

<li>Authors can embed raw data using the <code title=script><a href=#script>&lt;script type=""&gt;</a></code> mechanism with a custom
type, for further handling by a inline or server-side scripts.</li>

<li>Authors can create <a href=#plugin title=plugin>plugins</a> and
invoke them using the <code><a href=#the-embed-element>embed</a></code> element. This is how Flash
works.</li>

<li>Authors can extend APIs using the JavaScript prototyping
mechanism. This is widely used by script libraries, for
instance.</li>

<li>Authors can use the microdata feature (the <code title=attr-item>item=""</code> and <code title=attr-itemprop><a href=#names:-the-itemprop-attribute>itemprop=""</a></code> attributes) to embed
nested name-value pairs of data to be shared with other
applications and sites.</li>

</ul><div class=impl>

<hr><p>Vendor-specific proprietary user agent extensions to this
specification are strongly discouraged. Documents must not use such
extensions, as doing so reduces interoperability and fragments the
user base, allowing only users of specific user agents to access the
content in question.</p>

<p>If such extensions are nonetheless needed, e.g. for experimental
purposes, then vendors are strongly urged to use one of the
following extension mechanisms:</p>

<p>For markup-level features that can be limited to the XML
serialization and need not be supported in the HTML serialization,
vendors should use the namespace mechanism to define custom
namespaces in which the non-standard elements and attributes are
supported.</p>

<p>For markup-level features that are intended for use with
<a href=#syntax>the HTML syntax</a>, extensions should be limited to new
attributes of the form "<code title="">_<var title="">vendor</var>-<var title="">feature</var></code>", where
<var title="">vendor</var> is a short string that identifies the
vendor responsible for the extension, and <var title="">feature</var> is the name of the feature. New element names
should not be created. Using attributes for such extensions
exclusively allows extensions from multiple vendors to co-exist on
the same element, which would not be possible with elements. Using
the "<code title="">_<var title="">vendor</var>-<var title="">feature</var></code>" form allows extensions to be made
without risk of conflicting with future additions to the
specification.</p>

<div class=example>

<p>For instance, a browser named "FerretBrowser" could use "ferret"
as a vendor prefix, while a browser named "Mellblom Browser" could
use "mb". If both of these browsers invented extensions that turned
elements into scratch-and-sniff areas, an author experimenting with
these features could write:</p>

<pre>&lt;p&gt;This smells of lemons!
&lt;span -ferret-smellovision -fetter-smellcode="LEM01"
-mb-outputsmell -mb-smell="lemon juice"&gt;&lt;/span&gt;&lt;/p&gt;</pre>

</div>

<p>Attribute names starting with a U+005F LOW LINE character (_) are
reserved for user agent use and are guaranteed to never be formally
added to the HTML language.</p>

<p class=note>Pages that use such attributes are by definition
non-conforming.</p>

<p>For DOM extensions, e.g. new methods and IDL attributes, the new
members should be prefixed by vendor-specific strings to prevent
clashes with future versions of this specification.</p>

<p>All extensions must be defined so that the use of extensions
neither contradicts nor causes the non-conformance of functionality
defined in the specification.</p> <!-- thanks to QA Framework -->

<div class=example>

Expand All @@ -3132,16 +3214,6 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d

</div>

<p>When support for a feature is disabled (e.g. as an emergency
measure to mitigate a security problem, or to aid in development, or
for performance reasons), user agents must act as if they had no
support for the feature whatsoever, and as if the feature was not
mentioned in this specification. For example, if a particular
feature is accessed via an attribute in a Web IDL interface, the
attribute itself would be omitted from the objects that implement
that interface &mdash; leaving the attribute on the object but
making it return null or throw an exception is insufficient.</p>

<hr><p>When vendor-neutral extensions to this specification are needed,
either this specification can be updated accordingly, or an
extension specification can be written that overrides the
Expand All @@ -3158,6 +3230,16 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
processors), and styling them according to CSS (for CSS processors),
but not inferring any meaning from them.</p>

<p>When support for a feature is disabled (e.g. as an emergency
measure to mitigate a security problem, or to aid in development, or
for performance reasons), user agents must act as if they had no
support for the feature whatsoever, and as if the feature was not
mentioned in this specification. For example, if a particular
feature is accessed via an attribute in a Web IDL interface, the
attribute itself would be omitted from the objects that implement
that interface &mdash; leaving the attribute on the object but
making it return null or throw an exception is insufficient.</p>

</div>


Expand Down

0 comments on commit 07d7c25

Please sign in to comment.