Custom Components. Introduction and First Example

In Ext JS, building custom components is a powerful way to extend the framework’s capabilities and create reusable, modular UI elements tailored to your application’s specific needs.

They are user-defined classes that extend existing Ext JS components or base classes, allowing developers to encapsulate layout, logic, configuration, and behavior into reusable building blocks. These components are typically created by extending classes such as Ext.Component, Ext.panel.Panel, or any other core widget. They can be easily integrated into larger applications.

They improve maintainability and consistency by:

• Encapsulating logic and UI in one place
• Allowing reuse across multiple views or applications
• Supporting standard Ext JS features like event handling, data binding, and layout management

Best Practices

When developing custom components in Ext JS, following a consistent structure and naming convention helps maintain code clarity, reusability, and scalability.

Organize Components in a Dedicated Folder

While Ext JS allows you to save components anywhere in your project’s folder structure, it is strongly recommended to place custom components in a dedicated folder—typically named ux, short for user extensions. This clearly distinguishes your custom-built components from core Ext JS classes and application-specific views.

Recommended folder structure:
App/ux/ComponentName.js

Use Consistent Naming Conventions

Custom components should follow a consistent and descriptive naming pattern. A good convention is to prefix them with your app’s namespace followed by ux, and then the component name in PascalCase.

Example:

• App.ux.Timeline,
• App.ux.DataGrid,
• App.ux.FilterPanel

This makes components easily identifiable and avoids naming collisions with built-in or third-party components.

Extend the Most Relevant Base Class

Always extend from an existing Ext JS class that closely matches the functionality you’re aiming to achieve. This minimizes the amount of code you need to write and ensures better integration with the Ext JS ecosystem.

For example, if you’re building a custom data display panel, you might extend from Ext.panel.Panel or Ext.dataview.DataView.

Define Local Parameters Using the config Property

All configurable options and local parameters should be defined under the config block. This ensures that your component is compatible with Ext JS’s configuration system, enabling automatic getter/setter generation, event binding, and reactive updates.

config: {
	title: 'Default Title',
	data: null,
	scrollable: true
}

This approach keeps your component clean, manageable, and easily configurable by developers using it.

Design for Flexibility and Reusability

Make your component as flexible and configurable as possible. Avoid hardcoding values or behaviors; instead, expose properties, events, and hooks that can be customized or overridden by consuming views.

Key areas to consider for flexibility:

• Allow overriding templates (tpl) or layout options
• Provide configuration for data sources or display logic
• Emit custom events to notify parent components of state changes
• Avoid tight coupling with specific models, stores, or controllers

By designing with reusability in mind, you increase the longevity and utility of your components across different modules and projects.

Include Custom CSS

If your component uses custom CSS:

• Ensure the styles are scoped
• Rebuild and refresh your application with sencha command to apply styles
• Alternatively, run sencha app watch to automatically compile your CSS and keep your app in sync with changes

Document Your Component

Documentation is essential for long-term maintainability. Your component class should include:

• A clear description of its purpose
• A list of available config options
• Events it handles
• Public methods and their intended usage

Inline JSDoc comments are helpful for IDEs and code readers alike.

Provide Usage Examples

Include a sample implementation or usage block (in a comment or demo file) to demonstrate how the component should be instantiated and configured.

First Example. Pointless Component

The Pointless Component is a deliberately simple, beginner-friendly custom component built by extending the Ext.Button class in Ext JS. While the functionality may be minimal—and arguably “pointless”—it serves an important purpose: introducing the foundational concepts of component creation and configuration in Ext JS.

What It Does

This custom component acts like a standard button, but with some extra functionality:

• Each time the button is clicked, its label updates to reflect a countdown.
• For example, if it starts at 5, clicking it changes the text to 4, then 3, and so on.

While not useful in a real-world application, this behavior allows us to explore key development concepts.

The Component

/**
 * @class App.ux.useless.PointlessButton
 * @extends Ext.button.Button
 * @xtype pointless-button
 *
 * A simple and intentionally "pointless" custom button component that demonstrates
 * basic Ext JS component principles such as configuration, event handling, and state management.
 *
 * With each click, the button decrements its `value` and updates its displayed text.
 *
 * ## Example usage:
 * ```javascript
 * {
 *     xtype: 'pointless-button',
 *     value: 10 // optional starting value, defaults to 100
 * }
 * ```
 */
Ext.define('App.ux.useless.PointlessButton', {
    extend: 'Ext.button.Button',
    xtype: 'pointless-button',
    /**
     * @cfg {Number} value
     * The initial numeric value to display and decrement with each click.
     * Defaults to `100` if not provided.
     */
    config: {
        value: 100
    },
    /**
     * @property {String} text
     * The text label of the button, which is updated based on `value`.
     */
    text: '',
    /**
     * @event click
     * Fired when the button is clicked. Decrements the `value` by 1 (until it reaches 0)
     * and updates the button's text to reflect the new value.
     */
    listeners: {
        click: function () {
            if (this.value > 0) {
                this.value--;
            }
            this.setText(this.value);
        }
    },
    /**
     * Initializes the component and sets the initial button text based on the `value`.
     * Called automatically during the component lifecycle.
     *
     * @protected
     */
    initComponent: function () {
        this.callParent();
        this.setText(this.value);
    }
});

Usage

Using the component is as simple as including it like any standard Ext JS component. Just reference its xtype and pass any custom configuration you need.

{
    xtype: 'pointlesscomponent',
    count: 3 // starts at 3 instead of the default 5
}

This will render the Pointless Component with a starting count of 3. Each click will decrement the number until it reaches zero.

What we learned

The Pointless Component we just created demonstrated several important Ext JS principles:

Create a Custom Component

• Extending an existing base class (Ext.Button) to create a new component.
• Introduced inheritance and class structure in Ext JS using Ext.define.

Receive and Use Parameters

• We used the config object to define initial parameters (e.g., a starting count).
• Learned how to pass values into the component and access them in your logic.

Handle Events and Update State

• By binding a click event, we triggered changes in the component’s UI.
• This illustrated event handling, updating UI dynamically, and stateful behavior.

Next Steps

This is the first installment in a 5-part series on building custom Ext JS components.
In the next tutorial, we’ll take things a step further by creating a toggle button using the Classic Toolkit.