- Plone Mockup, from the mastermind behind it.
- Official docs
- List of existing patterns
- plone.app.widgets, the project that brings mockup to Plone 4.x
- My talk for PloneConf 2013
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...)
Say hello to generator-plonemockup (This package is most probably going to be merged into Mockup itself in the future)
Enough introduction, let's get our hands dirty
Assuming you have Yeoman tools already installed (globally), all you need to do is the following:
- 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
- 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.
- 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.
- (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.
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".
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.