Your first Component

1. Create a directory ${root}/src/main/webapp/Sample
2. Create a directory ${root}/src/main/webapp/Sample/components
3. Create a new file ${root}/src/main/webapp/Sample/components/foobar.js
4. Copy and paste this in the file:

   Archetype.Component.create({
   	name:"Sample.components.foobar",
   	/**
   	 * Set up the Component dependencies
   	 */
   	setup:{
   		dependencies: {
   			components:{},
   			lib:[]
   		}
   	},
   	/**
   	 * Constructor
   	 */
   	initialize: function () {
   		Logger.log("foobar has been instantiated!");
   		$(document.body).observe("click", this.createDate);
   		Logger.log("a click handler on the body of your page has been registered");
   	},
   	/**
   	 * Private method which launch the DateUpdate event
   	 * with the current date in parameter
   	 */
   	_createDate : function () {
   		this.fireDateUpdate(new Date());
   	},
   	/**
   	 * Fire a "DateUpdate" event
   	 */
   	fireDateUpdate: _,
   	/**
   	 * Listen to "DateUpdate" event
   	 */
   	onDateUpdate: function(eventName, date) {
   		Logger.log("foobar has received a date:" + date);
   	}
   });
   			

5. Now let's explain what it does:
   • "Archetype.Component.create" is the easiest way (it's aliased as "$C.create" if you're lazy) to build your component. There is only one parameter : the HashMap containing the component's definition.
   • "name" property must be defined in order to reference your component. It is usually the same as the file path in a java manner
   • "setup" provides the configuration of the component. It contains at the moment mostly dependencies which are in the "dependencies" Hashmap. In this example we don't need any dependencies.
   • "initialize" : as with Prototype's classes, this method is launched as the object constructor.
   • "_createDate":
     • createDate is a private method managed by Archetype
     • As you can see in initialize, it can only be accessed by the component itself with "this.createDate".
     • Also in initialize you can see that binding to "this" is unnecessary.

       In a normal JavaScript object, when defining a callback, you would have to use whether Prototype's "bind" method or the standard JavaScript more basic "apply", else you would be unable to the keyword "this" in your callback... Not having to do that is some of the magic of MethodBuilders.

     • This method launch the DateUpdate event (see fireDateUpdate) with a new Date as event data.
   • "fireDateUpdate":
     • "_" is a shortcut to the empty function (Prototype.emptyFunction).
     • This method is defined as the empty function because any function defined with a name starting with "fire" will be overridden to fire the corresponding event instead. This service is provided by a MethodBuilder too.
     • Adding this method is mandatory to allow the component to automatically fire the corresponding event with using this method.
   • "onDateUpdate":
     • All methods with a name starting with "on" are event listeners(another methodBuilder magic). They will be called automatically when an event with the corresponding name is fired.
     • It takes as parameters the eventName and the eventData (which is any kind of object).
     • In this case, firing and listening are in the same component but any other component can fire or listen this event too, as this event is broadcasted to all listening objects (mostly components) of the application.
6. Now let's load this brand new component in the application :

   //Static namespace for your application
   Sample = {
   	/**
   	 * Sample.main is launched when Archetype is available for page Sample.html
   	 */
   	main: function()
   	{
   	//--Do your application specific configuration here, e.g.:
   	//Archetype.useLogger("log.firebugLogger");
   	// or
   	//Sample.conf = {foo:"bar",bar:"foo"};
   	//--
   
   	// you will put your application BootStrap here
   	/**
   	 * This will require the component asynchronously then instanciate one by default
   	 */
   	Archetype.requireComponent("Sample.components.foobar");
   	Logger.log("hello, world !");
   	}
   };
   			

7. You can now display your page and look at your logger. The foobar component has been loaded and has registered a click event handler on the body of your page.

   At the moment, we have nothing in the document body, so clicking on it may be difficult.

   For a testing purpose without going further, you may want to add some text in your html page body. Just remove it then to continue the tutorial.

   Any click on the body of your page will result in a new line in your logger: this will display the current time when you have clicked on the body.