DHTML Info Object

The DHTML Info, or Dhi facilitator object contains
DHTML-related information for an HTTP response, with the
intention of making complex DHTML pages
easier to build and to debug.
A welcome additional advantage is that DHTML pages built in
this way tend to be simpler to render by web clients.

A dhi instance lives as
long as a hit, i.e. a request/response cycle. It corresponds
conceptually to the HTML HEAD element, and allows itself to be modified
by all components participating in a response.
Information such as
required CSS or Javascript files, inlined CSS and Javascript code,
as well as onload actions or attributes
on the BODY element, may be liberally accumulated in this way.
Given that dhi instances are always rendered last,
resulting DHTML pages can always make the following claims:

  • There is at most only one inline STYLE tag and
    at most only one inline SCRIPT tag.
  • STYLE and SCRIPT tags, whether for any inlined code or per
    external file,
    are all contained in the HEAD
    (thus guaranteed to be executed by the time
    the page onload event is fired).
  • Any required CSS or Javascript file is included once and only once.
    Same for any piece of inlined CSS or Javascript code, as well as any onload
    actions.

A dhi instance is
built transparently by components that use it, such as
gizmos,
and rendering is handled automatically when a
page is rendered via gz.skin.render.dhi_page()
— that is how both of the Skin classes provided render pages.

In non-DHTML contexts, such as an ajax JSON callback,
the dhi is not relevant, and therefore is not used.

For DHTML responses, using a dhi instance is anyway optional.
And, given that a dhi is only created when explicitly requested,
there is zero performance overhead for the DHTML responses that choose
to not use one.

Getting and manipulating a hit’s dhi

Responses that wish to make use of a dhi must explicitly request
an initialized instance. This is done by using the get_dhi() common
function:

from gz.pub.common import get_dhi
dhi = get_dhi()

The first time that get_dhi() is called during a hit’s life cycle,
a default dhi is created.
A custom dhi factory instance
may be specified per exportable
(see example of this in the
online demo),
that is then used for cloning a dhi for
each corresponding hit —
responses always work on a throw-away copy.

Once a dhi has been initialized for a hit, then the same instance
is used for the duration of the hit.
As a consequence, redirected responses (i.e. that trigger
a new hit) would also trigger a new dhi.

A hit’s dhi instance is cached at:

get_publisher().get_hit().get_info()[‘dhi’]

Here are the more relevant attributes and methods,
on the Dhi class itself, and a couple of
the page generation support methods that take care to
render a dhi instance
for pages that make use of it.

Dhi


Dhi.body_attrs : {}
Dhi.gizmos : bunch
Dhi.meta : bunch
Dhi.http_equiv : bunch

Infrequently used in client code, and may be accessed directly.
meta and http_equiv may be None.


Dhi.add_css_files(*css_files)
Dhi.add_css_codes(*css_codes)
Dhi.add_js_files(*js_files)
Dhi.add_js_codes(*js_codes)
Dhi.add_onload_actions(*onload_actions)

Update corresponding list attribute with the specified parameters.

Rendering support


gz.skin.render.dhi_page(title, *content, **kw)

Ensures that the dhi is rendered last.
Page renderers that use a dhi
are implemented as wrappers of this method.


gz.skin.render.render_dhi(dhi)

Render the dhi.
Only called within gz.skin.render.dhi_page().

More Information