Products.ResourceRegistries 1.5.0

Registry for managing CSS and JS

A registry for linked Stylesheet files and Javascripts.

This registry is mainly aimed at solving the following usecases:

- Enable product authors to register stylesheets with their product
installers without having to resort to override either header.pt or
ploneCustom.css creating potential conflicts with other products.

- Enable more componentialization of the stylesheets provided with Plone
(and other products) without having to increase the number of http
requests for a Plone page.

- Enable condition checking on stylesheets. Great for variable
look-and-feel for groups/roles/folders/departments/content-types/etc

- Enable inline dynamic stylesheets. For those style rules that should
vary for each request. Mainly used for things like header-bar-
backgroundimages, department colors etc.

- Enable developers to activate/deactivate their styles in a simpler way

- Enable compression to safe bandwidth and download time

Usage
=====

ResourceRegistries 1.3 requires CMF 1.6 or later. (Intrepid users can
probably get it working w/ CMF 1.5.5 w/ GenericSetup installed.)

The CSSRegistry and JSRegistry is configured through the ZMI. it can be found
in the ZMI of your plonesite as 'portal_css' and 'portal_javascript'.

Add links to stylesheets that exist in your skins paths, by ids; like
'plone.css', 'ploneCustom.css' etc.

Linked stylesheets take some parameters:

id -- The id mentioned above. the Zope id of the stylesheet to be used.

expression -- A CMF expression to be evaluated to check if the stylesheet
should be included in output or not.

conditionalcomment -- A small string to be included in a conditional comment
around the resource. For example, entering simply 'IE' in the field will
result in a conditional comment of: <!--[if IE]>...<![endif]--> This behavior
is currently only enabled for the CSS Registry. For more information see:
http://msdn.microsoft.com/en-us/library/ms537512.aspx

media -- The media for which the stylesheet should apply, normally empty or
'all'. other possible values are 'screen', 'print' etc.

rel -- Link relation. defaults to 'stylesheet', and should almost always
stay that way. For designating alternative stylesheets.

title -- the title for alternate stylesheets

rendering -- How to link the stylesheet from the html page:

- 'import' - the default. normal css import

- 'link' - works better for old browsers and is needed for alternate
stylesheets

- 'inline' - render the stylesheet inline instead of linking it
externally.
Shouldn't be used at all!
It isn't possible to create sites which validate if you do.
For more information see:
http://developer.mozilla.org/en/docs/Properly_Using_CSS_and_JavaScript_in_XHTML_Documents

compression -- Whether and how much the resource should be compressed:

- 'none' - the original content will not be changed

- 'safe' - the content will be compressed in a way which should be safe
for any workarounds for browser bugs. Conditional code for
Internet Explorer is preserved since ResourceRegistries
1.2.3 and 1.3.1.

- 'full' - the content will be compressed with some additional rules.
For css all comments and most newlines are removed, this may
break special browser hacks, so use with care.
For javascript this encodes variables with special prefixes
according to the rules described here (Special Characters):
http://dean.edwards.name/packer/usage/
The source code needs to be written according to those rules,
otherwise it's more than likely that it will break.

- 'safe-encode' - only available for javascript
- 'full-encode' - only available for javascript
Additionally encodes keywords. This heavily compresses the
javascript, but it needs to be decoded on the fly in the
browser on each load. Depending on the size of the scripts
this could lead to timeouts in Firefox.
Use with special care!

If several stylesheets listed directly after each other in the registry have
the same parameters and expression, they will be concatenated into a larger,
composite, stylesheet on rendering. - This can be useful for splitting
stylesheets into smaller components for overrideing, while preserving
cacheability and minimising the number of http-requests to Plone.

This tool was started at the excellent SnowSprint 2005 - Organised by
Telesis in the Austrian Alps. Thanks, Jodok! :)

Credits

* Florian Schulze -- Independent

* Laurence Rowe -- Independent

* Geir Baekholt -- "Jarn":http://www.jarn.com (Previously Plone Solutions)

* Matt Hamilton -- "Netsight Internet Solutions":http://www.netsight.co.uk

Jarn, formerly Plone Solutions AS

* "http://www.jarn.com":http://www.jarn.com

* "[e-mail]":mailto:[e-mail]

Netsight Internet Solutions

* "http://www.netsight.co.uk":http://www.netsight.co.uk/

* "[e-mail]":mailto:[e-mail]

Changelog
=========

1.5.0 - 2008-03-01
==================

* Removed the uppermost Save button from the ZMI pages for registries.
Clicking this button before the registry page has finished loading could
lead to data loss.
[dunlapm, fschulze]

* Resources beginning with "http://" or "https://" are now valid and may be
included as resources. Registries will automatically disable merging,
caching, compression, and inline rendering of external resources. This
closes http://dev.plone.org/plone/ticket/8312
[dunlapm, fschulze]

* Added option to have a conditional comment attached to a given resource.
Currently the UI only supports this behavior with the CSS and JavaScript
Registries, but the underpinnings for the KSS registry is in place.
This closes http://dev.plone.org/plone/ticket/5521
[dunlapm, fschulze]

* Do not try to export the `cooked_expression` into the GenericSetup
profiles. It is only an internal optimization and the value is reflected
in the `expression` value.
[hannosch]

* Store the cooked expressions as a real persistent expression object,
instead of compiling the expression on every view.
[hannosch]

* Added 'context' as an alias for 'object' in action expressions.
[davisagli, hannosch]

1.4.3
=====

* Fixed error where non-traversable resources could be registered. This closes
http://dev.plone.org/plone/ticket/8153
[dunlapm]

* Ensure that resources can be removed in xml.
[maurits]

* Purge old zope2 Interface interfaces for Zope 2.12 compatibility.
[elro]

* Encode inline resources using the site encoding.
Fixes http://dev.plone.org/plone/ticket/7522
[wichert]

* Fixed potential Acquisition problems in viewlets.
[hannosch]

1.4.2
=====

* Properly encode the resource id. This fixes moving of resource without JS
and removing recources which contain special chars like plus signs.
Fixes http://dev.plone.org/plone/ticket/7482
[fschulze]

* Revert part of r7143: returning NotFound from a API call is never
the right thing to do since it makes the publisher show a object-not-found
page, hiding the real error. Restore the old behaviour and raise a
ValueError instead. This fixes mysterious not-found errors from
GenericSetup imports.
[wichert]

* Support Z3 template resources (not just file and image resources).
[mj]

1.4.1
=====

* Added '/' to the strings that are filtered out in
BaseRegistry.generateId(). This fixes #7048.
[davconvent]

1.4.0
=====

* Add support for automatic grouping mode to the GenericSetup export/import
code.
[wichert]

1.4.0-rc1
=========

* Added a new automatic grouping mode feature. It is turned off by default.
When enabled the resources will first be sorted into groups with the same
merging-relevant settings and after that merged. In the groups the order of
the resources in the registries will be preserved.
[hannosch]

* Changed the exportimport handlers to only cook the resources once at the end
and not after each new resource has been added.
[hannosch]

1.4.0-beta5
===========

* Fixed setting of cache headers when the registry is associated with a
RAMCache.
[fschulze]

1.4.0-beta4
===========

* Switched back to getToolByName.
[wichert]

* Added portal_kss as registry for kss files.
[fschulze]

* Slightly optimized the viewlet manager templates.
[hannosch]

1.4.0-beta3
===========

* Replace usage of getToolByNames with getUtility.
[wichert, hannosch]

1.4.0-beta2
===========

* Reverted fix of tests, because Zope was wrong.
[fschulze]

1.4.0-beta1
===========

* Fixed test failures caused by changes in Zope 2.10.
[fschulze]

* Ported bugfixes from 1.3 line.
[fschulze]

1.4.0-alpha2
============

* Started to use views and viewlet managers.
[fschulze]

* Removed compatibility stuff for Plone version lower than 3.0.
[fschulze]

1.3.8
=====

* Cook resources after GS profile import.
[fschulze]

* Added missing enabled property handling to updateScript.
[fschulze]

* Fixed typo which prevented position-after/insert-after in GS profiles to
work.
[fschulze]

1.3.7
=====

* For compatibility with GenericSetup conventions, the import steps now
support 'insert-before' and 'insert-after' as aliases for
'position-before' and 'position-after', while 'insert-top' and
'insert-bottom' are aliases for 'position-top' and 'position-bottom',
respectively.
[mj]

1.3.6
=====

* Invalidate cache when cooking resources if the registry is assigned to a
RAMCache or similar cache manager.

* Fixed string replacement during packing when several resources got packed
in different threads at once, which resulted in exchanged strings.
[fschulze]

1.3.5
=====

* Fixed string protection for strings which mix single and double quotes.
[fschulze]

* Made packer.py usable as a standalone commandline tool.
[fschulze]

* Fixed several issues in 'full' compression.
[fschulze]

* Extended the GenericSetup import step to support positioning of resources:
the 'position-before' and 'position-after' attributes cause the resource
to be positioned before or after resource named in the attribute.
'position-top' and 'position-bottom' move a resource to the top or bottom.
[mj]

1.3.4
=====

* Improved IE conditional compilation protection, it now works in "full"
compression.
[fschulze]

* Improved regular expression for strings.
[fschulze]

* Fixed order of oneline and multiline comment removal in javascript packer.
[fschulze]

* Fixed validation warning about multiple comments when rendering resources
inline.
[fschulze]

* Made css "full" packing more aggressive.
[fschulze]

* Cleaned up testing framework and made all tests run properly.
[fschulze, hannosch]

1.3.3
=====

* Don't wrap None in aquisition wrapper if resource is not found.
[tesdal]

1.3.2
=====

* Made GenericSetup importer not fail on repeated imports.
[alecm]

* Made enabled checkbox work again.
[fschulze]

1.3.1
=====

* Enable use of z3 / Five resources.
[ree]

* Mark missing or unaccessible ressources in management screens.
[fschulze]

* Moved 'enabled' checkbox into legend before 'id' textbox.
[fschulze]

* Don't remove conditional compile instructions for IE from javascripts.
[fschulze]

* Fixed error when content is unicode.
[rocky]

1.3
===

* No changes since rc1.

1.3-rc1
=======

* Add patch from jenner to handle updating and removal of resources
from GenericSetup profiles.
[wichert]

1.3-beta2
=========

* Included fixes from the 1.2 line.
[fschulze]

1.3-beta1
=========

* Do not install default CSS and JS on upgrade, only on initial installation.
[wichert]

1.3-alpha1
==========

* Added GenericSetup import/export handlers (to support GS-based Plone 2.5
portal creation)
[rafrombrc]

1.2.4
=====

* Made enabled checkbox work again.
[fschulze]

1.2.3
=====

* Backported several fixes from 1.3.1:
[fschulze]

- Enable use of z3 / Five resources.
[ree]

- Mark missing or unaccessible ressources in management screens.
[fschulze]

- Moved 'enabled' checkbox into legend before 'id' textbox.
[fschulze]

- Don't remove conditional compile instructions for IE from javascripts.
[fschulze]

- Fixed error when content is unicode.
[rocky]

1.2.2
=====

* Added missing arguments in resource adding functions.
[jenner, fschulze]

1.2.1
=====

* Fixed traversal of security restricted resources.
[jenner, alecm, fschulze]

* Added javascript "full" compression, which achieves higher compression ratios
by doing variable name packing based on the rules from Dean Edwards packer:
http://dean.edwards.name/packer/usage/
[fschulze]

* Added keyword encoding for javascript. This greatly reduces the file size of
javascript files, but adds a small performance hit on the client for the
decoding.
[fschulze]

1.2
===

* Added compression for CSS and Javascript resources.
[fschulze]

* Added better labels and a short explanation to the debugmode-checkbox in the forms.
[elvix]

* Renamed 'TAL condition' to 'Condition' in the forms, as it has nothing to do with
TAL at all (it is a CMF/TALES expression) It should include a link to CMF Expressions help
[elvix]

1.1
===

* Fixed cooking of resources to ensure that uncookable resources are not merged.
[elro]

* Fixed tests for unauthorized to accept a 401 as an unauthorized error.
[elro]

* Fixed setDebugMode to recook resources after being changed.
[elro]

1.1b1
=====

* Added checkbox to configure cacheability of resources.
[fschulze]

* Made registries cacheable. This is most useful with the RAMCacheManager.
Just associate portal_css and portal_javascripts with the RAMCache.
[fschulze]

* Apply magic id to all resources when not in debug mode, so invalidation
works.
[fschulze]

* Made skin aware. This now depends on getCurrentSkinName added in CMF 1.5.5.
[elro]

1.0.5
=====

* Fixed encoding of javascripts.
[fschulze]

1.0.4
=====

* Fixed reordering of resources with javascript.
[fschulze]

1.0.3
=====

* Fixed typo in the migration external method which lead to portal_javascripts
not being migrated.
[fschulze]

* Small fixes to UI.
[limi]

1.0.2
=====

* Fix for bug #4392, where merging FSfiles could mess up http-status headers
and cause weird hanging in browsers.
[plonista][fschulze][elvix]

1.0.1
=====

* Don't filter resources in merged overview in ZMI.
[fschulze]

* Improved management UI.
[limi, fschulze]

* Fixed reinstall bug due to improper resource id lookup.
[alecm]

1.0
===

* Moved directory with skin layer for Plone 2.0.5 compatibility to product
root, so it doesn't interfere with Plone 2.1. The version check on install
time didn't seem to be enough.
[fschulze]

* getTitle and getMedia will return None now if they are empty, this removes
empty title and media attributes from the generated HTML.

* Fixed reordering of resources in ZMI when javascript is enabled.
[fschulze, jenner]

* Fixed submitting changes in ZMI for stylesheets on IE.
[fschulze]

0.95
====

* Added getResource function. This allows to change properties of each
resource. After that, a call to cookResources is needed.
[fschulze]

* Added getResourceIds function.
[fschulze]

* Added test for context dependancy to inline css rendering.
[dom]

* Now uses restrictedTraverse() rather than getattr() for returning resources,
to provide support for resources held within the ZODB.
[dom]

* Added a "is merging allowed?" option ("cookable" property) to determine where
a resource can be merged (default True). This was added because objects in
the ZODB may have variable permissions but be merged together. Whilst the
objects are checked at each REQUEST, a new REQUEST won't actually be made
each time because of the cache headers set on merged resources. If this
worries you, the simplest solution is not to merge such resources, hence this
option.
[dom]

* Added renameResource function with tests.
[fschulze]

* In Plone 2.1 plone_javascripts.js was removed, fixed tests by using
jstest.js from our own skin.
[dom]

0.9
===

* Fixed function of enabled checkbox when adding css/javascript from ZMI.
Added title field to the 'add stylesheet' part in the ZMI.
[fschulze]

* Added migration script for old instances. Just create a external method with
id 'migrate_resourceregistries', Module Name 'ResourceRegistries.migrate' and
Function Name 'migrate' and click on the 'Test' tab.
[fschulze]

* Cleaned up imports and whitespaces. Code standardization and small
improvements. Fixed ZMI templates XHTML markup.
[deo]

* Refactored the two registries to use one common base class.
[fschulze]

* Refactored moving functions, so we have more possibilities. The API reflects
the IOrderedContainer one.
[fschulze]

* Fix order of javascripts, the topmost in the management screen also needs
to be the topmost in the resulting source.
[fschulze]

* Added debugmode where scripts are not concatenated. This will let things
like the javascript console point to the right line-number. And makes it
easier to develop, because there is no caching of the scripts.
[fschulze]

* Fixed cooking of stylesheets so that composite stylesheets get correct
media settings. Thanks a lot to Denis Mishunoff[spliter] for discovery,
investigation and suggested fix
[elvix]

* Fixed some security declarations.
[fschulze]

* Made moving of stylesheets and javascripts in ZMI possible without javascript
being enabled in the browser.
[fschulze]

* Moved 2.0.5 header.pt to skins/ResourceRegistries_20compatibility and
remove ResourceRegistries_20compatibility when Plone != 2.0.x
[fschulze]

* Check existance of stylesheets and javascripts before registering. This
fixes reinstallation.
[fschulze]

* Removed duplicate getScripts function definition in tools/JSRegistry.py
[fschulze]

* Fixed JSRegistry for Plone < 2.1 where plone_utils.getSiteEncoding is not
available.
[fschulze]

* Renamed config.TOOLNAME to config.CSSTOOLNAME
and config.TOOLTYPE to config.CSSTOOLTYPE
[batlogg]

* Added tests for attributes on stylesheets. About time.
[elvix]

* Added title for alternate stylesheets.
[fschulze]

* Removing superflous skins directories.
[elvix]

* Added new debugmode where stylesheets are not concatenated. This will let
things like the DOM inspector in Mozilla point to the right line-number.
[ldr] [elvix]

* Added bugfix for handling disabled items when cooking stylesheets.
[fschulze]


0.8
===

* Renamed to ResourceRegistries instead of the historical and wrong
CSSRegistry.
[elvix]

* Upgraded JSRegistry to have a more proper ZMI form, now with reordering
support.
[elvix]

* Changed the order elements are added to the JSRegistry.
[elvix]

* Added license/copyright notice to composite files (neccesary for including
for third party stuff).
[elvix]

* Bugfix fixing ZMI form for CSSRegistry.
[fschulze]


0.7
===

* Added to Plone 2.1 migrations, added installation of the default
Plone javascripts and stylesheets.
[elvix]

* Make sure we intercept all requests for objects, even those already
present in the acquisition chain. Override __bobo_traverse__.
[elvix]

* Handle cache settings in http headers for served files.
[elvix]

* Handle http headers for inline scripts and stylesheets.
[elvix]

* Use explicit </script> tag since these pages are being served as
text/html. Both IE and firefox will have problems otherwise.
[bmh]


0.6 and earlier
===============

* Added a simple readme with basic documentation.
[elvix]

* Started HISTORY.txt (somewhat late perhaps, but better than never).
[elvix]

* Cleaned up forms. Better alignment.
[elvix]

* Separate JSRegistry and CSSRegistry to two tools.
[elvix]

* Lots of changes, numerous fixes.
[elvix]


Snowsprint 2005
===============

* Designed and built first version of the CSSregistry.
[HammerToe] [elvix]