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’ll 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).

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

Add your JavaScript files

In this example, we’re going to create a rather contrive example to demonstrate the bundling process. Add a static folder, 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’s register the static directory we just placed our script into. To register, 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"
     />

Registry 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

<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’s 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’re running with so our code doesn’t do anything.

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’ll utilize the plone-compile-resources script that Plone ships with.

Warning

If you’re not running a ZEO setup, you’ll 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 package.