Costruire su Amberjack

Abbiamo concepito e realizzato Amberjack, un sistema efficace e intimamente legato a Plone per generare tutorial sul CMS e su qualsiasi prodotto Plone, per consentire, a chi sviluppa nuovi prodotti Plone, di offrire il massimo supporto a coloro che useranno tali prodotti, aumentandone il gradimento e consentendo a tutti di utilizzarli al meglio. Questo livello di supporto si riverbera in positivo sull'intera comunità e sull' immagine pubblica di Plone.

Tuttavia, generare un tutorial Amberjack, fino a ieri, era un'attività piuttosto lenta, che richiedeva una certa dimestichezza con il linguaggio Python e con la programmazione a basso livello. Tali abilità non sono necessariamente presenti in chi, ad esempio negli Enti Pubblici, si occupa di formazione e comunque di supporto agli Utenti. Capita così che prodotti sviluppati all'interno degli Enti, con una partecipazione più o meno limitata delle Aziende, non abbiano ancora beneficiato di Amberjack.

Windmill e Amberjack, un matrimonio di interesse... per tutti!

Come potrete capire dal video che precede, per non inventare l'acqua calda, siamo ricorsi a Windmill (http://www.getwindmill.com/), prodotto libero ben noto a chi, come noi, pratica il test driven development. Windmill si basa su uno strumento installabile lato Client e integrato con Python, e su una serie di servizi Web  (acceduti via proxy tramite chiamate javascript remote) che centralizzano alcuni dei processi di generazione dei test, ad esempio il loro salvataggio su un file di idoneo formato.

E' così nato collective.amberjack.windmill, prodotto aggiuntivo che installa un'istanza Windmill sul sito Plone, e ne sostituisce alcune delle librerie con versioni specifiche per Amberjack. Ne nasce un "registratore di azioni" che, anzichè essere asservito alla creazione di casi di test, genera un tutorial esemplificativo, completo di ogni fase, dalla login alla logout. Ai formati nativi di Windmill, Python e Javascript, è stata aggiunta la possibilità di salvare queste registrazioni nel formato nativo di Amberjack, rendendo la loro creazione molto più rapida, semplice e immediata.

Prodotti Plone autoesplicativi

Il tutorial può, indifferentemente, essere creato su una istanza Plone locale o direttamente sul sito di produzione, passando l'URL come parametro sulla linea di comando al momento dell'avvio di Windmill. A prescindere dall'istanza Plone utilizzata per la generazione del tutorial, esso può agevolmente essere ricontestualizzato su un server differente grazie al supporto agli URL relativi. Il file zip generato da Windmill viene caricato sul sito di produzione tramite un'apposita funzionalità di upload.

A questo punto, non manca niente: Amberjack e Windmill, sposi felici, annunciano la nascita del loro pargolo, un Plone veramente autoesplicativo, che starà a tutti noi fare crescere nel modo migliore.

First of all: the inherited problems

Version 1.0 of collective.amberjack.core is a simple Plone 4 compatibility version of the old 0.9 released.

When we released this we already know that the Javascript code inside was a mess, but before beginning some kind of refactoring procedure we need to know how the project will be changed in future.

The product has a core got from the Amberjack library, in last years many different programmers take part to the develop, meanwhile the product itself (and also Plone) was changing.

Amberjack original library is framework independent while Plone (that is a smart guy) rely on jQuery. Also we must not forget that Amberjack has not exactly the same target of collective.amberjack...

Wow... how many problems!

Not all those problems will be fixed in the 1.1 version, but I managed to simplify a little the code of two of the main method of amberjackPlone.js source.

How the old amberjackPlone.js was done

Saying "the code is ugly but works" is not a valid excuse... amberjackPlone.js contains two important methods:

• highlightStep is the method that highlight all the clickable/usable elements in the page for all steps.
  
• doStep is the method called to reproduce the user action on the page

What a user can do in a Plone site is a long list of different actions... list that become something like this for highlightStep:

...
if(type_obj=="checkbox" || type_obj=="radio"){
	obj.parent().addClass(theAJClass);
	obj.addClass(theAJClassBehaviour);
}
else if (type_obj=="select"){
	var highlightThis = jq(obj + " option[value="+ AjSteps[num].getValue() +"]");
	highlightThis.addClass(theAJClass);
	obj.addClass(theAJClassBehaviour);
}
else if (type_obj=="multiple_select") {
...
...going on and on...
...
else{
	obj.addClass(theAJClass);
	obj.addClass(theAJClassBehaviour);
}
...

...and like this for doStep:

...
if (type_obj == 'link') {
	AmberjackPlone.setAmberjackCookies();
	location.href = obj.attr('href');
}
else if (type_obj == 'button')
	obj.click();
else if (type_obj == 'collapsible') {
...
...going on and on and on and on...
...

Ugly enough? Do you think that the AntiIfCampaign hate us? Yes... probably...

So the first step is to remove this mess and try to port in Javascript the concept of adapter (unluckily not so flexible as Zope ones).

Even worst: many of the if statement in both doStep and highlightStep was testing the same expressions (like the "select")!

All this code has been removed.

Now both doStep and highlightStep are simply calling a sort of adapter built in the stepAdapters.js file:

AmberjackPlone.stepAdapters = {
	
	link: {
		highlight: null,
		checkStep: null,
		step: function(obj, type_obj, jq_obj, value) {
			AmberjackPlone.setAmberjackCookies();
			location.href = obj.attr('href');
		}
	},
	button: {
		highlight: null,
		checkStep: null,
		step: function(obj, type_obj, jq_obj, value) {
			obj.click();
		}
	},
	collapsible: {
...
... going on and on, but more readable!
...

For every possible action know, highlightStep and doStep will check if an handler is present in this structure (in this example the code is from the doStep):

if (AmberjackPlone.stepAdapters[type_obj] && AmberjackPlone.stepAdapters[type_obj].step)
	AmberjackPlone.stepAdapters[type_obj].step(obj, type_obj, jq_obj, value);

The highlightStep will check for highlight function.

If not if found, perform the old final else statement.

What is the checkStep section? In this sprint another group (Mirco and Simone Orsi) take a look to the feature that test if a user has completed all the steps before can go to the next page. Again, for some possible action the tour can try to test if you have finished your work.

In the old approach this will lead us to a new big and monolithic function. Now is only a new tiny method that call an handler.

What's next?

Adding some documentation, for sure...

Also other part of the code can be changed to become more clear...

...to be continued!

Symposium

We have started collective.amberjack presence in Sorrento with Massimo's presentation at the European Plone Symposium. 

Sprint

Then we had two sprinting days. We have started day one with brainstorming. We had three objectives/questions:

• collective.amberjack sandbox
• refactoring the code - how to simplify collective.amberjack tour definition and registration
• translations - how to manage tour/steps translations

thanks to a fruitful discussion (garbas, dukebody, gborelli, miziodel, shywolf9982, sorry if I forgot your name ;-) we have right now answers to all of our dilemmas.

SanDbox

First idea of having a sandbox for collective.amberjack came up at last Plone Conference in Budapest. We have collected a lot of ideas for different use cases. We have had also some internal brainstorms in RedTurtle about it. Finally after confronting all the concepts - during Sorrento brainstorming - we will have a simple solution which should satisfy most of the users:

Code refactoring

We have started refactoring collective.amberjack. There are 3 areas of interests: javascript, tour definition and tour registration. Luca was doing a great job trying to simplify javascript part. He also prepare a good startup for future enhancements. I was refactoring tour part. We have decided to use a 

configuration baseD tour definition,

which looks like that:

[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

[0_create-a-new-folder]
blueprint = collective.amberjack.blueprints.step
title = Create a new folder
url = /
text = Folders are one of ....
validators = 
        python: isManager
        python: isNotFolderCreated
microsteps = 
        0_0_microstep
        0_1_microstep
        0_2_microstep

[0_0_microstep]
blueprint = collective.amberjack.blueprints.microstep
description = If you don't want to perform the ...
automatically done by your browser.

[0_1_microstep]
blueprint = collective.amberjack.blueprints.microstep
idstep = menu_add-new
description = Click the [Add new...] drop-down menu.

[0_2_microstep]
blueprint = collective.amberjack.blueprints.microstep
idstep = new_folder
description = Select [Folder] from the menu.

This concept is well known across the community. I hope it will be also more human readable comparing to python dictionary ;-). We have a working version in the trunk. For new tours we have also 

new tour registration 

- comparing to old approach (registration only using ZCML) you can now use also TTW registration. Other important change is that tour doesn't need to be a python package any more. Because it's a simple .cfg file right now you can simply zip it into an archive (zip, tar) and register it. We have a working implementation for web source and local file system registration (which you can find in the trunk). Archive file can be shipped with multiple tours and with

translationS

which right now are still just a concept that need to be implemented. We would like to make a use of i18ndude tool but because it was designed for ZPT this could be a wrong approach. Overall idea is to keep all the files (tour and the translations) together, something like:

- mytours.zip
  |- tour1.cfg
  |- tour1_en.po
  |- tour1_it.po
  |- tour1.pot
  |- tour2.cfg
  |- tour2_en.po
  ...

Fixing bugs

Mirco and Federica were working together and did an enormous job fixing most of the 1.1a release bugs. Thanks to Rob we have solved also some TinyMCE problems that we have had. We have still some open issues, like 'new portlet creation' tour that need some attention so we still need your help!

What's next?

The current development focus is on 1.1 release, which includes:

• new tour definition (python dictionary based tour will still work until 1.2)
• new tour registration (old registration will still work until 1.2)
• finish translation implementation
• fix last bugs
• deploy sandbox probably on demo.plone.org
• collective.amberjack.windmill - which should become default interface for creating and editing tours; we have right now something more then just proof of concept:

Gli obiettivi

Abbiamo una milestone da raggiungere: quella del rilascio della versione 1.1a. Questa comprendeva:

• la risoluzione di alcuni bug o problemi di interfaccia
• il refactoring del codice javascript
• il brainstorming su come evolvere il sistema

Abbiamo risolto i bug, introdotti ulteriori miglioramenti all'interfaccia e rifattorizzata buona parte del codice javacript. Rimane qualcosa da finire, nel complesso è stato un successo. 

Inoltre, sono stati introdotti cambiamenti strutturali alla definizione del tour.

Luca, Federica, Mirco ed Andrew hanno fatto un gran lavoro.

Il punto focale però è stato il confronto con la comunità. Avevamo preso alcune decisioni che ci è sembrato opportuno sottoporre al vaglio dei presenti e abbiamo ottenuto ottimi suggerimenti e conferme sulla strada intrapresa.

Windmill

Windmill diventerà l'interfaccia principale di creazione di un tour. E' il modo più semplice per crearlo, aggiornarlo, tradurlo. E' di enorme efficacia sia per un end-user in quanto servirà poco addestramento che per uno sviluppatore che potrà creare al tempo stesso un tutorial per i suoi add-on e un test funzionale che verifichi che l'introduzione di modifiche non inficino il comportamento generale del sistema.

Questa conferma ha portato ad alcune riflessioni e variazioni di indirizzo.

formato dei tour

Il formato cambia. Non più complessi dizionari scritti in python, ma file di configurazione altamente leggibili. qualcosa del tipo:

[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


[0_create-a-new-folder]
blueprint = collective.amberjack.blueprints.step
title = Create a new folder
url = /
text = Folders are one of ....
validators = 
        python: isManager
        python: isNotFolderCreated
microsteps = 
        0_0_microstep
        0_1_microstep
        0_2_microstep


[0_0_microstep]
blueprint = collective.amberjack.blueprints.microstep
description = If you don't want to perform the ...
automatically done by your browser.


[0_1_microstep]
blueprint = collective.amberjack.blueprints.microstep
idstep = menu_add-new
description = Click the [Add new...] drop-down menu.


[0_2_microstep]
blueprint = collective.amberjack.blueprints.microstep
idstep = new_folder
description = Select [Folder] from the menu.

Sarà ovviamente possibile salvare i tour, in questo nuovo formato, direttamente dall'interfaccia di Windmill.

Ovviamente è necessario avere un sistema di conversione dei vecchi tour: è stata creata l'utility "tour_converter" (in collective.amberjack.core) che migra vecchi dict-based tour in nuovi cfg-based tour.

I tour saranno quindi semplici file. Questo significa che la sorgente da cui verranno "pescati" non sarà più un package scaricabile da pypi, ma potrà essere salvato in locale, messo su un server condiviso, scaricato da sorgenti eterogenee (svn, http server, ftp, ecc.). Ovviamente abbiamo una registrazione "classica" via zcml oppure una più "cool" via pannello di controllo di plone.

E' già pronta e funzionante una versione experimental che funziona con questo nuovo approccio e i 12 plonetour sono stati già convertiti e pronti per l'uso.

Un discorso a parte per le traduzioni: dobbiamo reimplementare il meccanismo in quanto ora non abbiamo più file .py. Contiamo di definire una modalità di traduzione simile alla precedente, ma in qualche modo occorrerà effettuare qualche variazione al sistema di generazione dei file .po.

sandbox

Il brainstorming pre-serale in giardino è stato molto utile anche in questo caso. 

L'idea che ne è scaturita è quella di fornire un folder personale dedicato ai tour all'interno del quale l'utente abbia tutti i diritti necessari per poterli eseguire completamente. Questo copre il 90% delle situazione secondo le previsioni della maggior parte dei presenti.

Con questa sandbox 1.0 si potrà già creare un "demo.plone.org": chiunque potrà provare Plone senza doverlo scaricare.

Inoltre è semplice per ogni sviluppatore di add-on montare un'istanza in cui includere il proprio tour ed eventualmente richiedere alla foundation il dominio: "demo.myaddon.plone.org"

Assolutamente semplice sarà fornire un sistema che ogni notte ripristini il portale ad una situazione "pulita".

Non sembra interessare, almeno in questa fase, un sistema che automaticamente crei un'istanza on-the-fly che permetta all'utente di provare plone in completa autonomia. quel 10% di target-user possono tranquillamente utilizzare un comodo UnifiedInstaller

abbiamo un team di supporto!

Dalla 1.0x RedTurtle ha deciso di supportare il progetto. 

Questo non significa che collective.amberjack sta diventando un progetto aziendale, ma semplicemente che avremo un team che ne porterà avanti lo sviluppo.

Il team, oltre a me, è composto da Mirco Angelini, Federica D'Elia, Andrew Mleczko e Luca Fabbri. All'ultimo sprint a Ferrara abbiamo avuto il supporto di Jacopo Deyla e il ritorno di Giacomo Spettoli (tra i primi contributori) entrambi della Regione Emilia Romagna.

Ora, sei ancora di più il benvenuto se vorrai partecipare allo sviluppo, supportare l'iniziativa o semplicemente utilizzare il sistema. Il tuo contributo sarà ancora più utile ora che qualcuno lo porterà avanti sistematicamente.

what's new? 

Questa prima release 1.0x supporta completamente Plone 4:

• i 12 tour sono stati completamente rivisti
• è stato introdotto il supporto per TinyMCE
• abbiamo un piano di battaglia

what next?

Dicevo di un piano di battaglia. Il piano prevede che al prossimo sprint a Sorrento si concludano le operazioni che ci porteranno ad una versione 1.1 rifattorizzate e ulteriormente migliorata. 

Nel frattempo predisporremo una serie di step che ci porteranno ad avere un sistema più solido, usabile e soprattutto estensibile.

Contiamo di introdurre Windmill come tool di creazione di tour via web. I primi tentativi sono molto promettenti. Andrea Benetti sta portando avanti la parte di studio che verrà integrata successivamente in collective.amberjack.

Dove puoi seguire il progetto?

Se sei interessato a partecipare, i posti dove ci incontriamo sono questi:

• launchpad, per la gestione del progetto (blueprint, bug, ecc.)
• coactivate, ci è utile per documentare il tutto attraverso il suo wiki e per gestire la mailing list
• il codice è tutto rilasciato su collective.

Se, viceversa, vuoi utilizzare il sistema, pypi è il tuo amico:

we have a support team!

Starting from 1.0 release, RedTurtle decided to support the project providing a 4 person team.

It doesn't mean that collective.amberjack is going to be company branded - quite the contrary - it means that we have a stable team that is going to enhance and mantain the tool.

Except me, the team contains: Mirco Angelini, Federica D'Elia, Luca Fabbri e Andrew Mleczko. During the last Ferrara' sprint, we were glad to have Jacopo Deyla's contribution and the Giacomo Spettoli's return (former contributor) both of them from Regione Emilia Romagna.

You are even more then welcome to participate in the development, in supporting the initiative or just in using and testing the tool. Your contribution will be more useful since, from now, there will be someone that will take care of it.

WHAT'S NEW? 

This 1.0 release supports Plone 4:

• the 12 tours has been completely revised
• the TinyMCE support has been added
• we have a battle plan

WHAT NEXT?

I talked about a roadmap. It assumes that during next Sorrento sprint we'll complete the tasks that will refactore the code and improved 1.1 release.

In the meanwhile we're going to schedule a set of steps that move collective.amberjack in a more solid, usable and mostly, extensible tool.

We are also confident to introduce Windmill as the TTW tool for creating tutorials. Andrea Benetti from University of Ferrara is starting to extend it. Then we'll integrate it into a collective.amberjack.windmill package.

how could you get involved inTO the project?

If you are interested in contribution, the places where we meet are these:

• launchpad, for the project management (blueprints, bugs, etc.)
• coactivate, extremely useful for documentation through its wiki and for the mailing lists
• the code is obviously release on collective.

Otherwise, if you just want to use the system, pypi is your friend:

Non so esattamente quale sia la percezione dall'esterno, ma ogni anno la conference rappresenta, per me, la possibilità di ritrovare vecchi amici che hanno una passione in comune.

Si parte!

Già alla cena pre-conference l'accoglienza è stata incredibile.
Aaron aveva un posto buono a fianco a lui e subito i gruppi si sono mescolati: italiani, americani, polacchi, francesi, tedeschi, olandesi.

Tutti li' a parlare di tutto. C'era quello mi chiedeva di amberjack, quello che si ricordava di un piatto italiano e voleva la ricetta, quello che ti racconta che si è finalmente preso una spider e ne è così orgoglioso.

Tutto come se fossimo vecchi compagni di scuola che hanno condiviso qualcosa di particolare e prezioso.

Spesso si dice:

plone il cms, plone il framework, ma soprattutto plone la comunità

La solita retorica, trita retorica, dell'open source, vero? beh, magari no.

Se ne sei fuori, o meglio se ne vuoi stare fuori, sei libero di vederla così, ma così non è. Frequento e ho frequentato in passato altre comunità (i partner ibm, i lug, l'xpug) e nonostante abbia incotnrato alti livelli di eccellenza, questa community è quella più coinvolgente, appassionante, e professionalmente energizzante.

ZEA

Il gruppo ZEA si è riunito dopo diverso tempo in una riunione live. Ho potuto conoscere di persona e di scambiare opinioni con Matt, Russ, Kit e Jean Paul, che conoscevo solo in modo marginale, ma anche di rivedere vecchi amici come Xavier e Godefroid. E' stato utile, credo che il gruppo sia oggi più compatto e propositivo.

Plone Italia

Il riaggregarsi del gruppo italiano è stato allo stesso modo entusiasmante.

Ognuno aveva la sua idea, il suo modo di vedere le cose. E si è discusso, preso in considerazione le varie tesi.

Quello che ne è venuto fuori lo potete o lo avete letto sulla ML, ma il punto interessante, ancora una volta, non è stato solo il risultato finale.

Il confronto, il discutere, il mettere in dubbio quello che è il tuo piccolo mondo di fronte agli altri è un modo estremamente appagante di crescere. E ti rendi conto che dopo 12 anni di lavoro e non so quanti di informatica, non sei ancora arrivato. C'è sempre qualcuno che ha qualcosa di nuovo da raccontarti un punto di vista diverso, e cresci.

collective.amberjack

Poi c'è stata la mia personalissima ciliegina sulla torta: collective.amberjack.

Ho potuto presentarlo in un talk ufficiale, ho "guidato" uno sprint e raccontato a tutti gli sprinter gli avanzamenti del lavoro fatto.
Messa giù così ha un che di vagamente autocelebrativo e presuntuoso. E sicuramente una parte di me è decisamente soddisfatta dell'interesse che ne è uscito. Il punto però è un altro.

Perdersi nella comunità

Ho sempre visto tutti coloro che contribuivano come una specie di esseri con capacità tecniche, qualità personali di livello superiore.

Il che in parte è anche vero. Quello che è, però, ancora più vero non sono le capacità tecniche, ma la voglia di proporsi e di perseverare.

In fondo quello che è cambiato in me rispetto alle precedenti conference è stato il voler mettere sul piatto quello che so fare, tanto o poco non importa. La comunità ha apprezzato ed evidenziato. Poi, magari, amberjack sarà stata anche un buona idea, ma in ogni caso è stato l'impegno che ha fatto la differenza.

E' la differenza che passa tra lo stare nell'ombra e sfruttare l'open source, come molti purtroppo fanno, e il fondersi nella comunità: più dai, più ti impegni, più avrai in cambio in termini di credibilità, riconoscenza, amicizia!

Ritorno a casa

Alla fine del viaggio la lezione imparata è che tutta la retorica dell'open source, del fatto che tutti possono contribuire, che è la community che segna la strada è niente di più che la realtà.

Non ci si può, però, limitare a raccontarla (alle conferenze, ai linux day, in post sui blog), occorre declinarla in azioni, in codice, in attività, in quello che sai fare.

Allora? che pensi di proporre alla prossima ploneconf?

Due parole in più rispetto al precedente post di Massimo. 

Tra gli elementi di soddisfazione, oltre al solito clima costruttivo che la comunità sa offrire, è stata l'impressione che RedTurtle si sia costruita un suo spazio e una sua credibilità anche al di fuori dei confini nazionali: se ci aveva fatto piacere veder accettare due talk su tre proposti, ce ne ha fatto ancora di più vedere con quanto interesse siano stati accolte le nostre presentazioni.

Ci pare di capire che Carneade (presentazione, video youtube, e talk ustream) è piaciuto perchè è un'idea, trasversale rispetto agli scenari di impiego, per rappresentare in Plone le strutture organizzative reali in tutta la loro complessità,  e quindi ha un ampio ventaglio di applicazione sia nelle realtà pubbliche (il nostro tipico target), sia in quelle private.

Amberjack (presentazione, video youtube, e talk ustream), sebbene un po' meno "astratto", comunque risponde a un'esigenza diffusa, e sarà interessante vedere come la comunità lo farà crescere: l'idea di rendere i siti Plone sempre più autoesplicativi, trasformando un percorso guidato in un tutorial sulla tecnologia, sembra promettente.

La modestia è d'obbligo, quando si ha a che fare con chi ha creato una tecnologia e ne governa la roadmap, e quando ci si confronta con colleghi di aziende di tutto il mondo. Direi che, dopo Budapest, noi RedTurtle, sempre consapevoli dei nostri limiti, possiamo essere più tranquilli sulla nostra capacità di lavorare allo stesso livello degli altri sviluppatori mondiali Plone.

I talk presentati sono stati 2:

1. Carneade, dar vita alle relazioni del mondo reale: Plone come gestore di organizzazioni
2. collective.amberjack: Plone come piattaforma per i tutorial

Tutto il materiale è già in linea.

Carneade

• La presentazione (su slideshare)
  
• un video di presentazione del sistema (su youtube)
• l'intero talk in streaming video (su ustream)

collective.amberjack

• La presentazione (su slideshare)
• un video di presentazione del sistema (su youtube)
• l'intero talk in streaming video (su ustream)
  

What's that?

What does it provide?

The actual implementation provides 4 packages:

• collective.amberjack.core
• collective.amberjack.portlet
• collective.amberjack.plonetour
• collective.amberjack.metatour

collective.amberjack.core

This one contains all the basic functionalities:

• it lets you add tours via ZCML,
• it manages and validates tours and steps,

• it draws the tour box and it manages all the UI interactions via javascript

collective.amberjack.portlet

this package provides two portlets:

• a one shot tour portlet
• a portlet with a set of tours

collective.amberjack.plonetours

this one contains the first released 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
• Create external links
• Upload an image
• Insert image on a page
• Using the Display menu

others will be released soon.

collective.amberjack.metatour

the idea is to provide a TTW way to create new tours. You can translate them via LinguaPlone and can be used by a non-technical user.

A next step is to export the TTW created tours as packaged that can be shared for example via pypi.

how simple adding a tour IS?

First of all you need to define the tour:

add_folder = {
    'url': u'/',
           'xpath': u'',
           'xcontent': u'',
           'title': _(u"Create a new folder"),
           'text': _(u"Folders are ..."),
           'steps': ({'description': _(u"Click the [Add new...] drop-down menu."),
                      'idStep': u'menu_add-new',
                      'selector': u'',
                      'text': u''},
                     {'description': _(u"Select [Folder] from the menu."),
                      'idStep': u'new_folder',
                      'selector': u'',
                      'text': u''})}

ajTour = {'tourId': u'basic01_example',
          'title': _(u'Add a Folder'),
          'steps': (add_folder,
                   )}

then you have to register it

<collective.amberjack:tour
        tourdescriptor=".example_tour.ajTour"
        />

If you need a complete example, please refer to the code.

Where can I find infos and code?

• The project home page, with a mailing list and wiki pages
  
• The code:
• core
• portlet
• plonetour
• metatour
• you can get a 3.2.3 buildout if you want to try it
  
• there is also a PLIP and a to do list
  

We have organized a small amberjack sprint. There was a lot of things to-do and only 5 sprinters: vincentfretin (online from France), fdelia, massimo, mirna and amleczko (all directly from Ferrara).

Beneath you can find summary of the sprint:

This is a report of the work made today
we just refer to the issue that were in today's worklist

put tours in a pipeline:
 - Add a link to the first tour in the first page of the second one, so a user
   who selects the second one directly will be able to takethe first one first,
   since you need to create the MyFolder folder first.
 - The whole Amberjack should manage branches like "if you are not logged in,
   then, log in".
 - At the end of a tour, add a link to the next tutorial.

We decided to have preconditions that has to added to a step (macrostep).
For example:
isAnonymous
isAuthenticated
etc.

there is already a initial implementation (amleczko).
completed - there are two basic validators: isAnonymous and isAuthenticated
when a precondition is not met a warning "the step is not visible"
is displayed. next, we should disable the step and all the followers.

we need to choose and implement a good strategy to define dependencies between
tours


 - Check the entered texts: check if the texts entered in the fields are the
   ones we expected. If not we may have problems with ids (in the url) and with
   the xcontent. Otherwise, let both url and xcontent be function of what the
   user entered.
  
we decided that before submitting we have a ajax call that checks if
all the mandatory things has been done by the user.
to be done.


 - collective.jqueryui. actually we have a js file in core/skins. it contains
   both jquery.ui and jquery.ui.draggable.
   we could remove the jquery.ui stuff and leave only a file ui.draggable.js.
   unluckly, collective.js.jquery + ui.draggable.js doesn't work (raise a js error)
  
Vincent Fretin, both complete this ticket and created two different profiles
for plone3.2 and plone>=3.3
  
 - Write tests for meta directives, tour_manager...

Andrew Mleczko and federica d'elia wrote a couple of tests and also refactored the
code see:
http://svn.plone.org/svn/collective/collective.amberjack.core/trunk/docs/HISTORY.txt


 - Add an option to the Unified Installer
 - Add a run-profile option to plone.recipe.unifiedinstaller to run additional
   profiles when the Plone Site is created
  
to be done
  
 - Tours: (massimo azzolini e mirna bagnolatti)
  Tour 5: Format a page using the visual editor
  Tour 6.1: Create internal links
  Tour 6.2: Create external links
  to be completed

  Tour 7: Upload an image
  completed, but cannot show the last "all done" step since the url is
  function of the name of the image uploaded. we need a fix [1]

  Tour 8: Insert image on a page
  completed, but cannot correctly save. when submitting the form the stuff
  inside kupu is not saved. [2]
 
  Tour 9: Upload and link to a File
  completed, with the same problems as above:
  1. the file obj's url is function of the name of the file itself. [1]
  2. cannot save the kupu stuff [2]
 
  Tour 10: Using the Contents tab
  the main problem is that we have the same page, but we want to move on
  many different tour steps. see [1]
 
  Tour 12: Create a static text portlet
  almost finished. problems:
  1. click on Save button show the alert "are you sure you want to leave..." [2]
 
 
Some open issues

 - [1] Provide a better way to manage the progression of the steps: too often
   path + xpath/xcontent do not suffice.
   Use the step position number 1/5, 2/5 etc.
to be done
  
 - [2] all the submit buttons (form.button.save & co) have problems if just
   "submitting", maybe we have to say that we are clicking on that button.
   we cannot either click() on it since it opens the alert window
   "are you sure you want to leave..."

to be investigated