EXC | DEV | Documentation | Version 1.0

Components

In EXC components are used to provide an enhanced behavior to existing HTML controls and to create new controls and UI elements.

EXC comes with a set of built-in components and you may create your own.

Adding a component

Use the html tag <w></w> as a shorthand to add a component to your html.

<w type="textbox" name="username"></w>

The shorthand tag <w> requires a minimum of two attributes type and name, each component may require additional attributes.

• type string(string) The component type identifier.
• name string A unique name for the element.

For example:

<w type="textbox" name="username" default="" suffix='<i class="la la-user"></i>' attr='{"placeholder":"Username1"}'></w>

Here is an alternate syntax using the attribute def with a JSON payload:

<w def='{"type":"textbox", "name":"username", "default":"","attr":{"placeholder":"Username"}, "suffix":"<i class=\"la la-user\"></i>"}'></w>

Getting a reference to a component

In JS a component instance is nothing more than a HTML element decorated with additional functionality.

To obtain an instance we use the name of element:

	var widgetUsername = exc.component.get("fldUsername");
	var value = widgetUsername.getValue();

Actually in addition to the name you can pass an html element or a string with a selector to exc.component.get().

This function uses the attribute type to determine what kind of component is represented by an element. For some other cases the function exc.component.get() takes an optional second argument with the id of a component to be returned.

The function exc.component.get() will return undefined if not found. If a selector matches more than one element it will return the first matched element.

Component textbox

Methods of textbox

This component inherits methods from generic.

Component Checkbox

<w type="formRow">
	<w type="formField" caption="Checkbox">
		<w type="check" name="check1" label="Option 1" m-model="user_record"></w>
		<w type="check" name="check2" m-model="user_record">Option 2</w>
	</w>
</w>

Methods of checkbox

This component inherits methods from generic.

Value Modifiers

A textbox supports value modifiers to control the value returned by the widget.

Defining a Component

A new component is made available by registering its definition. This is done by calling:

exc.components.register(myComponentDefinition);

Component Definition

A component definition is an object with properties that define your component and some callback handlers to render the html and implement its behavior.

The following are the properties of a component definition:

A propertyBag

When using a shorthand tag or creating instances of widgets/components dynamically from JS we use a propertyBag with all the properties and attributes of the desired widget.

EXC will create a propertyBag for the attributes in a shorthand tag <w></w> that will be passed to a build() calback in a component definition.

The following snippet shows some of the propertyBag functionality, for more details you should check some of the built-in components in the code repository for reference.

	var name = propertyBag.name;
	//getting a property
	if( propertyBag.hasProperty("size") ){
		var size = propertyBap.property("size");
	}

	//copy css classes, "data-" attributes and exc's "m-" attributes to a node
	propertyBap.copyDefaultAttributes(node);

Example definition:

exc.components.register({
	id: 'textbox',
	selectors: ["[w='textbox']"],
	vs: "value", //value source

	fn : { //a plain object of functions to be added to a widget instance
		play: function(){
			console.log(this.uiw);
			console.log("at play...");
		}
	},
	build: function(e){
		//Build a widget node, from the widget properties passed on e

		//basic things that should be done on build:
		e.copyDefaultAttributes(node);


		//return a single node or an array of nodes like [ node1, node2]
		return node;
	}
	onInit: function(node){
		//Initialize the component's contents, called after a widget is built or a widget node is found
		exc.components.installValueInterface(node,"value", this); //sets a value interface
	}
	onInstance: function(node){
		//A widget reference is requested for the node (instance of this component).
		//decorate or add special functionality, beyond what is defined in fn
	}
}

More obscure details :)

The w attribute

An html element in your DOM that corresponds to a component is tagged with the attribute w that has the id of the component it represents.