follow inputEx on Twitter
bookmark on Del.icio.us
follow on GitHub

inputEx Guide

This guide tries to centralize everything that has been written on inputEx. If you think something is missing or need better explanation, please contact us through the forum. Being written by a french, help in finding typos, technical errors, or poorly worded sentences is greatly appreciated.



1 Overview

1.1 Presentation

inputEx is a javascript framework to build fields and forms.

It doesn’t use html markup (it is the opposite of obtrusive libraries): All the fields and forms are configured using json or javascript literal objects. It provides a very efficient abstraction for building interactive web applications. For detailed information, have a look at our complete API documentation.

The code for inputEx is provided under MIT license.

1.2 HTML forms VS. JS/Ajax

While it is still possible to create forms using inputEx and send them using the browser, inputEx was made to build web applications. A preferable way to retrieve value is to use javascript and to send the value using ajax.

We use some hacks to make inputEx work with "standard" html forms :

1.2 Terminology

inputEx is built around the Field class. It is an abstract class (we never instantiate it).
All the other field classes inherits directly or indirectly from this base class. (see diagram below)

The important difference between "fields" and "widgets" is simple :

All fields inherit from the inputEx.Field class (some inherits it indirectly through other field classes...)

The inputEx.Field class provides a common set of methods that are expected to work on all fields. This common abstraction makes it possible to nest standard fields into "meta"-fields (such as form, inplace-edit, ...)

The widgets are not meant to be inserted into forms. They are simply helpers to provide frequently-used user interface using inputEx forms.

For example :

Finally inputEx.register only register fields. This is necessary if you want to create a field using json: 

 		fields: [
 		   {type: "text", label:"name"},
 		   {type: "my-custom-type", label: "test" }
 		]

Warning: this diagram is not complete. See the API Doc for more information

2 Getting Started

2.1 Installation

inputEx is just a bunch of static files (javascript files, css, and images). As usual, you will have to copy those files into your project directory.

2.2 First Example

Add inputEx to your page

3 ways of doing this :

Basic example

2.3 Directory structure
file or directory
api/ Auto-generated API documentation
build/ Contains the minified javascript
css/ CSS files
examples/ Examples that are part of the library
images/ inputEx images
index.html inputEx Home page
js/ javascript sources
lib/ librairies required by inputEx
license.txt MIT license details
README.md links for the GitHub page
res/ resources for inputEx website and documentation
scripts/ scripts to build rollup files and documentation
tools/ tools built for or with inputEx
version.txt change log

2.4 Instantiating a Field / the "type" property :

There are 3 ways to instantiate a Field :

The default "type" associations : (Warning: this table is not complete, but each class follow the same naming conventions.)

type string class loader module
boolean inputEx.CheckBox inputex-checkbox
color inputEx.ColorField inputex-colorfield
date inputEx.DateField inputex-datefield
email inputEx.EmailField inputex-emailfield
form inputEx.Form inputex-form
group inputEx.Group inputex-group
hidden inputEx.HiddenField inputex-hiddenfield
html inputEx.RTEField inputex-rtefield
inplaceedit inputEx.InPlaceEdit inputex-inplaceedit
IPv4 inputEx.IPv4Field inputex-ipv4field
list inputEx.ListField inputex-listfield
password inputEx.PasswordField inputex-passwordfield
select inputEx.SelectField inputex-selectfield
string inputEx.StringField inputex-stringfield
text inputEx.Textarea inputex-textarea
type inputEx.TypeField inputex-typefield
uneditable inputEx.UneditableField inputex-uneditablefield
url inputEx.UrlField inputex-urlfield

To link a class with a "type", we use :

	inputEx.registerType(inputEx.StringField, 'string');

2.5 Meta-Fields :

Some special fields called meta-fields take one or multiple "type" construction objects as configuration.

2.6 Insert a Field into the DOM :

 

	var field = inputEx.FieldClass({...options...});
	parentEl.appendChild( field.getEl() );

	// or

	var field = inputEx.FieldClass({...options..., parentEl: parentEl});

	// or

	var field = inputEx.FieldClass({...options..., parentEl: 'parentElId'});

2.7 The "updated" event :

All the fields fire the same event when they are "updated".

To subscribe this event for a field, use : (see YUI Custom Events for more informations)

	myField.updatedEvt.subscribe(function(e,value) {
		// value = new value returned by getValue
		...code here...
	}, scope, true);

This event is fired when you use a setValue on the field. If you want to disable this behaviour, pass "false" as second argument to the setValue and the event won't be fired.

	// This setValue won't fire the updatedEvt
	myField.setValue("My Value", false);

3 Advanced Usage

3.1 Visualization

Introduction

The use of a template engine in inputEx first appeared for the Autocompleter, InPlaceEdit and Uneditable fields.
It has also proven very useful in projects that use inputEx.

The library itself doesn't include a template engine, but provides a standard way to use different engines and define your templates within field configurations. It is also very simple to add interfaces to other template engines.

Rendering

The fields should use the inputEx.renderVisu method to use templates:

Templating methods are stored in the inputEx.visus object. Methods can return either a HTMLElement or a String, since inputEx.renderVisu handle both.

inputEx.visus contains 3 default methods (you can add your own) :

inputEx.Visus methods are functions that take 2 parameters :


Examples

Check the following examples to see template usage:

4 Create custom fields

4.1 Introduction

Once you've grasped the main ideas behind inputEx, you'll probably want to create your own fields. Here are some hints on how to do so :

Choose the right parent Class

Look at the classes to pick the "closest" one. (in terms of code)
If you want to start from scratch, you should inherit from inputEx.Field

use YAHOO.extend to extend classes

Override methods

Some methods have a precise role :

  • setOptions : declare the options and their default value
  • render : create a wrapper around the field DOM and insert the component
  • renderComponent : render the DOM for your field
  • initEvents : subscribe to events once rendered
  • getValue : get the value of your field
  • setValue : set the value of your field

Send the updated event

Fire this event to indicate modifications (with this.fireUpdatedEvt())

Register your type

After your class definition, you can associate your class to a type string. You can either create a new type, or override a previous one.

use inputEx.registerType("myType", inputEx.MyFieldClass);

4.2 Markup Structure

Getting familiar with the inputEx markup structure will help a lot if you want to change CSS.

		div.inputEx-fieldWrapper	(+ state CSS classes)

				// Label floating left
				div.inputEx-label
						label

				// Field floating left
				div.inputEx-Field

						// field wrapper
						div.inputEx-AnyField

						// Description
						div.inputEx-description

				// Messages floating left
				div.inputEx-message

				// clear left floating
				div.breaker

The "fieldWrapper" create a box that contains the entire field, labels, descriptions, widgets, etc...

The wrapper childNodes have the "float" css attribute set to "left" so you can decide where to break lines between them by using css: it gets much easier to put the label over the field, or the messages under etc...

5 Contribute

5.1 Internationalization

Usage

The basic messages are stored into the inputEx.messages object :

	inputEx.messages = {
	   required: "This field is required",
	   invalid: "This field is invalid",
	   valid: "This field is valid"
	};

Additional fields should add their messages into the same object : 

	// Specific message for the email field
	inputEx.messages.invalidEmail = "Invalid email, ex: sample@test.com";

Contribute !

We are looking for contributors to extend inputEx localizations. If you use inputEx in a foreign language, please contribute by sending the localization file on the forum.

Examples

Then we only need one additional file, example with the French translation file :

		/**
		 * InputEx French localization
		 */
		(function() {

		   var msgs = YAHOO.inputEx.messages;

		   msgs.required = "Ce champ est obligatoire";
		   msgs.invalid = "Ce champ n'est pas valide";
		   msgs.valid = "Ce champ est valide";
		   msgs.invalidEmail = "Email non valide; ex: michel.dupont@fai.fr";
		   msgs.selectColor = "Sélectionnez une couleur :";
		   msgs.invalidPassword = ["Le mot de passe doit contenir au moins "," caractères (lettres ou chiffres)"];
		   msgs.invalidPasswordConfirmation = "Les mots de passe entrés ne sont pas identiques !";
		   msgs.capslockWarning = "Attention: touche majuscule activée";
		   msgs.invalidDate = "Date non valide; ex: 25/01/2007";
		   msgs.defaultDateFormat = "d/m/Y";
		   msgs.shortMonths = ["Jan", "Fév", "Mars", "Avril", "Mai", "Juin", "Juil", "Août", "Sept", "Oct", "Nov", "Déc"];
		   msgs.months = ["Janvier", "Février", "Mars", "Avril", "Mai", "Juin", "Juillet", "Août", "Septembre", "Octobre", "Novembre", "Décembre"];
		   msgs.weekdays1char =  ["D", "L", "M", "M", "J", "V", "S"];
		   msgs.shortWeekdays = ["Di","Lu","Ma","Me","Je","Ve","Sa"];
		   msgs.selectMonth = "- Choisissez -";
		   msgs.dayTypeInvite = "Jour";
		   msgs.monthTypeInvite = "Mois";
		   msgs.yearTypeInvite = "Année";
		   msgs.cancelEditor = "annuler";
		   msgs.okEditor = "Ok";
		   msgs.defautCalendarOpts = {
		      navigator: {
		               strings : {
		                   month: "Choisissez un mois",
		                   year: "Entrez une année",
		                   submit: "Ok",
		                   cancel: "Annuler",
		                   invalidYear: "Année non valide"
		               }
		      },
		      start_weekday: 1 // la semaine commence un lundi
		   };


		   // Datatable
		   msgs.saveText = "Sauver";
		   msgs.cancelText = "Annuler";
		   msgs.modifyText = "modifier";
		   msgs.deleteText = "supprimer";
		   msgs.insertItemText = "Ajouter";
		   msgs.confirmDeletion = "Êtes-vous sûr ?"

		})();

5.2 Reporting an Issue

The issues/bugs and feature requests are managed through the GitHub issue tracker. Feel free to add new ones, vote for your favorites, comment on existing one, ...

Then don’t get your hopes up. Unless you have a "Code Red, Mission Critical, The World is Coming to an End" kind of bug, you’re creating this ticket in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the ticket automatically will see any activity or that others will jump to fix it. Creating a ticket like this is mostly to help yourself start on the path of fixing the problem and for others to confirm it with a "I’m having this problem too" comment. (shamelessly copied from Rails guide)

5.3 Contributing to the Documentation

This guide represents the biggest documentation effort of the library. The API documentation is also a huge part of inputEx's documentation. How can you help ?

5.4 Contributing to the Code

The easiest way for us to integrate your work into inputEx, is to fork the project on GitHub, and commit your changes into your own branch.

You can contribute in a lot of different ways :

5.5 Contributors

Special thanks to the major contributors :

And to other contributors :

inputEx is released under the MIT license.