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
  

Description:%(searchterm)s^10 Title:%(searchterm)s^20 portal_type:Folder^10 portal_type:Document^30 review_state:published^100

Introduzione

L'idea che sta dietro al progetto nasce dalla "lentezza" di Plone in tutte quelle situazioni in cui è necessario effettuare data-entry massivo e/o ripetere molto spesso la stessa operazione.

Non si sta quindi parlando di rendere Plone più veloce (il Web è pieno di sanguinose discussioni a riguardo!) ma di rendere l'interfaccia più semplice. A volte bastano pochi accorgimenti.

Un esempio semplice, ma che fa capire quello che intendo è la PLIP 228 discussa per Plone 4. Si parla di ripristinare il menù a tendina "Aggiungi nuovo elemento" anche per i contenuti che non sono cartella (rimosso con l'avvento di Plone 2.5). I motivi che hanno portato alla sua rimozione sono tutto sommato buoni (legati all'usabilità dell'interfaccia) ma tutti si sono accorti quanto fosse più facile prima (leggasi "meno click e meno caricamenti") inserire più contenti in modo massivo.
Un'interfaccia più ricca è anche più potente, ma porta anche a svantaggi dovuti alla sua minore facilità. Qual'è il confine?

In questo caso, e nei casi di cui questa serie di prodotti vuole occuparsi, la questione è ovviamente un appesantimento dell'interfaccia che diventa meno semplice, meno chiara...
Ad ogni modo non è sempre sbagliato fornire (a chi la vuole) un'interfaccia più complessa, che magari necessita l'utente/redattore ad un addestramento maggiore, ma che può portare a anche a ridurre il numero di caricamenti.

Esempio numero 1: le briciole di pane

Cosa non va nelle briciole di pane di Plone? Ovviamente nulla!

Chiari, semplici, leggibili link che permettono di tornare velocemente ai contenitori del documento corrente...

Quando un utente usa le briciole di pane?
Un utente visitatore le usa per tornare al contenitore... nulla di più, e non ci si aspetta quindi che siano necessarie altre funzionalità.
Trovo il comportamento attuale un po' limitante invece per gli utenti redattori... questi possono voler tornare al contenitore/i per effettuare altre operazioni, che a mio parere possono essere:

• Modificare il contenuto
• Accedere alla vista dei contenuti della cartella
• Aggiungere nuovi elementi

redturtle.speedupui.pathbar

Il primo (e speriamo non l'ultimo) prodotto si occupa ovviamente della pathbar di Plone che non a caso ho portato come esempio.

SpeedUpUI Pathbar sostituisce la normale viewlet delle briciole di pane con una versione più complessa che offre un menù a tendina ai redattori, per effettuare le operazioni descritte sopra.

La versione 0.1.0dev non supporta ancora la gestione dell'aggiunta di nuovi elementi (ammettiamolo... probabilmente sarebbe la modifica più interessante... date tempo al tempo!) così come non c'è un effettivo controllo dei permessi (perché mostrare un link "modifica" se l'utente non ha effettivamente il permesso di farlo?), ma ha offerto comunque interessanti spunti per fare riflessioni...

Innanzi tutto l'elemento corrente delle briciole di pane non ha nessuna funzionalità avanzata. Se si vuole modificare il contenuto corrente Plone offre già un apposito comando.

Per quali contenuti poi mostrare la voce "Contenti" per visualizzare i contenuti della cartella?

In un primo momento verrebbe da pensare tutti. Ovviamente tutti gli elementi della pathbar tranne l'ultimo sono sicuramente contenitori. Ad ogni modo ci sono casi in cui il contenitore è stato scritto per non sembrare tale... L'unico esempio vivente che ho visto usare questa funzionalità è l'oggetto PoiIssue del gestore di segnalazioni Poi.

Gli oggetti di questo tipo utilizzano l'interfaccia INonStructuralFolder. L'uso di questa interfaccia viene utilizzato da Plone per capire se la cartella deve in effetti sembrare una cartella agli occhi dell'utente (deve avere una scheda per visualizzare i contenuti?).
Martin Aspeli ha scritto un vecchio tutorial ancora valido a riguardo.

La scelta è stata quindi quella di non mostrare il comando di visione dei contenuti per i contenuti INonStructuralFolder.

Conclusione

Il prodotto non è completo, forse migliorabile (di certo per quanto riguarda l'interfaccia mostrata) e probabilmente qualche altra buona funzionalità potrebbe essere implementata.

La scelta di usare un namespace di secondo livello speedupui nasce da un fatto preciso: ci sono altri "pezzi" del puzzle Plone che possono mostrare funzionalità aggiuntive che permettano di ridurre i caricamenti...

Un esempio?
Il navigatore...

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

I'm developing SOAP integration in Plone. I have never used efficiently SOAP python client before so first I wanted to test all of them. According to Plone there are two well-known python SOAP implementations: ZSI and SOAPpy. They are both focused on server not client implementation. It took me some time to configured them properly and found that the last release for ZSI was 2006 (for SOAPpy it was 2005). Finally I found suds. It's fast, light and powerful. And it has a community which is helpful - especially for beginners. 

Installing and using is veery simple. You can use easy_install:

>>> easy_install suds

and use it:

from suds.client import Client
url = 'http://localhost/testingservice.wsdl'
client = Client(url)

than accessing methods is as simple as:

document = client.service.getDocument(id=1)
print document
(Document)=
  {
     title = 'Document title'
     description = 'Document short description'
  }

even if your webservice has strange method names:

document = getattr(client.service,'get-document')(id=1)