developing a mvc component

1

DevelopingaMVCComponent

ContentsDevelopingaMVCComponent/DevelopingaBasicComponent.................................................................5

From Joomla! Documentation...........................................................................................................5

Contents...................................................................................................................................................5

The first basic component......................................................................................................................6

Public display......................................................................................................................................6

Administrator management...............................................................................................................6

Packaging an installation zip file.......................................................................................................6

DevelopingaMVCComponent/Addingaviewtothesitepart....................................................................8

From Joomla! Documentation...........................................................................................................8

Contents...................................................................................................................................................9

Introduction.............................................................................................................................................9

Setting the controller..............................................................................................................................9

Setting the view.....................................................................................................................................11

Packaging the component.....................................................................................................................12

DevelopingaMVCComponent/Addingamenutypetothesitepart........................................................14

From Joomla! Documentation.........................................................................................................14

Contents.................................................................................................................................................14

Introduction...........................................................................................................................................14

Abstract..................................................................................................................................................15

Adding a menu item type.....................................................................................................................15


DevelopingaMVCComponent/Addingamodeltothesitepart...............................................................17


Contents.................................................................................................................................................18

Introduction...........................................................................................................................................18

Adding a model.....................................................................................................................................18


DevelopingaMVCComponent/Addingavariablerequestinthemenutype...........................................22

2


Contents.................................................................................................................................................22

Introduction...........................................................................................................................................22

Adding a variable request in the menu type.......................................................................................22


DevelopingaMVCComponent/Usingthedatabase..................................................................................26


Contents.................................................................................................................................................26

Introduction...........................................................................................................................................26

Using the database................................................................................................................................27

Adding a new field type........................................................................................................................29

Display the chosen message..................................................................................................................31


DevelopingaMVCComponent/Basicbackend..........................................................................................33


Contents.................................................................................................................................................34

Introduction...........................................................................................................................................34

Basic backend........................................................................................................................................34

Create the general controller...............................................................................................................35

Create the view......................................................................................................................................35

Create the model...................................................................................................................................38


DevelopingaMVCComponent/Addinglanguagemanagement................................................................41


Contents.................................................................................................................................................41

Introduction...........................................................................................................................................42

Adding language translation in the public site...................................................................................42

Adding language translation when managing the component..........................................................42

Adding language translation when managing the menus in the backend........................................43

Language File Location Options..........................................................................................................43

Adding translation when installing the component...........................................................................44


3

DevelopingaMVCComponent/Addingbackendactions...........................................................................47


Contents.................................................................................................................................................48

Introduction...........................................................................................................................................48

Adding a toolbar...................................................................................................................................48

Adding specific controllers...................................................................................................................50

Adding an editing view.........................................................................................................................51

Adding a model and modifying the existing one................................................................................53


DevelopingaMVCComponent/Addingdecorationstothebackend.........................................................58


Contents.................................................................................................................................................58

Introduction...........................................................................................................................................58

Adding some icons.................................................................................................................................58

Modifying the views..............................................................................................................................58

Modifying the main entry file..............................................................................................................61

Adding some strings in the language file............................................................................................62


DevelopingaMVCComponent/Addingverifications.................................................................................65


Contents.................................................................................................................................................66

Introduction...........................................................................................................................................66

Verifying the form (client side)............................................................................................................66

Verifying the form (server side)...........................................................................................................72


DevelopingaMVCComponent/Addingcategories....................................................................................76


Contents.................................................................................................................................................76

Introduction...........................................................................................................................................76

Modifying the SQL...............................................................................................................................77

Modifying the form...............................................................................................................................77

Modifying the menu type......................................................................................................................78

4

Managing the submenu........................................................................................................................79

Adding some ACL.................................................................................................................................81

Adding some translation strings..........................................................................................................82


DevelopingaMVCComponent/Addingconfiguration...............................................................................86


Contents.................................................................................................................................................86

Introduction...........................................................................................................................................86

Adding configuration parameters.......................................................................................................87

Using configuration parameters as default value...............................................................................89

Modifying the SQL...............................................................................................................................90

Modifying the backend.........................................................................................................................92

Modifying the frontend.........................................................................................................................93

Adding some translation strings..........................................................................................................96


DevelopingaMVCComponent/AddingACL.............................................................................................100

From Joomla! Documentation.......................................................................................................100

Contents...............................................................................................................................................100

Introduction.........................................................................................................................................101

Adding Access Control.......................................................................................................................101

Minimal ACL requirements at the component level.......................................................................101

Add the 2 minimal component level actions to access.xml..........................................................102

Add the permissions fieldset to config.xml...................................................................................102

Add the 'Options' toolbar button when user is authorised for it................................................103

Restrict the access to the component's backend to authorised usergroups...............................103

Adding more actions, also at category level and item level.............................................................103

Describing the actions you want to control the access to.............................................................104

Adding the setting of permissions in the component's Preferences............................................104

Displaying only the right toolbar buttons.....................................................................................105

Restricting access to the component..............................................................................................110

Add the asset_id column to the database table.............................................................................111

Restricting access to the messages.................................................................................................111

5

Setting the permission values in the assets table..........................................................................112

Showing the setting of permissions on the item level...................................................................115

Adding language strings.................................................................................................................116

Further reading...................................................................................................................................117

Deprecated classes...............................................................................................................................117

Packaging the component...................................................................................................................117

DevelopingaMVCComponent/Addinganinstalluninstallupdatescriptfile.........................................121

From Joomla! Documentation.......................................................................................................121

Contents...............................................................................................................................................121

Introduction.........................................................................................................................................121

Creating the extension script file.......................................................................................................121

Adding some language keys...............................................................................................................123

Packaging the component...................................................................................................................124

DevelopingaMVCComponent/DevelopingaBasicComponent

From Joomla! Documentation

< J2.5:Developing a MVC Component(Redirected from Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 01)

This tutorial is for Joomla! CMS Version(s)

Contents 1 The first basic component

o 1.1 Public display o 1.2 Administrator management o 1.3 Packaging an installation zip file

2 Navigate 3 Contributors

[Expand]

Articles in this Series

6

This tutorial is part of the Developing a Model-View-Controller (MVC) Component for Joomla!2.5 tutorial.

The first basic component Let's create a Hello World! component.

Public display

With your favorite file manager and editor, create a file yoursite/components/com_helloworld/helloworld.php containing

Hello world

You can test this basic component by putting index.php?option=com_helloworld in your browser address (don't forget to prefix this address with your Joomla!2.5 installation path) after installing this component.

Administrator management

With your favorite file manager and editor, create a file yoursite/administrator/components/com_helloworld/helloworld.php containing

Hello world administration

You can test this basic component by putting administrator/index.php?option=com_helloworld in your browser address after installing the component.

Packaging an installation zip file

If you have used Joomla before reading this tutorial, you have noticed that extensions are installed using a compressed file containing all the things which are needed for installing and uninstalling them.

With your favorite file manager, create a directory (outside your Joomla installation directory) containing

helloworld.xml site/helloworld.php site/index.html admin/index.html admin/helloworld.php admin/sql/index.html admin/sql/updates/index.html admin/sql/updates/mysql/index.html

7

admin/sql/updates/mysql/0.0.1.sql

admin/sql/updates/mysql/0.0.1.sql is an empty file allowing to initialise schema version of the com_helloworld component.


Create a compressed file of this directory or directly download the archive and install it using the extension manager of Joomla. You can test this basic component by putting index.php?option=com_helloworld or administrator/index.php?option=com_helloworld in your browser address. You can also notice that the Hello World! component is visible in the administrator site of your Joomla installation under the Components menu.

Note: Hello World! is tricking you into thinking that this is actually only a name, and you could call it 'fluffy' or 'bippo', but this is not true. As far as I understand the name in between the tags is getting automagically lowercased, white spaces and special characters are removed (the ! for example) and joomla starts to look for files/folders responding to this name. So the name you are giving there is actually very crucial for your component to work. In other words, if you would change "Hello World!" to "helloworld" everyhting would still work. If you would change it to "helloworld2" the component would be looking for different folders and file names.

helloworld.xml

Hello World! November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.1 Description of the Hello World component ... sql/updates/mysql

8

index.html helloworld.php Hello World! index.html helloworld.php sql

site/helloworld.php

Hello World

admin/helloworld.php

Hello World administration

index.html common to all folders

DevelopingaMVCComponent/Addingaviewtothesitepart


< J2.5:Developing a MVC Component

See: JVersion 3.2

9


Contents 1 Introduction 2 Setting the controller 3 Setting the view 4 Packaging the component 5 Navigate 6 Contributors

[Expand]


Introduction This tutorial is part of the Developing a Model-View-Controller (MVC) Component for Joomla!2.5 tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

In the Joomla!2.5 framework, third party component authors divide their code into three main parts:

models They manage the data controllers They perform tasks, set and get the states of the models and ask the views to

display views They display the content according to the type (error, feed, html, json, raw, xml)

and the layout chosen by the controllers

Setting the controller In the core code of Joomla, there is a class able to manage controllers: JController. This class has to be extended to be used in our component. In the file site/helloworld.php (entry point of our Hello World component), put these lines

site/helloworld.php

11

This would try to call a function insert() of our controller (which we would actually have to implement in HelloWorldController ).

Setting the view When JController wants to display a view, it will look for certain files in the component/com_[component_name]/views/[name of view]/ folder.

The name of the folder of the default view is the name of the component itself. In our case the path is component/com_helloworld/views/helloworld/.

The file that will contain the code of the view is called view.[view_mode].php. The default view mode, and probably the only view a component might need is the html mode. So this give us our file name which is view.html.php.

With your favorite file manager and editor, create a file site/views/helloworld/view.html.php able to display the default view and containing

site/views/helloworld/view.html.php

This template file will be included by the JView class. Therefore, here, $this refers to the HelloWorldViewHelloWorld class.

So to give an example, one could call the view inside the component/com_[component_name]/views/[name of view]/ folder by calling:

http://localhost/joomla/index.php?option=com_helloworld

(this would default to the component/com_helloworld/views/helloworld/ folder) or we could explicitly call the folder by calling

http://localhost/joomla/index.php?option=com_helloworld&view=helloworld

if we change &view=helloworld to something else, e.g. &view=fluffy we would have to create a folder:

component/com_helloworld/views/fluffy/

Copy the contents of views/helloworld to views/fluffy

The classname of the file view.html.php of the fluffy folder would be HelloWorldViewFluffy. Afterwards you can customize the contents of default.php of the fluffy subfolder for custom output and see the output by calling:

http://localhost/joomla/index.php?option=com_helloworld&view=fluffy

Packaging the component Content of your code directory

helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html

13

site/views/helloworld/tmpl/default.php admin/index.html admin/helloworld.php admin/sql/index.html admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql

Create a compressed file of this directory or directly download the archive and install it using the extension manager of Joomla. You can test this basic component by putting index.php?option=com_helloworld in your browser address.

helloworld.xml

Hello World! November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.2 Description of the Hello World component ... sql/updates/mysql index.html helloworld.php controller.php views Hello World!

14

index.html helloworld.php sql

Result: You will see by default the message contained in the variable $this->msg in the view.html.php file.

DevelopingaMVCComponent/Addingamenutypetothesitepart




Contents 1 Introduction 2 Abstract 3 Adding a menu item type 4 Packaging the component 5 Navigate 6 Contributors

[Expand]


Introduction

15

This tutorial is part of the Developing a Model-View-Controller (MVC) Component for Joomla!2.5 tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

Abstract Generally speaking, this article describes how to get a link on your joomla page to open a specific page of your component. This gets simply done by adding an xml file to your specific page into your view folder.

E.g.

site/views/helloworld/tmpl/

Contains your view page default.php that we want to open.

A file default.xml is placed next to this file with some xml. This makes joomla able to recognize the view file default.php as a menu item.

Adding a menu item type In the Joomla framework, components are executed using menu items. If you go in the menu manager of your Joomla installation a HelloWorld menu item type does not yet exist. Adding this functionality is easy in Joomla. Simply put a site/views/helloworld/tmpl/default.xml file containing:

site/views/helloworld/tmpl/default.xml

For the moment the strings won't be translated in the administrator interface. We will see in a later article how translation is performed.

Also modify your helloworld.xml file to indicate a new version:

helloworld.xml

16

Hello World! November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.3 Description of the Hello World component ... sql/updates/mysql index.html helloworld.php controller.php views Hello World! index.html helloworld.php sql

17


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php admin/index.html admin/helloworld.php admin/sql/index.html admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql

Selecting the Menu Item Type Create a compressed file of this directory or directly download the archive and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend. To do so select "Add New Menu Item" from the one of the menus in the "Menus" menu; then you can select COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE for Menu Item Type. Once selected you can see the Link information is populated with the URL for the view.

DevelopingaMVCComponent/Addingamodeltothesitepart




18

Contents 1 Introduction 2 Adding a model 3 Packaging the component 4 Navigate 5 Contributors

[Expand]



Adding a model In the Joomla framework, models are responsible for managing the data. The first function that has to be written for a model is a get function. It returns data to the caller. In our case, the caller will be the HelloWorldViewHelloWorld view. By default, the model named HelloWorldModelHelloWorld residing in site/models/helloworld.php is the main model associated to this view.

So let's have a quick look at the naming conventions with an example, since the naming convention are the actual magic, that make everything work:

The class HelloWorldViewHelloWorld resides in site/views/helloworld/view.html.php and will make use of the class HelloWorldModelHelloWorld in the file site/models/helloworld.php

So let's just assume we want to use an imaginary view fluffy, you would have to have:

The class HelloWorldViewFluffy which resides in site/views/fluffy/view.html.php. The view will make use of HelloWorldModelFluffy in the file site/models/fluffy.php. Note: the actual screen of the view: site/views/fluffy/tmpl/default.php is required as well to make this example work.

Breaking any of these bold conventions will lead to errors or a blank page.

19

So back to the actual implementation of the single classes:

With your favorite file manager and editor put a site/models/helloworld.php file containing:

site/models/helloworld.php

0.0.4 Description of the Hello World component ... sql/updates/mysql

21

in this section are copied from /site/ in the package --> index.html helloworld.php controller.php views models Hello World! index.html helloworld.php sql


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php admin/index.html admin/helloworld.php admin/sql/index.html admin/sql/updates/index.html admin/sql/updates/mysql/index.html

22


Create a compressed file of this directory or directly download the archive and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

DevelopingaMVCComponent/Addingavariablerequestinthemenutype




Contents 1 Introduction 2 Adding a variable request in the menu type 3 Packaging the component 4 Navigate 5 Contributors

[Expand]



Adding a variable request in the menu type For the moment, the displayed message is always Hello World!. Joomla!2.5 gives the possibility to add parameters to menu types. In our case, this is done in the site/views/helloworld/tmpl/default.xml file:


23

COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC Hello World! Good bye World!

Two important things to note:

the request group of fields indicates mandatory fields the name attribute can be passed to the component in the URL. In this case

?option=com_helloworld&id=1 would indicate that you had chosen option 1.

The model has to be modified in order to switch between the two different messages (which is chosen by the user with the field defined above):


0.0.5 Description of the Hello World component ... sql/updates/mysql

25

index.html helloworld.php controller.php views models Hello World! index.html helloworld.php sql

You can test this variable request by putting index.php?option=com_helloworld&id=1 or index.php?option=com_helloworld&id=2 in your browser address.


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml

26

site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php admin/index.html admin/helloworld.php admin/sql/index.html admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql


DevelopingaMVCComponent/Usingthedatabase




Contents 1 Introduction 2 Using the database 3 Adding a new field type 4 Display the chosen message 5 Packaging the component 6 Navigate 7 Contributors

[Expand]



27

Using the database Components usually manage their contents using the database. During the install/uninstall/update phase of a component, you can execute SQL queries through the use of SQL text files.

With your favorite file manager and editor create two files called admin/sql/install.mysql.utf8.sql and admin/sql/updates/mysql/0.0.6.sql. They should both have the same content, as follows:

admin/sql/install.mysql.utf8.sql and admin/sql/updates/mysql/0.0.6.sql

DROP TABLE IF EXISTS `#__helloworld`; CREATE TABLE `#__helloworld` ( `id` int(11) NOT NULL AUTO_INCREMENT, `greeting` varchar(25) NOT NULL, PRIMARY KEY (`id`) ) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8; INSERT INTO `#__helloworld` (`greeting`) VALUES ('Hello World!'), ('Good bye World!');

The file install.mysql.utf8.sql will be executed when you install this component. The file 0.0.6.sql is executed when you do an update.

Important Note: When the component is installed, the files in the SQL updates folder (for example, admin/sql/updates/mysql) are read and the name of the last file alphabetically is used to populate the component's version number in the #__schemas table. This value must be in this table in order for the automatic update to execute the update SQL files for future versions. For this reason, it is good practice to create a SQL update file for each version (even if it is empty or just has a comment). This way the #__schemas version will always match the component version.

Important Note: When saving the SQL files in utf8, be sure to save them as utf8 NO BOM or the query will fail with MySQL error #1064.

This is the install file. It will be executed if you put an appropriate order in the helloworld.xml file

helloworld.xml

Hello World! November 2009 John Doe

28

[email protected] http://www.example.org Copyright Info License Info 0.0.6 Description of the Hello World component ... sql/install.mysql.utf8.sql sql/uninstall.mysql.utf8.sql sql/updates/mysql index.html helloworld.php controller.php views models Hello World! index.html helloworld.php sql

29

tables models

Do the same for the uninstall file:

With your favorite file manager and editor put a file admin/sql/uninstall.mysql.utf8.sql containing:

admin/sql/uninstall.mysql.utf8.sql

DROP TABLE IF EXISTS `#__helloworld`;

Adding a new field type For the moment, we have used a hard coded field type for messages. We need to use our database for choosing the message.

Modify the site/views/helloworld/tmpl/default.xml file and put these lines


COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC

30

It introduces a new field type and tells Joomla to look for the field definition in the /administrator/components/com_helloworld/models/fields folder.

With your favorite file manager and editor put a file admin/models/fields/helloworld.php file containing:

admin/models/fields/helloworld.php

31

The new field type displays a drop-down list of messages to choose from. You can see the result of this change in the menu manager section for the helloworld item.

Display the chosen message When a menu item of this component is created/updated, Joomla stores the identifier of the message. The HelloWorldModelHelloWorld model has now to compute the message according to this identifier and the data stored in the database.

Modify the site/models/helloworld.php file:


33


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php admin/index.html admin/helloworld.php admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql admin/models/index.html admin/models/fields/index.html admin/models/fields/helloworld.php admin/tables/index.html admin/tables/helloworld.php


Note: site/models/helloworld.php is not up-to-date as mentioned on this page. You need to copy the code yourself.

DevelopingaMVCComponent/Basicbackend



34


Contents 1 Introduction 2 Basic backend 3 Create the general controller 4 Create the view 5 Create the model 6 Packaging the component 7 Navigate 8 Contributors

[Expand]



And check the "discussion" tab for some clarifications.

Basic backend Designing the backend interface leads us to create at least a Model-View-Controller triptych. We have to modify the administrator entry point of our component, the admin/helloworld.php file


35

// Perform the Request task $controller->execute($task); // Redirect if set by the controller $controller->redirect();

Create the general controller The entry point now gets an instance of a HelloWorld prefixed controller. Let's create a basic controller for the administrator part:

admin/controller.php

37

This layout calls several sub-layout (head, foot and body). Each sub-layout corresponds to a file prefixed by the name of the main layout (default), and an underscore.

Put a file admin/views/helloworlds/tmpl/default_head.php containing

admin/views/helloworlds/tmpl/default_head.php

39

class HelloWorldModelHelloWorlds extends JModelList { /** * Method to build an SQL query to load the list data. * * @return string An SQL query */ protected function getListQuery() { // Create a new query object. $db = JFactory::getDBO(); $query = $db->getQuery(true); // Select some fields $query->select('id,greeting'); // From the hello table $query->from('#__helloworld'); return $query; } }

The _populateState method is, by default, automatically called when a state is read by the getState method.


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php admin/index.html admin/helloworld.php admin/controller.php admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql

40

admin/models/index.html admin/models/fields/index.html admin/models/fields/helloworld.php admin/models/helloworlds.php admin/views/index.html admin/views/helloworlds/index.html admin/views/helloworlds/view.html.php admin/views/helloworlds/tmpl/index.html admin/views/helloworlds/tmpl/default.php admin/views/helloworlds/tmpl/default_head.php admin/views/helloworlds/tmpl/default_body.php admin/views/helloworlds/tmpl/default_foot.php admin/tables/index.html admin/tables/helloworld.php


helloworld.xml

Hello World! November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.7 Description of the Hello World component ... sql/install.mysql.utf8.sql sql/uninstall.mysql.utf8.sql sql/updates/mysql

41

index.html helloworld.php controller.php views models Hello World! index.html helloworld.php controller.php sql tables models views

Now you can see in your component hello-world an array with two colums, two rows and checkboxes. You can click the checkboxes in order to select the different options you want.

DevelopingaMVCComponent/Addinglanguagemanagement




Contents 1 Introduction 2 Adding language translation in the public site 3 Adding language translation when managing the component 4 Adding language translation when managing the menus in the backend 5 Language File Location Options 6 Adding translation when installing the component 7 Packaging the component 8 Navigate 9 Contributors

[Expand]

42



Joomla!2.5 manages languages for components in four different situations:

displaying a component in the public site managing a component in the backend managing menus in the backend installing a component (new in 1.7)

Joomla!2.5 uses two different location folder for languages:

one in administrator/language or language one in the component folder (administrator/components/*component*/language or

components/*component*/language)

It depends how the component is installed.

Adding language translation in the public site With your favorite file manager and editor, put a file site/language/en-GB/en-GB.com_helloworld.ini. This file will contain translation for the public part. For the moment, this file is empty

site/language/en-GB/en-GB.com_helloworld.ini

For the moment, there are no translations strings in this file.

Adding language translation when managing the component With your favorite file manager and editor, put a file admin/language/en-GB/en-GB.com_helloworld.ini. This file will contain translation for the backend part.

admin/language/en-GB/en-GB.com_helloworld.ini

43

COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC="This message will be displayed" COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL="Message" COM_HELLOWORLD_HELLOWORLD_HEADING_GREETING="Greeting" COM_HELLOWORLD_HELLOWORLD_HEADING_ID="Id"

Adding language translation when managing the menus in the backend With your favorite file manager and editor, put a file admin/language/en-GB/en-GB.com_helloworld.sys.ini. This file will contain translation for the backend part.

admin/language/en-GB/en-GB.com_helloworld.sys.ini

COM_HELLOWORLD="Hello World!" COM_HELLOWORLD_DESCRIPTION="This is the Hello World description" COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World" COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message" COM_HELLOWORLD_MENU="Hello World!"

Language File Location Options Starting with version 1.7 there are 2 ways to install language files for an extension. One can use one or the other or a combination of both.

The 1.5 way will install the files in the CORE language folders (ROOT/administrator/language/ and ROOT/language/ ). The new way since 1.6 includes the files in a "language" folder installed at the root of the extension.

Therefore an extension can include a language folder with a .sys.ini different from the one installed in joomla core language folders (this last one not being included in that language folder but in root or any other folder not installed). This let's display 2 different descriptions: one from the sys.ini in the "language" folder is used as a message displayed when install has been done, the other (from the .ini) is used for "normal" operation, i.e. when the extension is edited in back-end. This can be extremely useful when installing also uses some scripts and requires a different value for the description.

Note: The sys.ini file is also used to translate the name of the extensions in some back-end Managers and to provide menu translation for components

Therefore, the xml would include since 1.6

45

COM_HELLOWORLD="Hello World!" COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"

The COM_HELLOWORLD_DESCRIPTION can be used in the helloworld.xml file


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php site/language/index.html site/language/en-GB/index.html site/language/en-GB/en-GB.com_helloworld.ini admin/index.html admin/helloworld.php admin/controller.php admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql admin/models/index.html admin/models/fields/index.html admin/models/fields/helloworld.php admin/models/helloworlds.php admin/views/index.html admin/views/helloworlds/index.html admin/views/helloworlds/view.html.php admin/views/helloworlds/tmpl/index.html admin/views/helloworlds/tmpl/default.php admin/views/helloworlds/tmpl/default_head.php admin/views/helloworlds/tmpl/default_body.php admin/views/helloworlds/tmpl/default_foot.php

46

admin/tables/index.html admin/tables/helloworld.php admin/language/en-GB/en-GB.com_helloworld.ini admin/language/en-GB/en-GB.com_helloworld.sys.ini language/en-GB/en-GB.ini


helloworld.xml

COM_HELLOWORLD November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.8 COM_HELLOWORLD_DESCRIPTION sql/install.mysql.utf8.sql sql/uninstall.mysql.utf8.sql sql/updates/mysql index.html

47

helloworld.php controller.php views models language COM_HELLOWORLD_MENU index.html helloworld.php controller.php sql tables models views language/en-GB/en-GB.com_helloworld.ini language/en-GB/en-GB.com_helloworld.sys.ini

In this helloworld.xml file, languages are installed in:

administrator/language for the admin part (look at the xml languages tag) components/com_helloworld/language for the site part (there are no xml languages tag in

the site part of the xml description file, but the language folder is included)

The corrected zip file, download and delete the .png extension before use: [1]

DevelopingaMVCComponent/Addingbackendactions


48



Contents 1 Introduction 2 Adding a toolbar 3 Adding specific controllers 4 Adding an editing view 5 Adding a model and modifying the existing one 6 Packaging the component 7 Navigate 8 Contributors

[Expand]



Adding a toolbar In Joomla, the administrator interacts generally with components through the use of a toolbar. In the file admin/views/helloworlds/view.html.php put this content. It will create a basic toolbar and a title for the component.

The args used in ex. JToolBarHelper::addNew is used to set a controller instance which will be used after button is clicked.

admin/views/helloworlds/view.html.php

49

* HelloWorlds View */ class HelloWorldViewHelloWorlds extends JView { /** * HelloWorlds view display method * @param string $tpl The name of the template file to parse; automatically searches through the template paths. * * @return mixed A string if successful, otherwise a JError object. */ function display($tpl = null) { // Get data from the model $items = $this->get('Items'); $pagination = $this->get('Pagination'); // Check for errors. if (count($errors = $this->get('Errors'))) { JError::raiseError(500, implode('', $errors)); return false; } // Assign data to the view $this->items = $items; $this->pagination = $pagination; // Set the toolbar $this->addToolBar(); // Display the template parent::display($tpl); } /** * Setting the toolbar */ protected function addToolBar() { JToolBarHelper::title(JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS')); JToolBarHelper::deleteList('', 'helloworlds.delete'); JToolBarHelper::editList('helloworld.edit'); JToolBarHelper::addNew('helloworld.add'); } }

You can find other classic backend actions in the administrator/includes/toolbar.php file of your Joomla installation.

Since the view can perform some actions, we have to add some input data. With your favorite file manager and editor, put in the file admin/views/helloworlds/tmpl/default.php

admin/views/helloworlds/tmpl/default.php

50

51

public function getModel($name = 'HelloWorld', $prefix = 'HelloWorldModel') { $model = parent::getModel($name, $prefix, array('ignore_request' => true)); return $model; } }

admin/controllers/helloworld.php

53

Adding a model and modifying the existing one The HelloWorldViewHelloWorld view asks form and data from a model. This model has to provide a getTable, a getForm method and a loadData method (called from the JModelAdmin controller)

admin/models/helloworld.php

55

/>


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php site/language/index.html site/language/en-GB/index.html site/language/en-GB/en-GB.com_helloworld.ini admin/index.html admin/helloworld.php admin/controller.php admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql admin/models/index.html admin/models/fields/index.html admin/models/fields/helloworld.php admin/models/forms/index.html admin/models/forms/helloworld.xml admin/models/helloworld.php admin/models/helloworlds.php admin/views/index.html admin/views/helloworlds/index.html admin/views/helloworlds/view.html.php admin/views/helloworlds/tmpl/index.html admin/views/helloworlds/tmpl/default.php admin/views/helloworlds/tmpl/default_head.php

56

admin/views/helloworlds/tmpl/default_body.php admin/views/helloworlds/tmpl/default_foot.php admin/views/helloworld/index.html admin/views/helloworld/view.html.php admin/views/helloworld/tmpl/index.html admin/views/helloworld/tmpl/edit.php admin/tables/index.html admin/tables/helloworld.php admin/language/en-GB/en-GB.com_helloworld.ini admin/language/en-GB/en-GB.com_helloworld.sys.ini admin/controllers/index.html admin/controllers/helloworld.php admin/controllers/helloworlds.php language/en-GB/en-GB.ini

Create a compressed file of this directory or directly download the archive, modify the code in /admin/models/helloworld.php and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

helloworld.xml

Hello World! November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.9 COM_HELLOWORLD_DESCRIPTION sql/install.mysql.utf8.sql sql/uninstall.mysql.utf8.sql

57

sql/updates/mysql index.html helloworld.php controller.php views models language COM_HELLOWORLD_MENU index.html helloworld.php controller.php sql tables models views controllers language/en-GB/en-GB.com_helloworld.ini language/en-GB/en-GB.com_helloworld.sys.ini

58

DevelopingaMVCComponent/Addingdecorationstothebackend




Contents 1 Introduction 2 Adding some icons 3 Modifying the views 4 Modifying the main entry file 5 Adding some strings in the language file 6 Packaging the component 7 Navigate 8 Contributors

[Expand]



Adding some icons With your favorite file manager put a 16x16 image and a 48x48 image (I choose tux) in a media/images/ folder and add a media tag in your install file. Modify the menu tag in order to use the new icon.

Modifying the views In the admin/views/helloworlds/view.html.php file put these lines:

admin/views/helloworlds/view.html.php

61

// Assign the Data $this->form = $form; $this->item = $item; // Set the toolbar $this->addToolBar(); // Display the template parent::display($tpl); // Set the document $this->setDocument(); } /** * Setting the toolbar */ protected function addToolBar() { $input = JFactory::getApplication()->input; $input->set('hidemainmenu', true); $isNew = ($this->item->id == 0); JToolBarHelper::title($isNew ? JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW') : JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT'), 'helloworld'); JToolBarHelper::save('helloworld.save'); JToolBarHelper::cancel('helloworld.cancel', $isNew ? 'JTOOLBAR_CANCEL' : 'JTOOLBAR_CLOSE'); } /** * Method to set up the document properties * * @return void */ protected function setDocument() { $isNew = ($this->item->id < 1); $document = JFactory::getDocument(); $document->setTitle($isNew ? JText::_('COM_HELLOWORLD_HELLOWORLD_CREATING') : JText::_('COM_HELLOWORLD_HELLOWORLD_EDITING')); } }

This view also uses the second parameter of the JToolBarHelper::title function and set the browser title

Modifying the main entry file In the admin/helloworld.php file, put these lines in order to use the 48x48 icon:

63

site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php site/language/index.html site/language/en-GB/index.html site/language/en-GB/en-GB.com_helloworld.ini admin/index.html admin/helloworld.php admin/controller.php admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql admin/models/index.html admin/models/fields/index.html admin/models/fields/helloworld.php admin/models/forms/index.html admin/models/forms/helloworld.xml admin/models/helloworld.php admin/models/helloworlds.php admin/views/index.html admin/views/helloworlds/index.html admin/views/helloworlds/view.html.php admin/views/helloworlds/tmpl/index.html admin/views/helloworlds/tmpl/default.php admin/views/helloworlds/tmpl/default_head.php admin/views/helloworlds/tmpl/default_body.php admin/views/helloworlds/tmpl/default_foot.php admin/views/helloworld/index.html admin/views/helloworld/view.html.php admin/views/helloworld/tmpl/index.html admin/views/helloworld/tmpl/edit.php admin/tables/index.html admin/tables/helloworld.php admin/language/en-GB/en-GB.com_helloworld.ini admin/language/en-GB/en-GB.com_helloworld.menu.ini admin/controllers/index.html admin/controllers/helloworld.php admin/controllers/helloworlds.php

64

language/en-GB/en-GB.ini media/index.html media/images/index.html media/images/tux-16x16.png media/images/tux-48x48.png


helloworld.xml

Hello World! November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.10 COM_HELLOWORLD_DESCRIPTION sql/install.mysql.utf8.sql sql/uninstall.mysql.utf8.sql sql/updates/mysql index.html

65

helloworld.php controller.php views models language index.html images COM_HELLOWORLD_MENU index.html helloworld.php controller.php sql tables models views controllers language/en-GB/en-GB.com_helloworld.ini language/en-GB/en-GB.com_helloworld.sys.ini

DevelopingaMVCComponent/Addingverifications


66



Contents 1 Introduction 2 Verifying the form (client side) 3 Verifying the form (server side) 4 Packaging the component 5 Navigate 6 Contributors

[Expand]



See Form validation for some more general info on form validation (rules).

Verifying the form (client side) Forms can be verified on the client side using javascript code.

In the admin/views/helloworld/tmpl/edit.php file, put these lines

admin/views/helloworld/tmpl/edit.php

67

You may have noted that the html form contained in the admin/views/helloworld/tmpl/edit.php file now has the form-validate css class. And that we added a JHTML::_('behavior.formvalidation'); call to tell Joomla to use its javascript form validation.

Modify the admin/models/forms/helloworld.xml file to indicate that the greeting field has to be verified:

Note for the moment that the css class is now "inputbox validate-greeting" and that the attribute required is set to true. It means that this field is required and has to be verified by a handler of the form validator framework of Joomla

With your favorite file manager and editor put a file admin/models/forms/helloworld.js containing

68

admin/models/forms/helloworld.js

window.addEvent('domready', function() { document.formvalidator.setHandler('greeting', function (value) { regex=/^[^0-9]+$/; return regex.test(value); }); });

It adds a handler to the form validator of Joomla for fields having the "validate-greeting" css class. Each time the greeting field is modified, the handler will be executed to verify its validity (no digits).

The final step is to verify the form when the save button is clicked.

With your favorite file manager and editor put a file admin/views/helloworld/submitbutton.js containing

admin/views/helloworld/submitbutton.js

Joomla.submitbutton = function(task) { if (task == '') { return false; } else { var isValid=true; var action = task.split('.'); if (action[1] != 'cancel' && action[1] != 'close') { var forms = $$('form.form-validate'); for (var i=0;i

69

'Some values are unacceptable')); return false; } } }

This function will verify that all forms which have the "form-validate" css class are valid. Note that it will display an alert message translated by the Joomla framework.

The HelloWorldViewHelloWorld view class has to be modified to use these javascript files:

admin/views/helloworld/view.html.php

71

defined('_JEXEC') or die('Restricted access'); // import Joomla modelform library jimport('joomla.application.component.modeladmin'); /** * HelloWorld Model */ class HelloWorldModelHelloWorld extends JModelAdmin { /** * Returns a reference to the a Table object, always creating it. * * @param type The table type to instantiate * @param string A prefix for the table class name. Optional. * @param array Configuration array for model. Optional. * @return JTable A database object * @since 2.5 */ public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array()) { return JTable::getInstance($type, $prefix, $config); } /** * Method to get the record form. * * @param array $data Data for the form. * @param boolean $loadData True if the form is to load its own data (default case), false if not. * @return mixed A JForm object on success, false on failure * @since 2.5 */ public function getForm($data = array(), $loadData = true) { // Get the form. $form = $this->loadForm('com_helloworld.helloworld', 'helloworld', array('control' => 'jform', 'load_data' => $loadData)); if (empty($form)) { return false; } return $form; } /** * Method to get the script that have to be included on the form * * @return string Script files */ public function getScript() { return 'administrator/components/com_helloworld/models/forms/helloworld.js'; } /**

72

* Method to get the data that should be injected in the form. * * @return mixed The data for the form. * @since 2.5 */ protected function loadFormData() { // Check the session for previously entered form data. $data = JFactory::getApplication()->getUserState('com_helloworld.edit.helloworld.data', array()); if (empty($data)) { $data = $this->getItem(); } return $data; } }

Verifying the form (server side) Verifying the form on the server side is done by inheritance of JControllerForm class. We have specified in the admin/models/forms/helloworld.xml file that the validate server function will use a greeting.php file.

With your favorite file manager and editor, put a admin/models/rules/greeting.php file containing:

admin/models/rules/greeting.php

73


helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php site/language/index.html site/language/en-GB/index.html site/language/en-GB/en-GB.com_helloworld.ini admin/index.html admin/helloworld.php admin/controller.php admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql admin/models/index.html admin/models/fields/index.html admin/models/fields/helloworld.php admin/models/forms/index.html admin/models/forms/helloworld.xml admin/models/forms/helloworld.js admin/models/rules/index.html admin/models/rules/greeting.php admin/models/helloworld.php admin/models/helloworlds.php admin/views/index.html admin/views/helloworlds/index.html admin/views/helloworlds/view.html.php admin/views/helloworlds/tmpl/index.html admin/views/helloworlds/tmpl/default.php admin/views/helloworlds/tmpl/default_head.php admin/views/helloworlds/tmpl/default_body.php

74

admin/views/helloworlds/tmpl/default_foot.php admin/views/helloworld/index.html admin/views/helloworld/view.html.php admin/views/helloworld/submitbutton.js admin/views/helloworld/tmpl/index.html admin/views/helloworld/tmpl/edit.php admin/tables/index.html admin/tables/helloworld.php admin/language/en-GB/en-GB.com_helloworld.ini admin/language/en-GB/en-GB.com_helloworld.sys.ini admin/controllers/index.html admin/controllers/helloworld.php admin/controllers/helloworlds.php language/en-GB/en-GB.ini media/index.html media/images/index.html media/images/tux-16x16.png media/images/tux-48x48.png


helloworld.xml

COM_HELLOWORLD November 2009 John Doe [email protected] http://www.example.org Copyright Info License Info 0.0.11 COM_HELLOWORLD_DESCRIPTION sql/install.mysql.utf8.sql

75

sql/uninstall.mysql.utf8.sql sql/updates/mysql index.html helloworld.php controller.php views models language index.html images COM_HELLOWORLD_MENU index.html helloworld.php controller.php sql tables models views controllers

76

language/en-GB/en-GB.com_helloworld.ini language/en-GB/en-GB.com_helloworld.sys.ini

DevelopingaMVCComponent/Addingcategories




Contents 1 Introduction 2 Modifying the SQL 3 Modifying the form 4 Modifying the menu type 5 Managing the submenu 6 Adding some ACL 7 Adding some translation strings 8 Packaging the component 9 Zips 10 Navigate 11 Contributors

[Expand]



77

The Joomla framework has implemented the use of categories for all components. Adding categorized ability to a component is fairly simple.

Modifying the SQL In order to manage categories, we have to change the SQL tables.

With your favorite editor, modify admin/sql/install.mysql.utf8.sql and put these lines:

admin/sql/install.mysql.utf8.sql

DROP TABLE IF EXISTS `#__helloworld`; CREATE TABLE `#__helloworld` ( `id` int(11) NOT NULL AUTO_INCREMENT, `greeting` varchar(25) NOT NULL, `catid` int(11) NOT NULL DEFAULT '0', PRIMARY KEY (`id`) ) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8; INSERT INTO `#__helloworld` (`greeting`) VALUES ('Hello World!'), ('Good bye World!');


ALTER TABLE `#__helloworld` ADD `catid` int(11) NOT NULL DEFAULT '0'

Modifying the form A HelloWorld message can now belong to a category. We have to modify the editing form. In the admin/models/forms/helloworld.xml file, put these lines:

admin/models/forms/helloworld.xml

JOPTION_SELECT_CATEGORY

Note that the category can be 0 (representing no category).

Modifying the menu type The HelloWorld menu type displays a drop down list of all messages. If the message is categorized, we have to add the category in this display.

In the admin/models/fields/helloworld.php file, put these lines:

admin/models/fields/helloworld.php

79

protected $type = 'HelloWorld'; /** * Method to get a list of options for a list input. * * @return array An array of JHtml options. */ protected function getOptions() { $db = JFactory::getDBO(); /// $query = new JDatabaseQuery; WARNING - There's an error in this line, JDatabaseQuery is an abstract class $query = $db->getQuery(true); // THIS IS THE FIX, WARNING IT MUST BE FIXED IN THE ZIP FILES $query->select('#__helloworld.id as id,greeting,#__categories.title as category,catid'); $query->from('#__helloworld'); $query->leftJoin('#__categories on catid=#__categories.id'); $db->setQuery((string)$query); $messages = $db->loadObjectList(); $options = array(); if ($messages) { foreach($messages as $message) { $options[] = JHtml::_('select.option', $message->id, $message->greeting . ($message->catid ? ' (' . $message->category . ')' : '')); } } $options = array_merge(parent::getOptions(), $options); return $options; } }

It will now display the category between parenthesis.

Managing the submenu The com_categories component allows to set the submenu using a helper file. With your favorite file manager and editor, put a admin/helpers/helloworld.php file containing these lines:

admin/helpers/helloworld.php

81

*/ class HelloWorldController extends JController { /** * display task * * @return void */ public function display($cachable = false, $urlparams = false) { // set default view if not set $input = JFactory::getApplication()->input; $input->set('view', $input->getCmd('view', 'HelloWorlds')); // call parent behavior parent::display($cachable, $urlparams); // Set the submenu HelloWorldHelper::addSubmenu('messages'); } }

Adding some ACL admin/access.xml

NOTE: If you don't add this file, buttons "New" "Edit" and ... don't show in category view . for more information read section Adding ACL on top of the page.


83

helloworld.xml site/index.html site/helloworld.php site/controller.php site/views/index.html site/views/helloworld/index.html site/views/helloworld/view.html.php site/views/helloworld/tmpl/index.html site/views/helloworld/tmpl/default.xml site/views/helloworld/tmpl/default.php site/models/index.html site/models/helloworld.php site/language/index.html site/language/en-GB/index.html site/language/en-GB/en-GB.com_helloworld.ini admin/index.html admin/helloworld.php admin/controller.php admin/access.xml admin/sql/index.html admin/sql/install.mysql.utf8.sql admin/sql/uninstall.mysql.utf8.sql admin/sql/updates/index.html admin/sql/updates/mysql/index.html admin/sql/updates/mysql/0.0.1.sql admin/sql/updates/mysql/0.0.6.sql admin/sql/updates/mysql/0.0.12.sql admin/models/index.html admin/models/fields/index.html admin/m

developing a mvc component

Documents