Development best practices

Joomla!

  • Stick to Joomla! MVC as possible
  • Use PHP versions tested/marked as compatible with Joomla
  • Keep PHP warnings ON (PHP+Joomla)
  • Each developer has to handle version in Joomla build file AND Java pom files before commit in branch (or request an integration)
  • Joomla stores dates at GMT time, look at : http://webamoeba.co.uk/blog/working-with-dates-in-joomla/

Javascript

  • javascript must be in js files and not in view
  • javascript event should be set via javascript and not in html
  • chaining should be use everytime it's possible
  • if possible, generated javascript should be store in a .js.php file in the same folder than js files (ie: js for Thesaurus)
  • AJAX call can be reduce by using more precise DOM selector (cf resources.js:initActionList)
  • Minified javascript must be loaded when joomla is not in DEBUG mode but readable non minified javascript should be loaded in DEBUG mode.
    if(JDEBUG)
       $doc->addScript('library.debug.js');
    }else{
       $doc->addScript('library.minify.js');
    }
    
  • by using namespace, js objects default settings can be set once ; object's instances can extend/override this default settings ; by having default settings let's uniformize the solution (cf datatables definition in version.js)
  • JS strings must use Joomla JS translation and INI files

SQL

  • SQL files should be review to be more concistent.
  • All SQL files must be located in com_easysdi_core
  • Keep consistency (names, types, constraints) between INSTALL and UPDATE scripts
  • a DROP FOREIGN KEY statement should preceed an ADD FOREIGN KEY statement

Mysql

Each 'CREATE TABLE':
  • is preceded by a DROP TABLE ;
  • defines its ENGINE ;
  • defines its COLLATE ;
  • define its CHARSET ;
  • have COMMENT to describe its utility (and its options if necessary) ;
  • column_definition can override the default table charset/collate (add a comment on that column to explain the reason) ;
  • key_definition should at least define the PRIMARY_KEY ;
  • ON DELETE/UPDATE have to be defined for each FOREIGN KEY (current behavior must be reviewed)

Each 'INSERT' must be used with 'INSERT IGNORE' to prevent error if the record already exists

Each 'ALTER TABLE `#__tablename` ADD CONSTRAINT `#__fkname` FOREIGN KEY' must be preceded by

CALL drop_foreign_key('tablename', 'fkname');

drop_foreign_key is a PROCEDURE that deletes the foreign key only if it exists. It has been created in the easysdi_cor preflight installer script.

Each 'ALTER TABLE `#__tablename` ADD COLUMN `columname` ' must be preceded by

CALL drop_column('tablename', 'columname');

drop_column is a PROCEDURE that deletes the column only if it exists. It has been created in the easysdi_cor preflight installer script.

System tables -> classes

  • In case of reused systables values in code: create a class containing enums:
    • we can directly make reference to this constants from everywhere without having to maintain the list in various place
    • constants are more readable than integer (with or without comment)
    • commenting removed table entries can hold history and be helpful for comprehension

UI

  • Use default modals as possible (Bootstrap in Joomla!)
  • Modals buttons should be placed and colored as specified in #924 (img)
  • Keep consistency with buttons placement and colors (see: #924)

Code style

File headers

PHP and JS files should have the following headers:

/**
 * @version     4.x.x
 * @package     com_easysdi_[component]
 * @copyright   Copyright (C) 2013-2015. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE.txt
 * @author      EasySDI Community <contact@easysdi.org> - http://www.easysdi.org
 */

Note : x.x is the current version. On version update, the continuous integration will adapt the headers. (ref #988)

!! Temporary down : use manual script : https://forge.easysdi.org/projects/community/wiki/Update_headers_script

External libraries

  • External libraries have to be validated by TC before add or upgrade
  • If any hack has to be done in external libs, the have to be validated by TC, and reported in 4 libs code hack list

SVN Management

SVN move
If you have to move a file and in order not to loose history of revisions, use a svn "move".
In windows with tortoise svn :
If you want to move files around inside your working copy, perhaps to a different sub-folder, use the right mouse drag-and-drop handler:

select the files or directories you want to move

right drag them to the new location inside the working copy

release the right mouse button

in the popup menu select Context Menu → SVN Move versioned files here

Make one commit per ticket.