Documentation Bugs - Ext 2.x

[mjlecomte]

Class Ext.layout.ContainerLayout
Package: Ext.layout
Defined In: ContainerLayout.js
Class: ContainerLayout
Subclasses: AnchorLayout, BorderLayout, ColumnLayout, FitLayout, TableLayout
Extends: Object

Currently:

Every layout is composed of one or more Ext.Container elements internally, and ContainerLayout provides the basic foundation for all other layout classes in Ext. It is a non-visual class that simply provides the base logic required for a Container to function as a layout. This class is intended to be extended and should generally not need to be created directly via the new keyword.

Ext overview has this which is worded a little better IMO:
[QUOTE]This is the base class for all other layout managers, and the default layout for containers when a specific layout is not defined. ContainerLayout has no visual representation

[mjlecomte]

Class Ext.layout.FormLayout
Package: Ext.layout
Defined In: FormLayout.js
Class: FormLayout
Extends: AnchorLayout

Currently

This is a layout specifically designed for creating forms. This class can be extended or created via the layout:'form' Ext.Container.layout config, and should generally not need to be created directly via the new keyword. However, when used in an application, it will usually be preferrable to use a Ext.form.FormPanel (which automatically uses FormLayout as its layout class) since it also provides built-in functionality for loading, validating and submitting the form.

Note that when creating a layout via config, the layout-specific config properties must be passed in via the Ext.Container.layoutConfig object which will then be applied internally to the layout. The container using the FormLayout can also supply the following form-specific config properties which will be applied by the layout:

The part in bold red is missing from the API and would be helpful:

The FormLayout is a utility layout specifically designed for creating data entry forms. Note that, in general, you will likely want to use a FormPanel rather than a regular Panel with layout:'form' since FormPanels also provide automatic form submission handling. FormPanels must use layout:'form' (this cannot be changed), so forms needing additional layout styles should use nested Panels to provide them.

[mjlecomte]

Class Ext.Container

Member: layout

Current:

The layout type to be used in this container. If not specified, a default Ext.layout.ContainerLayout will be created and used. Valid values are: absolute, accordion, anchor, border, card, column, fit, form and table. Specific config values for the chosen layout type can be specified using layoutConfig.

Proposed:

The layout type to be used in this container. If not specified, a default Ext.layout.ContainerLayout will be created and used. Valid values are: absolute, accordion, anchor, border, card, column, container, fit, form and table . Specific config values for the chosen layout type can be specified using layoutConfig.

Add in more background paraphrased from overview:

[QUOTE]Layouts are also managed by Ext so that size, position, scroll and other attributes. You can mix and match different containers, each with a different layout, nesting to any level you want.

Layouts are created and used internally by the container classes. Containers themselves know nothing about layout

[mjlecomte]

Class Ext.grid.GroupingView

Currently

Adds the ability for single level grouping to the grid.

Propose additions from overview:

Adds the ability for single level grouping to the grid so rows can be grouped on a given column, and regrouped by the user dynamically. Each group of rows can also have an optional summary row for summarizing the data in the group.

Mention link to the example/demo or show a code snippet example (entire example code below for reference .... clip out the extraneous?):

    // define a custom summary function
    Ext.grid.GroupSummary.Calculations['totalCost'] = function(v, record, field){
        return v + (record.data.estimate * record.data.rate);
    }

    var summary = new Ext.grid.GroupSummary(); 

    var grid = new xg.EditorGridPanel({
        ds: new Ext.data.GroupingStore({
            reader: reader,
            data: xg.dummyData,
            sortInfo:{field: 'due', direction: "ASC"},
            groupField:'project'
        }),

        columns: [
            {
                id: 'description',
                header: "Task",
                width: 80,
                sortable: true,
                dataIndex: 'description',
                summaryType: 'count',
                hideable: false,
                summaryRenderer: function(v, params, data){
                    return ((v === 0 || v > 1) ? '(' + v +' Tasks)' : '(1 Task)');
                },
                editor: new Ext.form.TextField({
                   allowBlank: false
                })
            },{
                header: "Project",
                width: 20,
                sortable: true,
                dataIndex: 'project'
            },{
                header: "Due Date",
                width: 25,
                sortable: true,
                dataIndex: 'due',
                summaryType:'max',
                renderer: Ext.util.Format.dateRenderer('m/d/Y'),
                editor: new Ext.form.DateField({
                    format: 'm/d/Y'
                })
            },{
                header: "Estimate",
                width: 20,
                sortable: true,
                dataIndex: 'estimate',
                summaryType:'sum',
                renderer : function(v){
                    return v +' hours';
                },
                editor: new Ext.form.NumberField({
                   allowBlank: false,
                   allowNegative: false,
                   style: 'text-align:left'
                })
            },{
                header: "Rate",
                width: 20,
                sortable: true,
                renderer: Ext.util.Format.usMoney,
                dataIndex: 'rate',
                summaryType:'average',
                editor: new Ext.form.NumberField({
                    allowBlank: false,
                    allowNegative: false,
                    style: 'text-align:left'
                })
            },{
                id: 'cost',
                header: "Cost",
                width: 20,
                sortable: false,
                groupable: false,
                renderer: function(v, params, record){
                    return Ext.util.Format.usMoney(record.data.estimate * record.data.rate);
                },
                dataIndex: 'cost',
                summaryType:'totalCost',
                summaryRenderer: Ext.util.Format.usMoney
            }
        ],

        view: new Ext.grid.GroupingView({
            forceFit:true,
            showGroupName: false,
            enableNoGroups:false, // REQUIRED!
            hideGroupedColumn: true
        }),

        plugins: summary,

        frame:true,
        width: 800,
        height: 450,
        clicksToEdit: 1,
        collapsible: true,
        animCollapse: false,
        trackMouseOver: false,
        //enableColumnMove: false,
        title: 'Sponsored Projects',
        iconCls: 'icon-grid',
        renderTo: document.body
    });
});

[mjlecomte]

Class Ext.Viewport

This appears to be missing from the discussion:

Note that the Viewport cannot be rendered to any container other than document.body, and as such, you can only use one Viewport instance per page.

[mjlecomte]

This blurb should be added to the top of Container:

Use XTypes to optimize Component creation and rendering. Any Component can be created implicitly as an object config with an xtype specified, allowing it to be declared and passed into the rendering pipeline without actually being instantiated as an object. Not only is rendering deferred, but the actual creation of the object itself is also deferred, saving memory and resources until they are actually needed. In complex, nested layouts containing many Components, this can make a noticeable improvement in performance.

//Explicit creation of contained Components:
var panel = new Ext.Panel({
   ...
   items: [
      new Ext.Button({
         text: 'OK'
      })
   ]
};
 
//Implicit creation using xtype:
var panel = new Ext.Panel({
   ...
   items: [{
      xtype: 'button',
      text: 'OK'
   }]
};

In the first example, the button will always be created immediately during the panel's initialization. With many added Components, this approach could potentially slow the rendering of the page. In the second example, the button will not be created or rendered until the panel is actually displayed in the browser. If the panel is never displayed (for example, if it is a tab that remains hidden) then the button will never be created and will never consume any resources whatsoever.

[mjlecomte]

Class Ext.Button
Package: Ext
Defined In: Button.js
Class: Button

Missing description for formBind config.

Only applicable for buttons in an Ext.FormPanel...blah blah...cross link with monitorValid of FormPanel.

[saJoshua]

Class Ext.grid.EditorGridPanel
Package : Ext
Defined in : EditorGrid.js

Class Ext.grid.GridPanel
Package : Ext
Defined in : GridPanel.js

Class Ext.grid.PropertyGrid
Package : Ext
Defined in : PropertyGrid.js

Missing description for setDisabled config.

There is also a dead link pointing to where the missing description should be, when searching from the welcome page in docs.

[mjlecomte]

saJoshua you don't say why you think it should be shown or where it's listed in the docs now with the dead link?

Ext Team:

It looks like setDisabled is a method (not config) of Component.

Is this a problem with the jsDoc algorithm or how it's currently tagged? I say this because just before setDisabled is "//private". Keep going upward in the file and look at all the places it is marked "//private"....the next property afterwards doesn't show up in the docs even if it has description. So it appears the private tag is cascading down to the next properties??

[mjlecomte]

http://extjs.com/deploy/dev/docs/?cl...&member=create

As reported here the example is wrong:

currently:

var TopicRecord = Ext.data.Record.create([
    {name: 'title', mapping: 'topic_title'},
    {name: 'author', mapping: 'username'},
    {name: 'totalPosts', mapping: 'topic_replies', type: 'int'},
    {name: 'lastPost', mapping: 'post_time', type: 'date'},
    {name: 'lastPoster', mapping: 'user2'},
    {name: 'excerpt', mapping: 'post_text'}
]);

var myNewRecord = new TopicRecord({
    topic_title title: 'Do my job please',
    username author: 'noobie',
    topic_replies totalPosts: 1,
    //etc
});
myStore.add(myNewRecord);