\n
\n<script type=\"text\/javascript src=\"\/path\/to\/EventHelpers.js\"><\/script>\r\n<script type=\"text\/javascript\" src=\"\/path\/to\/config-2.0.js\"><\/script><\/pre>\n<\/blockquote>\n<\/li>\n- The config block can be inserted into your HTML document by defining any HTML node with an
id<\/code> ofconfig<\/code>.\u00a0 The only content inside this node should be an HTML comment with your configuration values inside.\u00a0 Below is an example XML block that defines a configuration propertyformValidator.errors.mandatoryField<\/code>:
\n\n<div id=\u201dconfig\u201d>\r\n<!--\r\n<config>\r\n <formValidator>\r\n <errors>\r\n <mandatoryField>\r\n The above field is mandatory\r\n <\/mandatoryField>\r\n <\/errors>\r\n <\/formValidator>\r\n<\/config>\r\n-->\r\n<\/div><\/pre>\n<\/blockquote>\n<\/li>\n- Accessing the data inside the configuration block can be done with JavaScript by using the
config.getValue()<\/code> function.\u00a0 In the above example, the text inside themandatoryField<\/code> tag can be accessed inside JavaScript using theconfig.getValue()<\/code> function like this:
\n\ndocument.getElementById(\"message\") =\r\n config.getValue(\"formValidator.errors.mandatoryField\");<\/pre>\n<\/blockquote>\nNote:<\/strong> any call to
config.getValue()<\/code> must be made after<\/em> config.js loads the XML block into memory. If you are initializing your own code with awindow.onload<\/code>, you should replace it with a call toconfig.addLoadEvent()<\/code>.<\/p>\nFor example, replace<\/p>\n
\nwindow.onload=myObject.init<\/pre>\n<\/blockquote>\nwith:<\/p>\n
\nconfig.addLoadEvent(myObject.init)<\/pre>\n<\/blockquote>\n<\/li>\n<\/ol>\nYou can put as many values inside your XML as you like.\u00a0 For example the values inside the XML configuration block below can be retrieved using
config.getValue('<\/code>formValidator.errors.mandatoryField<\/code>')<\/code>,\u00a0config.getValue('<\/code>formValidator.errors.postalCode<\/code>')<\/code> andconfig.getValue('<\/code>formValidator.alerts.success<\/code>')<\/code>.<\/p>\n\n<!--\r\n<config>\r\n <formValidator>\r\n <errors>\r\n <mandatoryField>\r\n The above field is mandatory\r\n <\/mandatoryField>\r\n <postalCodeError>\r\n You did not format the postal code correctly.\r\n <\/postalCodeField>\r\n \u00a0<\/errors>\r\n <alerts>\r\n <success>\r\n Your changes have been submitted.\r\n <\/success>\r\n <\/alerts>\r\n <\/formValidator>\r\n<\/config>\r\n-->\r\n<\/div><\/pre>\n<\/blockquote>\nNote the object oriented “dot” notation of the configuration properties, which corresponds to the XML’s tree structure. The usual convention I follow is:<\/p>\n
\n
- I code all configuration values that have to do with the same script using the same top level object (in this case, the top-level object\u00a0 is called
formValidator<\/code> since it is being accessed by a script called formValidator.js).<\/li>\n- I then create properties for that top level object that describe logical categories that I want to configure\u00a0 (e.g. templates, errors, urls,\u00a0 etc).<\/li>\n
- I finally have the third level contain the actual configuration values.<\/li>\n<\/ol>\n
While I consider this best practice (insomuch as it works well for me), developers are of course not stuck with this convention, and can format their XML as they please, as long as there are no duplicate property names within an object.<\/p>\n
HTML Values<\/h2>\n
Note that a developer can insert HTML inside the XML string by placing the HTML content inside a
CDATA<\/code> node:<\/p>\n\n<config>\r\n <formValidator>\r\n <templates>\r\n <hasError><![CDATA[\r\n <div id=\"errorMessage\">\r\n <p>There are errors with the information you are trying\r\n to submit.\u00a0 Please check the form below, correct the\r\n errors and resubmit.<\/p>\r\n <\/div>\r\n ]]><\/hasError>\r\n <submissionAlert>\r\n If this was a real form, the information above would\r\n have been submitted.\u00a0 Since this isn't, we won't submit\r\n any of the form information.\r\n <\/submissionAlert>\r\n <\/templates>\r\n <errors>\r\n <mandatoryField>\r\n The above field is mandatory\r\n <\/mandatoryField>\r\n <\/errors>\r\n <\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nNote that the CDATA node has to immediately<\/em> follow the containing tag<\/strong> (in the above example, you’ll see there are no spaces hasError tag). This restriction will probably be relaxed in a subsequent release.<\/p>\n
Removing Extraneous Spaces<\/h2>\n
Let’s look at this example:<\/p>\n
\n<config>\r\n <formValidator>\r\n <templates>\r\n <submissionAlert>\r\n If this was a real form, the information above would\r\n have been submitted.\u00a0 Since this isn't, we won't submit\r\n any of the form information.\r\n <\/submissionAlert>\r\n <\/templates>\r\n <\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nIf we tried to execute
window.alert(\"formValidator.templates.submissionError\")<\/code>, we would get an alert box that would look something like this:<\/p>\nThis alert has bad spacing due to the way the XML is formatted.<\/p><\/div><\/p>\n
Doesn’t that look ugly?\u00a0 This is because the formatting of the text inside it’s configuration block is indented so that it is readable to the developer when viewing the code (Note that all carriage returns are ignored by config.js, but the spaces are left intact). In order to keep the pretty XML formatting while getting rid of the extra spacing inside the alert box, we can set the
removeMultispaces<\/code> attribute of it’s configuration tag to\"true\"<\/code>:<\/p>\n\n<config>\r\n <formValidator>\r\n <templates>\r\n <submissionAlert removeMultispaces=\"true\"<\/span>>\r\n If this was a real form, the information above would\r\n have been submitted.\u00a0 Since this isn't, we won't submit\r\n any of the form information.\r\n <\/submissionAlert>\r\n <\/templates>\r\n <\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nThis results in an alert box that is formatted as intended:<\/p>\n
All the extraneous spacing has been removed, regardless of where it appears in the XML.<\/p><\/div><\/p>\n
Dynamic Content:<\/h2>\n
Injecting variables into the contents of the configuration value can be achieved by using
config.getScriptedValue()<\/code>.\u00a0\u00a0 To do so, you first insert the variables into your XML using placeholders surrounded by @-symbols, which we’ll call “at values”<\/strong>:<\/p>\n\n<config>\r\n <formValidator>\r\n\r\n <submissionAlert>\r\n If this was a real form, the information above would\r\n have been submitted.\u00a0 Since this isn't, we won't submit\r\n any of the form information, including the @ccType@<\/span> Credit Card number\r\n @ccNum@<\/span>.\r\n <\/submissionAlert>\r\n\r\n <\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nIn this example,
@ccType@<\/code> and@ccExp@<\/code> are the at-values that will contain dynamic content. The following JavaScript creates an alert containing the configuration value offormValidator.templates.submissionAlert<\/code>, complete with dynamic content.<\/p>\n\nvar formToValidate = document.getElementById(\"formToValidate\");\r\nvar alertString = config.getScriptedValue(\r\n \"formValidator.templates.submissionAlert\",\r\n {\r\n ccNum: formToValidate.ccNum.value,\r\n ccType: formToValidate.ccType.value\r\n });<\/pre>\n<\/blockquote>\nThis replaces the at-value placeholders
@ccNum@<\/code> and@ccType@<\/code> with the values of the form fieldsccNum<\/code> andccType<\/code>, respectively.<\/p>\nExternal XML File<\/h2>\n
Instead of having the XML contained within an HTML comment, you can have the file loaded separately by defining the file name inside the config node like this:<\/p>\n
\n<!--\r\nxml=xml\/config.xml\r\n-->\r\n<\/div><\/pre>\n<\/blockquote>\nComments<\/h2>\n
If the XML is embedded in an HTML comment, then comments to the embedded XML must be put inside the XML block using JSP style
<%-- --%><\/code> comment notation:<\/p>\n\n<config>\r\n <formValidator>\r\n <%--\r\n This section contains english text that will\r\n be inserted into the page\r\n --%><\/span>\r\n <templates>\r\n <hasError><![CDATA[\r\n <div id=\"errorMessage\">\r\n <p>There are errors with the information you are trying\r\n to submit.\u00a0 Please check the form below, correct the\r\n errors and resubmit.<\/p>\r\n <\/div>\r\n ]]><\/hasError>\r\n <submissionAlert removeMultispaces=\"true\">\r\n If this was a real form, the information above would\r\n have been submitted.\u00a0 Since this isn't, we won't submit\r\n any of the form information, including the @ccType@ Credit\r\n Card number @ccNum@.\r\n <\/submissionAlert>\r\n <\/templates>\r\n<\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nIf the configuration XML is stored in an external file, use regular XML
<!-- --!><\/code> comment notation:<\/p>\n\n<config>\r\n <formValidator>\r\n <!--\r\n This section contains english text that will\r\n be inserted into the page\r\n --!><\/span>\r\n <templates>\r\n <hasError><![CDATA[\r\n <div id=\"errorMessage\">\r\n <p>There are errors with the information you are trying\r\n to submit. Please check the form below, correct the\r\n errors and resubmit.<\/p>\r\n <\/div>\r\n ]]><\/hasError>\r\n <submissionAlert removeMultispaces=\"true\">\r\n If this was a real form, the information above would\r\n have been submitted. Since this isn't, we won't submit\r\n any of the form information, including the @ccType@ Credit\r\n Card number @ccNum@.\r\n <\/submissionAlert>\r\n <\/templates>\r\n<\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nObject Arrays<\/h2>\n
Developers can also define arrays inside configuration files as well, by using the
datatype<\/code> attribute inside a tag.\u00a0 In the following example, the configuration propertyformValidator.creditCardForm.inputs<\/code> is an array containing three objects:<\/p>\n\n<config>\r\n <formValidator>\r\n <creditCardForm>\r\n <inputs datatype=\"array\">\r\n\r\n <ccType>\r\n <postalCode>\r\n <isMandatory>true<\/isMandatory>\r\n <%-- Note: We assume Canadian postal codes only - -%>\r\n <pattern>\r\n ^[a-zA-Z]\\d[a-zA-Z]\\s*\\d[a-zA-Z]\\d$\r\n <\/pattern>\r\n <unmatchError>\r\n The postal code must be in a valid format.\r\n <\/unmatchError>\r\n <\/postalCode>\r\n <\/ccType>\r\n\r\n <ccNum>\r\n <isMandatory>true<\/isMandatory>\r\n <pattern>^\\d{16}$<\/pattern>\r\n <unmatchError>\r\n The credit card you entered is not valid.\r\n <\/unmatchError>\r\n <\/ccNum>\r\n\r\n <ccExp>\r\n <isMandatory>true<\/isMandatory>\r\n <pattern>^(0[1-9]|1[1-2])\/\\d{2}$<\/pattern>\r\n <unmatchError>\r\n The expiry date must be in the form yy\/mm.\r\n <\/unmatchError>\r\n <\/ccExp>\r\n\r\n <\/inputs><\/span>\r\n <\/creditCardForm>\r\n<\/formValidator>\r\n<\/config><\/pre>\n<\/blockquote>\nEach of these elements have three properties (
isMandatory<\/code>,pattern<\/code> andunmatchError<\/code>).\u00a0 Note that each element in the array don’t have to have the same properties, in the same way that a the elements in a JavaScript array doesn’t have the same type of object.\u00a0 In the above example, we can\u00a0 access these array values with the following script:<\/p>\n\nvar inputs = config.getValue(\"formValidator.creditCardForm.inputs\");\r\nvar ccExp = inputs[\"ccExp\"]\r\nvar ccExpError = ccExp.unmatchError;<\/pre>\n<\/blockquote>\n\n<mandatoryField>\r\n The above field is mandatory\r\n <\/mandatoryField><\/pre>\n<\/div>\nExamples<\/h2>\n
\n
- A very simple example can be found on my blog post Configuring JavaScript Applications<\/a>.<\/li>\n
- A more complicated example<\/a> showing how to do simple client-side form validation with regular expressions.\u00a0 It uses code that is contained in this manual page.<\/li>\n
- The same example as shown above using an external configuration file<\/a> (i.e. not embedded in the HTML page.<\/li>\n<\/ul>\n
Download<\/h2>\n
You can get full source here:<\/p>\n
![\"This](\"https:\/\/www.useragentman.com\/blog\/wp-content\/uploads\/2009\/10\/alertWithBadSpacing.png\" "\\"alertWithBadSpacing\\"")
![\"All](\"https:\/\/www.useragentman.com\/blog\/wp-content\/uploads\/2009\/10\/alertWithGoodSpacing.png\" "\\"alertWithGoodSpacing\\"")