UsingADDTOZONE

The plan is to make this the master registry of ADDTOZONE identifiers and a centre of best practice.

Note: as of 25/7/10, this is all in CDot's checkout, and is done entirely using existing code. Only templates have been edited.

Registry

• Base system
  • JavascriptFiles/foswikilib - base Javascript in the core
  • JavascriptFiles/foswikiString
  • JavascriptFiles/foswikiWindow
  • JavascriptFiles/foswikiEvent
  • JavascriptFiles/foswikiHTML
  • JavascriptFiles/foswikiCSS
  • JavascriptFiles/foswikiForm
  • JavascriptFiles/foswikiPref
  • JavascriptFiles/foswikiStyles

• BehaviourContrib
  • BehaviourContrib/behaviour
• EditTablePlugin
  • EditTablePlugin/edittable.css
  • EditTablePlugin/edittable.js
  • EditTablePlugin/Meta
  • EDITTABLEPLUGIN_NO_JAVASCRIPTINTERFACE

• JQueryPlugin

• JSCalendarContrib
  • JSCalendarContrib/calendar
  • JSCalendarContrib/css
  • JSCalendarContrib/* - various, as dictated by options
• PatternSkin
  • PatternSkin/pattern
  • PatternSkin/pattern_edit
• TwistyPlugin
  • TwistyPlugin/twisty
  • TwistyPlugin/twisty.css

Best Practice

Adhering to these best practices it makes it easier for designers and maintainers, and reduces the risk of errors.

Zone Identifiers

Identifiers used with ADDTOZONE for Javascript files should be composed from the topic and attachment base name.

For example, the main Foswiki Javascript library is identified by the JavascriptFiles id, and has sub_id's Form, Pref, edit. This the ADDTOZONE id's are JavascriptFiles/foswikilib, JavascriptFiles/foswikiForm, JavascriptFiles/foswikiPref, JavascriptFiles/foswiki_edit etc.

The PatternSkin uses the following ids: PatternSkin, PatternSkin/pattern_edit.

Identifiers for CSS files should follow the same pattern.

To debug, or not to debug, that is the question

For historical reasons there are a number of different techniques used to distinguish source (debug), compressed, and zipped Javascript and CSS files. Browsers are not smart enough to decide which of these to include, so we have to provide some hints. Fortunately the use of the BuildContrib has normalised the main techniques.

1. XXX_src.js -> XXX.js -> XXX.js.gz
2. XXX.uncompressed.js -> XXX.compressed.js -> XXX.compressed.js.gz
3. XXX.uncompressed.js -> XXX.js -> XXX.js.gz

Which technique is used depends on the module. When debugging, it is desirable to disable compression and zipping. So the following standard preferences are provided in DefaultPreferences:

• Set FWSRC =
• Set FWCOMPRESSED = .compressed
• Set FWUNCOMPRESSED =
• Set FWGZ = .gz

So instead of spelling out the final filename, we write:

• XXX%FWSRC%.js%FWGZ% - for style 1 _src.js -> .js
• XXX%FWCOMPRESSED%.js%FWGZ% - for style 2 .uncompressed.js -> .compressed.js
• XXX%FWUNCOMPRESSED%.js%FWGZ% - for style 3 .uncompressed.js -> .js

This allows us to switch all JS and CSS into "debug" mode with a few preference settings, thus:

• Set FWUNCOMPRESSED = .uncompressed
• Set FWCOMPRESSED = .uncompressed
• Set FWSRC = _src
• Set FWGZ =

Using ADDTOZONE in skin templates

Using the parameterised TMPL:DEF feature, Foswiki 1.1's foswiki.tmpl defines a TMPL:DEF called LIBJS which is designed to simplify the adding of Javascript coming from the core and extensions. For example,

%TMPL:P{"LIBJS" id="FOSWIKILIB:edit" path="JavascriptFiles/foswiki_edit" requires="FOSWIKILIB,FOSWIKILIB:Pref,FOSWIKILIB:CSS"}%

is exactly equivalent to:

%ADDTOZONE{"script" id="FOSWIKILIB:edit"
 text="<script type=\"text/javascript\" src=\"%PUBURLPATH%/%SYSTEMWEB%/JavascriptFiles/foswiki_edit%FWSRC%.js%FWGZ%\"></script><!--FOSWIKILIB:edit-->"
 requires="%requires%"
}%

The macro ensures that consistent syntax is used for script tags, and helps clarify and simplify template code.

When a package (e.g. a skin) provides a set of templates that may be used by outside agencies (e.g. derived templates, or topic templates) then it is best to define a set of TMPL:DEF macros that handle the includes. For example,

%TMPL:DEF{"PATTERNSKIN:edit"}%
%TMPL:P{"FOSWIKILIB:edit"}%
%TMPL:P{"LIBJS" id="PATTERNSKIN:edit" name="PatternSkin/pattern_edit" requires="FOSWIKILIB:edit"}%
%TMPL:END%

This defines a macro PATTERNSKIN:edit that:

1. Has the same name as the id of the zone that is defined
2. Includes any required zones from the parent skin

Thus a caller only needs to %TMPL:P{"PATTERNSKIN:edit"}% to include all it needs to support editing in Pattern skin.

(An alternative approach is to use recursive ADDTOZONE i.e. include the ADDTOZONE statements for parent skins in the ADDTOZONE text for the derived skin. This is theory only and has not (yet) been explored)

Discussion

A registry for all the IDs is the most important part of the above. The skin-related stuff above is too pattern skin specific. Right now pattern isn't using zones at all. I'd wait until this job is done before settling on a specific best practice too early.

We already have a convention in JQueryPlugin that we could follow here as well.

I would'nt be too anal about the concrete pattern for IDs as long as they are documented and stable.

Related task Item8571

-- MichaelDaum - 25 Jul 2010

Commenting is disabled while not logged in