University of Natural Resources and Life Sciences (BOKU)
Institute of Computational Biology

You are here: Foswiki>System Web>Category>UserDocumentationCategory>Macros>VarADDTOZONE (24 Nov 2015, JulianeDohm)

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

Parameters

Parameter	Description	Default
`text`	text to be added to the named zone, mutually exclusive with `topic`.
`section`	section of the `topic` to be added	the default section between STARTINCLUDE and STOPINCLUDE
`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.
`topic`	full qualified `web.topic` name that contains the text to be added, mutually exclusive with `text`.	`%BASETOPIC%`
`"zone"`	comma-separated list of the names of zones that the content should be added to. The only zones guaranteed to exist are `head` and `script`	`head`
`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.

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 two special zones called head and script. 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 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>

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.

{MergeHeadAndScriptZones} is provided to maintain compatibility with legacy extensions that use ADDTOHEAD to add <script> markup and require content that is now in the script zone. {MergeHeadAndScriptZones} will be removed from a future version of Foswiki.

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>"
}%

RENDERZONE, Using ADDTOZONE, Updating applications to use script zone

System