(Javascript)¶
Description
How to add your own Javascript files to Plone and Plone add-on products
local
はじめに¶
Plone Javascripts are managed by resource registry portal_javascripts. You can find this in Zope Management interface, under your portal root folder.
portal_javascript will automatically
- compress JS files
- merge JS load requests
- determine which files are included on which HTML page
- support IE conditional comments
Creating Javascripts for Plone¶
The following ste
Put ZMI -> portal_javascripts to debug mode
Include new JS files
- Use ZCML configuration directive resourceFolder to include static media files in your add-on product
- Put in new Javascript via ZMI upload (you can use Page Template type) to portal_skins/custom folder
Register Javascript in portal_javascripts
- Do it through-the-web using portal_javascripts ZMI user interface ...or...
- Add profiles/default/jsregistry.xml file to describe Javascript files included with your add-on product
Executing Javascript code on page load¶
Plone includes JQuery library which has ready() event handler to run Javascript code when DOM tree loading is done (HTML is loaded, images and media files are not necesssarily loaded).
Create following snippet:
jq(document).ready(function() {
// TODO: Execute your page manipulating Javascript code here
});
Registering javascripts to portal_javascripts¶
Javascript files need to be registered in order to appear in Plone’s <html> <head> and in the Javascript merge compositions.
Javascripts are registered to portal_javascripts tool using profiles/default/jsregistry.xml GenericSetup profile file.
The following options are available
- id (required): URI from where the Javascript is loaded
- expression empty string or TAL condition which determintes whether the file is served to the user. The files with the same condition are grouped to the same compression bundle. For more information, see expressions documentation.
- cookable is merging of Javascript files allowed during the compression
- inline is script server as inline inside <script>...</script> tag
- enabled shortcut to disable some Javascripts
- compression none, safe or full. See full option list from portal_javascripts.
- insert-before and insert-after control the position of the Javascript file in relation to other served Javascript files
Full description in the source code.
Example profiles/default/jsregistry.xml in your add-on product
<?xml version="1.0"?>
<object name="portal_javascripts">
<javascript
id="++resource++plonetheme.yourproduct/cufon-yui.js"
cacheable="True" compression="safe" cookable="True"
enabled="True" expression="" inline="False" insert-after="toc.js"/>
</object>
Bundles¶
There are several compressed Javascript bundles cooked (compressed & merged) from Javascript definitions automatically.
- Anonymous users (no condition)
- Logged in users (condition: not: portal/portal_membership/isAnonymousUser)
- Visual editor (Kupu) related Javascripts (condition: python:portal.kupu_library_tool.isKupuEnabled(REQUEST=request))
To inspect bundles and whether Javascripts have been registered succesfully, go to portal_javascripts -> Merged composition tab in ZMI.
Javascript for anonymous¶
The following example includes Javascript file intended for anonymous site users. It is included after toc.js so that the file ends up to anonymous users compression bundle.
The Javascript file itself is in folder plonetheme/xxx/browser/scripts and it is mapped to ++resource++plonetheme.xxx.scripts namespace using <resourceDirectotory> ZCML directive.
If insert-after or insert-before is omitted, the script will end up as the last of the Javascript registry.
Example profiles/default/jsregistry.xml
<?xml version="1.0"?>
<object name="portal_javascripts">
<javascript
id="++resource++plonetheme.xxx.scripts/cufon-yui.js"
cacheable="True" compression="safe" cookable="True"
enabled="True" expression="" inline="False" insert-after="toc.js"/>
</object>
The following example registers an anonymous user Javascript file, but does no place it to the compression bundle, because it is very big and slows down the page loading. It is placed before dropdown.js which is the first script for logged in users.
<javascript
id="++resource++plonetheme.xxx.scripts/XXX_Script_400.font.js"
cacheable="True" compression="none" cookable="False"
enabled="True" expression="" inline="False" insert-before="dropdown.js"/>
