datasource.js

javascript 很酷的类库

// see W3C's tutorial here:
// +externalLink{http://www.w3.org/International/tutorials/tutorial-char-enc/}
// <p>
// <u><b>String localization</b></u>
// <p>
// All text appearing in SmartClient UI components is customizeable at the component prototype
// level and at the instance level.  For example, Button component has a default title of
// "Untitled Button" that is changed at the instance level when the button is created (using
// JavaScript syntax):
// <pre>
// Button.create({ title: "Click me!"});
// </pre>
// Likewise, the default title can be changed like so:
// <pre>
// Button.create({});  // this produces a button with the title "Untitled Button"
// Button.changeDefaults({ title: "Titled Button"});
// Button.create({});  // this now produces a button with the title "Titled Button"
// </pre>
// Using these mechanisms, you can set locale-specific text on any SmartClient component.
// <p>
// We'll use Java-based internationalization examples here because the SDK ships with a Java
// backend - but note that Java is not required to internationalize your SmartClient
// application - see the "Resources" section a the end of this overview for links to
// internationalization resources of other popular back-end technologies.  All those
// techonologies provide mechanisms for fetching locale-specific strings that are compatible
// with SmartClient because ultimately internationalizing a SmartClient application is not much
// different from internationalizing an HTML page.
// <p>
// So, to give a Java-based example, let's say we want to create a button on a page in a manner
// that permits future localization.  Let's say we currently have the following code in our JSP
// page: 
// <pre>
// &lt;SCRIPT&gt;
// Button.create({ title: "Click me!" });
// &lt;/SCRIPT&gt;
// </pre>
// One standards-based approach is to use the i18n component of the JSTL Core package (Java
// Server Pages Standard Tag Library) to replace that static "Click me!" text with a localized
// reference.  This can be done as follows:
// <pre>
// &lt;%@ taglib prefix="fmt" uri="/WEB-INF/fmt.tld" %&gt;
// &lt;SCRIPT&gt;
// Button.create({ title: &lt;fmt:message key="buttonTitle"&gt; });
// &lt;/SCRIPT&gt;
// </pre>
// Assuming you've set the current Locale and provided a resource bundle with the relevant
// translated text, the above would create a button with a title that comes from the locale-specific
// bundle you provided.  See Sun's i18n tutorial:
// +externalLink{http://java.sun.com/docs/books/tutorial/i18n/} and the JSTL home page:
// +externalLink{http://java.sun.com/products/jsp/jstl/} for more information on how to set up
// Resource Bundles.
// <p>
// If you're developing in XML, the mechanism is much the same.  Let's say we have the following
// XML code in our JSP:
// <pre>
// &lt;isomorphic:XML&gt;
// &lt;Button title="Click me!"/&gt;
// &lt;/isomorphic:XML&gt;
// </pre>
// We can localize this button by using JSTL as before by writing it like this:
// <pre>
// &lt;%@ taglib prefix="fmt" uri="/WEB-INF/fmt.tld" %&gt;
// &lt;isomorphic:XML&gt;
// &lt;Button&gt;
//   &lt;title&gt;&lt;fmt:message key="buttonTitle"&gt;&lt;/title&gt;
// &lt;/Button&gt;
// &lt;/isomorphic:XML&gt;
// </pre>
// Note that the XML must be well-formed so we can't just replace "Click me!" with the
// <code>fmt</code> tag because we would end up with embedded double quotes.
// <p>
// NOTE: even though you are dynamically adding localized data to your presentation using
// JSTL/JSPs, you can still allow the browser to cache the entire presentation layer (described
// in detail +link{group:smartArchitecture, here}.  Your bootstrap JSP (the application start
// page) can use a &lt;SCRIPT SRC=&gt; tag to load the localized presentation code as
// cacheable JavaScript, for example, &lt;SCRIPT SRC=/mainUI.jsp?locale=[localeName]&gt;.  This
// works with both XML and JS component descriptors since both are ultimately delivered to the
// browser as JavaScript.
// <p>
// <u><b>Framework message localization</b></u>
// <p>
// In addition to titles and other strings displayed on SmartClient widget instances, 
// SmarClient displays a number of standard prompts and error messages in various cases, all
// of which are fully customizeable for localization purposes.<br>
// A complete list of these standard messages is visible +link{group:i18nMessages, here}.<br>
// Customizing these standard messages is very similar to customizing any other strings, such
// as the <code>Button.title</code> attribute described above.  To take an example, the 
// +link{classAttr:RPCManager.timeoutErrorMessage} is displayed to the user in a warning dialog
// when a SmartClient operation fails to complete. By default this is set to 
// <code>"Operation Timed Out"</code> but can be modified using the +link{Class.addClassProperties()} 
// method, as follows:
// <pre>
// isc.RPCManager.addClassProperties({timeoutErrorMessage:"Custom Timeout Message"});
// </pre>
// <p>
// <u><b>DataSource localization</b></u>
// <p>
// DataSources can be created in +link{group:dataSourceDeclaration,several ways}.  DataSources
// created directly in JavaScript can be internationalized via the techniques described above.
// DataSources which are declared in XML (.ds.xml files) and are read by the ISC server, which
// are normally loaded into a .jsp page via the <code>&lt;isomorphic:loadDS&gt;</code> JSP tag,
// can instead be loaded and interpreted as .jsp files via the technique described below.  This
// allows JSTL and other JSP tags to be used to internationalize the titles and validation
// error messages in XML DataSources.
// <P>
// For example, given the following DataSource located in /shared/ds/supplyItem.ds.xml:
// <pre>
// &lt;DataSource&gt;
//     &lt;fields&gt;
//         &lt;field name="itemName"&gt;
//             &lt;title&gt;Item Name&lt;/title&gt;
//             &lt;validators&gt;
//                 &lt;Validator type="lengthRange" max="40"&gt;
//                     &lt;errorMessage&gt;Must be 40 characters or less.&lt;/errorMessage&gt;
//                 &lt;/Validator&gt;
//             &lt;/validators&gt;
//         &lt;/field&gt;
//     &lt;/fields&gt;
// &lt;/DataSource&gt;
// </pre>
// To localize the title and validator error string of the <code>itemName</code> field 
// using the same JSTL strategy we've been using, first add the following to your web.xml to
// allow DataSource files to be interpreted as JSPs:
// <pre>
// &lt;jsp-config&gt;
//     &lt;jsp-property-group&gt;
//       &lt;url-pattern&gt;/shared/ds/*&lt;/url-pattern&gt;
//     &lt;/jsp-property-group&gt;     
// &lt;/jsp-config&gt;
// </pre>
// Next change the DataSource definition as follows:
// <pre>
// &lt;!--
// &lt;%@ taglib prefix="fmt" uri="/WEB-INF/fmt.tld" %&gt;
// --&gt;
// &lt;DataSource xmlns:fmt="urn:jsptld:/WEB-INF/fmt.tld"&gt;
//     &lt;fields&gt;
//         &lt;field name="itemName"&gt;
//             &lt;title&gt;&lt;fmt:message key="itemTitle"&gt;&lt;/title&gt;
//             &lt;validators&gt;
//                 &lt;Validator type="lengthRange" max="40"&gt;
//                     &lt;errorMessage&gt;&lt;fmt:message key="itemLengthRangeValidator"/&gt;&lt;/errorMessage&gt;
//                 &lt;/Validator&gt;
//             &lt;/validators&gt;
//         &lt;/field&gt;
//     &lt;/fields&gt;
// &lt;/DataSource&gt;
// </pre>
// Note that the XML comment around the taglib declaration is intentional.  It is there to make
// sure the JSP parser sees the tag library declaration, while the file remains valid XML.
// If you need to use multiple JSP tag libraries to achieve your goals, simply add additional
// taglib declarations inside the XML comment and be sure to register the tag namespace in the
// DataSource tag via <code>xmlns:tagName</code> as done above for the <code>fmt</code>
// namespace. instead of using the <code>&lt;isomorphic:loadDS&gt;</code> JSP tag to load this
// DataSource, you would load it as follows in your JSP:
// <pre>
// &lt;SCRIPT&gt;
// &lt;isomorphic:XML&gt;
// &lt;jsp:include page="/shared/ds/supplyItem.ds.xml"&gt;&lt;/jsp:include&gt;
// &lt;/isomorphic:XML&gt;
// &lt;/SCRIPT&gt;
// </pre> 
// This makes it possible to internationalize field titles as well as validation error messages
// for built-in validators.  To internationalize custom server-side validation errors, simply
// provide internationalized strings when calling <code>DSResponse.setErrorReport()</code> to
// report validation errors (see the JavaDoc for that documentation).
// <p>
// <u><b>Support for Right-to-Left (RTL) languages</b></u>
// <P>
// SmartClient includes beta quality support for RTL langauges, with known issues in certain
// skins and components.  To enable, simple set <code>dir="rtl"</code> on the HTML element:
// <pre>
//    &lt;HTML dir="rtl"&gt;
// </pre>
// ListGrid columns, horizontal layouts, scrolling directions, etc will reverse order
// automatically.
// <P>
// If you need production-quality RTL support for your application, visit the<a
// href="http://forums.smartclient.com">SmartClient forums</a> for details of 
// known limitations.
// <P>
// <u><b>Image, CSS localization</b></u>
// <p>
// Most SmartClient components use a mixture of text, CSS and images to render.  If you wish to
// provide locale-specific images or use locale-specific CSS, you can create localized copies
// of a SmartClient skin named after the locale and modify images as you see fit.  A skin is
// specified at load time using either the <code>skin</code> attribute of the
// <code>&lt;isomorphic:loadISC&gt;</code> tag or by loading the skin
// directly using a script tag like so: &lt;SCRIPT SRC=/isomorphic/skins/[skin]/load_skin.js&gt;.
// If you're using the <code>loadISC</code> tag, you can specify a locale-specific skin like so:
// <pre>
// &lt;isomorphic:loadISC skin="[localeName]"/&gt;
// </pre>
// Or you can use a script tag like so:
// <pre>
// &lt;SCRIPT SRC=/isomorphic/skins/[localeName]/load_skin.js&gt;&lt;/SCRIPT&gt;
// </pre>
// Where the <code>[localeName]</code> is the name of the current locale - you'll have this in the
// current page context as you'll need it to use the JSTL &lt;fmt:setLocale&gt; tag.
//
// Resources:
// <p>
// <b><u>Java</u></b>
// <ul>
// <li>Sun's i18n tutorial: +externalLink{http://java.sun.com/docs/books/tutorial/i18n/}
// <li>JSTL home page: +externalLink{http://java.sun.com/products/jsp/jstl/}
// <li>Apache JSTL "Getting Started": 
//     +externalLink{http://jakarta.apache.org/taglibs/doc/standard-doc/standard/GettingStarted.html}
// <li>Apache taglibs: +externalLink{http://jakarta.apache.org/taglibs/}
// </ul>
// <p>
//
// <b><u>.NET</u></b>
// <ul>
// <li>MSDN Developer Resource: "Developing World-Ready Applications":
// +externalLink{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondesigningglobalapplications.asp}
// </ul>
//
// <b><u>PHP</u></b>
// <ul>
// <li>PHP Gettext manual: +externalLink{http://us2.php.net/gettext}
// <li>O'Reilly Gettext tutorial: +externalLink{http://www.onlamp.com/pub/a/php/2002/06/13/php.html}
// </ul>
// <p>
//
// <b><u>Perl</u></b>
// <ul>
// <li>Perl, Unicode and i18n FAQ: +externalLink{http://rf.net/~james/perli18n.html}
// </ul>
// @treeLocation Concepts
// @title Internationalization and Localization (i18n,l10n)
// @visibility external
//<

//> @groupDef eclipseIntegration
//
//    If you're developing with Eclipse, you can use the SmartClient personality for Eclipse ATF
//    (+externalLink{http://eclipse.org/atf, Ajax Toolkit Framework}).  Here's how to set it up:
//    <p>
//    1. If you haven't already, download and install ATF from 
//      +externalLink{http://www.eclipse.org/atf/downloads/index.php}.
//      The SmartClient personality has been tested against the ATF 0.1 Milestone Build, but is
//      also known to work with later releases.<p>