001: /*
002: * GWT-Ext Widget Library
003: * Copyright(c) 2007-2008, GWT-Ext.
004: * licensing@gwt-ext.com
005: *
006: * http://www.gwt-ext.com/license
007: */
008:
009: package com.gwtext.client.data;
010:
011: import com.google.gwt.core.client.JavaScriptObject;
012: import com.gwtext.client.util.JavaScriptObjectHelper;
013:
014: /**
015: * An implementation of DataProxy that reads a data object from a URL which may be in a domain other than the
016: * originating domain of the running page.
017: * <p>
018: * Note that if you are retrieving data from a page that is in a domain that is NOT the same as the originating domain of
019: * the running page, you must use this class, rather than {@link HttpProxy}.
020: * <p>
021: * The content passed back from a server resource requested by a ScriptTagProxy is executable JavaScript source code that
022: * is used as the source inside a <script> tag.
023: * <p>
024: * In order for the browser to process the returned data, the server must wrap the data object with a call to a callback
025: * function, the name of which is passed as a parameter by the ScriptTagProxy. Below is a Java example for a servlet which
026: * returns data for either a ScriptTagProxy, or an HttpProxy depending on whether the callback name was passed:
027: * <p/>
028: * <pre>
029: * <code>
030: * <p/>
031: * boolean scriptTag = false;
032: * String cb = request.getParameter("callback");
033: * if (cb != null) {
034: * scriptTag = true;
035: * response.setContentType("text/javascript");
036: * } else {
037: * response.setContentType("application/x-json");
038: * }
039: * Writer out = response.getWriter();
040: * if (scriptTag) {
041: * out.write(cb + "(");
042: * }
043: * out.print(dataBlock.toJsonString());
044: * if (scriptTag) {
045: * out.write(");");
046: * }
047: * <p/>
048: * </code>
049: * </pre>
050: * <p/>
051: * Consider the following code :
052: * </p><pre><code>
053: * RecordDef recordDef = new RecordDef(new FieldDef[]{
054: * new StringFieldDef("name", "name"), // "mapping" property not needed if it's the same as "name"
055: * new StringFieldDef("occupation") // this field will use "occupation" as the mapping.
056: * });
057: * <p/>
058: * JsonReader reader = new JsonReader(new JsonReaderConfig() {
059: * {
060: * setTotalProperty("results"); // The property which contains the total dataset size (optional)
061: * setRoot("rows"); // The property which contains an Array of row objects
062: * setId("id"); // The property within each row object that provides an ID for the record (optional)
063: * }}, recordDef);
064: * </code>
065: * </pre>
066: * <p>
067: * <p/>
068: * If the data is being server from the same domain, then you don;t need to use ScriptTagProxy but instead need to use
069: * {@link com.gwtext.client.data.HttpProxy} pointing to the URL that returns data in the following format :<br>
070: * <p/>
071: * </p><pre><code>{ <em>'results'</em>: 2, <em>'rows'</em>: [
072: * { <em>'id'</em>: 1, <em>'name'</em>: <em>'Bill'</em>, occupation: <em>'Gardener'</em> },
073: * { <em>'id'</em>: 2, <em>'name'</em>: <em>'Ben'</em>, occupation: <em>'Horticulturalist'</em> } ]
074: * }</code></pre>
075: * <p/>
076: * However if this data is being read from another domain, a couple of things need to be done.<br>
077: * <p/>
078: * First, you need to use ScriptTagProxy pointing to the external url. For example
079: * <pre>
080: * <code>
081: * ScriptTagProxy proxy = new ScriptTagProxy("http://externalurl:8023/foo/bar.php");
082: * </code>
083: * </pre>
084: * <p/>
085: * Now bar.php cannot return standard Json like the one above when using HttpProxy. Instead it needs to wrap the
086: * Json data in a callback. This is required when reading data from antoher domain. When the ScriptTagProxy tries
087: * for fetch data, it will issue an HTTP request to the specified URL passing the name of the callback function that
088: * it needs the results to be wrapped in. For example http://externalurl:8023/foo/bar.php?start=0&limit=25&sort=nome&dir=DESC&_dc=1196661274168&<b>callback=stcCallback1002</b>
089: * <br>
090: * Notice the request paramter "callback" has a value of "stcCallback1002" in the above example. This means that the
091: * request to http://externalurl:8023/foo/bar.php should return Json data wrapped in the callback funtion "stcCallback1002".
092: * <p/>
093: * <br>
094: * </p><pre><code><b>stcCallback1002(</b>{ <em>'results'</em>: 2, <em>'rows'</em>: [
095: * { <em>'id'</em>: 1, <em>'name'</em>: <em>'Bill'</em>, occupation: <em>'Gardener'</em> },
096: * { <em>'id'</em>: 2, <em>'name'</em>: <em>'Ben'</em>, occupation: <em>'Horticulturalist'</em> }]<b>);</b>
097: * }</code></pre>
098: * <br>
099: * So for ScriptTagProxy to work, the URL that it is reading data from is responsible to read the "callback" paramter,
100: * and wrap the Json data using the name of the passed callback function. By default the name of the callback
101: * request parameter is "callback" but you can specify a different one using the constructor {@link #ScriptTagProxy(String, int, String)}.
102: */
103: public class ScriptTagProxy extends DataProxy {
104:
105: /**
106: * Construct a new ScriptTagProxy.
107: *
108: * @param url the URL from which to request the data object.
109: */
110: public ScriptTagProxy(String url) {
111: JavaScriptObject config = JavaScriptObjectHelper.createObject();
112: JavaScriptObjectHelper.setAttribute(config, "url", url);
113: jsObj = create(config);
114: }
115:
116: //excluding nocache options since ScriptTagProxy calls are never cached
117: //http://extjs.com/forum/showthread.php?t=7096
118: /**
119: * Construct a new ScriptTagProxy.
120: *
121: * @param url the URL from which to request the data object.
122: * @param timeout the number of milliseconds to wait for a response. Defaults to 30 seconds.
123: */
124: public ScriptTagProxy(String url, int timeout) {
125: JavaScriptObject config = JavaScriptObjectHelper.createObject();
126: JavaScriptObjectHelper.setAttribute(config, "url", url);
127: if (timeout > 0)
128: JavaScriptObjectHelper.setAttribute(config, "timeout",
129: timeout);
130: jsObj = create(config);
131: }
132:
133: /**
134: * Construct a new ScriptTagProxy.
135: *
136: * @param url the URL from which to request the data object.
137: * @param timeout the number of milliseconds to wait for a response. Defaults to 30 seconds.
138: * @param callbackParam the name of the parameter to pass to the server which tells the server the name of the callback function set up by the load call to process the returned data object. Defaults to "callback".
139: * The server-side processing must read this parameter value, and generate javascript output which calls this named function passing the data object as its only parameter.
140: */
141: public ScriptTagProxy(String url, int timeout, String callbackParam) {
142: JavaScriptObject config = JavaScriptObjectHelper.createObject();
143: JavaScriptObjectHelper.setAttribute(config, "url", url);
144: if (callbackParam != null)
145: JavaScriptObjectHelper.setAttribute(config,
146: "callbackParam", callbackParam);
147: if (timeout > 0)
148: JavaScriptObjectHelper.setAttribute(config, "timeout",
149: timeout);
150: jsObj = create(config);
151: }
152:
153: protected native JavaScriptObject create(JavaScriptObject config) /*-{
154: return new $wnd.Ext.data.ScriptTagProxy(config);
155: }-*/;
156: }
|