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.
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.
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 :
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
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.
3 ways of doing this :
<!-- YUI loader--> <script src="http://yui.yahooapis.com/2.8.2r1/build/yuiloader/yuiloader-min.js"></script> <!-- inputEx loader --> <script src="../js/inputex-loader.js"></script>
<!-- YUI utilities --> <script src="http://yui.yahooapis.com/2.8.2r1/build/utilities/utilities.js" type="text/javascript"></script> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.8.2r1/build/reset-fonts/reset-fonts.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.8.2r1/build/assets/skins/sam/skin.css" /> ... and other yui dependencies... <!-- inputEx --> <link href="inputex/css/inputEx.css" rel="stylesheet" type="text/css" /> <script src="inputex/js/inputex.js" type="text/javascript"></script> <script src="inputex/js/Field.js" type="text/javascript"></script> <script src="inputex/js/Group.js" type="text/javascript"></script> <script src="inputex/js/Form.js" type="text/javascript"></script> <script src="inputex/js/fields/StringField.js" type="text/javascript"></script> <script src="inputex/js/fields/CheckBox.js" type="text/javascript"></script> ... and the other fields you need ...
<!-- YUI utilities --> <script src="http://yui.yahooapis.com/2.8.2r1/build/utilities/utilities.js" type="text/javascript"></script> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.8.2r1/build/reset-fonts/reset-fonts.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.8.2r1/build/assets/skins/sam/skin.css" /> ... and other yui dependencies... <!-- inputEx minified files --> <script src="inputex/build/inputex-min.js" type="text/javascript"></script> <link href="inputex/build/inputex-min.css" rel="stylesheet" type="text/css" />
YAHOO.util.Event.addListener(window, "load", function(){ new inputEx.Form({ parentEl: 'myFormContainer', fields: [], buttons: [] }); });
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 |
There are 3 ways to instantiate a Field :
var field = new inputEx.StringField({name: 'test'});
var field = inputEx({ type: 'string', name: 'test' });
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 |
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');
Some special fields called meta-fields take one or multiple "type" construction objects as configuration.
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'});
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);
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.
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 :
Check the following examples to see template usage:
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 :
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);
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...
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 ?" })();
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)
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 ?
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 :
Special thanks to the major contributors :
And to other contributors :
inputEx is released under the MIT license.