Changeset 8289

Timestamp:

07/24/10 08:11:38 (22 months ago)

Author:

CrawfordCurrie

Message:

Item9317: added a bunch more doc on how to use head and body zones, and corrected the sense of the doc describing OptimizePageLayout - it doesn't optimise when set, it de-optimises when not set, and that's an important difference.

Location:

trunk/core

Files:

• data/System/CommandAndCGIScripts.txt (modified) (1 diff)
• data/System/JavascriptFiles.txt (modified) (2 diffs)
• data/System/VarADDTOZONE.txt (modified) (3 diffs)
• data/System/VarRENDERZONE.txt (modified) (1 diff)
• lib/Foswiki.spec (modified) (2 diffs)

trunk/core/data/System/CommandAndCGIScripts.txt

@@ -255 +255 @@
 | =attachment= | Attachment to move | =none= |
 | =currentwebonly= | if defined, searches current web only for links to this topic | |
-| =newattachment= | (Optional) new name for attachment | =none= |
+| =newattachment= | New name for attachment | =attachment=, if given |
 | =newtopic= | new topic name | |
 | =newweb= | new web name | |

trunk/core/data/System/JavascriptFiles.txt

@@ -6 +6 @@
 user experience is significantly improved if it is enabled.
 
-Foswiki Javascript support comprises a number of base Javascript files,
+Foswiki Javascript support includes a number of base Javascript files,
 attached to this topic, that provide support for features in the basic screens,
 and are used by most skins. These files are automatically included as required
@@ -15 +15 @@
 user interface components.
 
-*Related Topics:* SkinTemplates, [[Skins]]
+You can use Javascript in the body of topics, but you are highly recommended
+to use the [[VarADDTOZONE][%<nop>ADDTOZONE{"body" ...}%]] macro if you do so.
+Bear in mind that inline Javascript represents a significant security risk to
+Foswiki sites, and sites vulnerable to hackers should seriously consider
+installing the =SafeWikiPlugin= to control it.
+
+*Related Topics:* SkinTemplates, [[Skins]], [[VarADDTOZONE][ADDTOZONE]]
 <!--
    * Set ALLOWTOPICCHANGE = %USERSWEB%.AdminGroup

trunk/core/data/System/VarADDTOZONE.txt

@@ -11 +11 @@
 </verbatim>
 
-_Zones_ are specific places in the output HTML that are marked in the source templates using the [[VarRENDERZONE][RENDERZONE]] macro. Zones are used to collect various materials together, such as Javascript and CSS, that must be included in the output HTML in a specific order, and in a specific place. By default, skins define two zones, =head= and =body= which are in the HEAD tag and at the end of the BODY tag respectively.
+_Zones_ are specific places in the output HTML that are marked in the source templates using the [[VarRENDERZONE][RENDERZONE]] macro. Zones are used to collect various materials together, such as Javascript and CSS, that must be included in the output HTML in a specific order, and in a specific place. Each =ADDTOZONE= call can be identified by a _unique identifier_, and you can state dependencies on other identifiers. In this way you can constrain the order in which they are expanded in the output.
 
-Each =ADDTOZONE= call can be identified by a _unique identifier_, and you can state dependencies on other identifiers. In this way you can constraint the order in which the text added by each call is expanded in the output.
+There are always at least two zones, =head= and =body= - see [[#HeadAndBody][below]] for more information on how to use these standard zones. You can create as many additional 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
 
 Parameters:
@@ -26 +28 @@
      STOPINCLUDE
 
-Note that using =topic= and =section= is actually a short form of 
+Using =topic= and =section= is actually a short form of 
 <verbatim class="tml">
 %ADDTOZONE{
@@ -34 +36 @@
 </verbatim>
 
+#HeadAndBody
+*How to use the =head= and =body= zones*
+
+Notionally the =head= and =body= zones correspond to the end of the HTML =&lt;HEAD&gt; tag and the end of the BODY tag respectively. Normally you should add CSS (and other HTML =&lt;HEAD&gt; content, such as =meta=) to the =head= zone, and Javascript to the =body= zone. There is a setting in =configure=, ={OptimizePageLayout}=, that controls what happens next. First, dependencies between the individual =ADDTOZONE= statements are resolved *within each zone*. Then, if ={OptimizePageLayout}= is enabled, the =head= content is added to the =&lt;HEAD&gt;, and the =body= content is added to the BODY. However, if ={OptimizePageLayout}= is _disabled_ (the default), both the =head= and =body= zones will be added to the HTML =&lt;HEAD&gt;.
+
+For this reason you must be careful to:
+   1 Only add HTML to the body zone _that is also legal in the =&lt;HEAD&gt;_
+   1 Ensure that no =head= content (and no inline Javascript) depends on =body= content. Any such dependency will be _silently ignored_.
+   1 Make sure that all inline JavaScript code in the topic (if it is allowed)
+     is added to the page using
+     =%<nop>ADDTOZONE{"body"...requires="library-tag"}%=
+     with the appropriate library-tag to guarantee a correct load order.
+
 See also [[VarRENDERZONE][RENDERZONE]]

trunk/core/data/System/VarRENDERZONE.txt

@@ -25 +25 @@
 required in the templates.
 
-Note that you can create as many zones as you like. You are not restricted
-to just =body= and =head=. Interesting use cases in wiki applications:
-
-   * create a =sidebar= zone to add widgets
-   * create a =toolbar= zone to add buttons icons
-
-See also [[VarADDTOZONE][ADDTOZONE]]
+See also [[VarADDTOZONE][ADDTOZONE]] for more information on zones.

trunk/core/lib/Foswiki.spec

@@ -565 +565 @@
 # Used to disallow the use of SCRIPT and LITERAL tags in topics by removing
 # them from the body of topics during rendering.
-# <font color="red">This setting is now DEPRECATED</font> - use SafeWikiPlugin
-# instead.
+# <font color="red">This setting is fundamentally unsafe and is now
+# DEPRECATED</font> - use SafeWikiPlugin instead.
 $Foswiki::cfg{AllowInlineScript} = $TRUE;
 
@@ -1066 +1066 @@
 #---++ HTML Page Layout
 # **BOOLEAN EXPERT**
-# Enable heuristics to optimize the HTML layout by placing all JavaScript files
-# at the bottom of the page, while leaving all CSS files at the top. Note, that
-# you will need to load JavaScript files using <code>%ADDTOZONE{"body" ...}%</code>
-# for content that should participate in this optimization step. Similarly, all
-# CSS files should be added to the page using <code>%ADDTOZONE{"head" ...}%</code>.
-# Note also, that placing JavaScript library files at the bottom of the page, JavaScript
-# code within the topic content area might potentially break when it relys on those libraries
-# being loaded before. So please make sure all JavaScript code is added to the page
-# using <code>%ADDTOZONE{"body"...requires="library-tag"}%</code> with the appropriate library tag
-# to guarantee a correct linear order of the files being loaded by the browser.
+# If this option is disabled then Foswiki will move all
+# <code>%ADDTOZONE{"body"...}%</code> statements to the end of the
+# HTML &lt;HEAD&gt; tag (immediately after the content added by
+# <code>%ADDTOZONE{"head"...}%</code>). If the option is enabled, then
+# <code>%ADDTOZONE{"body"...}%</code> statements are added to the end of
+# the &lt;BODY&gt; tag instead. This optimises the performance of browsers.
+# <strong>Warning</strong> enabling the optimisation might
+# <u>break</u> topics if Javascript code within the topic content has
+# a dependency on other code being loaded in the body zone. See
+# System.VarADDTOZONE for more information. There may also
+# be problems with plugins which post-process body content, such as
+# SafeWikiPlugin. 
 $Foswiki::cfg{OptimizePageLayout} = $FALSE;