Docs Help

Terms, Icons, and Labels

Many classes have shortcut names used when creating (instantiating) a class with a configuration object. The shortcut name is referred to as an alias (or xtype if the class extends Ext.Component). The alias/xtype is listed next to the class name of applicable classes for quick reference.

Access Levels

Framework classes or their members may be specified as private or protected. Else, the class / member is public. Public, protected, and private are access descriptors used to convey how and when the class or class member should be used.

Member Types

Member Syntax

Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).

lookupComponent ( item ) : Ext.Component
protected

Called when a raw config object is added to this container either during initialization of the items config, or when new items are added), or {@link #insert inserted.

This method converts the passed object into an instanced child component.

This may be overridden in subclasses when special processing needs to be applied to child creation.

Parameters

item :  Object

The config object being added.

Returns
Ext.Component

The component to be added.

Let's look at each part of the member row:

Member Flags

The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.

Class Icons

- Indicates a framework class

- A singleton framework class. *See the singleton flag for more information

- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)

- Indicates that the class, member, or guide is new in the currently viewed version

Member Icons

- Indicates a class member of type config

- Indicates a class member of type property

- Indicates a class member of type method

- Indicates a class member of type event

- Indicates a class member of type theme variable

- Indicates a class member of type theme mixin

- Indicates that the class, member, or guide is new in the currently viewed version

Class Member Quick-Nav Menu

Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.

Getter and Setter Methods

Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.

History Bar

Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.

Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.

If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.

Search and Filters

Both API docs and guides can be searched for using the search field at the top of the page.

On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level, inheritance, and read only. This is done using the checkboxes at the top of the page.

The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.

Clicking on an empty search field will show your last 10 searches for quick navigation.

API Doc Class Metadata

Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:

Expanding and Collapsing Examples and Class Members

Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.

Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.

Desktop -vs- Mobile View

Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:

Viewing the Class Source

The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.

Ext JS 7.0.0


top
premium

Exploring the Calendar

The Ext JS calendar is a powerful new component that allows users to incorporate their date and event data to create stunning custom calendars. The calendar utilizes a minimalistic design philosophy so that it can be extended to cater to any requirements. This minimalistic ideology extends to the data level as well.

The calendar package has been developed to excel in both toolkits, modern and classic. This means that you can create a cross platform solution to display your calendar information on any medium.

For a full example of the calendar integrated with Google Calendars, see our examples page.

You can also find smaller, and more specific examples in our Kitchen Sink:

Using the Calendar Package

Your calendar package should be located within the packages folder that came with your Ext JS Premium purchase. This packages folder should be copied to the root packages directory of the ext folder you use to generate applications.

For instance, if you have generated your application using Sencha Cmd, you would move the calendar package from:

{premiumLocation}/ext/packages/calendar

to:

{yourApplication}/ext/packages/calendar

or:

{yourWorkspace}/ext/packages/calendar

Once your package is in appropriately located, you'll need to modify your app.json file. Open {appDir}/app.json and add "calendar" to the "requires" block. It should now look like similar to the following code snippet:

"requires": [
   "calendar"
],

Do keep in mind that your requires block may contain other items depending on your default theme.

Your application should now be ready to use the calendar!

Note: The calendar package is only available in Ext Premium. For more information about Ext Premium and our other products, please check out the products page.

Calendar Without a Cmd Application

You can also utilize the calendar package without a Cmd built application. However, you may need to use Cmd to build the initial CSS/JS builds if they do not appear in your package's build folder.

We generally try to include pre-built packages, but sometimes they slip through the cracks and are not available until the next release.

Building a package is quick and simple. The process produces a singular JS/CSS file for inclusion in your non-Cmd application. To build these files, issue the following command from your CLI:

//target a specific theme
sencha package build {themeName}

Classic themes will just be theme names (triton, neptune, etc).

Modern themes will be prepended with "modern-" (modern-neptune).

or

//build for all themes
sencha package build

You should now have a build folder that contains the following built files:

calendar/{toolkit}/calendar.js
calendar/{toolkit}/{theme}/resources/calendar-all.css

You can now include these outputs by whatever method you are using.

Views

At the heart of it, the calendar package is a collection of views that digest and visualize data based on its timeframe (months, days, weeks, etc).

The most common form of the calendar is actually a composite of views, wrapped in panels (more about panels below).
This little snippet will create a full multi-view calendar that displays a compilation of the three most common calendar views (month, week, day).

Now that you've seen a few of the views in action, let's talk a little about each view in particular.

Weeks

Displays a series of weeks, one week per row. Days are arranged in a table like format, each cell represents a single day. There is no time axis for this view.

Week

The view range is calculated to show an entire week based on the value.

image alt text

Month

Displays a full month. The visible date range is calculated to show the entire month.

image alt text

Days

Displays a series of days, where each column represents a single day. A vertical time axis is included in this view.

Day

The same as the Days but restricted to a single day.

image alt text

Event Widgets

Each event visible in the view is a widget subclass. Similar to the data model, there is an API defined by Ext.calendar.EventBase and a default implementation in Ext.calendar.Event. The same event class is used across all views, however it is displayed in 3 modes (with matching sass mixins):

  • weekspan -> Used in view.Weeks for events that have a duration longer than 24 hours. Also used in view.Days for the all day view.

  • weekinline -> Used in view.Weeks for events that have a duration shorter than 24 hours.

  • day -> Used in the body of view.Days.

Timezones

The base view class has a timezone configuration that indicates the timezone to display events in. If one is not specified, it defaults to the current user TZ. This can affect how events are displayed, possibly even different days for the same event.

Compact mode

The base view class has a compact config. This boolean configures whether or not the view is in compact mode. It’s expected that this will be used as a platform config or a responsive config. Setting compact mode by itself does not modify how the view displays, however what it does do is apply the compactOptions config over the top over the current configuration options. These compactOptions are what is used to specify what compactness means for a particular view.

Promise based validation

UI events can require validation and the ability to veto them. For some events, a decision can’t be deferred (for example, starting a drag). However, things like dropping an event don’t require immediate processing to resolve. In fact, a remote source may need to be consulted to determine this. To do this in a consistent manner, promises are used to handle the possibly asynchronous nature of the validation. These validation events typically follow this pattern:

listeners: {
    validatefoo: : function(view, context) {

        context.validate = context.validate.then(function() {
            return true;
        });
    }
}

As we can see above there is a validate promise already on the context object. The user can chain onto the existing promise provided, or create a new one, however it is important that context.validate is overwritten by the time the event handler returns so the user promise can be consumed.

What's Next

Now that we've discussed the underlying views, let's talk about the things you'll be working with most often. Panels!

Panels

While the views themselves are the power behind the calendar, you will likely not interact them directly. Each view is wrapped in a panel that provide a lot of additional controls.

Remember this example?

Ext.calendar.panel.Panel is actually a composition panel that compiles three different panels into a single view. It also includes navigational controls, a title to show the active value, and a switcher control to navigate between the views. This is the view one would see for a calendar application and will probably be the most commonly consumed component by developers.

Let's look at the view panels that make up the composition panel.

Month

Month utilizes Ext.calendar.panel.Month

Week

Week utilizes Ext.calendar.panel.Week

Day

Day utilizes Ext.calendar.panel.Day.

In addition to the above three panels, there are also panels for the other two views not found in the combined class.

Days

Days utilizes Ext.calendar.panel.Days.

Weeks

Weeks utilizes Ext.calendar.panel.Weeks.

By virtue of being panels, all of these classes gain panel abilities (docking, titles, etc) in addition to including a base header class that can display header information.

These view wrappers relay events and configurations directly onto the panel itself This allows listeners, getters and setters to be called directly on the panel, without needing to do panel.getView().foo().

These panels don’t introduce any new functionality or modify the views in any way. They are just small convenience classes that introduce the headers.

Data

Data is an integral part of the calendar package. Since the calendar can display many different types of views, the data package brings some complexity.

Models

There are two data model types in the calendar package.

Calendar

The calendar model is essentially a group for events. Several calendars may be displayed on the same view. Typically, a calendar will hold events of a particular related type. The calendar has a method to return the store that will contain the events for that calendar.

Event

An event is an occurrence with a start date, end date, and duration. Each event must belong to one and only one calendar.

For each model type, there is a base (EventBase/CalendarBase) that defines the required interface to use these model types. They are declared as mixins, but have some abstract parts that must be implemented by the consuming class. The calendar package provides a default implementation of both model classes.

Getting and Setting Data

Throughout the calendar package, the get/set methods of a model are never called. Instead, all data is accessed/manipulated via getter and setter methods:

 record.setTitle(record.getTitle() + ‘!’); // Yes

  record.set(‘title’, record.get(‘title’) + ‘!’); // No

The calendar makes no assumptions about the structure of the data provided, only that it exists. This abstraction of data access ensures flexibility for a wide range of data structures to be used.

As an example of this concept, the default model implementation of Ext.calendar.model.Event has a startDate and endDate field on the model. The getDuration method is calculated based on these values. Another possible implementation could be to have a startDate and duration field on the model and have the getEndDate be a calculated quantity. The API makes no distinction here, as long as the EventBase interface is fulfilled.

Stores

There are 3 store types in the calendar package.

Calendars

The calendar store holds a list of Calendar. This small extension adds a method to return an EventSource for all calendars in this store (see below). This store type is the type of store bound to all views.

Events

The event store holds a list of Event for a particular Calendar. The store is typically created by calling the events method on a Calendar model. When used with a calendar view, this will happen automatically. The event store is intended to be filled for a particular date range, which should be governed by the appropriate view. This store type implements pre-fetching (and pruning) for a smoother experience when switching between dates in the view.

EventSource

The EventSource store holds an aggregated list of events for all calendars in a Calendars store, that are valid for a particular date range. This is a utility class used by the views as a single point of communication. The responsibility of this class is to control each Events store to keep a single flattened list of events to display. The content of this store is driven by the attached Events stores and the current date range.

Loading Data

Loading calendar data is divided between model types. A typical initial load of a calendar happens in 2 stages:

  1. Make a request to the server to retrieve all available calendars (wait for return). Here is an example of a sample response for a list of calendars:
[{
    "calendarId": 1,
    “title”: “Personal”
}, {
    “calendarId”: 2,
    “title”: “Work”
}]
  1. Make a request to the server for each calendar to retrieve events for the active date range. The date range and the calendarId are sent to the server. Here is an example of a sample response for calendar's events:
[{
    "id“: 1001,
    “calendarId“: 1,
    “endDate“: "2016-05-30T01:30:00.000Z",
    “startDate“: "2016-05-30T00:30:00.000Z",
    “title“: "Meet with Development"
}, {
    “id“: 1002,
    “calendarId“: 1,
    “endDate“: "2016-05-31T03:00:00.000Z",
    “startDate“: "2016-05-31T01:00:00.000Z",
    “title“: “Review with Marketing"
}]

Throughout the lifetime of the calendar component, a number of similar requests for events will likely be made for pre-fetching and loading data.

Misc Data Information

Date Formatting

All dates in the data package are to be specified as UTC.

All Day Events

An event that is "all day" must be TZ immune and end at midnight the following day. For example, if an event is all day On Jan 1st and Jan 2nd, then the start of the event is Jan 01 00:00:00 GMT and the end date is Jan 03 00:00:00 GMT.

Editable Calendars

Calendars have an editable flag. If this is set to false, the UI will not allow adding, editing or removing of events inside the calendar.

Forms

Because the forms depend on the model types, they follow much the same pattern. There is a minimal API declared for the forms, nothing specific about the fields. The form receives a record (blank record for creation) and is expected to populate the data. There is both an add and edit form. The default implementation treats these forms as the same.

Theming

Fashion theming follows the same pattern as other components found in the framework.

There is one slight addition to theming, because the system allows for specifying colors as part of the data model. As such, the color palette for basic event styling is handled as part of the javascript code. If a calendar does not have a color assigned, a default will be pulled from the pool of calendars and be claimed for that calendar id.

To specify custom colors, there are 3 items to override:

Ext.define('MyPalette', {
    override: 'Ext.calendar.theme.Theme',
    colors: [    
        'rgb(44,151,222)',    
        'rgb(233,75,53)',    
        'rgb(30,206,109)',    
        'rgb(156,86,184)',    
        'rgb(60,214,220)',    
        'rgb(232,126,3)',    
        'rgb(0,189,156)'    
    ],
    lightColor: 'rgb(238,238,238)',    
    darkColor: 'rgb(34,34,34)'    
});

Ext JS 7.0.0