Developing a Joomla 3.x Component using RAD/FOF - Joomladay UK 2014

Developing a Joomla Component
using RAD/FOF
by Peter Martin
www.db8.nl / @pe7er
JJoooommllaaddaayy UUKK 22001144

2
>>> Sheets available: www.db8.nl <<<
>>> Component: https://github.com/pe7er/db8locate <<<
Overview
a)Introduction
b)Rapid Application Development (RAD) / FOF
c)Developing a Joomla component, back-end
d)Developing a Joomla component, front-end

3
a) Introduction: Web Application
● From scratch
– PHP/MySQL/HTML/CSS/JavaScript
● Joomla component: Joomla = Framework
– Database object
– Layout Template
– Access Control List (ACL)
– MVC → template overrides
– Plugins

4
a) Functionality component back-end
● Items - List
– Display list of items
– New / Edit an item
– Delete item(s)
– Publish/unpublish item(s)
● Category - List
– Display list of categories
– New / Edit a category
– Delete categories
– Publish/unpublish categories
● Category - Form
– Display form of a category
– Save a category
● Item - Form
– Display form of an item
– Save an item

5
a) Functionality component front-end
● Items
– Display list of items
● Category
– Display list of categories
● Category
– Display category details
● Item
– Display item details

6
b) Rapid Application
Development (RAD)

7
b) Software Development Framework
● Abstracting common code functionality
● Conventions
● Don’t Repeat Yourself (DRY)
● Nooku Framework ('Koowa') – Johan Janssens
– Joomlatools extensies (DOCman), Anahita
● Framework on Framework – Nicholas
Dionysopoulos
– Basis of Akeeba Backup, Admin Tools etc

8
Rapid Application Development (RAD)
● RAD = Framework on Framework (since J 3.2)
– Extension of Joomla! Platform
– Backwards compatible
– Less code → faster development & less bugs
– Bootstrap
– Jquery
– JSON

9
Rapid Application Development (RAD)
● Convention over configuration ->
FOF convention:
● naming of functions
● database field names
-> automatic (“automagic”) functionality
● How to use?
– XML → “configure” component using FOF
– PHP → more control over output
– Anything different? →
Override / extend FOF code like models, controllers

10
RAD/ FOF/ F0F ?
● FOF (F O F)
– Akeeba etc
● RAD – FOF implementation
– In Joomla core since 3.2
● F0F (F zero F) – Fork of FOF
– Akeeba etc

11
c) Joomla Component
with FOF – back-end

12
c) Joomla Component with FOF
● Development Environment
– Local web environment (LAMP/XAMP/MAMP)
– phpMyAdmin
– Joomla 3.3.x installation
– Git (software version control) + github.com
– IDE for PHP:
● Netbeans / PHPStorm / Eclipse / ”weapon of choice”

13
“db8 locate” component
Manage & display locations on a Google Map
– Name: “db8 Locate”
– Component name: com_db8locate
– Database tabel name: #__db8locate_items
>>> Show example of back-end in browser

14
1. basic component
(back-end)

1.Entry point
/administrator/components/com_db8locate/db8locate.php
2.Dispatcher configuration
/administrator/components/com_db8locate/fof.xml
3.SQL definition of database table(s)
/administrator/components/com_db8locate/sql/install/mysql/install.sql
4.XML installation manifest
/administrator/components/com_db8locate/db8locate.xml
5.View: list
/administrator/components/com_db8locate/views/items/tmpl/form.default.xml
6.View: form
/administrator/components/com_db8locate/views/item/tmpl/form.form.xml
7.Language files
/administrator/components/com_db8locate/language/en-GB/
en-GB.com_db8locate.sys.ini + en-GB.com_db8locate.ini
15
1. basic component (back-end)

16
1.1 basic component – entry point
<?php
defined('_JEXEC') or die();
// Load FOF
include_once JPATH_LIBRARIES.'/fof/include.php';
// Quit if FOF is not installed
if(!defined('FOF_INCLUDED')) {
JError::raiseError ('500', 'FOF is not installed');
}
FOFDispatcher::getTmpInstance('com_db8locate')->dispatch();

1.2 basic comp. – dispatcher config
/administrator/components/com_db8locate/fof.xml
17
● <?xml version="1.0" encoding="UTF-8"?>
● <fof>
● <backend>
● <dispatcher>
● <option name="default_view">items</option>
</dispatcher>
● </backend>
● </fof>

1.3 basic component – SQL definition
– ID field contains component- & fieldname (singular)
db8locate_item_id (in Joomla: “id”)
18
● Create SQL installation file:
install.sql contains:
– CREATE TABLE, table name (plural):
#__db8locate_items
– PRIMARY KEY (`db8locate_item_id`) = ID field

1.3 basic component – SQL definition
19
CREATE TABLE IF NOT EXISTS `#__db8locate_items` (
● `db8locate_item_id` bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
● `title` varchar(255) NOT NULL,
● PRIMARY KEY (`db8locate_item_id`)
● ) DEFAULT CHARSET=utf8;

1.4 basic component – XML manifest 1/2
20
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.2" type="component" method="upgrade">
<name>db8 locate</name>
<author>Peter Martin</author>
<creationDate>12 September 2014</creationDate>
<copyright>Copyright (C) 2014 Peter Martin / db8.nl</copyright>
<license>GNU General Public License version 2</license>
<authorEmail>joomla@db8.nl</authorEmail>
<version>1.0.1</version>
<description>Component to manage and display locations on a Google Map</description>

<install>
● <sql>
● <file driver="mysql" charset="utf8">sql/install/mysql/install.sql</file>
● <file driver="mysql">sql/install/mysql/install.sql</file>
●
● <file driver="mysqli" charset="utf8">sql/install/mysql/install.sql</file>
● <file driver="mysqli">sql/install/mysql/install.sql</file>
● </sql>
● </install>

1.4 basic component – XML manifest 2/2
21

<administration>

<menu view="cpanel">COM_DB8LOCATE</menu>

<files folder="backend">
<folder>sql</folder>
<filename>db8locate.php</filename>
<filename>fof.xml</filename>
</files>
</administration>
</extension>

22
1.5 basic component – view list
<?xml version="1.0" encoding="UTF-8"?>
●
● <form type="browse"
● show_header="1"
● show_filters="1"
● show_pagination="1"
● norows_placeholder="COM_DB8LOCATE_COMMON_NORECORDS">
●
● <headerset>
● <header name="db8locate_item_id" type="rowselect" tdwidth="20" />
● <header name="title" type="fieldsearchable" sortable="true"
buttons="yes" buttonclass="btn" />
● </headerset>
●
● <fieldset name="items">
● <field name="db8locate_item_id" show_id="true" type="selectrow"/>
● <field name="title" type="text" show_link="true" url="index.php?option=com_db8locate
&view=item&id=[ITEM:ID]" empty_replacement="(no title)" />
● </fieldset>
●
● </form>

23
1.6 basic component – view form
●
● <form validate="true" serverside_validate="true">
●
● <fieldset name="basic_configuration"
● label="COM_DB8LOCATE_LOCATION_ITEM_EDIT"
●
description="COM_DB8LOCATE_LOCATION_ITEM_EDIT_BASIC_DESC"
● class="span4">
●
● <field name="title" type="text"
● class="inputbox"
● label="JGLOBAL_TITLE"
● required="true"
● Size="50" />
● </fieldset>
● </form>

24
1. basic component – installation
Via Extensions > Extension Manager >
Discover

25
● List view

26
● Form view

27
● List view after couple of new & save

28
2. language file

29
2. language file
sys.ini → For menu items etc.
Put in /language/ map of db8locate component!
/administrator/components/com_db8locate/
language/en-GB/en-GB.com_db8locate.sys.ini
●
COM_DB8LOCATE="db8 Locate"
COM_DB8LOCATE_XML_DESCRIPTION="Component to
manage and display locations on a Google Map"

30
COM_DB8LOCATE="db8 Locate"
COM_DB8LOCATE_TITLE_ITEMS="Location Items"
COM_DB8LOCATE_COMMON_NORECORDS="No Location
Items"
COM_DB8LOCATE_TITLE_ITEMS_EDIT="Edit Location Items"
COM_DB8LOCATE_LOCATION_ITEM_EDIT="Location Items"
COM_DB8LOCATE_LBL_ITEM_SAVED="Location Item saved"
COM_DB8LOCATE_CONFIRM_DELETE="Delete Location Item?"
2. language file
.ini → large file for all language lables com_db8locate
/administrator/components/com_db8locate/
language/en-GB/en-GB.com_db8locate.ini
TIP: “Debug Language” & collect all “lables to translate”

31
2. language file

32
3. switch on/off

33
3. switch on/off – database field
New field “enabled” to store publication status
ALTER TABLE `#__db8locate_items` ADD `enabled`
TINYINT( 3 ) NOT NULL DEFAULT '1';

3. switch on/off – database field
34
Add to <headerset>
●
<header name="enabled" type="published" sortable="true"
tdwidth="8%" />
●
● Add to <fieldset name="items">
● <field name="enabled" type="published"/>
●

35
3. switch on/off

36
3. switch on/off – form
Add to <fieldset>
●
<field name="enabled" type="list" label="JSTATUS"
● labelclass="todo-label"
● filter="intval" size="1" default="1" >
● <option value="1">JPUBLISHED</option>
● <option value="0">JUNPUBLISHED</option>
● </field>
●

37
3. switch on/off – form

38
4. order

39
4. order – database field
New database field “ordering”
ALTER TABLE `#__db8locate_items` ADD `ordering` INT( 11
) NOT NULL DEFAULT '0';

40
4. order – list
Add to <headerset>
●
<header name="ordering" type="ordering"
sortable="true" tdwidth="10%" />
●
●
<field name="ordering" type="ordering" labelclass="order"/>
●
●

41
4. order

42
5. categories

43
5. categories – database field
Add new database field “catid” to store category_id
ALTER TABLE `#__db8locate_items` ADD `catid` INT( 10 )
UNSIGNED NOT NULL DEFAULT '0';

Note: xml has hardcoded SQL for MySQL → should be model instead
44
5. categories – list
Add to <headerset>
●
<header name="category" type="category"
●
<field name="catid" type="sql" translate="false"
query="SELECT * FROM #__categories"
key_field="id" value_field="title" />
●

45
5. categories – list

46
5. categories – form
Add to <fieldset>
●
<field name="catid" type="category"
● extension="com_db8locate"
● label="JCATEGORY"
● required="true"
● size="1" />
●

47
5. categories – form

48
5. categories – toolbar
/administrator/components/com_db8locate/toolbar.php
● <?php
class Db8locateToolbar extends FOFToolbar {
public function Db8locateHelperRenderSubmenu($vName) {
return $this->renderSubmenu($vName);
}
public function renderSubmenu($vName = null) {
if (is_null($vName)) {
$vName = $this->input->getCmd('view', 'cpanel');
}
$this->input->set('view', $vName);
parent::renderSubmenu();
$toolbar = FOFToolbar::getAnInstance($this->input->getCmd('option',
'com_db8locate'), $this->config);
$toolbar->appendLink(Jtext::_('COM_DB8LOCATE_SUBMENU_CATEGORIES'),
'index.php?option=com_categories&extension=com_db8locate', $vName ==
'categories');
}
}

49
5. categories – toolbar

5. categories – toolbar in Category Manager
50
Create button in Category Manager to navigate back to “Items”:
/administrator/components/com_db8locate/helpers/db8locate.php
● <?php
● defined('_JEXEC') or die();
●
● /**
● * Helper to display db8 locate component submenus in com_categories
● */
● abstract class Db8locateHelper {
●
● public static function addSubmenu($submenu) {
JsubMenuHelper::addEntry(JText::_(
'COM_DB8LOCATE_TITLE_ITEMS'),
'index.php?option=com_db8locate', $submenu == 'locations');
JsubMenuHelper::addEntry(JText::_(
'COM_DB8LOCATE_SUBMENU_CATEGORIES'),
'index.php?option=com_categories&view=categories
&extension=com_db8locate', $submenu == 'categories');
● }
● }

Warning: Invalid argument supplied for foreach()
in /var/www/rad/libraries/cms/helper/content.php on
line 121
51
5. categories – Category Manager
Click on “Location Categories”, Result:

52
6. access levels
1. Access to application

53
6. access levels application 1/2
/administrator/components/com_db8locate/access.xml
● <?xml version="1.0" encoding="utf-8"?>
● <access component="com_db8locate">
●
● <section name="component">
● <action name="core.admin" title="JACTION_ADMIN"
description="JACTION_ADMIN_COMPONENT_DESC" />
<action name="core.manage" title="JACTION_MANAGE"
description="JACTION_MANAGE_COMPONENT_DESC" />
● <action name="core.create" title="JACTION_CREATE"
description="JACTION_CREATE_COMPONENT_DESC" />
● <action name="core.delete" title="JACTION_DELETE"
description="JACTION_DELETE_COMPONENT_DESC" />
● <action name="core.edit" title="JACTION_EDIT"
description="JACTION_EDIT_COMPONENT_DESC" />
● <action name="core.edit.state" title="JACTION_EDITSTATE"
description="JACTION_EDITSTATE_COMPONENT_DESC" />
● </section>

54
6. access levels application 2/2
/administrator/components/com_db8locate/access.xml
● <section name="category">
● <action name="core.manage" title="JACTION_MANAGE"
description="JACTION_MANAGE_COMPONENT_DESC" />
● <action name="core.create" title="JACTION_CREATE"
description="COM_CATEGORIES_ACCESS_CREATE_DESC" />
● <action name="core.delete" title="JACTION_DELETE"
description="COM_CATEGORIES_ACCESS_DELETE_DESC" />
● <action name="core.edit" title="JACTION_EDIT"
description="COM_CATEGORIES_ACCESS_EDIT_DESC" />
● <action name="core.edit.state" title="JACTION_EDITSTATE"
description="COM_CATEGORIES_
ACCESS_EDITSTATE_DESC" />
● </section>
●
● </access>

55
6. access levels
2. (Front-end) access to
database items

56
6. access levels – list

57
7. parameters

58
7. parameters
/administrator/components/com_db8locate/config.xml
via Components > db8 locate > categories > [options]
● <?xml version="1.0" encoding="UTF-8"?>
● <config>
●
● <fieldset name="permissions"
● label="JCONFIG_PERMISSIONS_LABEL"
● description="JCONFIG_PERMISSIONS_DESC" >
●
● <field name="rules"
● type="rules"
● label="JCONFIG_PERMISSIONS_LABEL"
● filter="rules"
● component="com_db8locate"
● section="component" />
●
● </fieldset>
●
● </config>

59
8. multilingual

60
8. multilingual – database field
Add new field “language” to store language code
ALTER TABLE `#__db8locate_items` ADD `language`
CHAR( 7 ) NOT NULL DEFAULT '*';

61
8. multilingual – list
Add to <headerset>
●
<header name="language" type="language"
●
●
<field name="language" type="text" tdwidth="10%" />
●

62
8. multilingual – form
Add to <fieldset>
●
<field name="language" type="contentlanguage"
label="JFIELD_LANGUAGE_LABEL" >
● <option value="*">JALL</option>
● </field>
●
●

63
8. multilingual – form
Add to <fieldset>
●
<field name="language" type="contentlanguage"
label="JFIELD_LANGUAGE_LABEL" >
● <option value="*">JALL</option>
● </field>
●
●

64
8. multilingual – list

65
9. “magic fields”

66
9. “magic fields”
● Present in component:
enabled (“state”), ordering,
● Also add to database table:
created_by, created_on(“created”),
modified_by, modified_on(“modified”),
locked_by(“checked_out”),
locked_on(“checked_out_time”), hits
● In list view: created_by & created_on
● In form view: all fields

67
10. tags

68
10. tags
#__tags tabel stores tags:
id title
4 Joomla
5 Linux
#__contentitem_tag_map links content items
and tags:
type_alias core_content_id content_item_id tag_id type_id
com_content.article 1 1 2 1
com_weblinks.weblink 2 1 4 2
com_weblinks.weblink 2 1 5 2

69
10. tags – form
Add to <fieldset>
●
<field name="tags"
type="tag"
label="JTAG"
description="JTAG_DESC"
class="inputbox span12"
multiple="true" >
</field>

70
10. tags
Unfortunately ... not working... bug in Joomla to versie 3.2.3:
Use of com_tags only possible if JTable is used in component.

71
11. my own fields...

72
11. db8locate – database field
Add your own fields to database
ALTER TABLE `jos_db8locate_items`
● ADD `location` VARCHAR( 60 ) NOT NULL ,
● ADD `address` VARCHAR( 50 ) NOT NULL ,
● ADD `postcode` VARCHAR( 12 ) NOT NULL ,
● ADD `city` VARCHAR( 50 ) NOT NULL ,
● ADD `region` VARCHAR( 50 ) NOT NULL ,
● ADD `country` VARCHAR( 50 ) NOT NULL ,
● ADD `latitude` VARCHAR( 10 ) NOT NULL ,
● ADD `longitude` VARCHAR( 10 ) NOT NULL ,
● ADD `website` VARCHAR( 100 ) NOT NULL

73
11. db8locate – list

74
11. db8locate – further improvements
● Update your SQL installation script:
● If "required fields" are not completed,
then "save" results in emptying the fields...
/administrator/components/com_db8locate/models/items.php
●
class Db8directoryModelItems extends F0Fmodel {
● protected $_savestate = 1;
● protected function loadFormData() {
● Jfactory::getApplication()->
● setUserState('com_db8locate.add.item.data', '');
●
●
● if (empty($this->_formData)) {
● return array();
● } else {
● return $this->_formData;
● }
● }
● }

75
● Edit form too long → divide into columns
●
<fieldset name="basic_configuration"
label="COM_DB8LOCATE_ITEM_LOCATION" class="span4"> fields in column 1
</fieldset>
●
● <fieldset name="address" label="COM_DB8LOCATE_ITEM_ADDRESS"
class="span4"> fields in column 2 </fieldset>

76
● Lookup Coordinates of each Address at Google Maps API
– Add lookup code for Google Map API in Model
– Add button in Toolbar
– Add handling in Controller

77
d) Joomla Component
with FOF – front-end

78
12. basic component (front-end)
1.Entry point
/components/com_db8locate/db8locate.php
2.View: list
/components/com_db8locate/views/items/tmpl/form.default.xml
/components/com_db8locate/views/items/metadata.xml –> for menu
3.View: single item
/components/com_db8locate/views/item/tmpl/form.item.xml
/components/com_db8locate/views/item/metadata.xml –> for menu
4.Language files
/components/com_db8locate/language/en-GB/en-GB.com_db8locate.ini

79
12.1 front-end – entry point
<?php
// Load FOF
include_once JPATH_LIBRARIES.'/fof/include.php';
// Quit if FOF is not installed
if(!defined('FOF_INCLUDED')) {
JError::raiseError ('500', 'FOF is not installed');
}
FOFDispatcher::getTmpInstance('com_db8locate')->dispatch()
;

80
12.2 front-end – view list
/components/com_db8locate/views/items/tmpl/form.default.xml
<form
type="browse"
show_header="1"
show_filters="0"
show_pagination="1"
show_enabled="1"
norows_placeholder="COM_DB8LOCATE_COMMON_NORECORDS" >
<headerset>
<header name="title" type="fieldsearchable" sortable="true"buttons="true" />
<header name="city" type="fieldsearchable" sortable="true"buttons="false" />
<header name="region" sortable="true"buttons="false" />
<header name="country" sortable="true"buttons="false" tdwidth="20%" />
<header name="category" sortable="false"buttons="false" />
</headerset>
<fieldset name="items">
<field name="title" type="text" show_link="true"
url="index.php?option=com_db8locate&view=item&id=[ITEM:ID]"
class="todoitem" empty_replacement="(no title)" />
<field name="city" type="text" />
<field name="region" type="text" />
<field name="country" type="text" />
<field name="catid" type="sql" translate="false" query="SELECT * FROM #__categories"
key_field="id" value_field="title"/>
</fieldset>
</form>

81
12.2 front-end – view list

82
12.3 front-end – view details
/components/com_db8locate/views/item/tmpl/form.item.xml
<?xml version="1.0" encoding="utf-8"?>
● <form
● type="read">
●
● <fieldset name="a_single_item" class="item-container form-horizontal">
● <field name="title" type="text"
● label="COM_DB8LOCATE_TITLE"
● class="db8locate-title-field"
● size="50"/>
●
● <field name="city" type="text"
● label="COM_DB8LOCATE_CITY"
● labelclass="db8locate-field"
● size="20" />
●
● <field name="website" type="text"
● label="COM_DB8LOCATE_WEBSITE"
● labelclass="db8locate-field"
● size="40" />
●
● </fieldset>
● </form>

83
12.3 front-end – view details

84
12.4 language files
/components/com_db8locate/language/en-GB/en-GB.com_db8locate.ini
TIP: “Debug Language” & collect all “lables to translate”

85
13. more views

86
<?php
$viewTemplate = $this->getRenderedForm();
echo $viewTemplate;
?>
13. more views
Combine XML & PHP
/components/com_db8locate/views/items/tmpl/default.php
and load form.default.xml
E.g. mix with Google Maps

87
13. more views – mixed php & xml

88
13. more views
Extra (built-in) output options:
&format=csv
administrator/index.php?option=com_db8locate&format=csv
&format=json
administrator/index.php?option=com_db8locate&format=json

89
d) tools

90
Errors
● IMHO Harder to detect than "regular" Joomla
component!
● Cache!!
● Debug
– E.g. back-end error:
“An error has occurred. 1064 You have an error in your SQL syntax; check the manual that corresponds to
your MySQL server version for the right syntax to use near 'ORDER BY node.lft' at line 4 SQL=SELECT
node.id FROM jos_categories AS node, jos_categories AS parent WHERE node.lft BETWEEN parent.lft AND
parent.rgt AND parent.id = ORDER BY node.lft”
can be caused by error in the front-end!
Test: rename front-end com_db8locate temporary
– Front-end error:
Notice: Undefined variable: form_class in /var/www/rad/libraries/fof/render/strapper.php on line 676
Test: rebuilt .xml files step-by-step
– print_r($object) / echo $query / die(“stop here!”)

91
Sources
● Documentation
https://www.akeebabackup.com/documentation/fof.html
● FOF Mailinglist:
https://groups.google.com/forum/#!forum/frameworkonframework
● Source code Github:
https://github.com/akeeba/fof
● Examples:
https://github.com/akeeba/todo-fof-example/
https://github.com/akeeba/contactus
Akeeba Backup, Akeeba Ticket System
https://github.com/tuum/com_timesheet

93
Contact
Presentation available at:
http://www.db8.nl
Component db8locate available at:
https://github.com/pe7er/db8locate
Peter Martin
e-mail: info at db8.nl
website: www.db8.nl
twitter: @pe7er
Review this presentation:
https://joind.in/talk/view/11625

94
Used Photos 1/2
● Speed Typing - Matthew Bowden http://www.sxc.hu/photo/275499
● Speedometer – Abdulhamid AlFadhly http://www.sxc.hu/photo/1390189
● LONDON SKYLINE CLIP ART
http://www.clker.com/clipart-london-skyline-19.html
● Forjados 1 - Albert Lazcano http://www.sxc.hu/photo/626785
● Bengali Keyborad - Mohammad Jobaed Adnan
http://www.sxc.hu/photo/676844
● Old Light Switches - Paul Cross http://www.sxc.hu/photo/1259922
● madera en pila 1 - jean froidevaux http://www.sxc.hu/photo/313864
● Books books books... - Brandon Blinkenberg
● Sign 3: forbidden access - Davide Guglielmo

95
Used Photos 2/2
● Communications Receiver - John Munsch http://www.sxc.hu/photo/260775
● Flags of the Baltic Sea countries - Johannes Raitio
● Lock - Robert Linder http://www.sxc.hu/photo/1395379
● Basho Collage 5 - Billy Alexander http://www.sxc.hu/photo/1330749
● Earth: Night Edition - Europe - Sigurd Decroos
● Retro/Vintage TV set - "meltingdog" http://www.sxc.hu/photo/1440150
● san sebastian views 1 - ibon san martin http://www.sxc.hu/photo/94018
● Tools - J Boontje http://www.sxc.hu/photo/805571
● The End Book, EWikist, 2010
http://commons.wikimedia.org/wiki/File:The_End_Book.png

Developing a Joomla 3.x Component using RAD/FOF - Joomladay UK 2014

More Related Content

What's hot

Similar to Developing a Joomla 3.x Component using RAD/FOF - Joomladay UK 2014

More from Peter Martin

Recently uploaded

Developing a Joomla 3.x Component using RAD/FOF - Joomladay UK 2014