ADDTOZONE -- add content to a named zone on the page
Parameters
| Parameter |
Description |
Default |
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. |
|
"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 |
topic |
full qualified web.topic name that contains the text to be added, mutually exclusive with text. |
%BASETOPIC% |
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. |
|
section |
section of the topic to be added |
the default section between STARTINCLUDE and STOPINCLUDE |
text |
text to be added to the named zone, mutually exclusive with topic. |
|
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
RSS-Feed
Index
Erweiterte Suche
Beratung
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.