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/
2. who am I?
Massimo Azzolini
RedTurtle’s co-founder and project manager
massimo@redturtle.net
3. link foto
the idea
✓ provide tours for plone’s
newbies
✓ show portal’s features
✓ tutor your audience
4. that’s not all folks!
✓ every product/add-on
might have its
amberjack tutorial
✓ just-hired people in
companies needs
tutorials
✓ wizards
5. 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
6. 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.
7. 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>
9. 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
11. 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.
12. 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
13. 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
15. 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
17. preconditions:
could I run this tutorial?
✓ isAnonymous
✓ isAuthenticated
✓ hasRole
✓ isCreated
✓ isNotCreated
✓ [add your precondition here]
18. validations:
did I finish?
✓ check the microstep
condition = checkstep
✓ custom condition
condition = {
"selector":
{"description":"id"},
"operator":"co",
"value":"Plone"
}
✓ can I go next?
condition = doitmanually
19. 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
20. 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 i18n
I don’t wanna re-invent the wheel
21. 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,
)}
22. 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')
23. 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': ({...})
24. 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
36. 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
38. What’s windmill?
• “Windmill is a web testing tool designed to let you painlessly
automate and debug your web application.”
39. 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
40. TTTW: wishes and dreams
✓make it easier:
if the html doesn’t speak enough it can be painful
✓create a tutorial directly from plone
start windmill from the plone site
✓save it on a local, but also on shared repository
so that it can be easily shared with someone else
✓import/export as a package
41. stop videos, start
interactive tutorials
use collective.amberjack.windmill
create a website
publish your tutorials
http://www.flickr.com/photos/orphanjones/414401592
44. 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)
45. 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
47. 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