The document introduces collective.amberjack, a tool designed to improve user interaction with Plone through interactive tutorials, featuring step-by-step guidance and unobtrusive JavaScript. It outlines the framework for tutorial creation, including validation processes and user-specific conditions, while emphasizing ease of use for editors and programmers. The project is actively supported by a team from Redturtle, with plans for future updates and enhancements.

1. collective.amberjack
chapter one: the interactive age.
Massimo Azzolini
RedTurtle

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>

8. http://www.flickr.com/photos/eklektikos/2541408630/sizes/l/
we want more:
the blueprint
tours, steps, editors, users

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

10. Demo: collective.amberjack at a glance

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

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

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

16. The registration
✓ZCML registration
✓file upload
✓url reference

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

25. python - a microstep
'steps': (
{'description':
_(u"In the [Title] field, type.."),
'idStep': u'form_title',
'selector': u'',
'text': u'MyFolder'},
…
,)}

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

27. python - ajStep (from aj-ids to html)
ajStandardSteps = (
...
('form_title',
'#archetypes-fieldname-title input'),
('form_description',
'#archetypes-fieldname-description textarea'),
...
)

28. cfg - ajStep (no more needed)
ajStandardSteps = (
...
('form_title',
'#archetypes-fieldname-title input'),
('form_description',
'#archetypes-fieldname-description textarea'),
...
)

29. python - ZCML registration
<collective.amberjack:tour
tourdescriptor=".tour1.ajTour"
/>
<collective.amberjack:ajstep
stepsdescriptor=
".ajStandardSteps.ajStandardSteps"
/>

30. cfg - ZCML registration
<collective.amberjack:tour
tourlocation="tours.zip"
/>
<collective.amberjack:ajstep
stepsdescriptor=
".ajStandardSteps.ajStandardSteps"
/>

31. 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”
✓ ...

32. Sandbox: member folders. Step 1.

33. ehm, I said “member folders”

34. Sandbox: member folders. Step 2.

35. Sandbox: member folders. Step 3.

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

37. Create a folder and a page - TTTW

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

42. playing with.. ploneformgen.demo.plone.org

43. http://www.flickr.com/photos/anirudhkoul/3786725982
we have a team the team, now

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

46. we have a plan and it’s public

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

48. 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/

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

50. Grazie. Thank you.

51. http://www.flickr.com/photos/seandreilinger/2326448445
Questions!?
Massimo Azzolini
massimo@redturtle.net