Joomla component builder: understand the templating

Marco's component maker for Joomla is based on plain text templates, so you can edit the them to improve the code or to add new features. Templates are stored in the templates directory.

This article is being written and is under revision, errors may occur. sorry!
Pant, pant...I'm working hard to finish it.

The fallback template strategy

You have three templates directories:

• default
• j25
• j3x

At present time default is not used. It is reserved for future implementation of the not cms Joomla! framework: please, do not use it.

The directories have the same structure and, almost, the same files. The component builder searches for a template in the directory of the targeted Joomla version, if no template is present it looks in the previous version directory.

So file that are common between j3x and j25 are stored only in j25 directory. If j3x template differs from the j25 one you can save only this one in the j3x directory (in the exact position).

 

The directory structure of templates

Here the directory structure. Please remember the structure is very important, only the file here listed (and in this exact position) can be used. Other files added to structure are ignored, modifiaction of structure will result in a program fault.

Directories are in Italics, files in bold, strike through file are not used at present time.

The back end templates are stored in the admin directory, the front end ones in the site directory. Anyway the prefix be is used for back end, fe for front end templates.

---

• install.xml
  this is the installation xml
• admin
• beAccess.xml
  ACL definition
• beConfig.xml
  configuration parameters
• beControllerDefault.php
  default controller for component
• beEntryPoint.php
  entry poit for the component
• controllers
• beController.php
  controller for sigle object
• beControllerList.php
  controller for object list
• models
• beModel.php
  model for single object
• beModelList.php
  model for object list
• fields
• beField.php
  field definition for type `custom`
• beFieldList.php
  field definition for type `custom list` (prepare a query)
• forms
• beForm.js
  form editing validation for javascript
• beForm.xml
  fields definition for single object editing
• filter_beList.xml
  filter definition for object list (j3+ only)
• rules
• beRule.php
  rule for server side field validation
• tables
• beTable.php
  table definition
• views
• beView
• beView.php
  view for single object
• tmpl
• beTmpl.php
  template for single object
• beViewList
• beViewList.php
  view for object list
• tmpl
• beTmplList.php
  template for object list
• site
• feControllerDefault.php
  default controller for component
• feEntryPoint.php
  entry poit for the component
• helpers
• assets
• edit.css
• controllers
• feController.php
  controller for single object
• feControllerList.php
  controller for object list
• models
• feModel.php
  model for single object
• feModelList.php
  model for object list
• forms
• feForm.xml
  fields definition for single object
• views
• feView
• feView.php
  view for single object
• tmpl
• feTmpl.php
  template for single object
• feTmpl.xml
  menu definition for the view
• feViewList
• feViewList.php
  view for object list
• tmpl
• feTmplList.php
  template for object list

---

If you are going to modify these files be sure to use a UTF-8 text editor and save without BOM or code will not work.

 

The place holders for names and code fragments

Templates are generic code, so you have to add the appropiate information to make this code run into Joomla framework.

Think to the declaration of the model to edit the single book in the example component:

class MybooksModelBook extends JModelAdmin

This code is specific for the book model of the mybooks component, but a template have to be generic, so in templates\j25\admin\models\beModel.php you will find:

class !Name!Model!Nameobject! extends JModelAdmin

here !Name! and !Nameobject! are place holder, they are needed to keep the template as generic as possible. Place holder are always in the format !placeholdername!.

Please, pay attention to the case of placeholder: !NAME!, !Name! and !name! are three different things! Pay attention also when and where you use a place holder !Name!Model!Nameobject! is a valid model name !name!model!nameobject! isn't! com_!name! is a valid reference to the component com_!Name! isn't.

All Templates wide place holders

The following place holder  can be used almost in every template. Of course place holders wich are table related can't be used for files in the root of /, site and admin (these templates are not related to a specific object)

 

the !name! placeholder

It is the safe name of the component, in the "book manager" example is mybooks; we have:

!NAME! MYBOOKS
!Name! Mybooks
!name! mybooks

 

the !nameobject! placeholder

It is the single record object name of the current object, in the "book manager" example is book for the book object from #__mybook_books table; we have:

!NAMEOBJECT! BOOK
!Nameobject! Book
!nameobject! book

 

the !nameobjectlist! placeholder

It is the recordset object name of the current object list, in the "book manager" example is booklist for the booklist object from #__mybook_books table; we have:

!Nameobjectlist! BOOKLIST
!nameobjectlist! booklist

the !table! placeholder

It is the name of the table related to the current object without the prefix; in the book manager example is mybook_books for every object (model, controller, table, view) generated from the #__mybook_books table; we have only:

!table!

 

the !primarykey! placeholder

It is the primary key of table related to the current object; in the book manager example is book_id for every object (model, controller, table, view) generated from the #__mybook_books table; we have only:

!primaryKey!

 

the !fieldList! placeholder

A comma separed list of field of table related to the current object we can use in search and ordering; we have only:

!fieldList!

 

the !nullableFieldList! placeholder

A comma separed list of nullable field of table related to the current object we can use in search and ordering; we have only:

!nullableFieldList!