lunes, 5 de agosto de 2013

Including Plone Mockup in your own project

Introduction

Plone Mockup is going to be the future in Javascript development in Plone from version 5.0 and up. If you still don't know what is this all about, here are a couple of links to get you started:

This blogpost, however, is not about an introduction to patterns, mockup, and all that, and assumes you already know the basics.

From July 23rd to the 26th, in the city of Rosario, Argentina, the second edition of the Cafecito Sprint was held, and although working on Mockup is not listed among the primary goals, it was one. And so, I worked on finding an easy way to let people include and develop patterns for their projects.

Let's get started

UPDATE 2013/10/10: There's a follow-up with some stuff that was changed since this write up, please go here and read about them if something here no longer works.

There are 2 major code "locations" to pay attention in Mockup:
The "Patterns" location is where all the different patterns are developed. 
(For the ones getting started with patterns, mockup, etc, as a quick tip, I would suggest to take a look into the "accesibility.js" or the "tablesorter.js" ones, to get started with really easy ones, and then go ahead and check a more complex one, such as "modal.js".)

The "Bundles" location is where bundles are (shocking!). Basically this will be the place to list the patterns you wish to include with your project, and where you will include code you want to get executed prior to the registry scanning the DOM. (Take your time to check how plone.app.widgets work to get a better understanding of all this...)

After compiling this code, you get the Javascript file you need to include in your project. This should be the only Javascript you need to include, as it contains everything.

Now, what happens if you want to use some patterns, not all of them, and/or you want to keep using your old Plone Javascript (without replacing it with patterns, as plone.app.widgets does.)?

Say hello to generator-plonemockup (This package is most probably going to be merged into Mockup itself in the future)

This new product, is the result of my research and work in the Cafecito Sprint, and is a generator intended to be used with Yeoman, which is a tool used by Javascript developers to generate new projects, get their dependencies, and build/compile the final product. If you don't know this set of tools, I suggest you read its docs and play around with it for a bit.

Enough introduction, let's get our hands dirty

Assuming you have Yeoman tools already installed (globally), all you need to do is the following:
  1. Install plonemockup generator using npm

    $ npm install -g generator-plonemockup

    If you didn't have any network, or "global npm" related issues, you should end up with the generator installed.
    Note: I had problems with "bower" 1.0.0, so I had to downgrade to version 0.10.0
  2. Create your project

    $ yo plonemockup

    Note: Bear in mind that "yo" assumes your project's directory is the current directory, so all files and folders will be generated in the current path, instead of a new folder with the project name.

    You will be presented with some questions, that if you answer them correctly, you shouldn't need to manually rename, move, etc any files or configuration options.
    I recommend you generate some test projects just to see what each option will result in the generated project.
  3. Make sure that when the process ends, you didn't get any errors, and that you do, in fact, have a folder in the current directory named "bower_components". If you don't, then you may need to downgrade "bower", and re-run "bower install" to get dependencies.
  4. (optional) Install additional dependencies your pattern may need.
If you reached this far, you should now have a bunch of files in your current directory, and you are ready to start coding your own pattern, bundle, or both.
Take a look at config.js, as here are listed the paths for getting each component when compiling the final Javascript that you will use in your project.

Let's go ahead and open "js/bundles/widgets.js" "js/bundles/bundle.js" file. And let's say, all you want is the "tablesorter" pattern in your project and nothing else. Where it says "<!~~ Add patterns below this line ~~!>", you should see the pattern that the generator created, listed below, named "[project_name]-patterns-[pattern_name]", so this name will depend on the names you used when answering the questions up there.
Since we are not developing a new pattern, then just replace this with "mockup-patterns-tablesorter", which is the name for the tablesorter pattern (check config.js file).

Save the file, and go to the project directory and run "grunt". You should see the directory paths for the dependencies, and an ending message saying: "Done, without errors.".
If this is the case, then you should get a "build/widgets.min.js" (which, at the moment of this writing, is not automatically minified, as the filename suggests) "build/bundle.js" and a minified version "build/bundle.min.js".

In order to test that everything worked fine, you can create a test html including this generated Javascript (along with the jquery you intend to use, since that is the only dependency not included with the result Javascript), and a table:

Check this example, which includes the compiled Javascript, the jquery and a table as defined in the tablesorter example

Of course, this bundle *only* includes this pattern, but you get the idea... you should list all the patterns you wish to use, and if you plan to develop your own, then do not remove the line we removed initially, and go to the js file that was created inside "js/patterns" to do the development.

If you want to develop additional patterns, then all you need to do is copy the same "skeleton" of this js file with a new name, and make sure you update the config.js accordingly.

If you want to include everything the Plone Mockup brings, and code "on top" of it, all you need to do is remove the comment from "mockup-bundles-widgets". This will cause everything (including the bundle) from Mockup to be included.

Finally, as plone.app.widgets does, everything you put into "transform", will be executed before having the registry to scan the DOM, so you can make any changes you need here.

What remains to be done

At this moment, the generator is at version 0.0.2, and what I would like to have in future versions:
  • Tests for the generator
  • Generate proper test skeleton with the resulting project (after running the generator) (Done as of version 0.0.4, read here)
  • Have a subgenerator to genereate patterns (provided we can get the project name when running the subgenerator)

So, start using it, report bugs, enhancements, and (preferably :P) pull requests.