ZonePlugin < System

You are here: Foswiki>System Web>ZonePlugin (15 Feb 2010, ProjectContributor) (raw view)EditAttach
---+!! %TOPIC%
<!--
   * Set SHORTDESCRIPTION = Gather content of a page in named zones while rendering it
-->
%SHORTDESCRIPTION%

%TOC%

The primary purpose of !ZonePlugin is to streamline the anatomy of a HTML page
in a way to allow today's browsers to process it more efficiently. Page loading
time has been [[http://www.die.net/musings/page_load_time/][reported]] to
decrease significantly when all !JavaScript files are removed from the HEAD
element and appended to the end of the BODY element of a page. That's because
the browser will stop processing a page as soon as a !JavaScript file is found
in the linear order of the page. The browser will only proceed after this file
has been downloaded and excecuted. Notably other content like CSS files and
image material will _not_ be downloaded in parallel as long as the !JavaScript
interpreter hasn't finished.

Currently, Foswiki uses ADDTOHEAD to place additional CSS and JS files into the
HEAD element. It does _not_ reorder those files in any way other than specified
by the explicit =requires= argument to the macro. Further more, it is only able
to add stuff to one specific location of a HTML page, the HEAD element.

By using ADDTOZONE CSS and JS material can be added to the resulting page
incrementally while the core engine parses templates and wiki applications.
ADDTOZONE's first parameter is the name of the zone to add stuff to. There are
two special zones: =script= and =head=. All CSS should be added to the =head=
zone while all JS goes into the =script= zone.

The actual location of a zone is specified with an explicit RENDERZONE macro.
This macro expands to the content of all material that has been posted to the
named zone. Note, that this happens at the very end of the rendering pipeline
of Foswiki. That means RENDERZONE is not processed as a normal macro obeying
the evaluation order of the TML parser.  Instead, all calls to ADDTOZONE are
processed by the TML parser first after which all zones are expanded.

If RENDERZONE{head} and RENDERZONE{script} aren't found in the final page
explicitly, they are expanded at the appropriate position, that is at
=&lt;/head>=.

The features of this plugin have been
[[Foswiki:Development/ImprovePageLoadTime][proposed]] as a core feature for
Foswiki to replace the standard ADDTOHEAD with the more generic ADDTOZONE tag.
This plugin allows authors of extensions and wiki applications to make use of
this advanced feature in a backwards-compatible way. As soon as the ADDTOZONE
macro has been released as part of newer Foswiki versions, this plugin won't be
of use anymore.

%RED%WARNING:%ENDCOLOR% Using this plugin can potentially break your installation.
If you experience occasional !JavaScript errors, enable ={MergeHeadAndScriptZones}=
in [[%SCRIPTURLPATH{"configure}%][configure]]. This mode will render the HTML page
in a non-optimized way similar to how the standard =ADDTOHEAD= mechanism does. 

In any case is it recommended to use =ADDTOHEAD= or =ADDTOZONE= to properly add
this code to the page. It is _not_ recommended to add !JavaScript code otherwise.

If you rely on having !JavaScript added to the
page _without_ using =ADDTOHEAD= or =ADDTOZONE= then you have to enable
={MergeHeadAndScriptZones}= mode most probably. In this case the HTML page cannot
be optimized.

---++ Syntax

%INCLUDE{"VarADDTOZONE"}%
%INCLUDE{"VarRENDERZONE"}%

---++ Perl API

This plugin patches the =Foswiki::Func= API for backwards compatibility. 

   * New =Foswiki::Func::addToZone($zone, $id, $text, $requires)=
   * Replaces =Foswiki::Func::addToHEAD() to use the =head= namespace of this plugin instead of =Foswiki::_HTMLHEAD=

The latter will try to detect =text/javascrtipt= and 
move content into the =script= zone. Otherwise, it will be added to the =head=. 

Any use of =ADDTOHEAD= or =Foswiki::Func::addToHEAD()= will emit a warning to
the log files (must be switched on with the =Warnings= flag in
[[%SCRIPTURLPATH{"configure}%][configure]]).  This can be used to hunt down
suboptimal use of these APIs.

---++ Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.



|  Author(s): | Michael Daum|
|  Copyright: | &copy; 2010 Michael Daum http://michaelaumconsulting.com |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Release: | 3.1 |
|  Version: | 9442 (2010-09-30) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  29 Sep 2010 | Foswikitask:Item9763 revert recent changes and forward port script zone to make it work on old foswiki engines | 
|  06 Sep 2010 | Foswikitask:Item9588: Update ZonePlugin to match Foswiki 1.1. Removed ={OptimizePageLayout}=, replaced with ={MergeHeadAndScriptZones}=. Removed =body= zone, replaced with =script= zone. Refer to Foswikitask:Item9588 for more info |
|  28 Mar 2010 | fix problem where Foswiki 1.0.x installations would fail with "Undefined subroutine &Foswiki::Func::addToZone" |
|  26 Mar 2010 | suppressing plugin initialisation on Foswiki engines >= 1.1; renamed <nop>BackwardsCompatible switch to <nop>OptimizePageLayout (defaults to off) |
|  19 Feb 2010 | added ={<nop>BackwardsCompatible}= switch |
|  15 Feb 2010 | be more careful applying the monkey-patch to the Func API; \
                 parsing RENDERZONE properly but finally inserting the zone at the end of the rendering pipeline |
|  12 Feb 2010 | initial release |
|  Dependencies: | None |
|  Home page: | Foswiki:Extensions/ZonePlugin |
|  Support: | Foswiki:Support/ZonePlugin |

<!-- Do _not_ attempt to edit this topic; it is auto-generated. -->
Topic revision: r1 - 15 Feb 2010, ProjectContributor
System
Webs
Main
Sandbox
System
Testweb
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback