Difference: VarADDTOZONE (r2 vs. r1)

ADDTOZONE

ADDTOZONE

%ADDTOZONE{
  "zone"
  ...
}%

%ADDTOZONE{
  "zone"
  ...
}%

Parameters:

• "zone" optional, 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. 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. The content will be rendered even if a specified id is missing.
• 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. Defaults to %BASETOPIC%
• section="..." optional, section of the topic to be added, defaults to 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.

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:

There are two special zones called headand 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.

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

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.

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

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

Parameters:

...
%RENDERZONE{"head"}%
%RENDERZONE{"script"}%

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

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.

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.

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

How to use the head and script zones

Adding content to a zone

Web browsers generally process the HTML on a page from top to bottom. When a " requires="some-id-that-exists-in-script" id="MY::TEST" }%

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.

Result

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

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

%ADDTOZONE{
  "script"
  text="
  "
  requires="some-id-that-exists-in-script"
  id="MY::TEST"
}%

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 .

Result

Example: Adding Javascript to a page

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="
     "
     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.

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="
   "
   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

Example: Adding CSS to a page

%ADDTOZONE{"head"
   id="MyCSS"
   text="
      "
}%

%ADDTOZONE{"head"
   id="MyCSS"
   text="
      "
}%

See also RENDERZONE, Using ADDTOZONE

See also RENDERZONE, Using ADDTOZONE, Updating applications to use script zone