Discuss TopicEditWYSIWYGAttachPrintable
r37 - 28 Apr 2008 - 20:15:16 - PeterThoenyYou are here: TWiki >  Codev Web > ChangeProposal > FeatureRequest > ProcessAddToHeadAdds
Tags:
twiki_func 1 Add my vote for this tag, , create new tag

Feature Proposal: Process addToHEAD adds

Motivation

Currently plugins call TWiki::Func::addToHEAD to add javascript and css text and file includes to the html <head> tag. The TWiki core blindly adds these to the header.

If these 'adds' were processed, we could:

  • use ordering/priorities for includes, for example to add things to the beginning instead of at the end
  • remove duplicate calls to the same files
  • accumulate javascript files to one file and dynamically compress it (or cache the compressed file) to improve page rendering speed
  • the same for css files

Specification

Usual interpretations of shall, should and may.

ADDTOHEAD

A new TWiki variable %ADDTOHEAD{...}% shall be a standard TWiki variable. This variable shall expand to the empty string, unless there is an error in which case the variable shall expand to an error string. The variable shall accept the following parameters:
  • _DEFAULT optional, id of the head block. Used to generate a comment in the output HTML.
  • text optional, text to use for the head block
  • topic optional, full TWiki path name of a topic that contains the full text to use for the head block. If text is also specified, then
  • pos optional, positive floating-point number that indicates position in the total ordering of all head blocks.

TWiki::Func::AddToHEAD

TWiki::Func::addToHEAD shall be extended to accept a third unnamed parameter, a number equivalent to pos.

RENDERHEAD

A new TWiki variable %RENDERHEAD% shall be a standard TWiki variable. This variable shall expand to a sorted list of the head blocks added at the point the RENDERHEAD variable is expanded. Each expanded head block shall be preceded by an HTML comment that shall record the ID of the head block and may record the pos of the head block.

Head blocks shall be sorted such that blocks that have pos specified shall be output before blocks that do not have pos specified. Blocks with a pos value shall be output in numerical order of their pos values, lowest pos first. The output order of blocks with no pos value may be the order in which they are expanded, but may also be undefined.

General Requirements

  • Head blocks shall support inclusion of TWiki variables. These TWiki variables shall be expanded after rendering of the topic is complete and after head sections have been sorted.
  • TML (TWiki formatting, not TWiki variables) in head blocks shall not be rendered.

Position Ranges

The following predefined values and ranges are defined for pos values:

0..999 unrestricted
1000..1999 plugin css
2000..2999 plugin javascipt
3000..3999 unrestricted
4000..4999 skin css
5000..5999 skin javascript
6000..6999 unrestricted
7000..7999 topic css
8000..8999 topic javascript
9000.. unrestricted

Explanation and Best Practice for use of Position Ranges

This is a first draft. It is based on the observations how page headers are be constructed up to now on a well behaving system. Anybody welcome to object and propose something different!

The following tries to explain the predefined position ranges and provide a guide on how to order javascript and css definitions coming from different sources in a way that plugins, skins and TWikiApplications cooperate in a well defined way.

Note, that the above ranges is just a general guide and does not force you to really obey it. You are free to use whatever priorities you want. Remember, however, that you might be at risk of sacrificing interoperability of different components. Only act so if you are sure what you are doing. In such cases, please make use of the ranges marked as "unrestricted".

In TWiki plugins may add the base definitions of css and javascript to the page. These may be restyled using the skins' css. That is, skins may come with support for a range of plugins that they restyle to match a certain webdesign. Skins may also come with additional javascript in its templates that build upon a set of plugin javascript. Thus they come after the plugin additions. Last but not least, TWikiApplications written in topics may add css or javascript to the page thus having the highest precedence. If you want to allow skins to override css definitions of a TWikiApplication, you should (1) either add a separate skin cover to blend them in using the template system, or (2) add the needed css for a TWikiApplication together with the plugin it comes with if that's the case or (3) make use of the "unrestricted" position ranges.

Javascript frameworks like, jQuery, Dojo or YUI, might have their own requirements on the order of head additions. These must be documented accordingly on their own behalf and are not covered by this specification. Plugins and skins shall obey the above general ranges, subdividing them as needed.

Examples

In templates / topics: 
%ADDTOHEAD{"no_style" text="<style> .none {} </style>"}%
%ADDTOHEAD{text="<style> .chic {} </style>" pos="2000"}%
%ADDTOHEAD{"doggy" topic="Styles.DoggyStyle" pos="100"}%
in plugins / contribs: 
TWiki::Func::addToHEAD("hair", "<style> .hair {} </style>", 500);
TWiki::Func::addToHEAD("free", "<style> .free {} </style>");
%RENDERHEAD% will expand to 
<!--doggy:100--><style>
.doggy { display:block }
</style>
<!--hair:500--><style> .hair {} </style>
<!--:2000--><style> .chic {} </style>
<!--no_style--><style> .none {} </style>
<!--free--><style> .free {} </style>

-- Contributors: ArthurClemens, CrawfordCurrie, SvenDowideit, MichaelDaum

To discuss this proposal, click "Discuss Topic" in the top bar, above.

ChangeProposalForm
TopicClassification FeatureRequest
TopicSummary Process addToHEAD adds
CurrentState ReadyForReleaseMeeting
CommittedDeveloper ArthurClemens
ReasonForDecision None
DateOfCommitment 2007-02-25
ConcernRaisedBy SvenDowideit
BugTracking

OutstandingIssues more discussion of possible simplifications
RelatedTopics

InterestedParties

ProposedFor GeorgetownRelease
TWikiContributors

Discuss Topic | Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r37 < r36 < r35 < r34 < r33 | More topic actions
 
Powered by TWiki
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback SourceForge.net Logo