EXC | DEV | Documentation | Version 1.0


# Components # {: #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 ## {: #adding}

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`(js:string) The component type identifier. - name `string`(http://apple.com) 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 ## {: #adding}

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

Property	Description
type	Required Value is "textbox"
name	Required A name for this widget.
disabled	Make it disabled
help	Help or Alt/Title attribute of the textbox.
width	Set a fixed width. Value must include a css unit, for example "100px".
size	Size attribute of textbox.
placeholder	Placeholder attribute of the textbox.
prefix	Decorates a textbox with an icon or text at the beginning.
suffix	Decorates a textbox with an icon or text at the end.

Methods of textbox

This component inherits methods from generic.

Function	Syntax	Description
enable	enabled()
disable	disable()
focus	focus()
setValue	setValue(value)	Sets the value.
getValue	getValue()	Returns the value.

Component Checkbox

Property	Description
type	Required Value is "check"
name	Required A name for this widget.
disabled	Make it disabled
help	Help or Alt/Title attribute of the textbox.
label	The label for the checkbox
default	The default value, either "1" or "0"

<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.

Function	Syntax	Description
enable	enabled()
disable	disable()
focus	focus()
setValue	setValue(value)	Sets the value. Either 1 or 0.
getValue	getValue()	Returns the value. Either 1 or 0.
toggle	toggle()	Toggles the value.

Value Modifiers

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

Name	Type	Description
.value-use-suffix	class	The value returned by this widget will have its suffix appended. (See: attribute suffix )
m-value-max	attribute	Max numeric value that can be returned. Ex: m-value-max="5000"
m-value-min	attribute	Min numeric value that can be returned. Ex: m-value-min="1000"
m-value-strip	attribute	Strips the string matched in the RegEx given. Ex: `m-value-strip="(\@.*)$"`
m-value-round-up	attribute	Rounds up the value to the given decimal precision. Ex: m-value-round-up="2"
m-value-round-down	attribute	Rounds down the value to the given decimal precision. Ex: m-value-round-down="2"
m-value-with-decimals	attribute	Formats number with the given number of decimals. It rounds up when required, except when 0 decimals is specified, in which case decimals are truncated. Ex: m-value-with-decimals="2"
m-value-with-suffix	attribute	Appends the string given to the value returned.
m-value-without-suffix	attribute	Removes the string given from the end of the value returned.

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:

Name	Type	Declaration	Description
id	string		Required The name of this component. It must be unique and only use alphanumeric characters and the underscore. For example: id: "textbox"
selectors	array of strings		Required A list of selectors that identify or match this component. For example: selectors: [ "[w='textbox']" ]
setter	function	function(node, value)	Optional Called to set the value of the widget represented by this component.
getter	function	function(node)	Optional Returns the value of the widget represented by this component.
vs	string or plain object		Optional A string with the name of a build in value provider interface (eg: "value", "attr", `"hidden"`) or a plain object with a getter function and a setter function. The signature of a getter function is function(elm) and must return a value. The signature of a setter function is function(elm, value). You may use the getter or setter functions instead.
isContainer	boolean		Optional Indicates that this component is a container for other components or HTML content. Default value is false.
inherits	array of strings		Optional Name of other components from where we get functionality. Example: inherits: ['container']
fn	plain object		Optional Additional functionality implemented by an instance of this component. The functions in this object will be added to the element.
onInit	callback	function(node)	Optional Called to initialize the element that represents this component. This function should be used to perform post processing that requires you to have the DOM of the component created. You may add event listeners required to implements the component's behavior.
onInstance	callback	function(node)	Optional Called when an instance of this component was referenced.
build	callback	function(propertyBag)	Optional Called when the component must build the corresponding HTML representation for a widget. This function is called before anything is injected in the actual DOM. The argument propertyBag is an object with the properties and attributes of the widget requested.

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.