mirror of
https://github.com/meteor/meteor.git
synced 2026-05-02 03:01:46 -04:00
Minor htmljs README changes
This commit is contained in:
David Greenspan
@@ -1,239 +0,0 @@
|
||||
# HTMLjs
|
||||
|
||||
A small library for expressing HTML trees in a concise
|
||||
syntax. This library is used at compile time and run time by Meteor UI.
|
||||
|
||||
```
|
||||
var UL = HTML.UL, LI = HTML.LI, B = HTML.B;
|
||||
|
||||
HTML.toHTML(
|
||||
UL({id: 'mylist'},
|
||||
LI({'class': 'item'}, "Hello ", B("world"), "!"),
|
||||
LI({'class': 'item'}, "Goodbye, world")))
|
||||
```
|
||||
|
||||
```
|
||||
<ul id="mylist">
|
||||
<li class="item">Hello <b>world</b>!</li>
|
||||
<li class="item">Goodbye, world</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
The functions `UL`, `LI`, and so on are "tag constructors" which
|
||||
return an object representation that can be used to generate HTML, or,
|
||||
via other packages, be used to generate DOM (`ui`), be parsed from
|
||||
HTML (`html-tools`), or serve as the backbone of the intermediate
|
||||
representation for a template compiler (`spacebars-compiler`).
|
||||
|
||||
# This document is out of date and will be revised soon.
|
||||
|
||||
## Syntax
|
||||
|
||||
Tag constructors take an optional first argument `attrs` followed by
|
||||
zero or more arguments, the `children`. The first argument is taken
|
||||
to be `attrs` if it is a "vanilla" JavaScript object such as an object
|
||||
literal.
|
||||
|
||||
> Ideally, a "vanilla" object would be one whose direct prototype is
|
||||
> `Object.prototype`. Since this test is impossible in IE 8, we test
|
||||
> `obj.constructor === Object`, which is true for object literals
|
||||
> (except ones like `{constructor: blah}`!) and false for most objects
|
||||
> with custom prototypes (because JavaScript sets
|
||||
> `MyClass.prototype.constructor = MyClass` when you create a function
|
||||
> `MyClass`).
|
||||
|
||||
Children of a tag may be of any of several built-in types:
|
||||
|
||||
* Tag (HTML.Tag)
|
||||
* HTML.CharRef
|
||||
* HTML.Comment
|
||||
* HTML.Raw
|
||||
* String
|
||||
* Boolean or Number (which will be converted to String)
|
||||
* Array (which will be flattened)
|
||||
* Null or undefined (which will be ignored)
|
||||
* Template/Component
|
||||
* Function returning one of these types
|
||||
|
||||
The set of allowed types is *open* in that any object may be included
|
||||
in the tree as long as the code consuming the tree can handle it.
|
||||
|
||||
Character references (like `&`) are *not* interpreted in strings.
|
||||
To include a character reference, use `HTML.CharRef({html:
|
||||
'&', str: '&'})`, specifying both the raw HTML form and the string
|
||||
form of the character.
|
||||
|
||||
> In other words, string values are of the form you would pass to
|
||||
`document.createTextNode`, not of the form you would see in an HTML
|
||||
document. The intent here is to only need to parse and interpret
|
||||
character references at compile time, making the representation
|
||||
maximally flexible easy to consume at runtime.
|
||||
>
|
||||
> The reason we represent character references at all, rather than
|
||||
> simply converting them to Unicode when parsing the source HTML
|
||||
> (and then escaping `&` and `<` at the very end)
|
||||
> is 1) to preserve the HTML author's intent, and 2) in case there
|
||||
> is a character-encoding-related reason that a character reference
|
||||
> is being used.
|
||||
|
||||
Attribute values can contain character references, using arrays to
|
||||
hold the string and CharRef parts:
|
||||
|
||||
```
|
||||
var amp = HTML.CharRef({html: '&', str: '&'});
|
||||
|
||||
HTML.toHTML(HTML.SPAN({title: ['M', amp, 'Ms']},
|
||||
'M', amp, 'M candies'))
|
||||
```
|
||||
|
||||
```
|
||||
<span title="M&Ms">M&M candies</span>
|
||||
```
|
||||
|
||||
A comment looks like `HTML.Comment("value here")`, where the value
|
||||
should not contain two consecutive hyphen (`-`) characters or an
|
||||
initial or final hyphen (or they will be stripped out).
|
||||
|
||||
A "raw" object like `HTML.Raw("<br>")` represents raw HTML to insert
|
||||
into the document. The HTML should be known to be safe and contain
|
||||
balanced tags! It will be injected without any parsing or checking
|
||||
when the representation is converted to an HTML string. If the
|
||||
representation is used to generate DOM directly, the "raw" node will
|
||||
be materialized using an innerHTML-like method.
|
||||
|
||||
Functions in the tree are used as reactivity boundaries when
|
||||
generating DOM directly. When generating HTML, they are simply called
|
||||
for their return value. Functions are passed no arguments and are
|
||||
given no particular value of `this`.
|
||||
|
||||
Templates/components like `Template.foo` can also be included in the
|
||||
representation. HTMLjs has very limited knowledge of what a component
|
||||
is. It knows components have an `instantiate` method that returns
|
||||
something with a `render` method. Operations that realize an HTMLjs
|
||||
tree as HTML, DOM, or some other form have a bit of boilerplate that
|
||||
they use to detect and instantiate components:
|
||||
|
||||
```
|
||||
HTML.toHTML = function (node, parentComponent) {
|
||||
// ... handle various types of `node`
|
||||
if (typeof node.instantiate === 'function') {
|
||||
// component
|
||||
var instance = node.instantiate(parentComponent || null);
|
||||
var content = instance.render();
|
||||
// recurse with a new value for parentComponent
|
||||
return HTML.toHTML(content, instance);
|
||||
}
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
The argument `parentComponent` is used to set a pointer that points
|
||||
from each component to its parent, used for name lookups.
|
||||
|
||||
## "Known" and Custom Tags
|
||||
|
||||
All the usual HTML and HTML5 tags are available as `HTML.A`,
|
||||
`HTML.ABBR`, `HTML.ADDRESS`, etc. These tags are called "known" tags
|
||||
and have predefined tag constructors. If you want to use a custom
|
||||
tag, you'll have to create the tag constructor using `getTag` or `ensureTag`.
|
||||
|
||||
```
|
||||
var SPAN = HTML.SPAN;
|
||||
var FOO = HTML.getTag('FOO');
|
||||
```
|
||||
|
||||
```
|
||||
HTML.ensureTag('FOO');
|
||||
var SPAN = HTML.SPAN;
|
||||
var FOO = HTML.FOO;
|
||||
```
|
||||
|
||||
All of these functions handle case conversion of `tagName` as
|
||||
appropriate, so whether you provide `foo` or `Foo` or `FOO`, the
|
||||
symbol on `HTML` will be `HTML.FOO`, while generated HTML and DOM will use
|
||||
the lowercase name `foo`.
|
||||
|
||||
`HTML.getTag(tagName)` - Returns a tag constructor for `tagName`, calling `ensureTag` if it doesn't exist.
|
||||
|
||||
`HTML.ensureTag(tagName)` - Creates a tag constructor for `tagName` if one doesn't exist and attaches it to the `HTML` object.
|
||||
|
||||
`HTML.isTagEnsured(tagName)` - Returns true if `tagName` has a built-in, predefined constructor. Useful for code generators that want to know if they should emit a call to `ensureTag`.
|
||||
|
||||
## Object Representation
|
||||
|
||||
Tag constructors follow an object-oriented paradigm with optional
|
||||
`new`. The returned objects are `instanceof` the tag constructor and
|
||||
also of `HTML.Tag`. In other words, all of the following are true:
|
||||
|
||||
```
|
||||
HTML.P() instanceof HTML.P
|
||||
HTML.P() instanceof HTML.Tag
|
||||
(new HTML.P) instanceof HTML.P
|
||||
(new HTML.P) instanceof HTML.Tag
|
||||
```
|
||||
|
||||
Similarly, objects constructed with `HTML.Comment` are instances of `HTML.Comment`, and so on.
|
||||
|
||||
In general, HTMLjs objects should be considered immutable.
|
||||
|
||||
HTML.Tag objects have these properties:
|
||||
|
||||
* `tagName` - the uppercase tag name
|
||||
* `attrs` - an object or null
|
||||
* `children` - an array of zero or more children
|
||||
|
||||
HTML.CharRef objects have `html` and `str` properties, specified by
|
||||
the object passed to the constructor.
|
||||
|
||||
HTML.Comment and HTML.Raw objects have a `value` property.
|
||||
|
||||
### Attributes
|
||||
|
||||
Attribute values can contain most kinds of HTMLjs content, but not Tag, Comment, or Raw. They may contain functions and components, even though these functions won't ever establish reactivity boundaries at a finer level than an entire attribute value.
|
||||
|
||||
The attributes dictionary of a tag can have a special entry `$dynamic`, which holds additional attributes dictionaries to combine with the main dictionary. These additional dictionaries may be computed by functions, lending generality to the calculation of the attributes dictionary that would not otherwise be present.
|
||||
|
||||
Specifically, the value of `$dynamic` must be an array, each element of which is either an attributes dictionary or a function returning an attributes dictionary. (These dictionaries may not themselves have a `$dynamic` key.) When calculating the final attributes dictionary for a tag, each dictionary obtained from the `$dynamic` array is used to modify the existing dictionary by copying the new attribute entries over it, except for entries with a "nully" value. A "nully" value is one that is either `null`, `undefined`, `[]`, or an array of nully values. Before checking if the dynamic attribute value is nully, all functions and components are evaluated (i.e. the functions are called and the components are instantiated, such that no functions or components remain).
|
||||
|
||||
The `$dynamic` feature is designed to support writing `<div class="myClass" {{moreAttrs1}} {{moreAttrs2}}>` in templates.
|
||||
|
||||
`HTML.evaluateDynamicAttributes(attrs, parentComponent)` - Returns the final attributes dictionary for a tag after interpreting the `$dynamic` property, if present. Takes a tag's `attrs` property and a `parentComponent` (used to instantiate any components in the attributes). `attrs` may be null.
|
||||
|
||||
`tag.evaluateDynamicAttributes(parentComponent)` - Shorthand for `HTML.evaluateDynamicAttributes(tag.attrs, parentComponent)`.
|
||||
|
||||
`HTML.isNully(value)` - Returns true if `value` is a nully value, i.e. one of `null`, `undefined`, `[]`, or an array of nully values.
|
||||
|
||||
`HTML.evaluate(node, parentComponent)` - Calls all functions and instantiates all components in an HTMLjs tree.
|
||||
|
||||
## toHTML and toText
|
||||
|
||||
`HTML.toHTML(node, parentComponent)` - Converts the HTMLjs content `node` to an HTML string, using `parentComponent` as the parent scope pointer when instantiating components.
|
||||
|
||||
`HTML.toText(node, textMode, parentComponent)` - Converts the HTMLjs content `node` into text, suitable for being included as part of an attribute value or textarea, for example. `node` must not contain Tags or Comments, but may contain CharRefs, functions, and components. The required argument `textMode` specifies what sort of text to generate, which affects how charater references are handled and which characters are escaped.
|
||||
|
||||
* `HTML.TEXTMODE.STRING` - JavaScript string suitable for `document.createTextNode` or `element.setAttribute`. Character references are replaced by the characters they represent. No escaping is performed.
|
||||
|
||||
* `HTML.TEXTMODE.ATTRIBUTE` - HTML string suitable for a quoted attribute. Character references are included in raw HTML form (i.e. `&foo;`). `&` and `"` are escaped when found in strings in the HTMLjs tree.
|
||||
|
||||
* `HTML.TEXTMODE.RCDATA` - HTML string suitable for the content of a TEXTAREA element, for example. (RCDATA stands for "replaced character data" as in the HTML syntax spec.) Character references are included in raw HTML form. `&` and `<` are escaped when found in strings in the HTMLjs tree.
|
||||
|
||||
> The reason to perform the escaping as part of `HTML.toText` rather than as a post-processing step is in order to support `HTML.CharRef`, allowing the HTML author's choice of character reference encoding to be passed through. If we only had `STRING` mode, we would lose the original form of the character references. If we only had `RCDATA` mode, say, we would have to interpret the character references at runtime to use the DOM API. On a related note, we don't allow `HTML.Raw` because character references are the only "raw" thing there is in text mode (and, again, we don't want to interpret them at runtime). `HTML.CharRef` is sort of like a one-character version of `Raw`.
|
||||
|
||||
## Name Utilities
|
||||
|
||||
All of these functions take case-insensitive input.
|
||||
|
||||
`HTML.properCaseTagName(tagName)` - Case-convert a tag name for inclusion in HTML or passing to `document.createElement`. Most tags belong in lowercase, but there are some camel-case SVG tags. HTML processors must know the proper case for tag names, because HTML is case-insensitive but the DOM is sometimes case-sensitive.
|
||||
|
||||
`HTML.properCaseAttributeName(name)` - Case-convert an attribute name for inclusion in HTML or passing to `element.setAttribute`. See `HTML.properCaseTagName`.
|
||||
|
||||
`HTML.isValidAttributeName(name)` - Returns true if `name` conforms to a restricted set of legal characters known to work both in HTML and the DOM APIs. Allows at least ASCII numbers and letters, hyphens, and underscores, where the first character can't be a number or a hyphen.
|
||||
|
||||
`HTML.isKnownElement(tagName)` - Returns true if `tagName` is a known HTML/HTML5 element, excluding SVG and other foreign elements.
|
||||
|
||||
`HTML.isKnownSVGElement(tagName)` - Returns true if `tagName` is a known SVG element.
|
||||
|
||||
`HTML.isVoidElement(tagName)` - Returns true if `tagName` is a known void element such as `BR`, `HR`, or `INPUT`. Void elements are output as `<br>` instead of `<br></br>`. Note that neither HTML4 nor HTML5 has true self-closing tags (except when parsing SVG). `<br/>` is the same as `<br>` and `<div/>` is the same as `<div>`. It was only the now-abandoned XHTML standard that said otherwise, which was a backwards-incompatible change. Modern browsers refer to the list of void elements instead.
|
||||
|
||||
`HTML.asciiLowerCase(str)` - "ASCII-lowercases" `str`, converting `A-Z` to `a-z`. The case-insensitive parts of the HTML spec use this operation for case folding.
|
||||
|
||||
@@ -157,6 +157,7 @@ instances of a class -- so-called "constructed objects" (see
|
||||
from the vanilla JS objects that represent attributes dictionaries
|
||||
when constructing Tags.
|
||||
|
||||
Functions are also considered foreign objects.
|
||||
|
||||
## HTML.getTag(tagName)
|
||||
|
||||
|
||||
@@ -227,6 +227,8 @@ var Attrs = HTML.Attrs = function (/*attrs dictionaries*/) {
|
||||
* `HTML.isConstructedObject`) -- so that they can be distinguished
|
||||
* from the vanilla JS objects that represent attributes dictionaries
|
||||
* when constructing Tags.
|
||||
*
|
||||
* Functions are also considered foreign objects.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user