Log inRegister
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 calledhead, 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.
The
You may create as many zones in addition to the standard body zone is new with Foswiki 2.1.5. It was
added for improved compatibility with the NatSkin. 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
sidebarzone to add widgets, - Create a
toolbarzone to add buttons icons - Create a
menuzone to add menu entries
Adding content to a zone
ADDTOZONE adds content to a zone identified with theid 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 theirids 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 nohead 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 usescript zoneSitemap
Copyright © by the contributing authors. All material on this site is the property of the contributing authors. Ideas, requests, problems regarding Foswiki? Send feedback
This page was cached on 2024.11.23 - 09:13.