A well-structured Ext JS 4 project with consistent naming conventions will be a joy to work with. Enterprise applications with hundreds of files should be structured in a way that is easy to learn and maintain. It should be a rare occurrence when you ask a colleague, "Where is the file that displays the editing toolbar for the xyz widget?".
The Ext JS 4 directory structure, comprising a top-level app and subdirectories named controller, model, store, and view, should always be used. This is the default directory structure for any Ext JS 4 application and allows out-of-the-box integration with the Sencha Cmd build tools.
Large projects have many hundreds of JavaScript files, so it is important to have a consistent project structure. Practical namespacing, especially in the view directory, can simplify a project structure and make it easier to find components. In Chapter 10, Logging On and Maintaining Users, Chapter 11, Building the Task Log User Interface, and Chapter 12, 3T Administration Made Easy, for example, we will be creating a view structure containing the files displayed in the following screenshot (on the left-hand side):
The preceding screenshot displays all views (on its right-hand side) in the same directory. Which is the better way? That depends on the nature of the project and the number of files. Enterprise projects are usually namespaced at a modular level with many subdirectories logically grouping related components. Smaller projects can just as easily have a flat structure where all files are found in the same directory. Whichever structure you choose, be consistent! It should be easy for any new developer to find a component without searching through a large number of files and directories.
We recommend defining a consistent naming convention that is easy to understand and follow. It should be easy to locate files, both on the filesystem and in the IDE you are using.
Each model should be named as the singular of the entity it represents (for example, Company, Project, Task, TaskLog, and User). Each store should be named in a similar singular manner. We have seen Store added as a postfix to store names in Ext JS 3 (for example, ProjectStore), but this is not recommended for Ext JS 4. Controllers automatically create a get function for each store by adding Store to the store name. Naming a store ProjectStore will result in a function named getProjectStoreStore in each controller that the store is referenced. For this reason, we recommend that you use store names without the Store postfix.
The store name in its singular form is often replaced with the plural version. For example, a Project store is often named Projects. Once again, consistency is the key. If you decide to use the plural form, use it for each store name. In our application, this would result in Companies, Projects, Tasks, TaskLogs, and Users stores. This tends to sometimes cause confusion in spelling; we have seen both Companies and Companys used for the plural version of Company. When English is not your first language, it may be difficult to know the correct plural name for entities, such as territories, countries, companies, currencies, and statuses. For this reason, we prefer using the singular version when naming stores.
Consider the following situation, in which we have been researching panels on the Sencha Docs website:
There are four different Panel files open (Ext.grid.Panel, Ext.tab.Panel, Ext.form.Panel, and Ext.panel.Panel). It is frustrating to try and locate the Ext.grid.Panel file in this situation; in the worst case, you will need to click on four different tab items. In a large project, there may be many panel containers worthy of the name Panel. We recommend giving each file a unique name, regardless of how it is namespaced. Unlike models and stores, where the same filename is used for the model and store namespaces, we do not recommend using the same filename between view classes. For example, the files app.view.user.List and app.view.tasklog.List cannot be easily differentiated in an IDE tab bar without examining the file content. It is far easier to make these filenames unique, even though they may exist in different namespaces.
The use of postfixing class types is another issue worthy of discussion. Ext JS 3 used typed postfixing on class names. This resulted in GridPanel, FormPanel, TabPanel, and Panel filenames. They were all panels. It was easy to identify what the class was by examining the filename. Ext JS 4 took a namespaced approach and dropped the descriptive name. The preceding examples became Ext.grid.Panel, Ext.tab.Panel, Ext.form.Panel, and Ext.panel.Panel. Each file is named Panel, which is not very helpful without knowledge of the directory it resides in.
Whatever naming convention you implement, it is important to be consistent. We will use the following naming conventions:
- All namespacing folder names will be lowercase.
- Any class that is used to represent a list of items will have the class name postfixed with
List. The implementation ofListis not important; we do not care if the listing is created using a grid, simple template, or data view. - Any class that is a form will be postfixed with
Form. - Any class that is a tree will be postfixed with
Tree. - Any class that is a window will be postfixed with
Window. - Any component that manages the positioning and layout of a set of related components will be prefixed with
Manage. Such a class will usually contain toolbars, lists, forms, and tab panels arranged in an appropriate layout.
You may wish to introduce other conventions appropriate for your development environment. This is fine; the important point is to be consistent and ensure that everyone understands and adheres to your conventions.
We recommend that all controller class names be postfixed with Controller. This makes them easy to identify in any IDE. The controller responsible for user maintenance, for example, would hence be named UserController.