Graphical components

Overview

Graphical components is an extension of regular components on which we add lots of features in order to handle a graphical representation inserted in the DOM.

These components brings the Model View Controller architecture to Archetype. We assume that the Model is binged from the Ajax Framework you use, the Controller is your component and the View is the template assiociated to your component.

Graphical component API

First, take a look at the structure of a graphical component:

$C.Extend(["Archetype.component.graphicalComponent"], {
	name: "<name of the component>",

	setup:{
		dependencies: {
			components: { 
				<componentKey>: <componentName>,
				<...>
			},
			lib: [
				<libraryName>,
				<...>
			],
			css: [
				<cssFileName>,
				<...>
			],
			html: {
				<templateKey>: <templateName>,
				<...>
			}
		},
		template: <template engine>
	},
	
	initialize: <initialization method>,
	
	<first method name>: function() {/*your code!*/},
	<second method name>: function() {/*your code again!*/},
	...
});
			

$C.Extend : Extend a generic graphical component (located at the module name Archetype.component.graphicalComponent) for defining our component.

$C.Extend allows you to create components with inheritance of one or multiple other components already defined. The default graphical component is a core component include in the framework.

• name : The name of the component. You can instantiate any registered component by using "new (Archetype.Component.get("name.of.the.component"))()
• setup.dependencies : a hashmap containing all the dependencies information used by a component (see bellow).
• setup.template : name of the template system you want to use if different from the default one. If you want to make a redistribuable component, please set this value.
• initialize : this is the constructor of your component. In most cases the component will be instantiated without any parameter, take this in account.
• different methods : your code !

Dependency management

There is four kinds of dependency you can configure for a basic component: components and libraries as for normal components and two newer: css and templates.

• components : defined by a HashMap, values are module names of components you want, keys of each one can be used further to instanciate the component.
• lib (libraries) : defined by an Array of all module names of js files you need.
• css : defined by an Array of all module names of css files you want to add.
• templates : defined by a HashMap, values are module names of templates you want, keys of each one can be used further to use it.

Inside your methods, templates you declare as needed can be called by using this.templates :

$C.Extend(["Archetype.component.graphicalComponent"], {
	name: "MyApp.components.aComponent",

	setup:{
		dependencies: {
			templates: { 
				myTemplate: "MyApp.templates.myTemplate"
			}
		}
	},
	
	initialize: function() {
		var myData = {
			foo: "bar"		
		}
	
		//Evaluate the template
		Logger.debug(this.templates.myTemplate.evaluate(myData));
	}
});
			

For more documentation of using templates, see the the template chapter .

Graphical Component API

The purpose of inherit of graphical component is to allow you to use the render method which add the component view in the DOM (in the page). Lets take a look to the complete API:

• render(/*DOM Element*/ element) : Render the component into the element in parameter. Use the method renderViewAsString to get the String representation of the HTML for the component. After insertion, launch the afterRender method in order to perform actions which needs the component to be rendered (like define event listening).
• renderViewAsString(/*void*/) : must return the String of the HTML for the component. This method is defined by default in the graphical component defintion, it return the evaluation of the template with key main and the component itself as data. You can override this method by yours, it can be useful when you switch between more than one template.
• afterRender(/*void*/) : is launched just after the DOM insertion of the component. It's almost always useful to do something at this moment specially add listener on new element we just added. By default, this method do nothing, you can override it to add behaviors.

There is an example of graphical component which use default renderViewAsString and the default afterRender method:

$C.Extend(["Archetype.component.graphicalComponent"], {
    name: "Slidy.components.container",
    setup: {
        dependencies: {
            components: {
                slideManager: "Slidy.components.slideManager",
                slideChangeHandler: "Slidy.components.slideChangeHandler",
                slideCounter: "Slidy.components.slideCounter"
            },
            lib: ["Slidy.libs.shjs.sh_main", "Slidy.libs.shjs.sh_javascript", "Slidy.libs.shjs.sh_html"],
            css: ["Slidy.css.slidy", "Slidy.css.w3c-blue", "Slidy.libs.shjs.sh_typical"],
            html: {
                main: "Slidy.templates.container" 
            }
        }
    },
    initialize: function(){
		//Insert in the main template evaluation into the element mached by the selector
        this.render($$("#bodyContent")[0]);

        new this.components.slideChangeHandler();
        new this.components.slideCounter();
        new this.components.slideManager();
    }
});