ADDTOZONE -- add content to a named zone on the page

Parameters

Parameter	Description	Default
"zone"	comma-separated list of the names of zones that the content should be added to. The only zones guaranteed to exist are head, script and body.	head
id	identifier for the text being added with the ADDTOZONE call, to be used in the requires parameter of other ADDTOZONE calls. Multiple ADDTOZONE calls with the same id parameter will simply overwrite the earlier ADDTOZONE call.
requires	comma separated string of ids of text within this zone that this content should follow when the zone is rendered. The content will be rendered even if a specified id is missing.
text	text to be added to the named zone, mutually exclusive with topic.
topic	full qualified web.topic name that contains the text to be added, mutually exclusive with text.	%BASETOPIC%
section	section of the topic to be added	the default section between STARTINCLUDE and STOPINCLUDE

What is a "Zone"?

Zones are specific places in the output HTML that are marked by calls to the RENDERZONE macro. Zones are used to collect various content together, such as Javascript and CSS, that must be included in the output HTML in a specific order, and in a specific place.

There are three special zones called head, script and body. The head zone is rendered as part of the HTML head section. It is the catch-all container for any content supposed to be placed into the HTML head section, except Javascript, which is collected in the script zone.

All Javascript must always be added to the script zone exclusively, in order to grant ordering constraints among scripts are resolved properly. Never add Javascript to the head zone -- never add non-Javascript content to the script zone.

Both head and script zones are added to the HTML head section automatically just before the closing </head> tag as if they were specified explicitly in the skin templates using:

<head>
...
%RENDERZONE{"head"}%
%RENDERZONE{"script"}%
</head>

The body zone is added to the end of the rendered page just prior to the closing <body> tag.

You may create as many zones in addition to the standard head and script zones as you like. For any non-standard zone specified in ADDTOZONE you will also need to provide an appropriate RENDERZONE.

Interesting use cases in wiki applications:

• Create a sidebar zone to add widgets,
• Create a toolbar zone to add buttons icons
• Create a menu zone to add menu entries

Adding content to a zone

ADDTOZONE adds content to a zone identified with the id parameter. An id identifier is unique within the zone that they are added to. When the same id is used in multiple calls to ADDTOZONE the last call will win, that is previous content of the same id will be overwritten.

Enforcing a linear order of content within a zone

An ADDTOZONE call may ensure that its content appears after the content of some other ADDTOZONE calls by specifying their ids in the requires parameter. The requires parameter constraints the linear order of content added to a zone. When a zone is rendered, all ordering constraints expressed via requires are satisfied. Those ids not found in a zone don't have any influence on the final ordering. Missing ids aren't considered an error rather than an over-specified ordering problem.

Working with {MergeHeadAndScriptZones} disabled (default)

In this mode, the head and script zones are treated separately.

Even when head and script zones are treated separately, the head zone will always be rendered before the script zone, unless otherwise specified using RENDERZONE explicitly. So any content in the script zone that depends on content placed into the head zone is satisfied intrinsicly as they are both rendered as specified above.

Working with {MergeHeadAndScriptZones} enabled

In this mode, the head and script zones are separate when adding to them, but may be treated as merged when you call RENDERZONE if there are any dependencies specified that only exist in the opposite zone. This allows an ADDTOZONE{"head"...} to to successfully require an id that has been added to script.

Examples

Adding to a zone with missing dependencies

You must ensure that no head content (and no inline Javascript) depends on script content. Any such dependency will be ignored.

In real world application this isn't a problem as Javascript is never added to the head zone or Javascript zone part of the script zone never really depends on non-Javascript content part of the head zone.

HTML comment decoration which normally appears after each id's content in the rendered HTML will contain a small informative text to aid debugging.

Example

%ADDTOZONE{
  "script"
  text="
  <script type='text/javascript'>
    alert('test');
  </script>"
  requires="some-id-that-exists-in-script"
  id="MY::TEST"
}%

Result

<script type='text/javascript'>
  alert('test');
</script>
<!-- MY::TEST: requires= missing ids: some-id-that-exists-in-script -->

Adding Javascript to a page

Make sure that all inline Javascript code in the topic (if it is allowed) is added to the page using %ADDTOZONE{"script"...requires="library-id"}% with the appropriate library-id to guarantee a correct load order. For example, jQuery code should be added as follows:

%JQREQUIRE{"shake"}%
%ADDTOZONE{
   "script"
   id="MyApp::ShakePart"
   text="
   <script type='text/javascript'>
      jQuery('#something').shake(3, 10, 180);
   </script>"
   requires="JQUERYPLUGIN::SHAKE"
}%

where "MyApp::ShakePart" is a unique id to identify the text added to script; and JQUERYPLUGIN::SHAKE signifies that the content added with that identifier should appear beforehand.

Adding CSS to a page

%ADDTOZONE{"head"
   id="MyCSS"
   text="
      <style type='text/css' media='all'>
         @import url('%PUBURLPATH%/%SYSTEMWEB%/MyCSS/foo.css');
      </style>"
}%

Related

RENDERZONE, Using ADDTOZONE, Updating applications to use script zone