Actions

Naming conventions

From Joomla! Documentation

Revision as of 11:52, 30 September 2010 by Chrishaan (Talk | contribs)

Copyedit.png
This Article Needs Your Help

This article is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


Contents

Introduction

Components in Jooomla! 1.5 can now benefit from the flexibility and power of using Object Oriented Programming (OOP) practices. Most complex components will follow the Model-View-Controller (MVC) design pattern. This pattern separates the data gathering (Model), presentation (View) and user interaction (Controller) activities of a component. Such separation allows for expanding or revising properties and methods of one section without requiring additional changes to the other sections. A useful set of tutorials demonstrating the process of creating an MVC component can be found here.

Throughout this discussion, {ComponentName} is used to represent the name of the component. Notice also that case is important and is shown here as upper case or lower case dependent on the standard for the filename, classname or subdirectory.

File Structure

Many Joomla! Developers make use of the PHP Eclipse IDE when developing a new component to share with the community. This discussion and the file structure example provided below assumes this development environment.

Component files for the site are located in site/ and administrative files are located in admin/. After the component has been uploaded and installed through the Extension Manager, the site files will reside on the server at site/components/com_{componentname}/ and the administrative files will be at administrator/components/com_{componentname}/.

The component's main file of both site and administration is named {componentname}.php, and will be located in site/ and admin/.

The default controller for both site and administration is named controller.php and these files are located in site/ and admin/. If additional controllers are needed, these are located in a site/controllers/ and admin/controllers and named {controllername}.php.

View files are located in site/views/{viewname} and admin/views/{viewname}, and are always called view.html.php. If only one view is necessary, {viewname} will be the same as {componentname}. Additional views and their related files are contained within their own {viewname} subdirectorys. The default template and any other templates for each view are located under site/views/{viewname}/tmpl and admin/views/{viewname}/tmpl.

Model files are located in site/models and admin/models. The model filename should match the name of the view that the model data is being pushed into, {modelname}.php.

All filenames and foldernames for models, views and controllers must be lowercase in order to operate well on Unix/Linux-systems.

Class Naming Conventions

The model, view and controller files use the jimport function to load classes from the Joomla! framework, JModel, JView and JController, respectively. Each class is then extended with a new class specific to the component.

The base controller class for the site is named {ComponentName}Controller. For the administrative section, an "s" is added to the ComponentName, giving {ComponentName}sController. Classnames for additional controllers found within the controllers/ subdirectory are {ComponentName}Controller{ControllerName} for site/ and {ComponentName}sController{ControllerName} for admin/.

The view class is named {ComponentName}View{ViewName}.

The model class is named {ComponentName}Model{ModelName}. Remember that the {ModelName} and the {ViewName} should be the same.

Much of the above is based on the forum thread jtopic:228926.

Reserved Words

There are reserved words, which can't be used in names of classes and components.

An example is word "view" (in any case) for view class (except "view" that must be second part of that class name)[1]. Because first part of view class name is the same as controller class name, controller class name also can't contain word "view". And because of convention (although violating of it won't produce an error) controller class name must contain component name, so component name also can't contain word "view". So components can't be named "com_reviews", or if they are, they must violate naming convention and have different base controller class name (or have some other hacks).

Example

/com_{ComponentName}
  {componentname}.php
  controller.php                        class = {ComponentName}Controller

     /controllers
        sample.php                      class = {ComponentName}ControllerSample
        
     /views
          /{componentname}
             view.html.php              class = {ComponentName}View{ViewName}
                /tmpl
                   default.php
          /alternate
             view.html.php              class = {ComponentName}ViewAlternate
                /tmpl
                   form.php
        
     /models
        {componentname}.php                     class = {ComponentName}Model{ModelName}
        alternate.php                   class = {ComponentName}ModelAlternate
           
     /admin
        {componentname.php}
        controller.php                  class = {ComponentName}Controller

          /controllers
             groups.php                 class = {ComponentName}ControllerGroups
             list.php                           class = {ComponentName}ControllerList

          /views
               /{componentname}
                  view.html.php
                    /tmpl
                        default.php
               /alternate
                  view.html.php
                    /tmpl
                        default.php

          /models   
             {componentname}.php        class = {ComponentName}Model{ModelName}
             alternate.php              class = {ComponentName}ModelAlternate


Cite error: <ref> tags exist, but no <references/> tag was found