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!)
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
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
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
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
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
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