collective.amberjack on-line tutorials with

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

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

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

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

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

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

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

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

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

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

the blueprint

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

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

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

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

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

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

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

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

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

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

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

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

collective.amberjack.core - tour

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,
)}

collective.amberjack.core - step

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': ({...})

collective.amberjack.core - microsteps

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...")},)}

collective.amberjack.core - ajStep

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

collective.amberjack.core - ZCML registration

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

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

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

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

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

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

Create a folder and a page

Create a folder and a page

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

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

Let’s see some, still in progress, code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Grazie. Thank you.