Dhi 

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