The Engine

The engine generates boilerplate, based on the values of its attributes. They are all documented here, just so you are aware of what is available, though you will only need to use a handful normally.

Note: The engine's constructor has no required arguments, but can take any of the engine's attributes as keyword arguments.

The Miscellaneous Attributes

The engine has three miscellaneous attributes:

• lang = "en" A required ISO 639-1 language code that is used for the HTML element's lang attribute, unless this attribute is set to None, in which case it does nothing.
• freezer = {} The engine's freezer. This should be a dictionary (which is used directly), or another object with a freezer (an element or another engine instance), in which case, the object's freezer is shallow copied (they are flat in practice anyway).
• tree = Tree() The tree used to define the guts of the body.

The Attribute Dicts for the Three Main Boilerplate Elements

The engine has html_attributes, head_attributes and body_attributes properties, which all default to empty dictionaries. The dictionaries contain any attributes that should be added to the corresponding boilerplate element (HTML, HEAD and BODY respectively).

The Expandable Directive Element Attributes

The engine has eight attributes that can be set to None, an element or a string. If the value is None, the element is omitted from the output. If the value is an element, the element is used directly. If the value is a string, it is used to generate the element automatically.

• charset = "utf-8" The required charset META element, or its character encoding.
• ie_version = "edge" The optional X-UA-Compatible META element, or the value of the ie subattribute of its content attribute.
• base = None The optional BASE element, or its href attribute.
• title = "" The required title element, or its content.
• author = None The optional author META tag, or the value of its content attribute.
• description = None The optional description META element, or the value of its content attribute.
• manifest = None The optional web manifest META element, or the value of its href attribute.
• favicon = None The optional favicon META element, or the value of its href attribute.

The Viewport Attributes

The viewport META tag sets the initial scale, maximum and minimum scale, scalability, height and width of the viewport. It is a complicated element, but important, as it helps mobile devices to render pages correctly.

The engine has a viewport attribute, which defaults to True.

If viewport is None, no element is rendered, and if viewport is an element, the element is used directly.

If viewport is True (the default), the element is constructed from the scale, scalable, width, height, maximum_scale and minimum_scale attributes automatically. If any of those six attributes are None, the corresponding subattribute is omitted from the element. Otherwise, the subattribute uses the value you provide.

The scalable, height, maximum_scale and minimum_scale attributes all default to None, so are omitted by default.

The scale attribute (which maps to the initial-scale subattribute) defaults to 1, and width defaults to device-width.

You normally just leave all of the viewport attributes alone, and let the engine generate its recommended default element automatically:

<meta content="width=device-width, initial-scale=1" name="viewport">

The Installation & Augmentation

The installation is our term for the LINK and SCRIPT tags at the end of the HEAD element that load any CSS and JavaScript resources that should be installed before the body is parsed. The augmentation is how we describe the similar resource elements that are appended to the body, loading resources after the body is parsed.

The engine has installation and augmentation attributes, which are both lists of elements.

There are helper methods (install, uninstall, augment and unaugment) that make the installation and augmentation easier to manage, and magic element classes (Style and Logic) that make it easier to define the individual elements that go in the lists.

The Icons

The icons attribute is a list that works exactly like the installation and augmentation lists. It contains elements that load favicons and mobicons (our name for Apple Touch Icons) with different sizes, which are used on the home screens of iOS and Android devices, new tab pages et cetera.