mf2-spec-template-brainstorming: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(→‎Examples: Added example JSON representation of example, notes on design)
m (Added “see also” section)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''h-example''' is a [[microformats-2]] schema (?) for representing Examples. It builds upon the classic [[hExample]] microformat.
'''h-example''' is a [[microformats-2]] standard for representing Examples. It builds upon the classic [[hExample]] microformat.


Translations: link to each translation as [[hCard]] does
Translations: link to each translation as [[hCard]] does
TODO: properties first or examples first? returning viewers are most likely to want quick reference to properties, first time viewers are most likely to want an example. Perhaps do as hCard does with the property list => markup 1:1 thing, unless that ends up looking too noisy?


== Properties ==
== Properties ==


For each property, give:
All properties are optional and are parsed according to the [[microformats-2-parsing]] specification.
 
* classname e.g. <code>p-name</code>
* legacy BC classname
* meaning e.g. The name of the example
* example value e.g. “An example of an artisanal banana-peeling pattern”
** full element
 
Example:
 
* '''p-name''' (was <code>fn</code>): The name of the example
** E.G. <code>&lt;span class="p-name">Banana #1&lt;/span></code>


TODO: how to handle properties which probably should be a nested microformat but can also be a plain value? E.G. author:
* '''p-name''' <i>(was <code>fn</code>)</i> full example name
 
** <code>&lt;span class="p-name">Banana #1&lt;/span></code>
* '''p-author''' (was <code>author</code>): The author of the example. Optionally an [[h-card]]
* '''p-summary''' <i>(was <code>example-summary</code>)</i> short summary
** <code>&lt;p class="p-summary">An example of how examples may be exampled&lt;/p></code>
* '''p-author''' [[h-card]] <i>(was <code>author</code>)</i> author


== Examples ==
== Examples ==


Ideally all examples will be shown 1:1 with their JSON representation, OR editable with JS to submit it to a parser and show the JSON — this would encourage people to experiment and greater understand the relationship between markup and parsed structure.
Implied examples, if any:
 
Minimal sane example (if applicable e.g. implied h-card):
 
Meatier example:


* (perhaps marked up as a test case so the spec page becomes a test suite too)
Full example:
* actually, side by side doesn’t work so well, perhaps one after the other or switch between them or just have an external parser provide the JSON repr?


<div style="width: 60%; float: left;">
<source lang=html4strict>
<source lang=html4strict>
<div class="h-example">
<div class="h-example">
Line 49: Line 32:
</div>
</div>
</source>
</source>
</div>
 
<div style="width: 40%; float: left;">
<source lang=javascript>
<source lang=javascript>
{
{
Line 69: Line 51:
}
}
</source>
</source>
</div>
 
=== Examples in the wild ===
 
* List of sites using h-example, with “move to new page if it gets too big” note
 
== Background ==
 
What this was based off, why it was created etc.
 
== See Also ==
 
* [[h-card]] is nested as '''p-author'''
* [[example-brainstorming]]
* [[example-formats]]
* [[validators]] to make sure your h-example markup works as expected
* [[microformats-2]]
 
<hr />
 
== Feedback/Discussion ==
 
Properties first or examples first? returning viewers are most likely to want quick reference to properties, first time viewers are most likely to want an example. Perhaps do as hCard does with the property list => markup 1:1 thing, unless that ends up looking too noisy?
 
=== Properties ===
 
For each property, give:
 
* classname e.g. <code>p-name</code>
* legacy BC classname
* meaning e.g. The name of the example
* example value e.g. “An example of an artisanal banana-peeling pattern”
** full element
 
Perhaps link to common, shared/implied property classnames (p-name, u-url etc) to their own page?
TODO: how to handle properties which probably should be a nested microformat but can also be a plain value? E.G. author:
 
=== Examples ===
 
Ideally all examples will be shown 1:1 with their JSON representation, OR editable with JS to submit it to a parser and show the JSON — this would encourage people to experiment and greater understand the relationship between markup and parsed structure.
 
* (perhaps marked up as a test case so the spec page becomes a test suite too)
* actually, side by side doesn’t work so well, perhaps one after the other or switch between them or just have an external parser provide the JSON repr?

Latest revision as of 16:58, 6 June 2013

h-example is a microformats-2 standard for representing Examples. It builds upon the classic hExample microformat.

Translations: link to each translation as hCard does

Properties

All properties are optional and are parsed according to the microformats-2-parsing specification.

  • p-name (was fn) full example name
    • <span class="p-name">Banana #1</span>
  • p-summary (was example-summary) short summary
    • <p class="p-summary">An example of how examples may be exampled</p>
  • p-author h-card (was author) author

Examples

Implied examples, if any:

Full example: 

<div class="h-example">
  <span class="p-name">An Example Example</span>
  
  <p>Published <time class="dt-published" datetime="2013-05-02 12:00:00">two days ago</time></p>
  
  <p class="p-author h-card">Mr. Author</p>
  
  <img class="u-photo" src="http://cdn.memegenerator.net/instances/400x/38481344.jpg" alt="" />
  
  <p class="p-summary">An example example showing you how to example</p>
</div>

{
 "type": ["h-example"],
 "properties": {
  "name": ["An Example Example"],
  "published": ["2013-05-02 12:00:00"],
  "author": [{
    "type": ["h-card"],
    "properties": {
     "name": ["Mr. Author"]
    },
    "value": "Mr. Author"
  }],
  "photo": ["http://cdn.memegenerator.net/instances/400x/38481344.jpg"],
  "summary": ["An example example showing you how to example"]
 }
}

Examples in the wild

  • List of sites using h-example, with “move to new page if it gets too big” note

Background

What this was based off, why it was created etc.

See Also

Feedback/Discussion

Properties first or examples first? returning viewers are most likely to want quick reference to properties, first time viewers are most likely to want an example. Perhaps do as hCard does with the property list => markup 1:1 thing, unless that ends up looking too noisy?

Properties

For each property, give:

  • classname e.g. p-name
  • legacy BC classname
  • meaning e.g. The name of the example
  • example value e.g. “An example of an artisanal banana-peeling pattern”
    • full element

Perhaps link to common, shared/implied property classnames (p-name, u-url etc) to their own page? TODO: how to handle properties which probably should be a nested microformat but can also be a plain value? E.G. author:

Examples

Ideally all examples will be shown 1:1 with their JSON representation, OR editable with JS to submit it to a parser and show the JSON — this would encourage people to experiment and greater understand the relationship between markup and parsed structure.

  • (perhaps marked up as a test case so the spec page becomes a test suite too)
  • actually, side by side doesn’t work so well, perhaps one after the other or switch between them or just have an external parser provide the JSON repr?
Retrieved from "http://microformats.org/wiki/index.php?title=mf2-spec-template-brainstorming&oldid=54063"