.. _tutorial2: Tutorial 2: writing page elements ================================== Step-by-step demonstration on how page elements work and get related to the target DOM. .. note:: The example below includes code snippets from MDN site, by Mozilla Contributors and licensed under CC-BY-SA 2.5. .. note:: MDN site's HTML is too good for `manners`. It is well written, clean and structured. Manners can do much worse than that. HTML vs HTML -------------- Open MDN in the `div element `_ . Open the inspector to examine the DOM of that page. .. highlight:: html The body of the page, contracted, looks like this::
...
...
And, focusing a part of the ``
`` element we could see a snippet like:: In principle, pasting the above section into a pagelem template file, should work. It would match 1:1 to the MDN site DOM, that page. Removing redundant elements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Not all html elements are worth matching. Say, that ``
`` needs not be that specific, nor the "Jump to:" text is any more specific than the ``id="toc"`` of the outer ``
`` So, the above snippet could be cleaned like:: Adding components ~~~~~~~~~~~~~~~~~~~ The above will not `emit` any matched components, until ``this`` attributes are set in the interesting elements:: That would produce a structure of components like:: [page-toc] - [links] - [Attributes] - [Specifications] Generalizing ~~~~~~~~~~~~~ Then, the indidual ``
  • `` elements should be covered all with one rule, rather than hard-coding their exact attributes. This allows the same `toc` code to match any table of contents that conforms to this layout. Pagelem code now can be simplified like:: Getting simpler, and will also match all entries in the TOC this way. ``href="[href]"`` syntax means that the value of ``href=`` attribute will be assigned to a ``href`` attribute of the resulting component. Will match anything in there. Likewise ``[title]`` as text of an element will copy whatever text into a ``title`` attribute. Then, ``this="[title]"`` means that the value assigned to ``title`` becomes the name of the resulting component. Thus, the resulting component structure after this generalisation should now be:: [page-toc] - [links] - [Attributes] href = #Attributes title = Attributes - [Usage notes] href = #Usage_notes title = Usage notes - [Examples] href = #Examples title = Examples ... Full page ---------- The above example cannot work standalone; rather it needs to be put in context of a full HTML page. Assuming the earlier structure, it would need to be written as::
    This works for the MDN case, because "toc" is just one level down from "main". But would become worse if "toc" had been somewhere deep within the page DOM. In that case, intermediate levels could be skipped with:: making code now more compact. Templating ------------ Since the TOC, footer and menu of this site are expected to be re-occuring across all pages, makes sense to write them as re-usable templates *gallery.html* :: *div-element.html* ::
    Templates may be called repeatedly in some page, even recursively. Attribute matching ------------------- Attributes of pagelems will match same attributes on remote DOM, by default. Example::
    will match a `div` only if it's class equals to "toc". That's not always convenient, since other classes may exist along "toc", that matching should ignore. ::
    will then match if the div's class *contains* "toc". Then, several values could be or-ed by mentioning them each::
    Writing ``title="[tooltip]"`` will NOT attempt any match, but transfer the value of remote DOM attribute ``title`` to Component attribute ``.tooltip`` . That can co-exist with a matcher, like::
    Note here the underscore after ``class_`` , because attribute names need to be valid Python variable names, ``class`` is a reserved word. Attribute matching can be negated with the ``!`` operator::
    or, when the element should not contain a class::
    Other pagelems --------------- The `pagelem` HTML-like language offers some other extra elements and attributes that help match remote DOM with less code on the testing side. Components may be tagged as ``pe-optional`` rather than failing the match. Pagelem can match regardless of DOM tag with ```` element. Alternate structures may be matched with ```` . Within a repetition or ```` , collections of elements can be forced to go together in a ````. More about them can be read in the reference and supplied examples.