Actions

Difference between revisions of "File Structure and Naming Conventions"

From Joomla! Documentation

(Add in Joomla Versions)
m (trying source tags)
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{version/tutor|1.5,2.5,3.0}}
+
{{version/tutor|2.5,3.1}}
 
+
{{page|needs version review}}
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. Please see [[Developing a Model-View-Controller Component - Part 1|the MVC tutorial]] for an explanations of the MVC structure.
+
{{RightTOC}}
 +
Components in Jooomla! 2.5+ can now benefit from the flexibility and power of using Object Oriented Programming (OOP) practices.  
 +
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. Please see [[Developing_a_Model-View-Controller_Component|the MVC tutorial]], then select a Joomla! version for an explanations of the MVC structure.
  
 
Joomla!'s file loading system enables developers to work with separate files for controllers, views and models without worrying about importing the right file in the right place. However, for this to work, certain naming conventions need to be observed.
 
Joomla!'s file loading system enables developers to work with separate files for controllers, views and models without worrying about importing the right file in the right place. However, for this to work, certain naming conventions need to be observed.
Line 14: Line 16:
 
There are reserved words which can't be used in names of classes and components.
 
There are reserved words which can't be used in names of classes and components.
  
An example is the word "view" (in any case) for view classes (except "view" that must be second part of that class name)<ref>Reason is in line 420 of file libraries/joomla/application/component/view.php: "<code>if (!preg_match('/View((view)*(.*(view)?.*))$/i', get_class($this), $r)) {</code>"</ref>. Because the first part of the name of view classes is the same as the controller class name, controller class names can't contain the word "view" either. And because of the conventions (although violating of it won't produce an error), controller class names must contain the component name, so component names can't contain the word "view" either. So components can't be named "com_reviews", or if they are, they must violate the naming conventions and have a different base controller class name (or have some other hacks).
+
An example is the word "view" (in any case) for view classes (except "view" that must be second part of that class name)<ref>Reason is in line 420 of file libraries/joomla/application/component/view.php:  
 +
<source lang="php">if (!preg_match('/View((view)*(.*(view)?.*))$/i', get_class($this), $r)) {</source></ref>.
 +
Because the first part of the name of view classes is the same as the controller class name, controller class names can't contain the word "view" either. And because of the conventions (although violating of it won't produce an error), controller class names must contain the component name, so component names can't contain the word "view" either. So components can't be named "com_reviews", or if they are, they must violate the naming conventions and have a different base controller class name (or have some other hacks).
  
 
== Installation package vs. actual file placement ==
 
== Installation package vs. actual file placement ==

Revision as of 14:57, 8 May 2013

Copyedit.png
This Article Needs Your Help

This article is tagged because it NEEDS VERSION 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

Components in Jooomla! 2.5+ can now benefit from the flexibility and power of using Object Oriented Programming (OOP) practices. 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. Please see the MVC tutorial, then select a Joomla! version for an explanations of the MVC structure.

Joomla!'s file loading system enables developers to work with separate files for controllers, views and models without worrying about importing the right file in the right place. However, for this to work, certain naming conventions need to be observed.

The Joomla! framework is extremely flexible, and it is possible to diverge from these conventions in many ways. It is nonetheless recommended to apply standard naming wherever possible to increase readability and maintainability. Additionally, the framework will take care of the many tedious class management tasks when the files and classes of a component are named correctly.

Throughout this article, {ComponentName} is used to represent the name of the component (for example, Content). Notice also that case is important. {componentname} will refer to the lowercase version of {ComponentName}, eg. CamelCasedController -> camelcasedcontroller. Similarly, {ViewName} and {viewname}, {ModelName} and {modelname}, {ControllerName} and {controllername}.

Reserved words

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

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

Installation package vs. actual file placement

All Joomla! extensions must be packaged as a .zip installation file. According to the most common file arrangement, the package should contain at least the following two folders as a basic structure:

  • site
  • admin

If you set up your XML manifest file according to standard practice, the contents of site will be installed to /components/com_{componentname}, whereas the contents of admin will be installed to /administrator/components/com_{componentname}.

The /site folder

This folder keeps the files for the frontend part of the component.

/site/{componentname}.php
This is the component's main file and entry point for the frontend part.
/site/controller.php
This file holds the default frontend controller, which is a class called {ComponentName}Controller. This class must extend the base class JController.
/site/views
This folder holds the different views for the component.
/site/views/{viewname}
This folder holds the files for the view {ViewName}.
/site/views/{viewname}/view.html.php
This file is the entry point for the view {ViewName}. It should declare the class {ComponentName}View{ViewName}. This class must extend the base class JView. The .html section of the filename is related to the format the view will be loaded in. For example, if the format URL parameter is set to format=feed, the file view.feed.php will be loaded.
/site/views/{viewname}/tmpl
This folder holds the template files for the view {ViewName}.
/site/views/{viewname}/tmpl/default.php
This is the default template for the view {ViewName}. In this PHP file, the $this keyword refers to the view class that the template belongs to.
/site/models
This folder holds additional models, if needed by the application.
/site/models/{modelname}.php
This file holds the model class {ComponentName}Model{ModelName}. This class must extend the base class JModel. Note that the view named {ViewName} will by default load a model called {ViewName} if it exists. Most models are named after the view they are intended to be used with, but this is not a requirement. See Using multiple models in an MVC component for more information.
/site/controllers
This folder holds additional controllers, if needed by the application.
/site/controllers/{controllername}.php
This file holds the controller class {ComponentName}Controller{ControllerName}. This class must extend the base class JController.

The /admin folder

The file structure is exactly the same as in the /site folder. Note that the view, models, controllers etc. of the site and admin parts are by default completely separated, and have nothing to do with each other - the site part and the admin part can be thought of as two different components! A view in the /admin folder may have a counterpart with the same name in the /site folder, yet the two views have nothing in common but their name.

However, it might sometimes make sense to share classes between the site and admin parts of the component. Especially models can be shared to avoid duplicating model code. The Joomla! framework supports this strategy. When sharing any code between site and admin applications, the classes should be designed with great care to avoid the possibility of a site user executing admin actions.


  1. Reason is in line 420 of file libraries/joomla/application/component/view.php:
    if (!preg_match('/View((view)*(.*(view)?.*))$/i', get_class($this), $r)) {