Project

General

Profile

Coding standards and hints for Virtuemart » History » Version 13

Max Milbers, 02/18/2014 04:11 PM

1 1 Max Milbers
h1. Coding standards and hints for Virtuemart
2 1 Max Milbers
3 3 Max Milbers
In general we avoid the use of globals. Globals are hard to maintain and they are unsure variables. 
4 3 Max Milbers
5 1 Max Milbers
h2. Code Formatting:
6 1 Max Milbers
7 12 Max Milbers
We follow the joomla standard in most cases. We use camelCase for methods. For faster copypasting and working with database fields, both variable and database fields are lowercase and seperated with "_". You may use for internal variables camelCase also. 
8 12 Max Milbers
We prefer for any if/else constrution clear brackets. Clear and simple "one line if" constructions are allowed, but in case there is an else use curly brackets.
9 1 Max Milbers
10 1 Max Milbers
Example:
11 1 Max Milbers
12 1 Max Milbers
<pre>
13 1 Max Milbers
function exampleMethod($data = 0) {
14 12 Max Milbers
15 1 Max Milbers
    if (!$product_id) $product_id = JRequest::getInt('product_id', 0);
16 12 Max Milbers
17 1 Max Milbers
    if ($product_id > 0) {
18 1 Max Milbers
        ...;
19 1 Max Milbers
    }
20 1 Max Milbers
}
21 12 Max Milbers
</pre>
22 12 Max Milbers
23 13 Max Milbers
Templates keep the open and closing tags <?php and ?> in one line. Avoid closing and directly opening again. Prefer always plain html without echoing whole lines (just echo the variable instead)
24 12 Max Milbers
<pre>
25 12 Max Milbers
<?php if ($link) { ?>
26 12 Max Milbers
    <a href="<?php echo $link; ?>">My link</a>
27 12 Max Milbers
<?php } ?>
28 1 Max Milbers
</pre>
29 1 Max Milbers
30 1 Max Milbers
h2. SQL Formatting:
31 1 Max Milbers
32 1 Max Milbers
The queries should follow this format:
33 1 Max Milbers
34 10 Max Milbers
@$q  = 'SELECT `example_id` FROM  `#__vm_table` WHERE `user_id`= "' . (int)$user_id . '"';@
35 1 Max Milbers
36 1 Max Milbers
or if the
37 1 Max Milbers
38 1 Max Milbers
$user_id is an array, use $user_id["myId"]
39 1 Max Milbers
40 1 Max Milbers
Placing of the ` improves speed, because the sql-engine can parse faster ( and do not have to reparse).
41 1 Max Milbers
42 1 Max Milbers
h2. Variable Formatting:
43 1 Max Milbers
44 1 Max Milbers
Due abstract logic many people name their variables or database fields just "id", "key", "value" and so on.
45 1 Max Milbers
46 1 Max Milbers
In our case we want to rewrite the structure of an old code, therefore it is very important to find the variable in the code rather fields in the database.
47 1 Max Milbers
48 1 Max Milbers
So we want a kind of this: <classname><tablename>variable like here
49 1 Max Milbers
50 1 Max Milbers
$vendor_id or $payment_method_id
51 1 Max Milbers
52 1 Max Milbers
Exception from this rule is the use of ordering and published. Ordering and published with 0 and 1 as values are useable with the joomla standard methods.
53 1 Max Milbers
54 1 Max Milbers
h2. Filename Formatting:
55 1 Max Milbers
56 1 Max Milbers
Filenames should be lowercase.
57 1 Max Milbers
58 1 Max Milbers
Models filenames (mymodel.php), view direcorynames (myview), all helper files and probably all other files loaded by the Joomla Framework, must be lowercase, no matter how you load the file:
59 1 Max Milbers
60 1 Max Milbers
 @$this->loadHelper('adminMenu'); // looks for the file helpers/adminmenu.php@
61 1 Max Milbers
62 1 Max Milbers
More complex filenames that are specific to your task and loaded by your own code (using require_once()), e.g. mySpecificClass.php, can be camelcase.
63 1 Max Milbers
64 1 Max Milbers
Read this article for more info http://docs.joomla.org/Talk:Developing_a_Model-View-Controller_Component_-_Part_1#Use_lowercase_file_and_folder_names_in_your_components.21 
65 1 Max Milbers
66 1 Max Milbers
h2. URL Requests:
67 1 Max Milbers
68 1 Max Milbers
As written in the section __Filename Formatting__ above, Joomla requires lowercase filenames. However, URL requests are not lowercased by Joomla. In order to find the proper views and controllers, make sure you use lowercase only in requests, e.g.:
69 1 Max Milbers
70 1 Max Milbers
  $this->setRedirect('index.php?option=com_virtuemart&view=updatesMigration', $msg); // Fails
71 1 Max Milbers
$this->setRedirect('index.php?option=com_virtuemart&view=updatesmigration', $msg); // Works
72 1 Max Milbers
73 1 Max Milbers
74 1 Max Milbers
h2. Character Encoding:
75 1 Max Milbers
76 11 Max Milbers
Like in joomla we use UTF-8, without BOM. Please ensure the right character set in your IDE.
77 2 Max Milbers
78 6 Max Milbers
h2. Path constants
79 1 Max Milbers
80 6 Max Milbers
Always use:
81 6 Max Milbers
82 6 Max Milbers
JPATH_VM_SITE for the frontend (points to JPATH_SITE.DS.'components'.DS.'com_virtuemart')
83 1 Max Milbers
JPATH_VM_ADMINISTRATOR for the backend (points to JPATH_SITE.DS.'components'.DS.'com_virtuemart')
84 1 Max Milbers
85 1 Max Milbers
This is important for performance and that all pieces of code work in every application that means, plugins, modules and so on.
86 1 Max Milbers
87 7 Max Milbers
h1. Database tables and fields
88 7 Max Milbers
89 7 Max Milbers
h2. Naming convention
90 7 Max Milbers
91 7 Max Milbers
In general we follow now the nooku conventions for naming tables and fields (http://nooku.assembla.com/spaces/nooku-framework/wiki/KDatabase). 
92 7 Max Milbers
93 7 Max Milbers
All tables must start with the component name, here virtuemart => #__virtuemart_ and be lowercase.
94 7 Max Milbers
95 7 Max Milbers
All non xref tables should use plural. Don't use underscore to make long words readable. Concat them like the germans do, for exampel:
96 7 Max Milbers
vm_user_info => virtuemart_userinfos, vm_admin_menu => virtuemart_adminmenu, vm_payment_method => virtuemart_paymentmethods, ...
97 7 Max Milbers
98 7 Max Milbers
All xref tables are now added with underscore, the use of singular or plural gives a hint on the kind of the xref.
99 7 Max Milbers
For exampel the xref table linking products to categories looks like #__virtuemart_product_categories. Or the hardcore exampel category_categories :-).
100 7 Max Milbers
101 7 Max Milbers
Next is to consider that all primary keys should be always the table name in singular + id on it. Look on this as exampel
102 7 Max Milbers
103 8 Max Milbers
  CREATE TABLE IF NOT EXISTS `#__virtuemart_product_categories` (
104 7 Max Milbers
  `virtuemart_product_id` int(11) NOT NULL DEFAULT '0',
105 7 Max Milbers
  `virtuemart_category_id` int(11) NOT NULL DEFAULT '0',
106 7 Max Milbers
107 7 Max Milbers
108 1 Max Milbers
h2. Standard publishing fields use:
109 9 Max Milbers
110 7 Max Milbers
Except the published field we use now the nooku conventions. So we use   
111 1 Max Milbers
112 7 Max Milbers
  `ordering` tinyint(2) NOT NULL,
113 7 Max Milbers
  `shared` tinyint(1) NOT NULL,
114 7 Max Milbers
  `published` tinyint(1) NOT NULL DEFAULT '1',
115 7 Max Milbers
  `created_on` datetime NOT NULL default '0000-00-00 00:00:00',
116 7 Max Milbers
  `created_by` int(11) NOT NULL DEFAULT 0,
117 7 Max Milbers
  `modified_on` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
118 7 Max Milbers
  `modified_by` int(11) NOT NULL DEFAULT 0,
119 7 Max Milbers
  `locked_on` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
120 7 Max Milbers
  `locked_by` int(11) NOT NULL DEFAULT 0,
121 7 Max Milbers
122 2 Max Milbers
- publish_up and publish_down formatted in the db as datetime with standard 0000-00-00 00:00:00
123 2 Max Milbers
124 2 Max Milbers
The standard query is then 
125 2 Max Milbers
126 5 Max Milbers
	@ $db = &JFactory::getDBO();
127 5 Max Milbers
	$this->_nullDate = $db->getNullDate();
128 5 Max Milbers
	$this->_now        = JFactory::getDate()->toMySQL();
129 5 Max Milbers
130 5 Max Milbers
 $query  = 'SELECT * FROM `#__sometable` WHERE yourexampel ="myexampelvalue" AND ';
131 5 Max Milbers
 $query .= ' ( publish_up = '.$this->_db->Quote($this->_nullDate).' OR publish_up <= '.$this->_db->Quote($this->_now).' )' .
132 5 Max Milbers
 ' AND ( publish_down = '.$this->_db->Quote($this->_nullDate).' OR publish_down >= '.$this->_db->Quote($this->_now).' ) '; @