Exercise 5: Simple Pattern#

Warning

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

In this exercise we will be walking through creating a simple Plone pattern.

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

Add Your Pattern File#

First off, in your exercise5/static directory, add a file named pattern.js. Use this file to build your pattern.

Use jQuery to modify the content of an element:

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

  var Pattern = Base.extend({
    name: 'exercise5',
    trigger: '.pat-exercise5',
    parser: 'mockup',
    defaults: {
    },
    init: function() {
      var that = this;
      that.$el.append(' <span>Exercise 5 was here</span>');
    }
  });

  return Pattern;
});

For more details on how to write a mockup pattern, check the various resources available:

In our example, we are using the RequireJS define function to define our pattern as a JavaScript module.

Integrating With LESS#

Add a pattern.less file to the exercise5/static directory and provide whatever styles you like for your pattern.

.pat-exercise5 {
  color: red;
}

Creating Your Bundle#

To register the pattern, we will create a bundle. Recall the difference between using require and define from the RequireJS docs.

Our bundle will use the require function to include the JavaScript module pattern we created previously.

Create a bundle.js file in your exercise5/static directory

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

The only thing we are doing in this file is including the exercise5 module we defined earlier—that's it.

Bundles can do more as well. They can include initialization code for example. See Plone 5's default bundle, plone-base.js.

Note

The foregoing link targets the 1.x branch in the repository plone/plone.staticresources used by Plone 5.

Bundles more or less tell the compiler what we care about loading. They do the dependency resolution and include the modules that were required with them.

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="exercise5"
    />

Register Your Bundle#

Registering your bundle is done by adding Generic Setup xml configuration to the Plone registry. This is done in the registry.xml file in the profiles/default directory.

Resource#

Resource is done exactly the same as in Exercise 1

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

Bundle Resource#

The bundle resource is another resource registration like any other. Remember, the 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-exercise5"
         interface='Products.CMFPlone.interfaces.IResourceRegistry'>
  <value key="js">++plone++exercise5/bundle.js</value>
  <value key="css">
    <element>++plone++exercise5/pattern.less</element>
  </value>
</records>

Bundle#

Finally, let us create our bundle registration

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

  <!-- so we do not 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 5 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 exercise5 bundle

  4. Click Save

This should load your JavaScript and LESS files now. However, we do not have any elements with the pat-exercise5 class assigned to them.

It is up to you how to apply the pattern class to an element of your choice. A couple options available to you are:

  1. use TinyMCE source view and add class="pat-exercise5" onto any p tag

  2. customize the theme on your site and add it to an element in your theme file or use a diazo rule to dynamically add the class to an element.

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=exercise5

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