ADDTOZONE

%ADDTOZONE{
  "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.

You may create as many zones in addition to the standard head and script zones as you like. Interesting use cases in wiki applications:

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

ADDTOZONE adds content identified with the id parameter to zone, which will later be expanded with RENDERZONE. id identifiers are unique within the zone that they are added to. 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. requires may only list ids within the specified zone, except for the special case of head and script zones when {MergeHeadAndScriptZones} is set (read more).

Parameters:

• "zone" optional, comma-separated list of the names of zones that the content should be added to. Defaults to head.
• id optional, 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="..." optional, comma separated string of ids of text within this zone that this content should follow when the zone is rendered.
• text="..." optional, text to be added to the named zone, mutually exclusive with topic.
• topic="..." optional, full qualified web.topic name that contains the text to be added, mutually exclusive with text.
• section="..." optional, section of the topic to be added, defaults to the default section between STARTINCLUDE and STOPINCLUDE.
  
  • Using topic and section is actually a short form of

    %ADDTOZONE{
       "myzone"
       text="$percentINCLUDE{\"topic\" section=\"section\" warn=\"off\"}$percent"
    }%

Note: Foswiki uses the requires parameter to resolve the ordering of dependencies within a zone. It does not work across zones. If you have an id in requires that cannot be resolved during sorting, then RENDERZONE will generate an HTML comment to mark the problem.

How to use the head and script zones

Web browsers generally process the HTML on a page from top to bottom. When a <script> tag is encountered with a URL to some Javascript file, processing of the page will stop while the file is fetched and executed before continuing. When a page makes heavy use of Javascript you can get a "blank screen" effect in the browser while each script is downloaded. To avoid this effect, <script> tags can be moved to the end of the HTML page, so that the user may view the page content while scripts are being loaded.

Foswiki makes this move possible by providing the head and script zones. These are automatic zones - they do not require a corresponding RENDERZONE.

Rendering the script zone at the end of the HTML body requires skin template customisation with %RENDERZONE{"script"}%

Notionally the head and script zones correspond to a point just before the HTML </HEAD> tag. Normally you should add CSS (and other HTML <HEAD> content, such as <META>) to the head zone, and Javascript <script> markup to the script zone. The setting {MergeHeadAndScriptZones} in Configure controls what happens when RENDERZONE is called.

Normally, dependencies between the individual ADDTOZONE statements are resolved within each zone. However, if {MergeHeadAndScriptZones} is enabled, then head content which requires an id that only exists in script (and vice-versa) will be re-ordered to satisfy any dependency.

{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.

Workign with {MergeHeadAndScriptZones} disabled (default)

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

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.

Only add content to the script zone that is also legal in the <HEAD>.

Example: Adding to a zone with missing dependencies

You must ensure that no head content (and no inline Javascript) depends on script content, or vice-versa. Any such dependency will be ignored. However, the 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{
  "head"
  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 -->

On the other hand, as explained earlier - when {MergeHeadAndScriptZones} is enabled - Foswiki is able resolve such dependencies successfully.

Note that if you do have an explicit call to %RENDERZONE{"head"}% in your templates then the content expanded at that point will be the same content as would be inserted before the </HEAD>.

Example: 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.

Example: Adding CSS to a page

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

See also RENDERZONE, Using ADDTOZONE