Amberjack is a tool that allows you to create tours directly in your site. The purpose of the collective.amberjack project is to improve its functionality and to provide a way for creating not just tours but something more: online interactive tutorials on a Plone site. (all slides has been "grafically refactored" by nekorin, thanks for that!)

1. collective.amberjack on-line tutorials with

2. the basic idea
✓ plone tours for new
comers
✓ born @ bolzano sprint
(nov ’08)
link foto

3. that’s all folks?
maybe not...
✓ every product/add-on
might have his
amberjack tutorial
✓ just-hired people in
companies needs
tutorials
✓ wizards
✓ simplified e-learning

4. the first goal
✓ PLIP #9324
✓ Use Amberjack to offer
guided help for first-time
users
✓ to be included in a next
4.x release

5. we are writing
these tours
✓ Add and publish a Folder
✓ Add and publish a Page
✓ Add and publish a News
Item
✓ Add and publish an Event
✓ Format a page using the
visual editor
✓ Create internal links
link foto

6. we are writing
these tours
✓ Create external links
✓ Upload an image
✓ Insert image on a page
✓ Upload and link to a File
✓ Using the Contents tab
✓ Using the Display menu
✓ Create a static text
portlet
link foto

7. a spotlight
http://www.flickr.com/photos/slopjop/1300515408

8. you just installed Plone... and you’re an happy guy

9. ..and you need to
learn it by yourself..
hum, selecting the tour from the
list? so easy?

10. ... and complete the
steps!
one at a time, please

11. http://www.flickr.com/photos/eklektikos/2541408630/sizes/l/
the blueprint tours, steps, steps, steps

12. the blueprint

13. the blueprint
✓ A tour has
• a name (and an Id)
• a set of steps

14. the blueprint
✓ A tour has
• a name (and an Id)
• a set of steps
✓ every step is made by
• a tuple (url, xpath, xcontent)
• a title
• a set of microsteps

15. the blueprint
✓ A tour has ✓ every microstep has
• a name (and an Id) • a description
• a set of steps • a id for an ajStep (choosen
from the available ones’ set)
• selector
✓ every step is made by
• text
• a tuple (url, xpath, xcontent)
• a title
• a set of microsteps

16. the blueprint
✓ A tour has ✓ every microstep has
• a name (and an Id) • a description
• a set of steps • a id for an ajStep (choosen
from the available ones’ set)
• selector
✓ every step is made by
• text
• a tuple (url, xpath, xcontent)
• a title
✓ajStep is related to the HTML
• a set of microsteps generated by Plone

17. Do not touch Plone
✓ collective.amberjack
do not changes anything
in Plone itself
✓ it’s just unobtrusive
javascript code and tours
descripted through HTML
http://www.flickr.com/photos/dhowellphoto/3023319312

18. the software components
amberjack library
collective.amberjack.core
collective.amberjack.portlet
collective.amberjack.plonetour
collective.amberjack.metatour

19. amberjack.org
✓ developed by Arash
Yalpani
✓ provides an unobtrusive
javascript infrastructure
for online tours
✓ not completely usable for
our purposes
link foto

20. 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.
amberjack.org

21. some use case not fully supported
✓ in Plone a path does not identify uniquely a html page:
• view a page (/plone/page-a/view)
• edit a page (/plone/page-a/edit)
• save a page (/plone/page-a/view)
✓ it’s not just about links, we also submit forms

22. the solutions
✓ make the mapping between steps and url less strong:
• now the steps has an order (1. 2. 3....)
✓ don’t just rely on urls to pass tour variables
• use cookies

23. collective.amberjack.core
✓ tour definition and ✓ amberjack skins
registration
• model_t
✓ step definition • safari
✓ amberjack integration and
✓ZCML configuration for extension
• tours
✓special use case
• ajStep configurations
• aj_xpath_exists
✓ validators definition
• aj_any_url

24. an example: add a folder
✓ the tour is made by the steps: ✓ filling a field is entering a string
inside a HTML field: it’s about JS
• add_folder, and HTML.
• fill_out_the_fields,
• publish_folder,
• all_done
✓ the “fill_out_the_fields” step has to:
• fill the “title” field with a value
• fill the “description” field with
another value
• save it

25. collective.amberjack.core - tour

26. collective.amberjack.core - tour
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,
)}

27. collective.amberjack.core - step

28. collective.amberjack.core - step
add_folder = {
'validators': (isManager, isNotFolderCreated,),
'url': u'/',
'xpath': u'',
'xcontent': u'',
'title': _(u"Create a new folder"),
'text': _(u"Folders are one..."),
'steps': ({...})

29. collective.amberjack.core - microsteps

30. collective.amberjack.core - microsteps
'steps': (
{'description':
_(u"In the [Title] field, type.."),
'idStep': u'form_title',
'selector': u'',
'text': u'MyFolder'},
{'description':
_(u"In the [Description] field, type .."),
'idStep': u'form_description',
'selector': u'',
'text': _("This folder will be used...")},)}

31. collective.amberjack.core - ajStep

32. collective.amberjack.core - ajStep
ajStandardSteps = (
...
('form_title',
'#archetypes-fieldname-title input'),
('form_description',
'#archetypes-fieldname-description textarea'),
...
)

33. collective.amberjack.core - ZCML registration

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

35. validators
✓ isAnonymous
✓ isAuthenticated
✓ isManager
✓ isReviewer
✓ isContributor
✓ isEditor
✓ isReader
http://www.flickr.com/photos/traveleden/3797157077

36. collective.amberjack.plonetour
✓ defines the 12 tours ✓translations
✓ provides tour specific validators • french
• isFolderCreated • italian
• isNotFolderCreated
✓ZCML registration

37. collective.amberjack.portlet
✓ a portlet for starting a single tour
• it just lets you provide the tourId and the skinId
✓ a portlet that lets you provide a set of tour in a given order, you
provide:
• portlet’s title
• tours’ list and order
• skinId

38. collective.amberjack.metatour
✓provides 2 archetypes:
• ajtour
• ajstep
• url, xpath, xcontent
• microsteps
✓ metatours and ZCML registered tours are identical

39. http://www.flickr.com/photos/vramak/3499502280
See in action

40. Create a folder and a page

41. Create a folder and a page

42. http://www.flickr.com/photos/orphanjones/414401592
write your own tour as simple as you need

43. what you need to
do
✓ create an empty package
via paster
✓ write your tour in
myTour.py
✓ add it to the available ones
through ZCML
✓ translate it
✓ (opt. add custom ajSteps)
http://www.flickr.com/photos/domhuk/197875701

44. Let’s see some, still in progress, code

45. http://www.flickr.com/photos/anirudhkoul/3786725982
who’s involved the team, actually now

46. who’s involved
✓ Nate Aune proposed the
idea to find a framework
to create tours and adapt
it to plone

47. who’s involved
✓ Nate Aune
✓ Vincent Fretin
completely refactored the
code, i18ned everything,
has been a guide to me

48. who’s involved
✓ Nate Aune
✓ Vincent Fretin
✓ Sam Knox wrote all the
tours

49. who’s involved
✓ Nate Aune
✓ Vincent Fretin
✓ Sam Knox
✓ Giacomo Spettoli during
his thesis worked on the
initial core

50. who’s involved
✓ Nate Aune
✓ Vincent Fretin
✓ Sam Knox
✓ Giacomo Spettoli
✓ Mirna Bagnolatti during
her thesis developed
tours from scratch,
translated them in italian

51. who’s involved
✓ Nate Aune
✓ Vincent Fretin
✓ Sam Knox
✓ Giacomo Spettoli
✓ Mirna Bagnolatti
✓ Andrew Mleczko tour
validations, tiny
refactoring, test test test

52. who’s involved
✓ Nate Aune
✓ Vincent Fretin
✓ Sam Knox
✓ Giacomo Spettoli
✓ Mirna Bagnolatti
✓ Andrew Mleczko
✓ Federica D’Elia test
coverage

53. who’s involved
✓ Nate Aune
✓ Vincent Fretin
✓ Sam Knox
✓ Giacomo Spettoli
✓ Mirna Bagnolatti
✓ Andrew Mleczko
✓ Federica D’Elia
✓ Me, spiritus movens of
the project

54. http://www.flickr.com/photos/tranchis/3173646667
Coding events when the project improves

55. Sprints
✓ Bolzano Sprint ’08
✓ Sorrento Sprint ’09
✓ a short summer sprint
’09
✓ Plone conference ’09
http://www.flickr.com/photos/johnthescone/2526186118

56. Thesis
smart students from the
University of Ferrara
http://www.flickr.com/photos/fabio48/317814195/

57. Everyday’s work
ok, ok, we’re not so tough
http://www.flickr.com/photos/nickallen/3631367614/

58. What’s next
✓ don’t you think we
already finished, right?!
http://www.flickr.com/photos/biscuitsmlp/2246503687

59. complete the work
✓Complete all the tours ✓Activate the prev/next buttons just
only they have a real meaning
✓Check the entered texts: the texts
entered in the fields should be the ✓Translate javascript messages
ones we expect and plone's interface parts referring
✓ Add an option to the Unified ✓Fix problem when submitting forms
Installer, something like "./ with contents inside the kupu
install.sh --with-tours" editor
• Add a run-profile option to
plone.recipe.unifiedinstaller to
run additional profiles when the
Plone Site is created

60. upgrade it - some ideas
✓ Check if the user completes the ✓setUp/tearDown.
step • provide a way to create an
• provide a way to check if the environment in which the user
user completes all the runs his tours.
microsteps • explore possible security
• provide a way to autocomplete issues.
all of them
✓Provide a way to create a tour using
✓ Clicking on next step button do paster.
all the microsteps of the current
step.
✓collective.amberjack as a
doctest-like environment?
✓Load the js stuff only if the tour is
running
✓...

61. I want you
we’ll sprint on Sat-Sun
http://ploneconf2009.org/
program/sprint/collective-
amberjack
http://www.flickr.com/photos/uhuru1701/2247554605

62. References
✓ Project’s website:
• http://www.coactivate.org/projects/collectiveamberjack/
✓mailing list:
• http://www.coactivate.org/projects/collectiveamberjack/lists/
collectiveamberjack-discussion
✓code:
• http://dev.plone.org/collective/browser/collective.amberjack.buildout

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

64. Grazie. Thank you.