Joomla! Documentation LF

8/6/2019 Joomla! Documentation LF

1/66

From Joomla! Documentation

Joomla! already is a rich featured content management system, but if you're building a website with Joomla! and you

need extra features which aren't available in Joomla! by default, you can easily extend it with extensions. There are

five types of extensions for Joomla!: Components, Modules, Plugins, Templates, and Languages. Each of these extensions

handle specific functionality. (Some built-in features of Joomla! are implemented using extensions.)

Components are the largest and most complex extensions of them all; they can be seen as mini-applications. Most

components have two parts: a site part and an administrator part. Every time a Joomla page loads, one component is called

to render the main page body. For example, Content (com_content) is the component which handles the display of content;

users can view at the frontend of your site and, as an administrator, you can edit the content. Components are the major

portion of your page because a component is driven by a menu item and every menu item runs a component.

Examples: Content (com_content), Banners (com_banners), Contact (com_contact), News Feeds (com_newsfeeds) and

Web Links (com_weblinks)

Management feature:Admin head menu > Components (Content for com_content)

1


2/66

Modules are more lightweight and flexible extensions used for page rendering. These modules are mostly known as the

boxes that are arranged around a component, for example: the login module. The footer is a module. Modules are

assigned per menu item. So, you can decide to show or hide the logon module depending on which menu item the user is

viewing. Sometimes modules are linked to components such as the latest news module which links to the com_content

and displays links to the newest content items. However, modules do not need to be linked to components, as a matter of

fact they don't even need to be linked to anything and can be just static HTML or text.

Examples: Banners (mod_banners), Menus (mod_menu), Who's Online (mod_whosonline)

Management feature:Admin head menu > Extensions > Module Manager

Plugins are more advanced extensions and are in essence event handlers. In the execution of any part of Joomla, be it the

core, a module or a component, an event can be triggered. When an event is triggered, plugins that are registered with the

application to handle that event execute. For example, a plugin could be used to intercept user-submitted articles and filter

out bad words. Plugins were known in Joomla! 1.0 as mambots.

Examples: content.searchbot, tinymce

Management feature:Admin head menu > Extensions > Plugin Manager

A template is basically the design of your Joomla! powered website. With a template you can change the look and feel of

your website. Templates have certain fields in which the component (just one) and modules (as many as you like) will be

shown. Templates are easy to build or customize and they provide maximum flexibility in how you style your site.

Management feature:Admin head menu > Extensions > Template Manager

Probably the most basic extensions are languages. Languages can be packaged in two ways, either as a core package or as

an extension package. In essence, these files consist key/value pairs, these pairs provide the translation of static text strings

which are assigned within the Joomla! source code. These language packs will affect both the front and administrator side.

Note: these language packs also include an XML meta file which describes the language and font information to use for

PDF content generation.

Management feature:Admin head menu > Extensions > Language Manager

Retrieved from "http://docs.joomla.org/Extension_types_(general_definitions)"

Category: Extensions

2


3/66


A software framework is the base of an application that can be used by a developer. The framework in Joomla! 1.5

unleashes a great deal of power for them. The Joomla! code has been designed for extensibility. This tutorial will guide

you through the process of developing a component using the framework.

The scope of this project will be to develop a simple Hello World! component. In future tutorials, this simple

framework will be built upon to show the full power and versatility of the MVC design pattern in Joomla!

You need Joomla! 1.5 or greater for this tutorial.

While the idea behind a component may seem extremely simple, code can quickly

become very complex as additional features are added or the interface is customized.

Model-View-Controller (herein referred to as MVC) is a software design pattern that

can be used to organize code in such a way that the business logic and data

presentation are separate. The premise behind this approach is that if the business logicis grouped into one section, then the interface and user interaction that surrounds the

data can be revised and customized without having to reprogram the business logic.

MVC was originally developed to map the traditional input, processing, output roles into a logical GUI architecture.

These three main roles are the basis for the Joomla MVC. They are described here in brief, but for a more thorough

explanation, please refer to the links provided at the end of this tutorial.

Model

The model is the part of the component that encapsulates the application's data. It will often provide routines tomanage and manipulate this data in a meaningful way in addition to routines that retrieve the data from the model. In

our case, the model will contain methods to add, remove and update information about the greetings in the database. It

will also contain methods to retrieve the list of greetings from the database. In general, the underlying data access

technique should be encapsulated in the model. In this way, if an application is to be moved from a system that utilizes

a flat file to store its information to a system that uses a database, the model is the only element that needs to be

changed, not the view or the controller.

View

The view is the part of the component that is used to render the data from the model in a manner that is suitable for

interaction. For a web-based application, the view would generally be an HTML page that is returned to the data. The

view pulls data from the model (which is passed to it from the controller) and feeds the data into a template which is

populated and presented to the user. The view does not cause the data to be modified in any way, it only displays data

retrieved from the model.

1


4/66

Controller

The controller is responsible for responding to user actions. In the case of a web application, a user action is

(generally) a page request. The controller will determine what request is being made by the user and respond

appropriately by triggering the model to manipulate the data appropriately and passing the model into the view. The

controller does not display the data in the model, it only triggers methods in the model which modify the data, and

then pass the model into the view which displays the data.

MVC connection

The simplified picture on the right depicts the basic components being used within

Joomla. Besides the Model, the View and the Controller, an Entry Point has been

added that is depicted as a small circle. Attached to the viewer (view) a Template has

been added. With these five components you should be able to understand this tutorial

about making a basic Joomla! MVC component.

Part 1 of the tutorial only focuses on the Controller and the View (with the use of the

Template); these are marked with the blue colour in the picture. Part 2 adds and Part 3

extends the model functionality for the data manipulation abstraction; marked with the

green colour in the picture.

Keep in mind that this simplified picture only applies for the site section (i.e the front-end). An identical picture is

applicable for the admin section (i.e. the back-end). The administrative section is taken care of in Parts 4 through 6 of

this component development tutorial. Both the site and the admin section are maintained and configured in an XML

based installation file (typically termed a manifest file).

In Joomla!, the MVC pattern is implemented using three classes: JModel (http://api.joomla.org/Joomla-Framework

Application/JModel.html) , JView (http://api.joomla.org/Joomla-Framework/Application/JView.html) and JController(http://api.joomla.org/Joomla-Framework/Application/JController.html) . For more detailed information about these

classes, please refer to the API reference documentation (WIP).

For learning purposes and debugging, adding a run-time debugger to your Joomla! site might be a good extension

especially during development of your (tutorial) component. A good example is the community project J!Dump

(http://extensions.joomla.org/extensions/miscellaneous/development/1509/details) that has the advantage of being a

pop-up which leaves the view output unchanged. The J!Dump system allows you to view not only your development

properties but also the methods.

For our basic component, we only require five files:

site/hello.php - this is the entry point to our componentsite/controller.php - this file contains our base controllersite/views/hello/view.html.php - this file retrieves the necessary data and pushes it into the templatesite/views/hello/tmpl/default.php - this is the template for our outputhello.xml - this is an XML (manifest) file that tells Joomla! how to install our component.

Remember that the filename for the entry point must have the same name of the component. For example, if you call

your component "Very Intricate Name Component", at install time (see below in the hello.xml section) Joomla! willcreate the folder com_veryintricatenamecomponent and the entry point php file must be named

veryintricatenamecomponent.php otherwise it will not work. Be aware that use of some special characters, notibly the

underscore '_', may have special meaning in Joomla and should be avoided in component names or files.

The site directory here is for the parts of the component which are installed in the front end site.

2


5/66

Naming conventions

Main article: Naming conventions

At this point it is important to say that some words are reserved for using in component or its class names, and

violating some of that will produce a hard for debugging error. One of them is "view" (in any character case) for view

class (subclass of JView) and controller class (subclass of JController), because view class need to have first part of

name the same as controller class name, and component name (although violating of last one won't produce an error,

it's just a useful convention).

All filenames and foldernames for models, views and controllers must be lower-case in order to operate well on

Unix/Linux-systems.

Creating the Entry Point

This recently added article requires a review

Joomla! is always accessed through a single point of entry: index.php for the Site Application or

administrator/index.php for the Administrator Application. The application will then load the required component,

based on the value of 'option' in the URL or in the POST data. For our component, the URL would be:

index.php?option=com_hello&view=hello

This will load our main file, which can be seen as the single point of entry for our component: components/com_hello

/hello.php.

The code for this file is fairly typical across components.

site/hello.php:

3


6/66


7/66

takes care of the actual redirection.

The main entry point (hello.php) essentially passes control to the controller, which handles performing the task that

was specified in the request.

Note that we don't use a closing php tag in this file: ?>. The reason for this is that we will not have any unwanted

whitespace in the output code. This is default practice since Joomla! 1.5, and will be used for all php-only files.

Creating the Contr oller

Our component only has one task - greet the world. Therefore, the controller will be very simple. No data

manipulation is required. All that needs to be done is the appropriate view loaded. We will have only one method in

our controller: display(). Most of the required functionality is built into the JController class, so all that we need to do

is invoke the JController::display() method.

The code for the base controller site/controller.php is:


8/66

view is organized.

In our component, we will have a single view called hello, and a single layout (default).

Creating the View

The task of the view is very simple: It retrieves the data to be displayed and pushes it into the template. Data is pushed

into the template using the JView::assignRef method. (Note: The key (the first argument) passed to the assignRef method cannot be

preceded by an underscore i.e. $this->assignRef('_greeting',$greeting). Doing so will cause the assignRef method to return false and your

variable will not be pushed into the template.)

The code for the view at site/views/hello/view.html.php:

6


9/66

Wrapping It All Up - Creating the hello.xml File

It is possible to install a component manually by copying the files using an FTP client and modifying the database

tables. It is more efficient to create a package file that will allow the Joomla! Installer to do this for you. This package

file contains a variety of information:

basic descriptive details about your component (i.e. name), and optionally, a description, copyright and licenseinformation.a list of files that need to be copied.

optionally, a PHP file that performs additional install and uninstall operations.optionally, an SQL file which contains database queries that should be executed upon install/uninstall

The format of the XML file at hello.xml is as follows:

Hello

2007-02-22

John Doe

[email protected]://www.example.org

Copyright Info

License Info

1.01

Description of the component ...

controller.php

hello.php

index.html

views/index.html

views/hello/index.html

views/hello/view.html.php

views/hello/tmpl/default.php

views/hello/tmpl/index.html

Hello World!

hello.php

index.html

Put this xml file, also called manifest, in the root of your package (because theinstaller will take its path as the root path for all other files).Don't include itself under ...

7


10/66

You may have noticed the manifest source above mentioned files we have not discussed. These are the index.html

files and the admin files. An index.html file is placed in each directory to prevent prying users from getting a directory

listing. If there is no index.html file, some web servers will list the directory contents. This is often undesirable. These

files have the simple line:

It will simply display a blank page.

The hello.php file in the admin folder is the entry point for the our component's admin section. Since our component

has no administrator needs (yet), this file will have the same content as the index.html files for now.

If you've followed along, you can visit URL index.php?option=com_hello to see your work.

Developing a Model-View-Contr oller Component - Par t 1

Developing a Model-View-Controller Component - Part 2 - Adding a Model

Developing a Model-View-Controller Component - Part 3 - Using the Database

Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface

Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework

Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions

mjazstaalandendannystapleStilgar

The component can be downloaded at: com_hello1_01 (http://joomlacode.org/gf/download/frsrelease/8108/29433

/com_hello1_01.zip)

Retrieved from "http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1"Categories: Articles that require a review | Tutorials | Component Development

This page was last modified on 16 May 2011, at 05:04.Content is available under Joomla! EDL.

8


11/66


This recently added article requires a review

In the first tutorial of this series, creating a simple view-controller component using the Joomla! 1.5 CMS framework

was demonstrated.

In the first tutorial, the greeting was hardcoded into the view. This doesn't follow the MVC pattern exactly because theview is intended to only display the data, and not contain it.

In this second part of the tutorial we will demonstrate how to move this out of the view and into a model. In future

tutorials we will demonstrate the power and flexibility that this design pattern provides.

The concept of model gets its name because this class is intended to represent (or 'model') some entity. In our case,

our first model will represent a 'hello', or a greeting. This is in line with our design thus far, because we have one view

('hello'), which is a view of our greeting.

The naming convention for models in the Joomla! framework is that the class name starts with the name of the

component (in our case 'hello', followed by 'model', followed by the model name. Therefore, our model class is called

HelloModelHello.

At this point, we will only model one behaviour of our hello, and that is retrieving the greeting. We will thus have one

method, called getGreeting(). It will simply return the string 'Hello, World!'.

The code for the model at site/models/hello.php:

1

12/66

< ? p h p

/ * *

* He l l o Mo d e l f o r He l l o Wo r l d Co mp o n e n t

*

* @p a c k a g e J o o ml a . T u t o r i a l s

* @s u b p a c k a g e Co mp o n e n t s

* @l i n k h t t p : / / d o c s . j o o ml a . o r g / De v e l o p i n g _ a _ Mo d e l - Vi e w- Co n t r o l l e r _ Co mp o n e n t _ - _ Pa r t _ 2

* @l i c e n s e GNU/ GP L

* /

/ / No d i r e c t a c c e s sd e f i n e d ( ' _ J E XE C' ) o r d i e ( ' Re s t r i c t e d a c c e s s ' ) ;j i mp o r t ( ' j o o ml a . a p p l i c a t i o n . c o mp o n e n t . mo d e l ' ) ;

/ * *

* He l l o Mo d e l

*



* /

c l a s s He l l o Mo d e l He l l o e x t e n d s J Mo d e l{ / * *

* Ge t s t h e g r e e t i n g

* @r e t u r n s t r i n g T h e g r e e t i n g t o b e d i s p l a y e d t o t h e u s e r

* /

f u n c t i o n g e t Gr e e t i n g ( )

{ r e t u r n ' He l l o , Wo r l d ! ' ; }}

You will notice a line that starts with jimport. The jimport function is used to load files from the Joomla! frameworkthat are required for our component. This particular statement will load the file /libraries/joomla/application

/component/model.php. The '.'s are used as directory separators and the last part is the name of the file to load. All

files are loaded relative to the libraries directory. This particular file contains the class definition for the JModel class,

which is necessary because our model extends this class.

Now that we have created our model, we must modify our view so that it uses it to obtain the greeting.

The Joomla! framework is setup in such a way that the controller will automatically load the model that has the samename as the view and will push it into the view. Since our view is called 'Hello', our 'Hello' model will automatically be

loaded and pushed into the view. Therefore, we can easily retrieve a reference to our model using the

JView::getModel() method. (If the model had not followed this convention, we could have passed the model name to

JView::getModel() (http://api.joomla.org/Joomla-Framework/Application/JView.html#getModel) )

Our previous view code contained the lines:

$ g r e e t i n g = " He l l o Wo r l d ! " ;

To take advantage of our model, we change this line to:

$ m o d e l = &$ t h i s - > g e t Mo d e l ( ) ;$ g r e e t i n g = $ m o d e l - > g e t Gr e e t i n g ( ) ;

2

13/66

The complete view now looks like:

< ? p h p

/ * *





* /

/ / No d i r e c t a c c e s s

d e f i n e d ( ' _ J E XE C' ) o r d i e ( ' Re s t r i c t e d a c c e s s ' ) ;j i mp o r t ( ' j o o ml a . a p p l i c a t i o n . c o mp o n e n t . v i e w ' ) ;

/ * *

* HT ML Vi e w c l a s s f o r t h e He l l o Wo r l d Co mp o n e n t

*

* @p a c k a g e He l l o Wo r l d

* /

c l a s s He l l o Vi e wHe l l o e x t e n d s J Vi e w{ f u n c t i o n d i s p l a y ( $ t p l = n u l l )

{ $ m o d e l = &$ t h i s - > g e t Mo d e l ( ) ; $ g r e e t i n g = $ m o d e l - > g e t Gr e e t i n g ( ) ; $ t h i s - > a s s i g n Re f ( ' g r e e t i n g ' , $ g r e e t i n g ) ;

p a r e n t : : d i s p l a y ( $ t p l ) ; }}

Adding the File to the Package

All that remains is to add an entry to the XML file so that our new model will be copied. The Joomla! framework will

look for our model in the models directory, so the entry for this file will look like (it should be added to the site

section):

< f i l e n a me > mo d e l s / h e l l o . p h p < / f i l e n a me >

Our new hello.xml file will look like:

3

14/66

< ? x ml v e r s i o n = " 1 . 0 " e n c o d i n g = " u t f - 8 " ? >



< n a me > He l l o < / n a me >

< c r e a t i o n Da t e > 2 0 0 7 - 0 2 - 2 2 < / c r e a t i o n Da t e > < a u t h o r > J o h n Do e < / a u t h o r > < a u t h o r E ma i l >j o h n . d o e @e x a mp l e . o r g < / a u t h o r E ma i l > < a u t h o r U r l > h t t p : / / www. e x a mp l e . o r g < / a u t h o r Ur l > < c o p y r i g h t > C o p y r i g h t I n f o < / c o p y r i g h t >

< l i c e n s e > L i c e n s e I n f o < / l i c e n s e >

< v e r s i o n > 1 . 0 1 < / v e r s i o n >

< d e s c r i p t i o n > De s c r i p t i o n o f t h e c o mp o n e n t . . . < / d e s c r i p t i o n >

t o c o p y FROM i n t h e p a c k a g e t o i n s t a l l t h e r e f o r e f i l e s c o p i e d

i n t h i s s e c t i o n a r e c o p i e d f r o m / s i t e / i n t h e p a c k a g e - - >

< f i l e s f o l d e r = " s i t e " >

< f i l e n a me > c o n t r o l l e r . p h p < / f i l e n a me >

< f i l e n a me > h e l l o . p h p < / f i l e n a me >

< f i l e n a me > i n d e x . h t ml < / f i l e n a me > < f i l e n a me > mo d e l s / h e l l o . p h p < / f i l e n a me > < f i l e n a me > mo d e l s / i n d e x . h t ml < / f i l e n a me > < f i l e n a me > v i e ws / i n d e x . h t ml < / f i l e n a me >

< f i l e n a me > v i e ws / h e l l o / i n d e x . h t ml < / f i l e n a me >

< f i l e n a me > v i e ws / h e l l o / v i e w. h t ml . p h p < / f i l e n a me >

< f i l e n a me > v i e ws / h e l l o / t mp l / d e f a u l t . p h p < / f i l e n a me >

< f i l e n a me > v i e ws / h e l l o / t mp l / i n d e x . h t ml < / f i l e n a me >

< / f i l e s >

< a d mi n i s t r a t i o n >

< me n u > He l l o Wo r l d ! < / me n u >

< f i l e s f o l d e r = " a d mi n " >


< f i l e n a me > i n d e x . h t ml < / f i l e n a me >

< / f i l e s >

< / a d mi n i s t r a t i o n >



We now have a simple MVC component. Each element is very simple at this point, but provides a great deal of

flexibility and power.

Developing a Model-View-Controller Component - Part 1





4


15/66


staalanden

The component can be downloaded at: com_hello2_01 (http://joomlacode.org/gf/download/frsrelease/8109/29434/com_hello2_01.zip)

Retrieved from "http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2_-

_Adding_a_Model"

Categories: Articles that require a review | Tutorials | Component Development

This page was last modified on 16 June 2011, at 11:55.

Content is available under Joomla! EDL.

5


16/66


In the first two tutorials, we showed you how to build a simple model-view-controller component. We had one view

which retrieved data from a model (which was created in the 2nd tutorial). In this tutorial, we will be working with the

model. Instead of the data being hard coded in the model, the model will retrieve the data from a table in the database.

This tutorial will demonstrate how to use the JDatabase class to retrieve data from the database.

Our model currently has one method: getGreeting(). This method is very simple - all it does is return the hard-codedgreeting.

To make things more interesting, we will load the greeting from a database table. We will demonstrate later how to

create an SQL file and add the appropriate code to the XML manifest file so that the table and some sample data will

be created when the component is installed. For now, we will simply replace our return statement with some code that

will retrieve the greeting from the database and return it.

The first step is to obtain a reference to a database object. Since Joomla! uses the database for its normal operation, a

database connection already exists; therefore, it is not necessary to create your own. A reference to the existing

database can be obtained using:

$ d b = & J F a c t o r y : : g e t DBO( ) ;

JFactory is a static class that is used to retrieve references to many of the system objects. More information about this

class can be found in the API documentation JFactoryAPI (http://docs.joomla.org/JFactory) .

The method name (getDBO) stands for get DataBase Object, and is easy and important to remember.

Now that we have obtained a reference to the database object, we can retrieve our data. We do this in two steps:

store our query in the database objectload the result

Our new getGreeting() method will therefore look like:

f u n c t i o n g e t Gr e e t i n g ( )

{ $ d b = & J F a c t o r y : : g e t DBO( ) ;

$ q u e r y = ' S EL E C T g r e e t i n g F ROM # _ _ h e l l o ' ;

$ d b - > s e t Qu e r y ( $ q u e r y ) ; $ g r e e t i n g = $ d b - > l o a d Re s u l t ( ) ;

r e t u r n $ g r e e t i n g ;}

1


17/66

hello is the name of the table that we will create later, and greeting is the name of the field that stores the greetings. If

you are not familiar with SQL, it would be helpful to take a tutorial or a lesson to get yourself up to speed. One such

tutorial can be found at w3schools (http://www.w3schools.com/sql/default.asp) .

The $db->loadResult() method will execute the stored database query and return the first field of the first row of the

result. See JDatabase API reference (http://api.joomla.org/Joomla-Framework/Database/JDatabase.html) for more

information about other load methods in the JDatabase class.

The Joomla! installer has built-in support for executing queries during component installation. These queries are all

stored in a standard text file.

We will have three queries in our install file: the first will drop the table in case it already exists, the second will create

the table with the appropriate fields, and the third will insert the data.

Here are our queries:

DROP T A B L E I F EXI S TS ` # _ _ h e l l o ` ;

C R E A T E T A B L E ` # _ _ h e l l o ` (

` i d ` i n t ( 1 1 ) u n s i g n e d NO T NULL a u t o _ i n c r e me n t ,

` g r e e t i n g ` v a r c h a r ( 2 5 ) NO T NULL ,

P RI MARY KE Y ( ` i d ` )

) ENGI NE = My I S A M AUTO_ I NCRE MENT = 0 DEF AULT CHARS ET = u t f 8 ;

I NS ERT I NTO ` # _ _ h e l l o ` ( ` g r e e t i n g ` ) VALUES ( ' He l l o , Wo r l d ! ' ) , ( ' Bo n j o u r , Mo n d e ! ' ) , ( ' Ci a o ,

You might find the prefix on the table names rather odd. Joomla! will replace this prefix with the prefix used by the

current install. For most installs, this table will become jos_hello. This allows multiple installs of Joomla! to use the

same database, and prevents collisions with other applications using the same table names (i.e. two applications mightshare a database, but might both require a 'users' table. This convention avoids problems.)

We have specified two fields in our database. The first field is id, and is called the 'primary key'. The primary key of a

database table is a field that is used to uniquely identify a record. This is often used to lookup rows in the database.

The other field is greeting. This is the field that stores the greeting that is returned from the query that we used above.

We will save our installation queries in a file called admin/install.sql. (Note: In the original version of this file,

install.utf.sql was used - this was incorrect. Also see discussion.)

Creating the Uninstall SQL File

Though we might hope that people will never want to "uninstall" our component, it is important that if they do,

nothing is left behind after uninstalling our component. Joomla! will look after deleting the files and directories that

were created during the "install", but we must manually include queries that will remove any tables that were added to

the database. Since we have only created one table, we only need one query:

DROP T A B L E I F EXI S TS ` # _ _ h e l l o ` ;

We will save this uninstall query in a file called admin/uninstall.sql. (Note: In the original version of this file,

uninstall.utf.sql was used - this was incorrect. Also see discussion.)

We need to change a few things in our hello.xml file. First, we need to add our two new sql files to the list of files to

2

18/66

install. Secondly, the SQL install files have to be placed in the admin directory. Thirdly, we need to tell the installer to

execute the queries in our files on install and uninstall.

Our new file looks like this:


 < n a me > He l l o < / n a me >

< c r e a t i o n Da t e > 2 0 0 7 - 0 2 - 2 2 < / c r e a t i o n Da t e > < a u t h o r > J o h n Do e < / a u t h o r > < a u t h o r E ma i l >j o h n . d o e @e x a mp l e . o r g < / a u t h o r E ma i l > < a u t h o r Ur l > h t t p : / / www. e x a mp l e . o r g < / a u t h o r Ur l > < c o p y r i g h t > C o p y r i g h t I n f o < / c o p y r i g h t > < l i c e n s e > L i c e n s e I n f o < / l i c e n s e >

< v e r s i o n > 3 . 0 1 < / v e r s i o n >

< d e s c r i p t i o n > De s c r i p t i o n o f t h e c o mp o n e n t . . . < / d e s c r i p t i o n >

t o c o p y FROM i n t h e p a c k a g e t o i n s t a l l t h e r e f o r e f i l e s c o p i e d

i n t h i s s e c t i o n a r e c o p i e d f r o m / s i t e / i n t h e p a c k a g e - - >

< f i l e s f o l d e r = " s i t e " >

< f i l e n a me > c o n t r o l l e r . p h p < / f i l e n a me >


< f i l e n a me > i n d e x . h t ml < / f i l e n a me > < f i l e n a me > mo d e l s / h e l l o . p h p < / f i l e n a me > < f i l e n a me > mo d e l s / i n d e x . h t ml < / f i l e n a me > < f i l e n a me > v i e ws / i n d e x . h t ml < / f i l e n a me > < f i l e n a me > v i e ws / h e l l o / i n d e x . h t ml < / f i l e n a me > < f i l e n a me > v i e ws / h e l l o / v i e w. h t ml . p h p < / f i l e n a me > < f i l e n a me > v i e ws / h e l l o / t mp l / d e f a u l t . p h p < / f i l e n a me >

< f i l e n a me > v i e ws / h e l l o / t mp l / i n d e x . h t ml < / f i l e n a me > < / f i l e s >



< s q l >

< f i l e c h a r s e t = " u t f 8 " d r i v e r = " my s q l " > i n s t a l l . s q l < / f i l e >

< / s q l >

 

< s q l >

< f i l e c h a r s e t = " u t f 8 " d r i v e r = " my s q l " > u n i n s t a l l . s q l < / f i l e >

< / s q l >



< a d mi n i s t r a t i o n >





< f i l e n a me > i n s t a l l . s q l < / f i l e n a me >

< f i l e n a me > u n i n s t a l l . s q l < / f i l e n a me >

< / f i l e s >




You will notice two attributes present on the tags within the and sections: charset and

driver. The charset is the type of charset to use. The only valid charset is utf8. If you want to create install files for

3


19/66

non-utf8 databases (for older version of MySQL), you should omit this attribute.

The driver attribute specifies which database the queries were written for. Currently, this can only be mysql, but in

future versions of Joomla! there may be more database drivers available.

We now have a component that takes advantage of both the Joomla! MVC framework classes and the JDatabase

classes. You are now able to write MVC components that interact with the database and can use the Joomla! installer

to create and populate database tables.







staalanden


/com_hello3_01.zip)

Retrieved from "http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_3_-_Using_the_Database"Categories: Database | Tutorials | Component Development

This page was last modified on 15 January 2011, at 17:35.

Content is available under Joomla! EDL.

4

20/66


This {{#namespace:developing a model-view-controller component - part 4 -creating an administrator interface}} page has been divided into three sections,two new articles are added. Especially this page needs a review (August 2009)

In the first three Parts, we have developed a MVC component that retrieves its data from a table in the database.

Currently, there is no way to add data to the database except to do it manually using another tool. In the next Parts of

this tutorial, we will develop an administrator section for our component which will make it possible to manage the

entries in the database.

This Part, Par t 4 - Creating an Administr ator Inter face, will be an article with no new source code for our Hello

component but will describe some basic details and in-depth explanation of the MVC pattern. This intermediate

chapter is not required to complete the Hello model so if you think you understand the basics continue with

Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework.

In the frontend solution (site section, parts 1,2 and 3) we developed the first part of our component. The frontend

solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust"

the default handling of the code. This is going to change in the Backend or Administration section of our Hello

component ( parts 5 and 6) - we will have to develop all of the code that manages the application flow.

Joomla! is a content management system. The frontend is used for presenting the users with content and allows

certain logged in users to manipulate the content. The backend is responsible for administering the website framework

(structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend)

administration is a fundamental aspect of the Joomla! architecture.

Entrance points

From the XML file of our frontend example it was already obvious that there would be an administration part:


. . . < a d mi n i s t r a t i o n >





< f i l e n a me > i n s t a l l . s q l < / f i l e n a me >

< f i l e n a me > u n i n s t a l l . s q l < / f i l e n a me >

< / f i l e s >


. . .

1

21/66

Only the .sql files were of use and only during installation for our frontend view, the other two files have no content

besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server)

and browse through the directories after installing the frontend com_hello component. You may have noticed that our

Hello component is to be found twice:

< r o o t > / c o mp o n e n t s / c o m_ h e l l o< r o o t > / a d mi n i s t r a t o r / c o mp o n e n t s / c o m_ h e l l o

These two sub-directories link to the previously explained site-content and administration. Administrator interactions

explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on theroot:

< r o o t > / i n d e x . p h p

Administrative users will have to log in, and after logging in they will enter your site via:

< r o o t > / a d mi n i s t r a t o r / i n d e x . p h p

With the different access points it is easy to grasp that with setting up the administrator section the namingconventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator

section this implies that identical Controllers, Views and Models naming can (and sometimes must) be used as in the

site section.

In Developing a Model-View-Controller Component - Part 1 the figure on the right

was used to explain the focus of the first three parts of thisDeveloping a Model-

View-Controller Component tutorial. Now we will use this figure to explain how

decisions are made on what is going to be displayed and how to manipulate this.

Example roll-out

For explanation purposes an easy to grasp example will be used. A library has the main

function of lending books to registered users. Simply laid out there are three tables:

usersbooksrelation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the

relation contains both Ids and the date of lending.

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative

side of our Hello component is not even that complex with only one table to manage. After the explanation of this Part

it should be easy to follow the tutorial in the succeeding Parts.

Mapping a Joomla! MVC component from the example

In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the

2

22/66

administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back

the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting

registered users only see their own books. (See: JUser object (http://api.joomla.org/Joomla-Framework

/User/JUser.html) for making user deviations in template module).

Just like our frontend Hello component, for this library component only the default view is being used in the frontend.

It lists the relational table, left joining the other two tables to obtain a human readable list of books with their

corresponding due date.

Al i c e | On e f l e w o v e r . . . | 1 2 - a u g - 2 0 0 9Al i c e | C e l e b t a l k | 1 2 - a u g - 2 0 0 9Ma r k | J o o ml a ! | 1 5 - a u g - 2 0 0 9

With respect to the administration part it is important to understand that we have one default and three dedicated

views, each controlling three tasks:

User administration

Add

ChangeDelete

Book administrationAddChangeDelete

Relation administrationAddChangeDelete

Controllers

The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that

are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.

< r o o t > / a d mi n i s t r a t o r / c o n t r o l l e r . p h p< r o o t > / a d mi n i s t r a t o r / c o n t r o l l e r s / u s e r s . p h p< r o o t > / a d mi n i s t r a t o r / c o n t r o l l e r s / b o o k s . p h p< r o o t > / a d mi n i s t r a t o r / c o n t r o l l e r s / r e l a t i o n . p h p

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also theinitiator of instantiating the model with the same name and it is responsible for setting the view and the desired form

for that view. The controller really justifies its name.

Within the controller it is good to make a difference between activating tasks (for example the edit selection from a

menu) and resulting tasks (for example the result of an edit trigger is the posted data).

Typical controller functions look like:

3

23/66

f u n c t i o n < a c t i v a t i n g t a s k > ( ) / / a c t i o n ( ) ) { / / s e t R e d i r e c t ( ' i n d e x . p h p ? o p t i o n = < c o mp o n e n t n a me > ' , $ ms g ) ;

}

A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module willreturn to the main administration entrance point for that component, the main controller with the default view.

Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the

general understanding and consistency this field should mostly be default. In complex views multiple forms could be

defined within one view.

Models

The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used

to retrieve data. The backend has more controllers and thus also more model files. The backend model files not onlyare responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model

contains all actions required to manage a single table in the database.

< r o o t > / a d mi n i s t r a t o r / mo d e l s / < c o mp o n e n t n a me > . p h p< r o o t > / a d mi n i s t r a t o r / mo d e l s / u s e r s . p h p< r o o t > / a d mi n i s t r a t o r / mo d e l s / b o o k s . p h p< r o o t > / a d mi n i s t r a t o r / mo d e l s / r e l a t i o n . p h p

Views

Separate views are of course also required. For views and subsequent forms no forced naming conventions are

required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are

identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't

matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used

for all the deletes for all administrative tasks asking an "Are you sure" display.

< r o o t > / a d mi n i s t r a t o r / v i e w s / < c o mp o n e n t n a me > / v i e w . h t ml . p h p + . . . / t mp l / d e f a u l t . p h p< r o o t > / a d mi n i s t r a t o r / v i e ws / u s e r s / v i e w. h t ml . p h p + . . . / t mp l / d e f a u l t . p h p< r o o t > / a d mi n i s t r a t o r / v i e w s / b o o k s / v i e w . h t ml . p h p + . . . / t mp l / d e f a u l t . p h p< r o o t > / a d mi n i s t r a t o r / v i e ws / r e l a t i o n / v i e w. h t ml . p h p + . . . / t mp l / d e f a u l t . p h p< r o o t > / a d mi n i s t r a t o r / v i e ws / d e l e t e / v i e w . h t ml . p h p + . . . / t mp l / d e f a u l t . p h p

Note: In general it is good practice to maintain one form per view because the view.html.php still has to deliver the

content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start

considering splitting up the view.

Note: Sharing template parts amongst the different views (for uniform layouting of headers and titles of your

4

24/66

component) can be done using the PHP i n c l u d e / r e q u i r e ; . There is one slight problem ... how to make the logical

reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I

put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the

first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following

example the files marked with a '*' use the following code:

/ c o m_ c o mp n a me / v i e w s / g e n e r a l / n a v i g a t e . h e a d e r . p h p < - - s n i p l e t c o d e f o r t h e h e a d e r/ c o m_ c o mp n a me / v i e ws / g e n e r a l / n a v i g a t e . f o o t e r . p h p < - - s n i p l e t c o d e f o r t h e f o o t e r/ c o m_ c o mp n a me / v i e ws / mn g t a b l e 1 / v i e w. h t ml . p h p/ c o m_ c o mp n a me / v i e w s / mn g t a b l e 1 / t mp l / d e f a u l t . p h p *

/ c o m_ c o mp n a me / v i e ws / mn g t a b l e 2 / v i e w. h t ml . p h p/ c o m_ c o mp n a me / v i e w s / mn g t a b l e 2 / t mp l / d e f a u l t . p h p *

$ p a t h T o Ge n e r a l Vi e w = s t r c h r ( d i r n a me ( _ _ F I L E_ _ ) , d i r n a me ( $ _ S ERVE R [ ' S CR I P T_ NAME ' ] ) ) ;$ p a t h T o Ge n e r a l Vi e w = s t r _ r e p l a c e ( d i r n a me ( $ _ S E RVE R[ ' S CRI P T_ NAME ' ] ) , ' . ' , $ p a t h T o Ge n e r a l Vi e w ) ;$ p a t h To Ge n e r a l Vi e w = $ p a t h To Ge n e r a l Vi e w . " / . . / . . / g e n e r a l / " ; < - - r e t u r n i n g p a t h f r o m c u r r e. . .< ? p h p r e q u i r e _ o n c e $ p a t h T o Ge n e r a l Vi e w . ' n a v i g a t e . h e a d e r . p h p ' ; ? >

 Do s o me t h i n g< ? p h p r e q u i r e _ o n c e $ p a t h T o Ge n e r a l Vi e w . ' n a v i g a t e . f o o t e r . p h p ' ; ? >

Another Way to do the same thing:

$ p a t h T o Ge n e r a l Vi e w = J P AT H_ C OMP ONE NT _ ADMI NI S TRAT OR. " / v i e ws / g e n e r a l / " ; < - - wi l l r e t u r n ' p a. . .< ? p h p r e q u i r e _ o n c e $ p a t h T o Ge n e r a l Vi e w . ' n a v i g a t e . h e a d e r . p h p ' ; ? >

 Do s o me t h i n g< ? p h p r e q u i r e _ o n c e $ p a t h T o Ge n e r a l Vi e w . ' n a v i g a t e . f o o t e r . p h p ' ; ? >

Note: Giving the forms logical instead of the defaultnaming is of course handy when having a lot of different views.

Also, having that many defaultforms can make it difficult to determine the context. On the other hand, theview.html.php cannot be renamed, and one is always forced to look at the directory name for the view.

Essential Interaction Parameters

Everything is in place:

main and dedicated controllers;main and dedicated models;different views and their forms.

Just one big question remains: How to use them!

Three parameters are mandatory for letting Joomla! do its job:

optioncontrollertask

These three parameters are almost self explaining ;). The option part when developing a component is easy, always

assign your component name to it. For component development consider this one as a constant, of course the Joomla!

engine has more options than only components.

The controllerand taskparameters can be manipulated within your component anyway you want it to.

How it all works together

Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:

5


25/66

26/66

< f o r m a c t i o n = " i n d e x . p h p " me t h o d = " p o s t " >< i n p u t t y p e = " t e x t " n a me = " u s e r n a me " i d = " u s e r n a me " s i z e = " 3 2 " ma x l e n g t h = " 2 5 0 " v a l u e = " < ? p h p e



 / / < - - ma n d a t o / / < - - ma n d a t o / / < - - ma n d a t o u s e r - > i d ; ? > " / > / / < - - u s e r p a

< / f o r m>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any

way but will be added to the posting data.

Tip: when debugging this form, replace in the form tag me t h o d = " p o s t " temporarily with me t h o d = " g e t " . All posted

parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it

looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the

browser URL themselves. Another reason is more technical and the simple explanation is that post methods (i.e.

method="post") can contain more (complex) data. There is a third reason for using me t h o d = " p o s t " in form

processing, and that is to increase security and prevent CSRF (http://en.wikipedia.org/wiki/Cross-

site_request_forgery) attacks on your site. me t h o d = " p o s t " should always be used when the resulting operation will

modify the database.

Remark: In some developed modules you may notice that developers have also added the view parameter. This is bad

programming whilst the controller(s) should take care of the view and theform.

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this

knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.




Developing a Model-View-Controller Component - Par t 4 - Creating an Administr ator Inter face



staalandenjamesconroyuk

Retrieved from "http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4_-_Creating_an_Administrator_Interface"Categories: Tutorials | Component Development


7


27/66

28/66

< ? p h p

/ * *





* /

/ / No d i r e c t a c c e s s

d e f i n e d ( ' _ J E XE C' ) o r d i e ( ' Re s t r i c t e d a c c e s s ' ) ;

/ / Re q u i r e t h e b a s e c o n t r o l l e r

r e q u i r e _ o n c e ( J P ATH_C OMP ONENT . DS . ' c o n t r o l l e r . p h p ' ) ;

/ / Re q u i r e s p e c i f i c c o n t r o l l e r i f r e q u e s t e d

i f ( $ c o n t r o l l e r = J R e q u e s t : : g e t Wo r d ( ' c o n t r o l l e r ' ) ) { $ p a t h = J P ATH_C OMP ONENT . DS . ' c o n t r o l l e r s ' . DS . $ c o n t r o l l e r . ' . p h p ' ; i f ( f i l e _ e x i s t s ( $ p a t h ) ) { r e q u i r e _ o n c e $ p a t h ; } e l s e { $ c o n t r o l l e r = ' ' ; }}

/ / Cr e a t e t h e c o n t r o l l e r

$ c l a s s n a me = ' He l l o s C o n t r o l l e r ' . $ c o n t r o l l e r ;$ c o n t r o l l e r = n e w $ c l a s s n a me ( ) ;

/ / Pe r f o r m t h e Re q u e s t t a s k

$ c o n t r o l l e r - > e x e c u t e ( J R e q u e s t : : g e t Va r ( ' t a s k ' ) ) ;

/ / Re d i r e c t i f s e t b y t h e c o n t r o l l e r

$ c o n t r o l l e r - > r e d i r e c t ( ) ;

The view and model that we will start with is the hellos view and the hellos model. We will start with the model.

The Hellos Model

The Hellos Model will be very simple. The only operation that we currently need is the ability to retrieve the list of

hellos from the database. This operation will be implemented in a method called getData().

The JModel class has a built in protected method called _getList(). This method can be used to simplify the task of

retrieving a list of records from the database. We simply need to pass it the query and it will return the list of records.

At a later point in time, we might want to use our query from within another method. Therefore, we will create a

private method called _buildQuery() which will return the query that will be passed to _getList(). This makes it easier

to change the query as well since it is localized in one place.

Therefore we need two methods in our class: getData() and _buildQuery().

_buildQuery() simply returns the query. It looks like:

2


29/66

/ * *

* Re t u r n s t h e q u e r y

* @r e t u r n s t r i n g T h e q u e r y t o b e u s e d t o r e t r i e v e t h e r o ws f r o m t h e d a t a b a s e

* /

f u n c t i o n _ b u i l d Qu e r y ( )

{ $ q u e r y = ' S E LE CT * ' . ' F ROM # _ _ h e l l o ' ;

r e t u r n $ q u e r y ;}

getData() will obtain the query and retrieve the records from the database. Now it might happen that we need to

retrieve this list of data twice in one page load. It would be a waste to have to query the database twice. Therefore, we

will have this method store the data in a protected property so that on subsequent requests it can simply return the

data it has already retrieved. This property will be called _data. (

30/66

< ? p h p

/ * *

* He l l o s Mo d e l f o r He l l o Wo r l d Co mp o n e n t

*





* /

/ / Ch e c k t o e n s u r e t h i s f i l e i s i n c l u d e d i n J o o ml a !d e f i n e d ( ' _ J E XE C' ) o r d i e ( ) ;j i mp o r t ( ' j o o ml a . a p p l i c a t i o n . c o mp o n e n t . mo d e l ' ) ;

/ * *

* He l l o Mo d e l

*



* /

c l a s s He l l o s Mo d e l He l l o s e x t e n d s J Mo d e l

{ / * *

* He l l o s d a t a a r r a y

*

* @v a r a r r a y

* /

v a r $ _ d a t a ;

/ * *

* Re t u r n s t h e q u e r y

* @r e t u r n s t r i n g T h e q u e r y t o b e u s e d t o r e t r i e v e t h e r o ws f r o m t h e d a t a b a s e

* /

f u n c t i o n _ b u i l d Qu e r y ( )

{ $ q u e r y = ' S E LE CT * ' . ' F ROM # _ _ h e l l o ' ; r e t u r n $ q u e r y ; }

/ * *

* Re t r i e v e s t h e h e l l o d a t a

* @r e t u r n a r r a y Ar r a y o f o b j e c t s c o n t a i n i n g t h e d a t a f r o m t h e d a t a b a s e

* /

f u n c t i o n g e t Da t a ( )

{ / / L e t s l o a d t h e d a t a i f i t d o e s n ' t a l r e a d y e x i s t

i f ( e mp t y ( $ t h i s - > _ d a t a ) ) { $ q u e r y = $ t h i s - > _ b u i l d Qu e r y ( ) ; $ t h i s - > _ d a t a = $ t h i s - > _ g e t L i s t ( $ q u e r y ) ; }

r e t u r n $ t h i s - > _ d a t a ; }}

This file is saved as models/hellos.php.

The Hellos View

Now that we have a model to retrieve our data, we need to display it. This view will be fairly similar to the view from

the site section as well.

4

31/66

Just as our model was automatically instantiated in the frontend, so is it in the administrator section. Methods that start

with "get" [e.g. getData()] in the model can be accessed using the get() method of the JView class. So our view has

three lines: one to retrieve the data from the model, one to push the data into the template, and one to invoke the

display method to display the output. Thus we have:

< ? p h p

/ * *

* He l l o s V i e w f o r He l l o Wo r l d Co mp o n e n t

*

* @p a c k a g e J o o ml a . T u t o r i a l s* @s u b p a c k a g e Co mp o n e n t s



* /

/ / Ch e c k t o e n s u r e t h i s f i l e i s i n c l u d e d i n J o o ml a !

d e f i n e d ( ' _ J E XE C' ) o r d i e ( ) ;j i mp o r t ( ' j o o ml a . a p p l i c a t i o n . c o mp o n e n t . v i e w ' ) ;

/ * *

* He l l o s V i e w

*



* /

c l a s s He l l o s Vi e wHe l l o s e x t e n d s J Vi e w

{ / * *

* He l l o s v i e w d i s p l a y me t h o d

* @r e t u r n v o i d

* * /

f u n c t i o n d i s p l a y ( $ t p l = n u l l )

{

J T o o l Ba r He l p e r : : t i t l e ( J T e x t : : _ ( ' He l l o Ma n a g e r ' ) , ' g e n e r i c . p n g ' ) ;J T o o l Ba r He l p e r : : d e l e t e L i s t ( ) ;J T o o l Ba r He l p e r : : e d i t L i s t X( ) ;J T o o l Ba r He l p e r : : a d d N e w X( ) ;

/ / Ge t d a t a f r o m t h e mo d e l

$ i t e ms = & $ t h i s - > g e t ( ' Da t a ' ) ;

$ t h i s - > a s s i g n Re f ( ' i t e ms ' , $ i t e ms ) ;

p a r e n t : : d i s p l a y ( $ t p l ) ; }}

This file is saved as views/hellos/view.html.php.

Look carefully at the almost hidden differences compared to site example. The data is stored in a variable that is

encapsulated within the model. Because the data amount is huge due to using the very handy _getList(), the need for

returning a reference instead of a value is obvious. This is handled in:

$ i t e ms = & $ t h i s - > g e t ( ' Da t a ' ) ;

Looking again at this line and you will notice another difference with respect to the site view.html.php. The calling ofthe model function is done implicitly. The actual model function name is getData(). In the site example you had to call

following two lines:

$ mo d e l = & $ t h i s - > g e t Mo d e l ( ) ;$ g r e e t i n g = $ mo d e l - > g e t Da t a ( ) ;

5

32/66

Both lines are now taken care of by calling: $ t h i s - > g e t ( ' Da t a ' ) ; . Under the surface of this g e t ( ) the 'Data' is

prefixed with 'get' so when using this function make sure the model functions are preceded with 'get'. This function can

also be used in the site section. Keeping the data in the model and accessing it by reference, via g e t ( ) methods, is the

preferred way of getting data from the model.

The Hellos Template

The template will take the data pushed into it from the view and produce the output. We will display our output in a

simple table. While the frontend template was very simple, in the administrator we will need a minimal amount of

extra logic to handle looping through the data.

Here is our template:

< ? p h p d e f i n e d ( ' _ J E XE C' ) o r d i e ( ' R e s t r i c t e d a c c e s s ' ) ; ? >

< f o r m a c t i o n = " i n d e x . p h p " me t h o d = " p o s t " n a me = " a d mi n F o r m" >< d i v i d = " e d i t c e l l " >

< t a b l e c l a s s = " a d mi n l i s t " >< t h e a d >

< t r >< t h wi d t h = " 5 " >

< ? p h p e c h o J T e x t : : _ ( ' I D ' ) ; ? >< / t h >< t h >

< ? p h p e c h o J T e x t : : _ ( ' Gr e e t i n g ' ) ; ? >

< / t h >< / t r >

< / t h e a d > < ? p h p

$ k = 0 ; f o r e a c h ( $ t h i s - > i t e ms a s &$ r o w) { ? >

< t r c l a s s = " < ? p h p e c h o " r o w " . $ k ; ? >" >

< t d > < ? p h p e c h o $ r o w- > i d ; ? >

< / t d >< t d >


33/66

models/hellos.php

views/hellos/view.html.php

views/hellos/tmpl/default.php

You can now add these files to the XML install file and give it a try!

We have now implemented a basic framework for the backend admin component. A list where all of the Hellos are

displayed. The next chapter will extend this framework and add user interaction / database manipulation.





Developing a Model-View-Contr oller Component - Par t 5 - Basic Backend Framewor k


staalanden

jamesconroyuk

The full admin component can be downloaded at: com_hello4_01 (http://joomlacode.org/gf/download/frsrelease

/8111/29436/com_hello4_01.zip) .

Retrieved from "http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_5_-

_Basic_Backend_Framework"

Categories: Tutorials | Component Development


7


34/66

35/66

select certain records. This is done in our template.

In order to the add the checkboxes, we need to add an extra column into our table. We will add the column in

between the two that we already have.

In the header of the column, we will add a checkbox which can be used to toggle all the boxes below it on or off:

< t h wi d t h = " 2 0 " >< i n p u t t y p e = " c h e c k b o x " n a me = " t o g g l e " v a l u e = " " o n c l i c k = " c h e c k Al l (


36/66

form to be submitted if it is not. The fourth input field is the controller field. This is used to specify that tasks fired

from this form will be handled by the hello controller.

Here is the code for the completed default.php file:

37/66

Our default controller just isn't going to cut it when it comes to doing work - all it is capable of doing is displaying

views.

We need to be able to handle the tasks that we are launching from the Hellos view: add, edit and remove. The singular

named Hello controller is created (and located in the controllers sub-directory) to actually add, edit and remove the

individual entries.

Add and edit are essentially the same task: they both display a form to the user that allows a greeting to be edited. The

only difference is that new displays a blank form, and edit displays a form with data already in it. Since they are

similar, we will map the add task onto the edit task handler. This is specified in our constructor:

/ * *

* c o n s t r u c t o r ( r e g i s t e r s a d d i t i o n a l t a s k s t o me t h o d s )


* /

f unc t i on _ _ c o n s t r u c t ( )

{p a r e n t : : _ _ c o n s t r u c t ( ) ;

/ / Re g i s t e r Ex t r a t a s k s

$ t h i s - > r e g i s t e r T a s k ( ' a d d ' , ' e d i t ' ) ;

}

The first parameter of JController::registerTask is the task to map, and the second is the method to map it to.

We will start with handling the edit task. The controller's job is fairly simple for the edit task. All it has to do is specify

the view and layout to load (the hello view and the form layout). We will also tell Joomla! to disable the mainmenu

while we are editing our greeting. This prevents users from leaving unsaved records open.

Our edit task handler looks like:

/ * *

* d i s p l a y t h e e d i t f o r m


* /

f unc t i on e d i t ( )

{J R e q u e s t : : s e t Va r ( ' v i e w' , ' h e l l o ' ) ;J R e q u e s t : : s e t Va r ( ' l a y o u t ' , ' f o r m' ) ;J R e q u e s t : : s e t Va r ( ' h i d e ma i n me n u ' , 1 ) ;

p a r e n t : : d i s p l a y ( ) ;

}

NOTE on naming conventions: The top calling program (hello.php) makes assumptions about the file names and class

names of the controllers. To summarize for this example:

De f a u l t c o n t r o l l e r p a t h : / c o n t r o l l e r . p h pDe f a u l t c o n t r o l l e r c l a s s n a me : He l l o s Co n t r o l l e r

R e q u e s t e d c o n t r o l l e r p a t h / c o n t r o l l e r s / < r e q u e s t Na me > . p h pR e q u e s t e d c o n t r o l l e r c l a s s n a me : He l l o s C o n t r o l l e r < r e q u e s t Na me >

The code for the controller at admin/controllers/hello.php:

4


38/66

39/66

We will add two buttons to the toolbar: save and cancel. Though the functionality will be the same, we want to display

different buttons depending on whether it is a new or existing record. If it is a new record, we will display cancel. If it

already exists, we will display close.

Thus our display method looks like this:

/ * *

* d i s p l a y me t h o d o f He l l o v i e w


* * /f unc t i on d i s p l a y ( $ t p l = nul l )

{ / / g e t t h e h e l l o

$ h e l l o = & $ t h i s - > g e t ( ' Da t a ' ) ; $ i s N e w = ( $ h e l l o - > i d < 1 ) ;

$ t e x t = $ i s Ne w ? J T e x t : : _ ( ' Ne w ' ) : J T e x t : : _ ( ' E d i t ' ) ;J T o o l Ba r He l p e r : : t i t l e ( J T e x t : : _ ( ' He l l o ' ) . ' : < s ma l l > < s ma l l > [ ' . $ t e x t . ' ] < / s ma l l > < / J T o o l Ba r He l p e r : : s a v e ( ) ;

i f ( $ i s N e w) {J T o o l B a r He l p e r : : c a n c e l ( ) ;

} e l s e { / / f o r e x i s t i n g i t e ms t h e b u t t o n i s r e n a me d ` c l o s e `

J T o o l B a r He l p e r : : c a n c e l ( ' c a n c e l ' , ' C l o s e ' ) ; }

$ t h i s - > a s s i g n Re f ( ' h e l l o ' , $ h e l l o ) ;p a r e n t : : d i s p l a y ( $ t p l ) ;

}

The code for the view at admin/views/hello/view.html.php:

6


40/66


41/66


42/66

/ * *

* Me t h o d t o g e t a h e l l o

* @r e t u r n o b j e c t wi t h d a t a

* /

f unc t i on &g e t Da t a ( )

{ / / L o a d t h e d a t a i f ( e mp t y ( $ t h i s - > _ d a t a ) ) { $ q u e r y = ' S E LE CT * F ROM # _ _ h e l l o ' .

' WHE RE i d = ' . $ t h i s - > _ i d ; $ t h i s - > _ d b - > s e t Qu e r y ( $ q u e r y ) ; $ t h i s - > _ d a t a = $ t h i s - > _ d b - > l o a d Ob j e c t ( ) ; } i f ( ! $ t h i s - > _ d a t a ) { $ t h i s - > _ d a t a = ne w s t d C l a s s ( ) ;

$ t h i s - > _ d a t a - > i d = 0 ; $ t h i s - > _ d a t a - > g r e e t i n g = nul l ;

} r e t u r n $ t h i s - > _ d a t a ;}

The Form

Now all that is left is to create the form that the data will go into. Since we specified our layout as form, the form will

go in a file in the tmpl directory of the hello view called form.php:


43/66

records. We need to write code to handle and perform these tasks.

Saving a Record

The logical next step is to implement the functionality to save a record. Normally, this would require some switches

and logic to handle various cases, such as the difference between creating a new record (an INSERT query), and

updating an existing query (an UPDATE query). Also, there are complexities involved in getting the data from the

form and putting it into the query.

The Joomla! framework takes care of a lot of this for you. The JTable class makes it easy to manipulate records in thedatabase without having to worry about writing the SQL code that lies behind these updates. It also makes it easy to

transfer data from an HTML form into the database.

The JTable class is an abstract class from which you can derive child classes to work with specific tables. To use it,

you simply create a class that extends the JTable class, add your database fields as properties, and override the

constructor to specify the name of the table and the primary key.

Here is our JTable class:

10


44/66


45/66

/ * *

* Me t h o d t o s t o r e a r e c o r d

*

* @a c c e s s p u b l i c

* @r e t u r n b o o l e a n T r u e o n s u c c e s s

* /

f unc t i on s t o r e ( )

{ $ r o w = & $ t h i s - > g e t T a b l e ( ) ;

$ d a t a = J R e q u e s t : : g e t ( ' p o s t ' ) ; / / Bi n d t h e f o r m f i e l d s t o t h e h e l l o t a b l e

i f ( ! $ r o w- > b i n d ( $ d a t a ) ) { $ t h i s - > s e t E r r o r ( $ t h i s - > _ d b - > g e t E r r o r Ms g ( ) ) ; r e t u r n f al s e ;

}

/ / Ma k e s u r e t h e h e l l o r e c o r d i s v a l i d

i f ( ! $ r o w- > c h e c k ( ) ) { $ t h i s - > s e t E r r o r ( $ t h i s - > _ d b - > g e t E r r o r Ms g ( ) ) ; r e t u r n f al s e ;

}

/ / S t o r e t h e we b l i n k t a b l e t o t h e d a t a b a s e

i f ( ! $ r o w- > s t o r e ( ) ) { $ t h i s - > s e t E r r o r ( $ t h i s - > _ d b - > g e t E r r o r Ms g ( ) ) ; r e t u r n f al s e ;

}

r e t u r n t r ue ;

}

This method gets added to the hello model.

The method takes one parameter, which is an associative array of data that we want to store in the database. This caneasily be retrieved from the request as will be seen later.

You will see that the first line retrieves a reference to our JTable object. If we name our table properly, we don't have

to specify its name - the JModel class knows where to find it. You may recall that we called our table class TableHello

and put it in a file called hello.php in the tables directory. If you follow this convention, the JModel class can create

your object automatically.

The second line will retrieve the data from the form. The JRequest class makes this very easy. In this case, we are

retrieving all of the variables that were submitted using the 'POST' method. These will be returned as an associative

array.

The rest is easy - we bind, check and store. The bind() (http://docs.joomla.org/API15:JTable/bind) method will copy

values from the array into the corresponding property of the table object. In this case, it will take the values of id and

greeting and copy them to our TableHello object.

The check() (http://docs.joomla.org/API15:JTable/check) method will perform data verification. In the JTable() class,

this method simply returns true. While this doesn't provide any value for us currently, by calling this method we make

it possible to do data checking using our TableHello class in the future. This method can be overridden in our

TableHello class with a method that performs the appropriate checks.

The store() (http://docs.joomla.org/API15:JTable/store) method will take the data that is in the object and store it inthe database. If the id is 0, it will create a new record (INSERT), otherwise, it will update the existing record

(UPDATE).

12


46/66

We are now ready to add our task to the controller. Since the task that we are firing is called 'save', we must call our

method 'save'. This is simple:

/ * *

* s a v e a r e c o r d ( a n d r e d i r e c t t o ma i n p a g e )


* /

f unc t i on s a v e ( )

{

$ m o d e l = $ t h i s - > g e t Mo d e l ( ' h e l l o ' ) ;i f ( $ m o d e l - > s t o r e ( ) ) {

$ ms g = J T e x t : : _ ( ' Gr e e t i n g S a v e d ! ' ) ; } e l s e { $ ms g = J T e x t : : _ ( ' E r r o r S a v i n g Gr e e t i n g ' ) ; }

/ / Ch e c k t h e t a b l e i n s o i t c a n b e e d i t e d . . . . we a r e d o n e wi t h i t a n y wa y

$ l i n k = ' i n d e x . p h p ? o p t i o n = c o m_ h e l l o ' ; $ t h i s - > s e t R e d i r e c t ( $ l i n k , $ ms g ) ;}

All we do is get our model and invoke the store() method. Then we use the setRedirect() method to redirect back to

our list of greetings. We also pass a message along, which will be displayed at the top of the page.

Deleting a Record

Implementing the Function in the Model

In the model, we will retrieve the list of IDs to delete and call the JTable class to delete them. Here it is:

/ * *

* Me t h o d t o d e l e t e r e c o r d ( s )

*

* @a c c e s s p u b l i c

* @r e t u r n b o o l e a n T r u e o n s u c c e s s

* /

f unc t i on d e l e t e ( )

{ $ c i d s = J R e q u e s t : : g e t Va r ( ' c i d ' , a r r a y ( 0 ) , ' p o s t ' , ' a r r a y ' ) ; $ r o w = & $ t h i s - > g e t T a b l e ( ) ;

f o r e a c h ( $ c i d s a s $ c i d ) {

i f ( ! $ r o w- > d e l e t e ( $ c i d ) ) { $ t h i s - > s e t E r r o r ( $ r o w- > g e t E r r o r Ms g ( ) ) ; r e t u r n f al s e ;

} }

r e t u r n t r ue ;

}

We invoke the JRequest::getVar() method to get the data from the request, then we invoke the $row->delete() method

to delete each row. By storing errors in the model we make it possible to retrieve them later if we so choose.

Handling the Remove Task in the Controller

This is similar to the save() method which handled the save task:

13


47/66

/ * *

* r e mo v e r e c o r d ( s )


* /

f unc t i on r e mo v e ( )

{ $ m o d e l = $ t h i s - > g e t Mo d e l ( ' h e l l o ' ) ; i f ( ! $ m o d e l - > d e l e t e ( ) ) { $ ms g = J T e x t : : _ ( ' E r r o r : On e o r Mo r e G r e e t i n g s C o u l d n o t b e De l e t e d ' ) ; } e l s e {

$ ms g = J T e x t : : _ ( ' Gr e e t i n g ( s ) De l e t e d ' ) ; }

$ t h i s - > s e t R e d i r e c t ( ' i n d e x . p h p ? o p t i o n = c o m_ h e l l o ' , $ ms g ) ;}

Cancelling the Edit Operation

To cancel the edit operation, all we have to do is redirect back to the main view:

/ * *

* c a n c e l e d i t i n g a r e c o r d


* /

f unc t i on c a n c e l ( )

{ $ ms g = J T e x t : : _ ( ' Op e r a t i o n Ca n c e l l e d ' ) ; $ t h i s - > s e t Re d i r e c t ( ' i n d e x . p h p ? o p t i o n = c o m_ h e l l o ' , $ ms g ) ;}

We have now implemented a basic backend to our component. We are now able to edit the entries that are viewed in

the frontend. We have demonstrated the interaction between models, views and controllers. We have shown how the

JTable class can be extended to provide easy access to tables in the database. It can also be seen how the

JToolBarHelper class can be used to create button bars in components to present a standardized look between

components.







staalandenjamesconroyuk

14


48/66


/com_hello4_01.zip)

Retrieved from "http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_6_-_Adding_Backend_Actions"Categories: Tutorials | Component Development

This page was last modified on 9 April 2011, at 19:40.Content is available under Joomla! EDL.

15


49/66

Fr om Joomla! Documentation

A module is a lightweight and flexible extension that is used for page rendering. They are used for small bits of the

page that are generally less complex and are able to be seen across different components.

You can see many examples of modules in the standard Joomla! install: - menus - Latest News - Login form - andmany more.

This tutorial will explain how to go about creating a simple Hello World module. Through this tutorial you will learn

the basic file structure of a module. This basic structure can then be expanded to produce more elaborate modules.

There are four basic files that are used in the standard pattern of module development:

mo d _ h e l l o wo r l d . p h p - This file is the main entry point for the module. It will perform any necessaryinitialization routines, call helper routines to collect any necessary data, and include the template which willdisplay the module output.

mo d _ h e l l o wo r l d . x ml - This file contains information about the module. It defines the files that need to beinstalled by the Joomla! installer and specifies configuration parameters for the module.

h e l p e r . p h p - This file contains the helper class which is used to do the actual work in retrieving theinformation to be displayed in the module (usually from the database or some other source).

t mp l / d e f a u l t . p h p - This is the module template. This file will take the data collected by mod_helloworld.php

and generate the HTML to be displayed on the page.

The mod_helloworld.php file will perform three tasks:

include the helper.php file which contains the class to be used to collect the necessary datainvoke the appropriate helper class method to retrieve the datainclude the template to display the output.

The helper class is defined in our helper.php file. This file is included with a require_once statement:

r e q u i r e _ o n c e ( d i r n a me ( _ _ F I L E _ _ ) . DS . ' h e l p e r . p h p ' ) ;

e q u i r e _ o n c e is used because our helper functions are defined within a class, and we only want the class defined

once.

Our helper class has not been defined yet, but when it is, it will contain one method: getHello(). For our basic

example, it is not really necessary to do this - the Hello, World message that this method returns could simply be

included in the template. We use a helper class here to demonstrate this basic technique.

Our module currently does not use any parameters, but we will pass them to the helper method anyway so that it can

be used later if we decide to expand the functionality of our module.

The helper class method is invoked in the following way:

1

50/66

$ h e l l o = mo d He l l o Wo r l d He l p e r : : g e t He l l o ( $ p a r a ms ) ;

Completed mod_helloworld.php file

The complete mod_helloworld.php file is as follows:

< ? p h p

/ * ** He l l o Wo r l d ! Mo d u l e En t r y Po i n t

*


* @s u b p a c k a g e Mo d u l e s

* @l i n k h t t p : / / d e v . j o o ml a . o r g / c o mp o n e n t / o p t i o n , c o m_ j d - wi k i / I t e mi d , 3 1 / i d , t u t o r i a l s : mo d u l e s /

* @l i c e n s e GNU/ GPL , s e e L I CENS E. p h p

* mo d _ h e l l o wo r l d i s f r e e s o f t wa r e . T h i s v e r s i o n ma y h a v e b e e n mo d i f i e d p u r s u a n t

* t o t h e GNU Ge n e r a l Pu b l i c L i c e n s e , a n d a s d i s t r i b u t e d i t i n c l u d e s o r

* i s d e r i v a t i v e o f wo r k s l i c e n s e d u n d e r t h e GNU Ge n e r a l Pu b l i c L i c e n s e o r

* o t h e r f r e e o r o p e n s o u r c e s o f t wa r e l i c e n s e s .

* /

/ / n o d i r e c t a c c e s s

d e f i n e d ( ' _ J E XE C' ) o r d i e ( ' Re s t r i c t e d a c c e s s ' ) ;

/ / I n c l u d e t h e s y n d i c a t e f u n c t i o n s o n l y o n c e

r e q u i r e _ o n c e ( d i r n a me ( _ _ F I L E _ _ ) . DS . ' h e l p e r . p h p ' ) ;

$ h e l l o = mo d He l l o Wo r l d He l p e r : : g

Joomla! Documentation LF

Documents