Exercise 4: Gallery integration as resources

Warning

This exercise requires a working buildout using a fork of the collective.jstraining package.

In this exercise, we will include our custom JavaScript file into your Plone site as a bundled resource, instead of manually including it into your theme template (as in exercise 3).

You will be working in the exercise4 directory of the collective.jstraining package.

Add your JavaScript files

In this example, we are going to create a rather contrive example to demonstrate the bundling process. Add a static folder, then inside it create a file named resource.js:

define([
  'jquery',
  'pat-base',
], function($, Base) {
  'use strict';

  $('body').ready(function() {
    alert("Woohoo, it worked!");
  });
});

Additionally, create a file named bundle.js

require([
  'exercise4'
], function() {
  'use strict';
});

Register static resource directory

Next, let us register the static directory we just placed our script into. To register it, you need to add ZCML registration for the static directory your script is in. Add this to the exercise5/configure.zcml file:

<plone:static
    directory="static"
    type="plone"
    name="exercise4"
    />

Register your JS as a resource

In order to include our files, we need to registry them as static resources. In the registry.xml file, under profiles/default add the following:

<records prefix="plone.resources/exercise4"
         interface='Products.CMFPlone.interfaces.IResourceRegistry'>
  <value key="js">++plone++exercise4/resource.js</value>
</records>

Bundle resource

The bundle resource is just another resource registration like any other. Remember, the only difference here is in the content of the JavaScript file. One file uses require, the other uses define. Addditionally, we include our CSS/LESS dependencies here:

<records prefix="plone.resources/bundle-exercise4"
         interface='Products.CMFPlone.interfaces.IResourceRegistry'>
  <value key="js">++plone++exercise4/bundle.js</value>
</records>

Bundle

Finally, let us create our bundle registration

<records prefix="plone.bundles/exercise4"
         interface='Products.CMFPlone.interfaces.IBundleRegistry'>
  <value key="resources">
    <!-- reference to bundle resource definition -->
    <element>bundle-exercise4</element>
  </value>
  <value key="merge_with">default</value>
  <value key="enabled">True</value>
  <value key="jscompilation">++plone++exercise4/exercise4-compiled.min.js</value>
  <value key="last_compilation">2016-10-04 00:00:00</value>

  <!-- so we don't include these modules multiple times -->
  <value key="stub_js_modules">
    <element>jquery</element>
    <element>pat-base</element>
  </value>
</records>

Installation

1. Start up your Plone instance

2. Install the Exercise 4 add-on

Running

At this point, we have no compiled version of the code that we are running with so our code does nothing.

1. Go into Site Setup -> Resource Registries

2. Check "Development Mode"

3. Select to develop JavaScript and CSS for the exercise4 bundle

4. Click save

This should load your JavaScript and LESS files now. Reload the page, and you should be greated by our "exciting" new alert box.

Production

To build our bundle, we will utilize the plone-compile-resources script that ships with Plone.

Warning

If you are not running a ZEO setup, you will need to shut down your Plone instance since the ZODB in this mode does not allow multiple processes to access it at the same time.

An example command will look like this

./bin/plone-compile-resources --site-id=Plone --bundle=exercise4

Once this command finishes, your bundle is built and will be deployed with your package.