/ext-4.0.7/docs/source/Controller.html

https://bitbucket.org/srogerf/javascript · HTML · 430 lines · 395 code · 35 blank · 0 comment · 0 complexity · a5d6bbfb4420e0cb978a64db8e8e3a88 MD5 · raw file

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  5. <title>The source code</title>
  6. <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
  7. <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
  8. <style type="text/css">
  9. .highlight { display: block; background-color: #ddd; }
  10. </style>
  11. <script type="text/javascript">
  12. function highlight() {
  13. document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14. }
  15. </script>
  16. </head>
  17. <body onload="prettyPrint(); highlight();">
  18. <pre class="prettyprint lang-js"><span id='Ext-app-Controller'>/**
  19. </span> * @class Ext.app.Controller
  20. *
  21. * Controllers are the glue that binds an application together. All they really do is listen for events (usually from
  22. * views) and take some action. Here's how we might create a Controller to manage Users:
  23. *
  24. * Ext.define('MyApp.controller.Users', {
  25. * extend: 'Ext.app.Controller',
  26. *
  27. * init: function() {
  28. * console.log('Initialized Users! This happens before the Application launch function is called');
  29. * }
  30. * });
  31. *
  32. * The init function is a special method that is called when your application boots. It is called before the
  33. * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
  34. * your Viewport is created.
  35. *
  36. * The init function is a great place to set up how your controller interacts with the view, and is usually used in
  37. * conjunction with another Controller function - {@link Ext.app.Controller#control control}. The control function
  38. * makes it easy to listen to events on your view classes and take some action with a handler function. Let's update
  39. * our Users controller to tell us when the panel is rendered:
  40. *
  41. * Ext.define('MyApp.controller.Users', {
  42. * extend: 'Ext.app.Controller',
  43. *
  44. * init: function() {
  45. * this.control({
  46. * 'viewport &gt; panel': {
  47. * render: this.onPanelRendered
  48. * }
  49. * });
  50. * },
  51. *
  52. * onPanelRendered: function() {
  53. * console.log('The panel was rendered');
  54. * }
  55. * });
  56. *
  57. * We've updated the init function to use this.control to set up listeners on views in our application. The control
  58. * function uses the new ComponentQuery engine to quickly and easily get references to components on the page. If you
  59. * are not familiar with ComponentQuery yet, be sure to check out the {@link Ext.ComponentQuery documentation}. In brief though,
  60. * it allows us to pass a CSS-like selector that will find every matching component on the page.
  61. *
  62. * In our init function above we supplied 'viewport &gt; panel', which translates to &quot;find me every Panel that is a direct
  63. * child of a Viewport&quot;. We then supplied an object that maps event names (just 'render' in this case) to handler
  64. * functions. The overall effect is that whenever any component that matches our selector fires a 'render' event, our
  65. * onPanelRendered function is called.
  66. *
  67. * &lt;u&gt;Using refs&lt;/u&gt;
  68. *
  69. * One of the most useful parts of Controllers is the new ref system. These use the new {@link Ext.ComponentQuery} to
  70. * make it really easy to get references to Views on your page. Let's look at an example of this now:
  71. *
  72. * Ext.define('MyApp.controller.Users', {
  73. * extend: 'Ext.app.Controller',
  74. *
  75. * refs: [
  76. * {
  77. * ref: 'list',
  78. * selector: 'grid'
  79. * }
  80. * ],
  81. *
  82. * init: function() {
  83. * this.control({
  84. * 'button': {
  85. * click: this.refreshGrid
  86. * }
  87. * });
  88. * },
  89. *
  90. * refreshGrid: function() {
  91. * this.getList().store.load();
  92. * }
  93. * });
  94. *
  95. * This example assumes the existence of a {@link Ext.grid.Panel Grid} on the page, which contains a single button to
  96. * refresh the Grid when clicked. In our refs array, we set up a reference to the grid. There are two parts to this -
  97. * the 'selector', which is a {@link Ext.ComponentQuery ComponentQuery} selector which finds any grid on the page and
  98. * assigns it to the reference 'list'.
  99. *
  100. * By giving the reference a name, we get a number of things for free. The first is the getList function that we use in
  101. * the refreshGrid method above. This is generated automatically by the Controller based on the name of our ref, which
  102. * was capitalized and prepended with get to go from 'list' to 'getList'.
  103. *
  104. * The way this works is that the first time getList is called by your code, the ComponentQuery selector is run and the
  105. * first component that matches the selector ('grid' in this case) will be returned. All future calls to getList will
  106. * use a cached reference to that grid. Usually it is advised to use a specific ComponentQuery selector that will only
  107. * match a single View in your application (in the case above our selector will match any grid on the page).
  108. *
  109. * Bringing it all together, our init function is called when the application boots, at which time we call this.control
  110. * to listen to any click on a {@link Ext.button.Button button} and call our refreshGrid function (again, this will
  111. * match any button on the page so we advise a more specific selector than just 'button', but have left it this way for
  112. * simplicity). When the button is clicked we use out getList function to refresh the grid.
  113. *
  114. * You can create any number of refs and control any number of components this way, simply adding more functions to
  115. * your Controller as you go. For an example of real-world usage of Controllers see the Feed Viewer example in the
  116. * examples/app/feed-viewer folder in the SDK download.
  117. *
  118. * &lt;u&gt;Generated getter methods&lt;/u&gt;
  119. *
  120. * Refs aren't the only thing that generate convenient getter methods. Controllers often have to deal with Models and
  121. * Stores so the framework offers a couple of easy ways to get access to those too. Let's look at another example:
  122. *
  123. * Ext.define('MyApp.controller.Users', {
  124. * extend: 'Ext.app.Controller',
  125. *
  126. * models: ['User'],
  127. * stores: ['AllUsers', 'AdminUsers'],
  128. *
  129. * init: function() {
  130. * var User = this.getUserModel(),
  131. * allUsers = this.getAllUsersStore();
  132. *
  133. * var ed = new User({name: 'Ed'});
  134. * allUsers.add(ed);
  135. * }
  136. * });
  137. *
  138. * By specifying Models and Stores that the Controller cares about, it again dynamically loads them from the appropriate
  139. * locations (app/model/User.js, app/store/AllUsers.js and app/store/AdminUsers.js in this case) and creates getter
  140. * functions for them all. The example above will create a new User model instance and add it to the AllUsers Store.
  141. * Of course, you could do anything in this function but in this case we just did something simple to demonstrate the
  142. * functionality.
  143. *
  144. * &lt;u&gt;Further Reading&lt;/u&gt;
  145. *
  146. * For more information about writing Ext JS 4 applications, please see the
  147. * [application architecture guide](#/guide/application_architecture). Also see the {@link Ext.app.Application} documentation.
  148. *
  149. * @docauthor Ed Spencer
  150. */
  151. Ext.define('Ext.app.Controller', {
  152. mixins: {
  153. observable: 'Ext.util.Observable'
  154. },
  155. <span id='Ext-app-Controller-cfg-id'> /**
  156. </span> * @cfg {String} id The id of this controller. You can use this id when dispatching.
  157. */
  158. <span id='Ext-app-Controller-cfg-models'> /**
  159. </span> * @cfg {String[]} models
  160. * Array of models to require from AppName.model namespace. For example:
  161. *
  162. * Ext.define(&quot;MyApp.controller.Foo&quot;, {
  163. * extend: &quot;Ext.app.Controller&quot;,
  164. * models: ['User', 'Vehicle']
  165. * });
  166. *
  167. * This is equivalent of:
  168. *
  169. * Ext.define(&quot;MyApp.controller.Foo&quot;, {
  170. * extend: &quot;Ext.app.Controller&quot;,
  171. * requires: ['MyApp.model.User', 'MyApp.model.Vehicle']
  172. * });
  173. *
  174. */
  175. <span id='Ext-app-Controller-cfg-views'> /**
  176. </span> * @cfg {String[]} views
  177. * Array of views to require from AppName.view namespace. For example:
  178. *
  179. * Ext.define(&quot;MyApp.controller.Foo&quot;, {
  180. * extend: &quot;Ext.app.Controller&quot;,
  181. * views: ['List', 'Detail']
  182. * });
  183. *
  184. * This is equivalent of:
  185. *
  186. * Ext.define(&quot;MyApp.controller.Foo&quot;, {
  187. * extend: &quot;Ext.app.Controller&quot;,
  188. * requires: ['MyApp.view.List', 'MyApp.view.Detail']
  189. * });
  190. *
  191. */
  192. <span id='Ext-app-Controller-cfg-stores'> /**
  193. </span> * @cfg {String[]} stores
  194. * Array of stores to require from AppName.store namespace. For example:
  195. *
  196. * Ext.define(&quot;MyApp.controller.Foo&quot;, {
  197. * extend: &quot;Ext.app.Controller&quot;,
  198. * stores: ['Users', 'Vehicles']
  199. * });
  200. *
  201. * This is equivalent of:
  202. *
  203. * Ext.define(&quot;MyApp.controller.Foo&quot;, {
  204. * extend: &quot;Ext.app.Controller&quot;,
  205. * requires: ['MyApp.store.Users', 'MyApp.store.Vehicles']
  206. * });
  207. *
  208. */
  209. onClassExtended: function(cls, data) {
  210. var className = Ext.getClassName(cls),
  211. match = className.match(/^(.*)\.controller\./);
  212. if (match !== null) {
  213. var namespace = Ext.Loader.getPrefix(className) || match[1],
  214. onBeforeClassCreated = data.onBeforeClassCreated,
  215. requires = [],
  216. modules = ['model', 'view', 'store'],
  217. prefix;
  218. data.onBeforeClassCreated = function(cls, data) {
  219. var i, ln, module,
  220. items, j, subLn, item;
  221. for (i = 0,ln = modules.length; i &lt; ln; i++) {
  222. module = modules[i];
  223. items = Ext.Array.from(data[module + 's']);
  224. for (j = 0,subLn = items.length; j &lt; subLn; j++) {
  225. item = items[j];
  226. prefix = Ext.Loader.getPrefix(item);
  227. if (prefix === '' || prefix === item) {
  228. requires.push(namespace + '.' + module + '.' + item);
  229. }
  230. else {
  231. requires.push(item);
  232. }
  233. }
  234. }
  235. Ext.require(requires, Ext.Function.pass(onBeforeClassCreated, arguments, this));
  236. };
  237. }
  238. },
  239. <span id='Ext-app-Controller-method-constructor'> /**
  240. </span> * Creates new Controller.
  241. * @param {Object} config (optional) Config object.
  242. */
  243. constructor: function(config) {
  244. this.mixins.observable.constructor.call(this, config);
  245. Ext.apply(this, config || {});
  246. this.createGetters('model', this.models);
  247. this.createGetters('store', this.stores);
  248. this.createGetters('view', this.views);
  249. if (this.refs) {
  250. this.ref(this.refs);
  251. }
  252. },
  253. <span id='Ext-app-Controller-method-init'> /**
  254. </span> * A template method that is called when your application boots. It is called before the
  255. * {@link Ext.app.Application Application}'s launch function is executed so gives a hook point to run any code before
  256. * your Viewport is created.
  257. *
  258. * @param {Ext.app.Application} application
  259. * @template
  260. */
  261. init: function(application) {},
  262. <span id='Ext-app-Controller-method-onLaunch'> /**
  263. </span> * A template method like {@link #init}, but called after the viewport is created.
  264. * This is called after the {@link Ext.app.Application#launch launch} method of Application is executed.
  265. *
  266. * @param {Ext.app.Application} application
  267. * @template
  268. */
  269. onLaunch: function(application) {},
  270. createGetters: function(type, refs) {
  271. type = Ext.String.capitalize(type);
  272. Ext.Array.each(refs, function(ref) {
  273. var fn = 'get',
  274. parts = ref.split('.');
  275. // Handle namespaced class names. E.g. feed.Add becomes getFeedAddView etc.
  276. Ext.Array.each(parts, function(part) {
  277. fn += Ext.String.capitalize(part);
  278. });
  279. fn += type;
  280. if (!this[fn]) {
  281. this[fn] = Ext.Function.pass(this['get' + type], [ref], this);
  282. }
  283. // Execute it right away
  284. this[fn](ref);
  285. },
  286. this);
  287. },
  288. ref: function(refs) {
  289. var me = this;
  290. refs = Ext.Array.from(refs);
  291. Ext.Array.each(refs, function(info) {
  292. var ref = info.ref,
  293. fn = 'get' + Ext.String.capitalize(ref);
  294. if (!me[fn]) {
  295. me[fn] = Ext.Function.pass(me.getRef, [ref, info], me);
  296. }
  297. });
  298. },
  299. getRef: function(ref, info, config) {
  300. this.refCache = this.refCache || {};
  301. info = info || {};
  302. config = config || {};
  303. Ext.apply(info, config);
  304. if (info.forceCreate) {
  305. return Ext.ComponentManager.create(info, 'component');
  306. }
  307. var me = this,
  308. selector = info.selector,
  309. cached = me.refCache[ref];
  310. if (!cached) {
  311. me.refCache[ref] = cached = Ext.ComponentQuery.query(info.selector)[0];
  312. if (!cached &amp;&amp; info.autoCreate) {
  313. me.refCache[ref] = cached = Ext.ComponentManager.create(info, 'component');
  314. }
  315. if (cached) {
  316. cached.on('beforedestroy', function() {
  317. me.refCache[ref] = null;
  318. });
  319. }
  320. }
  321. return cached;
  322. },
  323. <span id='Ext-app-Controller-method-control'> /**
  324. </span> * Adds listeners to components selected via {@link Ext.ComponentQuery}. Accepts an
  325. * object containing component paths mapped to a hash of listener functions.
  326. *
  327. * In the following example the `updateUser` function is mapped to to the `click`
  328. * event on a button component, which is a child of the `useredit` component.
  329. *
  330. * Ext.define('AM.controller.Users', {
  331. * init: function() {
  332. * this.control({
  333. * 'useredit button[action=save]': {
  334. * click: this.updateUser
  335. * }
  336. * });
  337. * },
  338. *
  339. * updateUser: function(button) {
  340. * console.log('clicked the Save button');
  341. * }
  342. * });
  343. *
  344. * See {@link Ext.ComponentQuery} for more information on component selectors.
  345. *
  346. * @param {String/Object} selectors If a String, the second argument is used as the
  347. * listeners, otherwise an object of selectors -&gt; listeners is assumed
  348. * @param {Object} listeners
  349. */
  350. control: function(selectors, listeners) {
  351. this.application.control(selectors, listeners, this);
  352. },
  353. <span id='Ext-app-Controller-method-getController'> /**
  354. </span> * Returns instance of a {@link Ext.app.Controller controller} with the given name.
  355. * When controller doesn't exist yet, it's created.
  356. * @param {String} name
  357. * @return {Ext.app.Controller} a controller instance.
  358. */
  359. getController: function(name) {
  360. return this.application.getController(name);
  361. },
  362. <span id='Ext-app-Controller-method-getStore'> /**
  363. </span> * Returns instance of a {@link Ext.data.Store Store} with the given name.
  364. * When store doesn't exist yet, it's created.
  365. * @param {String} name
  366. * @return {Ext.data.Store} a store instance.
  367. */
  368. getStore: function(name) {
  369. return this.application.getStore(name);
  370. },
  371. <span id='Ext-app-Controller-method-getModel'> /**
  372. </span> * Returns a {@link Ext.data.Model Model} class with the given name.
  373. * A shorthand for using {@link Ext.ModelManager#getModel}.
  374. * @param {String} name
  375. * @return {Ext.data.Model} a model class.
  376. */
  377. getModel: function(model) {
  378. return this.application.getModel(model);
  379. },
  380. <span id='Ext-app-Controller-method-getView'> /**
  381. </span> * Returns a View class with the given name. To create an instance of the view,
  382. * you can use it like it's used by Application to create the Viewport:
  383. *
  384. * this.getView('Viewport').create();
  385. *
  386. * @param {String} name
  387. * @return {Ext.Base} a view class.
  388. */
  389. getView: function(view) {
  390. return this.application.getView(view);
  391. }
  392. });
  393. </pre>
  394. </body>
  395. </html>