PDA

View Full Version : Documentation for object-literal based configs



alexmcmillan
7 Apr 2014, 4:51 PM
I am learning ExtJS. It appears very heavy on "config" objects, most of which are object literals. These configuration objects do not appear in Sencha Docs, as far as I can see.

Example:

I follow a tutorial on creating a store and populating it via an Ajax proxy. The proxy configuration is displayed like so:


proxy: { type: 'rest', url: '/api/option/colors' reader: { type: 'json', root: 'data', totalProperty: 'count' }}(This is a configuration object specified in the definition of a class extending Ext.data.Store.)

According to this document at SenchaDocs (http://docs-origin.sencha.com/extjs/4.2.1/#!/api/Ext.data.Store-cfg-proxy), the "proxy" config can be one of 3 types: a String, an Ext.data.proxy.Proxy, or an Object. Here, we are clearly using an Object. The keys specified do not appear in the documentation (http://docs-origin.sencha.com/extjs/4.2.1/#!/api/Ext.data.proxy.Proxy) for an Ext.data.proxy.Proxy and the links to "String" and "Object" are irrelevant, showing only general information about their meaning.

How are beginners expected to understand these configurations and learn the possible options and values? Where is the documentation for the "type" option for a proxy defined as an object (like above)? Where is the documentation for the "type" option for a reader defined as an object? What values are available? What do those values actually mean?

skirtle
9 Apr 2014, 1:47 AM
There does seem to be a lack of documentation on this. This style is used throughout the examples but it isn't always clear how the mechanism works. It's a recurring pattern throughout the framework so once you've understand it in one place it should be obvious everywhere else. This makes it difficult to know where to document it without being highly repetitive.

The gist is that configs are turned into proper objects via a class alias. The type of object to create is determined by the type, xtype, ptype, etc. in the config. That type specifies the final part of the alias. The first part of the alias is determined by where the config is used.

So, in the REST proxy example, the type is given as 'rest'. For proxies the prefix is 'proxy.'. Combine these two bits and you get the alias 'proxy.rest'.

You'll notice that for most classes in the docs the relevant type is documented right at the top (immediately after the class name).

alexmcmillan
9 Apr 2014, 2:05 PM
Thanks :)

Does this mean, for example, that if I am working with a YYY and specify a "type" of XXX, I can then go on to specify any and all configuration options that exist on the class Ext.YYY.XXX (assuming it has the expected alias) ?

skirtle
10 Apr 2014, 2:58 AM
I believe the answer to your question is yes.

A config is used to create an object. The type config is a special case that allows you to specify which class to use (via its alias). The config is then passed to the constructor for that class.

However, it's important to note that the aliases and the class names are not necessarily linked in the way your question implies. The alias could, theoretically, have nothing in common with the class name or namespace.

If you haven't already, I strongly suggest digging into the source code for some of this stuff to give yourself a better understanding of how it all works. The docs app provides direct links to the relevant source files. You won't understand most of it at first but what little you do understand will go a long way. The source will usually give you a faster, more accurate and more complete answer than asking a question on the forums.