3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
18 * This class is a base for all id generators. It also provides lookup of id generators by
21 * Generally, id generators are used to generate a primary key for new model instances. There
22 * are different approaches to solving this problem, so this mechanism has both simple use
23 * cases and is open to custom implementations. A {@link Ext.data.Model} requests id generation
24 * using the {@link Ext.data.Model#idgen} property.
26 * # Identity, Type and Shared IdGenerators
28 * It is often desirable to share IdGenerators to ensure uniqueness or common configuration.
29 * This is done by giving IdGenerator instances an id property by which they can be looked
30 * up using the {@link #get} method. To configure two {@link Ext.data.Model Model} classes
31 * to share one {@link Ext.data.SequentialIdGenerator sequential} id generator, you simply
32 * assign them the same id:
34 * Ext.define('MyApp.data.MyModelA', {
35 * extend: 'Ext.data.Model',
42 * Ext.define('MyApp.data.MyModelB', {
43 * extend: 'Ext.data.Model',
50 * To make this as simple as possible for generator types that are shared by many (or all)
51 * Models, the IdGenerator types (such as 'sequential' or 'uuid') are also reserved as
52 * generator id's. This is used by the {@link Ext.data.UuidGenerator} which has an id equal
53 * to its type ('uuid'). In other words, the following Models share the same generator:
55 * Ext.define('MyApp.data.MyModelX', {
56 * extend: 'Ext.data.Model',
60 * Ext.define('MyApp.data.MyModelY', {
61 * extend: 'Ext.data.Model',
65 * This can be overridden (by specifying the id explicitly), but there is no particularly
66 * good reason to do so for this generator type.
68 * # Creating Custom Generators
70 * An id generator should derive from this class and implement the {@link #generate} method.
71 * The constructor will apply config properties on new instances, so a constructor is often
74 * To register an id generator type, a derived class should provide an `alias` like so:
76 * Ext.define('MyApp.data.CustomIdGenerator', {
77 * extend: 'Ext.data.IdGenerator',
78 * alias: 'idgen.custom',
80 * configProp: 42, // some config property w/default value
82 * generate: function () {
83 * return ... // a new id
87 * Using the custom id generator is then straightforward:
89 * Ext.define('MyApp.data.MyModel', {
90 * extend: 'Ext.data.Model',
95 * Ext.define('MyApp.data.MyModel', {
96 * extend: 'Ext.data.Model',
103 * It is not recommended to mix shared generators with generator configuration. This leads
104 * to unpredictable results unless all configurations match (which is also redundant). In
105 * such cases, a custom generator with a default id is the best approach.
107 * Ext.define('MyApp.data.CustomIdGenerator', {
108 * extend: 'Ext.data.SequentialIdGenerator',
109 * alias: 'idgen.custom',
111 * id: 'custom', // shared by default
117 * Ext.define('MyApp.data.MyModelX', {
118 * extend: 'Ext.data.Model',
122 * Ext.define('MyApp.data.MyModelY', {
123 * extend: 'Ext.data.Model',
127 * // the above models share a generator that produces ID_1000, ID_1001, etc..
130 Ext.define('Ext.data.IdGenerator', {
135 * Initializes a new instance.
136 * @param {Object} config (optional) Configuration object to be applied to the new instance.
138 constructor: function(config) {
141 Ext.apply(me, config);
144 Ext.data.IdGenerator.all[me.id] = me;
150 * The id by which to register a new instance. This instance can be found using the
151 * {@link Ext.data.IdGenerator#get} static method.
154 getRecId: function (rec) {
155 return rec.modelName + '-' + rec.internalId;
159 * Generates and returns the next id. This method must be implemented by the derived
162 * @return {String} The next id.
169 * @property {Object} all
170 * This object is keyed by id to lookup instances.
177 * Returns the IdGenerator given its config description.
178 * @param {String/Object} config If this parameter is an IdGenerator instance, it is
179 * simply returned. If this is a string, it is first used as an id for lookup and
180 * then, if there is no match, as a type to create a new instance. This parameter
181 * can also be a config object that contains a `type` property (among others) that
182 * are used to create and configure the instance.
185 get: function (config) {
190 if (typeof config == 'string') {
193 } else if (config.isGenerator) {
196 id = config.id || config.type;
200 generator = this.all[id];
202 generator = Ext.create('idgen.' + type, config);