Exercise 5: Simple Pattern

Warning

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

In this exercise, we’ll be walking through creating a simple Plone pattern.

We 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.

This example will stay very simple we’ll use jQuery to do a simply 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, utilize the various resources available.

In our example, we’re 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’d like for your pattern

.pat-exercise5 {
  color: red;
}

Creating Your Bundle

To register the pattern, we’ll 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 our previously.

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

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

The only thing we’re doing in this file is including the exercise5 module we defined earlier–that’s it.

Bundles can do more as well. Then can include initialization code for example.

See Plone’s default bundle.

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’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="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’s 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 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 5 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 exercise5 bundle
  4. Click Save

This should load your JavaScript and LESS files now; however, we don’t have any elements with the pat-exercise5 class assigned to them.

It’s 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 diazo rule to dynamically add the class to an element

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

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