New

Packages were released on pypi:

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

and on plone.org:

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

Everything is also on collective:

• collective.amberjack.buildout/
• collective.amberjack.core/
• collective.amberjack.portlet/
• collective.amberjack.metatour/
• collective.amberjack.plonetour/
• collective.amberjack.windmill/
­

See the tours in action

­

Bugtracking

The new tool for bugtracking is launchpad

Goals

Actually the main topic is to create a framework that supports the creation of:

• a step by step introduction
• tutorial

the arguments may be:

• plone
• creating content
• how to use a certain area in a portal/intranet

who can manage/create the tutorials:

• end users
• programmer-like skilled persons

The basic Idea

To create a tutorial you need:

1. a html part that describes the tutorial itself. inside it you have references to "macrosteps" and to "steps".
   
1. A macrostep is a bunch of actions semantically related. e.g. Fill in all the fields in a page.
2. A Step is a single simple action: e.g. write "hello max" in the title, or write "lorem lipsum" in the description, or click the menu
2. The steps are still a macro language that describe what to do.
   

What we have now

Core

Core is the engine of the entire model. See README.txt of collective.amberjack.core.
there are:
 - javascript files
 - layouts for the popup
 - images
 - css

Windmill

collective.amberjack.windmill is a tool for creating tutorials TTW obtained by extending "Windmill Testing Framework".
you can find a full description in the README.txt of the package.

See it in action:

­

Portlet

This one is just a portlet: there you can choose which tour run (actually writing the tourId in a field) and with which layout. 

We planned also to provide an alternative portlet on which the user chooses which tutorial run.

See README.txt of collective.amberjack.portlet.

PloneTour

This an example of a tour. See README.txt of collective.amberjack.plonetour.

Actually what it does is to provide:

• a viewlet containing the tour in a "amberjake-like" way.

• a set of microsteps defined in an "abstract" way. For example a microstep may say "write 'helloworld' in the title_field":

 AjSteps = {
          '1': new AjStep('new_folder','',''),
          '2': new AjStep('form_title','','MyFolder'),
          ...
   }

 see ajStandardSteps.py­ which is a plone view that creates a initial built-in set of steps. 

Actually this package is not up-to-date but it could be a good starting point for creating new tutorials that can be delivered as an egg (obviously as soon as I refactor it)

Javascript

The engine relies on 5 js file:

• amberjack.js (core)
• amberjackDefaults.js (core)
• ajStandardSteps.js (core)
• amberjackPlone.js (core)
• ajSteps.js (plonetour or metatour)

amberjack.js is the original js library grabbed from the framework and extended: it just managed the url as a key to discriminate the step to execute. We need something more. For example in addiction to the url, we search if something appears on the page or not:

getPageId: function(children, pos){
    var element = children[pos]
	var title = element.getAttribute('title');
	var xpath = element.getAttribute('xpath');
	var xcontent = element.getAttribute('xcontent');
	
	return '(' + title + ';' + xpath + ';' + xcontent + ';' + pos + ')';
  },

amberjackSteps.js maps semantic related nouns to css selectors that we can find on a plone page. It's automatically generated and it could be also a configuration in a config.py file.

amberjackDefaults.js is just a way to provide to javascript paths known by python, any improvement is welcome.

amberjackPlone.js is the plone core part of these libraries. It provides the engine that manages the way the steps are declined from a high level view to pure javascript actions.

Install

Download the buildout from collective and run it.

There is a sample metatour already created in /exampletour: copy it in /parts/instance/import and import it via ZMI.

For the installing steps see README.txt.

How to create a new tour "MyTour"

To create a tour you should install collective.amberjack.windmill/ and register one.

A complete guide

We have now a first version of a complete guide of our product.

It's a beta version and there is again much work to do. We accept any help from people with some experience into the product.

If someone is interested can become member of this CoActivate project.

Thanks to Vilmos Somogyi that has started to write a complete guide of collective.amberjack

Ideas? Bug?

If you have any idea to propose or you found a bug (seems impossible, doesn't it? :) please refer to the issue tracker on launchpad.

Sprints

• Budapest PloneConference 2009 
• Sorrento Sprint 2010