Embed Size (px)
DESCRIPTION
collective.amberjack is a plone based tool to create interactive tutorial. These are the slides presented during this talk: http://ploneconference2010.blip.tv/file/4317469/
Citation preview
collective.amberjackchapter one: the interactive age.
Massimo Azzolini
RedTurtle
link foto
the idea
✓ provide tours for plone’s newbies
✓ show portal’s features
✓ tutor your audience
that’s not all folks!
✓ every product/add-on might have its amberjack tutorial
✓ just-hired people in companies needs tutorials
✓ wizards
amber-what?!?
✓ it provides an unobtrusive
javascript infrastructure for online tours
✓ your audience can
navigate the site and get additional info
✓ developed by Arash Yalpani
amberjack.org
basically it provides
✓ a fancy popup “div” with prev/next/exit buttons, fully html enabled for your steps.
✓ a mapping between a step and each url you can visit.
chunks of HTML
<div title="http://amberjack.org/skins/customize/?travel=2">
<strong>Include a video for example:</strong>
<object width="330" height="272"><param name="movie" value="http://www.youtube.com/v/C-3wuYyXGN8" /><param name="wmode" value="transparent" /><embed src="http://www.youtube.com/v/C-3wuYyXGN8" type="application/x-shockwave-flash" wmode="transparent" width="330" height="272"></embed></object>
<form>
What is your favorite cocktail?
<select><option value="">Select</option>
...</select>
</form>
</div>
http://www.flickr.com/photos/eklektikos/2541408630/sizes/l/
we want more:the blueprint
tours, steps, editors, users
the blueprint
✓we want interactive tutorials, not just tours
✓we need a UI to show them
✓we need people that write them
✓we want to deliver and to share them
Demo: collective.amberjack at a glance
So, interaction!
✓let the user interact with the plone interface
✓let the tool guide the user
✓let the tool replace the user’s actions
✓there are many features to cover in plone:
• we have “helpers” for plone’s features
• we didn’t cover them all… yet.
the core package: collective.amberjack.core
✓wraps the amberjack javascript library
✓gives it the interactive flavour
✓registers the tutorials
✓manages validations
✓tutorial preconditions
✓microstep validations
Javascript Libraries
✓amberjack.js - the basic library, revised and improved
✓amberjackPlone.js - the engine for the interaction
✓stepAdapters.js - the behaviour associated with any helper:helper: { highlight: function() {...}, step: function() {...}},
✓windmillUtils.js - utilities shared with the windmill tool
http://www.flickr.com/photos/dhowellphoto/3023319312
Do not touch Plone
✓ collective.amberjack does not change anything in Plone itself
✓ we used unobtrusive javascript code and tours described through HTML
How a tutorial is made
✓ A tutorial is made of steps
• a step an url
• e.g. “insert an external link”
✓ every step is made by several microsteps
• e.g. “type the following text…”
• or “click the link icon…”
✓ two types of microsteps• with helper “>>”
• just description
The registration
✓ZCML registration
✓file upload
✓url reference
preconditions:could I run this tutorial?
✓ isAnonymous
✓ isAuthenticated
✓ hasRole
✓ isCreated
✓ isNotCreated
✓ [add your precondition here]
validations: did I finish?
✓ check the microstepcondition = checkstep
✓ custom conditioncondition = {
"selector":
{"description":"id"},
"operator":"co", "value":"Plone"
}
✓ can I go next?condition = doitmanually
collective.amberjack.portlet
✓provides a portlet that draws a set of tours in a given order
✓you may choose:
• the title
• the list of tours and order them
• popup skin type
✓it enables/disables the tours in accordion to the validators
• e.g.: first create a folder then a page
The Tutorials: collective.amberjack.plonetour
• the python approach, not so good:
• too complicated for middle experienced user
• so custom
• not reusable
• extremely integrated with i18n
• the .cfg approach #success:
• easier to read
• easier to write
• easier to be generated
• easier to distribute
• problems with i18nI don’t wanna re-invent the wheel
python - tour definition
ajTour = {
'tourId':u'basic01_add_and_publish_a_folder',
'title': _(u'Add and publish a Folder'),
'steps': (add_folder,
fill_out_the_fields,
publish_folder,
all_done,
)}
cfg - tour definition
[amberjack]
steps =
0_create-a-new-folder
1_fill-out-the-fields
2_publish-the-folder
3_all-done
title = Add and publish a folder
validators =
python: isNotCreated(context,'/myfolder')
python: hasRole(context,request, 'Reviewer')
python - the step
add_folder = {
'validators': (isManager, isNotFolderCreated,),
'url': u'/',
'xpath': u'',
'xcontent': u'',
'title': _(u"Create a new folder"),
'text': _(u"Folders are one..."),
'steps': ({...})
cfg - the step
[0_create-a-new-folder]
blueprint = collective.amberjack.blueprints.step
text = the folders are..
title = Create a new folder
url = /
microsteps =
0_0_microstep
0_1_microstep
0_2_microstep
0_3_microstep
python - a microstep
'steps': ( {'description':
_(u"In the [Title] field, type.."),
'idStep': u'form_title',
'selector': u'',
'text': u'MyFolder'},
…
,)}
cfg - a microstep
[0_1_microstep]
blueprint = collective.amberjack.blueprints.windmillmicrostep
selector = {"//dl[@id='plone-contentmenu-factories']/dt/a/span[1]" : 'xpath'}
method = click
description = Click the [Add new...] drop-down menu.
python - ajStep (from aj-ids to html)
ajStandardSteps = (
...
('form_title',
'#archetypes-fieldname-title input'),
('form_description',
'#archetypes-fieldname-description textarea'),
...
)
cfg - ajStep (no more needed)
ajStandardSteps = (
...
('form_title',
'#archetypes-fieldname-title input'),
('form_description',
'#archetypes-fieldname-description textarea'),
...
)
python - ZCML registration
<collective.amberjack:tour
tourdescriptor=".tour1.ajTour"
/>
<collective.amberjack:ajstep
stepsdescriptor= ".ajStandardSteps.ajStandardSteps"
/>
cfg - ZCML registration
<collective.amberjack:tour
tourlocation="tours.zip"
/>
<collective.amberjack:ajstep
stepsdescriptor= ".ajStandardSteps.ajStandardSteps"
/>
http://www.flickr.com/photos/bhollar/425116404/
Sandbox
✓ portal as a sandbox✓ personal folders as
sandboxes✓ from sandbox to wizard✓ “save my data, I’ll be
back soon”✓ ...
Sandbox: member folders. Step 1.
ehm, I said “member folders”
Sandbox: member folders. Step 2.
Sandbox: member folders. Step 3.
TTTW - Tutorials Through The Web
✓ editors want to use the browser to create their tours
✓ what’s better than click and save?
✓ we enhanced Windmill
Create a folder and a page - TTTW
What’s windmill?
• “Windmill is a web testing tool designed to let you painlessly automate and debug your web application.”
the audience
✓editors, should have less difficulties in writing a tutorial
• “..and in your opinion, that CFG syntax should be easy?!?”
✓programmers, may use the collective.amberjack suite to
• create the online demo for the plone add-on
• get functional tests
TTTW: wishes and dreams
✓make it easier: if the html doesn’t speak enough it can be painful
✓create a tutorial directly from plonestart windmill from the plone site
✓save it on a local, but also on shared repositoryso that it can be easily shared with someone else
✓import/export as a package
stop videos, start interactive tutorials
use collective.amberjack.windmillcreate a websitepublish your tutorials
http://www.flickr.com/photos/orphanjones/414401592
playing with.. ploneformgen.demo.plone.org
http://www.flickr.com/photos/anirudhkoul/3786725982
we have a team the team, now
the contributors
• Mirco Angelini
• Andrea Benetti
• Federica D'Elia
• Luca Fabbri
• Andrew Mleczko
• Vincent Fretin
• Giacomo Spettoli
• Massimo Azzolini
• Aaron VanDerlip
• Michael Davis
• Irene Capatti
• Giorgio Borelli
• Jacopo Deyla
• Domen Kozar
• Leonardo J. Caballero (es)
• Vincent Fretin (fr)
• Stefano Marchetti (it)
• Andrew Mleczko (pl)
• Tamosauskas (pt-br)
RedTurtle is supporting the project
✓ stable team to enhance and mantain the tool
✓ more people
✓ you’re still welcome!
✓ amberjack company branded
✓ Activities won't be based on my spare time anymore
✓ They are going to be supported and scheduled in a more stable way.
✓ “10 percent manifesto”-ish
we have a plan and it’s public
next release 1.1
✓refactor the code
✓validations & preconditions
✓TTTW: implementation
✓sandbox
✓1.0: implementation
✓2.0: brainstorm
✓Check if the user completes the step
✓manage prev/next buttons
✓amberjack’s template for sunburst
✓translations: choose the right approach
✓test coverage
References
✓Project management:
• https://launchpad.net/collective.amberjack
• https://blueprints.launchpad.net/collective.amberjack
• https://bugs.launchpad.net/collective.amberjack
• https://launchpad.net/collective.amberjack.windmill
✓wiki & documentation
• http://www.coactivate.org/projects/collectiveamberjack/
References
✓mailing list:
• http://www.coactivate.org/projects/collectiveamberjack/lists/collectiveamberjack-discussion
• http://www.coactivate.org/projects/collectiveamberjack/lists/collective-amberjack-support/
✓code svn on collective:
• http://dev.plone.org/collective/browser/collective.amberjack.buildout
• http://dev.plone.org/collective/browser/collective.amberjack.core
• http://dev.plone.org/collective/browser/collective.amberjack.plonetour
• http://dev.plone.org/collective/browser/collective.amberjack.portlet
• http://dev.plone.org/collective/browser/collective.amberjack.windmill
Grazie. Thank you.
