phpBB3 • Coding Guidelines

3.i. Style Config Files

Style cfg files are simple name-value lists with the information necessary for installing a style. Similar cfg files exist for templates, themes and imagesets. These follow the same principle and will not be introduced individually. Styles can use installed components by using the required_theme/required_template/required_imageset entries. The important part of the style configuration file is assigning an unique name.

Style cfg files are simple name-value lists with the information necessary for installing a style. The important part of the style configuration file is assigning an unique name.

-        # General Information about this style
-        name = prosilver_duplicate
-        copyright = © phpBB Group, 2007
-        version = 3.0.3
-        required_template = prosilver
-        required_theme = prosilver
-        required_imageset = prosilver
+# General Information about this style
+name = prosilver_duplicate
+copyright = © phpBB Group, 2007
+version = 3.1.0
+
+# Defining a different template bitfield
+# template_bitfield = lNg=
+
+# Parent style
+# Set value to empty or to this style's name if this style does not have a parent style
+parent = prosilver

3.2. General Styling Rules

Templates should be produced in a consistent manner. Where appropriate they should be based off an existing copy, e.g. index, viewforum or viewtopic (the combination of which implement a range of conditional and variable forms). Please also note that the indentation and coding guidelines also apply to templates where possible.

@@ -1175,7 +1179,7 @@ append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&

Row colours/classes are now defined by the template, use an IF S_ROW_COUNT switch, see viewtopic or viewforum for an example.

Remember block level ordering is important ... while not all pages validate as XHTML 1.0 Strict compliant it is something we're trying to work on.

Remember block level ordering is important.

Use a standard cellpadding of 2 and cellspacing of 0 on outer tables. Inner tables can vary from 0 to 3 or even 4 depending on the need.

@@ -1243,13 +1247,13 @@ append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&

A bit later loops will be explained further. To not irritate you we will explain conditionals as well as other statements first.

Including files

Something that existed in 2.0.x which no longer exists in 3.0.x is the ability to assign a template to a variable. This was used (for example) to output the jumpbox. Instead (perhaps better, perhaps not but certainly more flexible) we now have INCLUDE. This takes the simple form:

Something that existed in 2.0.x which no longer exists in 3.x is the ability to assign a template to a variable. This was used (for example) to output the jumpbox. Instead (perhaps better, perhaps not but certainly more flexible) we now have INCLUDE. This takes the simple form:

 <!-- INCLUDE filename -->

You will note in the 3.0 templates the major sources start with  or , etc. In 2.0.x control of "which" header to use was defined entirely within the code. In 3.0.x the template designer can output what they like. Note that you can introduce new templates (i.e. other than those in the default set) using this system and include them as you wish ... perhaps useful for a common "menu" bar or some such. No need to modify loads of files as with 2.0.x.

You will note in the 3.x templates the major sources start with  or , etc. In 2.0.x control of "which" header to use was defined entirely within the code. In 3.x the template designer can output what they like. Note that you can introduce new templates (i.e. other than those in the default set) using this system and include them as you wish ... perhaps useful for a common "menu" bar or some such. No need to modify loads of files as with 2.0.x.

Added in 3.0.6 is the ability to include a file using a template variable to specify the file, this functionality only works for root variables (i.e. not block variables).

@@ -1281,7 +1285,7 @@ append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&amp;
 it will be included and executed inline.

A note, it is very much encouraged that template designers do not include PHP. The ability to include raw PHP was introduced primarily to allow end users to include banner code, etc. without modifying multiple files (as with 2.0.x). It was not intended for general use ... hence www.phpbb.com will not make available template sets which include PHP. And by default templates will have PHP disabled (the admin will need to specifically activate PHP for a template).
 
 Conditionals/Control structures
-The most significant addition to 3.0.x are conditions or control structures, "if something then do this else do that". The system deployed is very similar to Smarty. This may confuse some people at first but it offers great potential and great flexibility with a little imagination. In their most simple form these constructs take the form:
+The most significant addition to 3.x are conditions or control structures, "if something then do this else do that". The system deployed is very similar to Smarty. This may confuse some people at first but it offers great potential and great flexibility with a little imagination. In their most simple form these constructs take the form:
 
  <!-- IF expr -->
@@ -1352,7 +1356,7 @@ div
 <!-- ENDIF -->
 
 
-Each statement will be tested in turn and the relevant output generated when a match (if a match) is found. It is not necessary to always use ELSEIF, ELSE can be used alone to match "everything else".

So what can you do with all this? Well take for example the colouration of rows in viewforum. In 2.0.x row colours were predefined within the source as either row color1, row color2 or row class1, row class2. In 3.0.x this is moved to the template, it may look a little daunting at first but remember control flows from top to bottom and it's not too difficult:
+Each statement will be tested in turn and the relevant output generated when a match (if a match) is found. It is not necessary to always use ELSEIF, ELSE can be used alone to match "everything else".

So what can you do with all this? Well take for example the colouration of rows in viewforum. In 2.0.x row colours were predefined within the source as either row color1, row color2 or row class1, row class2. In 3.x this is moved to the template, it may look a little daunting at first but remember control flows from top to bottom and it's not too difficult:
 
  <table>
-- 
cgit v1.2.1


From 6deb7b3671c29ab7ce1db6e11b5c6be0950d265f Mon Sep 17 00:00:00 2001
From: Igor Wiedler 
Date: Sat, 31 Mar 2012 02:50:19 +0200
Subject: [feature/class-prefix] Rename user and session to phpbb_*

PHPBB-10609
---
 phpBB/docs/coding-guidelines.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index e6dfe579e9..6d428916c7 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -248,7 +248,7 @@ PHPBB_QA                   (Set board to QA-Mode, which means the updater also c
 If the PHPBB_USE_BOARD_URL_PATH constant is set to true, phpBB uses generate_board_url() (this will return the boards url with the script path included) on all instances where web-accessible images are loaded. The exact locations are:
 
 
-	/includes/session.php - user::img()
+	/includes/user.php - phpbb_user::img()
 	/includes/functions_content.php - smiley_text()
 
 
-- 
cgit v1.2.1


From 02cc32b901d29df4b67c0d09c02370cbaf61170d Mon Sep 17 00:00:00 2001
From: Senky 
Date: Mon, 16 Apr 2012 15:19:10 +0200
Subject: [ticket/10161] coding-guidelines.html updated

PHPBB3-10161
---
 phpBB/docs/coding-guidelines.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index 6d428916c7..e60d20cd43 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -356,7 +356,7 @@ phpbb_dir_subdir_class_name - includes/dir/subdir/class_name.php
 	The basic philosophy here is to not hurt code clarity for the sake of laziness. This has to be balanced by a little bit of common sense, though; print_login_status_for_a_given_user() goes too far, for example -- that function would be better named print_user_login_status(), or just print_login_status().
 
 	Special Namings: 
-	For all emoticons use the term smiley in singular and smilies in plural.
+	For all emoticons use the term smiley in singular and smilies in plural. For emails we use the term email (without dash between “e” and “m”)
 
 	2.ii. Code Layout
 
-- 
cgit v1.2.1


From 0858a8023be7b01e308959383bc1f955dbd4bf2d Mon Sep 17 00:00:00 2001
From: Senky 
Date: Mon, 16 Apr 2012 23:53:11 +0200
Subject: [ticket/10161] added fullstop to the end of sentence

PHPBB3-10161
---
 phpBB/docs/coding-guidelines.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index e60d20cd43..3f2c142ac6 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -356,7 +356,7 @@ phpbb_dir_subdir_class_name - includes/dir/subdir/class_name.php
 	The basic philosophy here is to not hurt code clarity for the sake of laziness. This has to be balanced by a little bit of common sense, though; print_login_status_for_a_given_user() goes too far, for example -- that function would be better named print_user_login_status(), or just print_login_status().
 
 	Special Namings: 
-	For all emoticons use the term smiley in singular and smilies in plural. For emails we use the term email (without dash between “e” and “m”)
+	For all emoticons use the term smiley in singular and smilies in plural. For emails we use the term email (without dash between “e” and “m”).
 
 	2.ii. Code Layout
 
-- 
cgit v1.2.1


From 3978e2620ea3ad50f80bc273542ff9dc830743fd Mon Sep 17 00:00:00 2001
From: Callum Macrae 
Date: Sun, 29 Apr 2012 19:07:48 +0100
Subject: [ticket/10855] Modified coding guidelines to reflect JS brace
 changes.

Braces always go on the same line in JavaScript.

PHPBB3-10855
---
 phpBB/docs/coding-guidelines.html | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index 3f2c142ac6..fbec59a6ff 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -397,7 +397,7 @@ for ($i = 0; $i < size; $i++)
 	
 
 	Where to put the braces:
-	This one is a bit of a holy war, but we're going to use a style that can be summed up in one sentence: Braces always go on their own line. The closing brace should also always be at the same column as the corresponding opening brace, examples:
+	In PHP code, braces always go on their own line. The closing brace should also always be at the same column as the corresponding opening brace, examples:
 
 	 if (condition)
@@ -427,6 +427,30 @@ function do_stuff()
 	...
 }
 	
+	
+	In JavaScript code, braces always go on the same line:
+
+	+if (condition) {
+	while (condition2) {
+		...
+	}
+} else {
+	...
+}
+
+for (var i = 0; i < size; i++) {
+	...
+}
+
+while (condition) {
+	...
+}
+
+function do_stuff() {
+	...
+}
+	
 
 	Use spaces between tokens:
 	This is another simple, easy step that helps keep code readable without much effort. Whenever you write an assignment, expression, etc.. Always leave one space between the tokens. Basically, write code as if it was English. Put spaces between variable names and operators. Don't put spaces just after an opening bracket or before a closing bracket. Don't put spaces just before a comma or a semicolon. This is best shown with a few examples, examples:
-- 
cgit v1.2.1


From ee2e2cb2c36d7abf7571d2593061eedfdf5edb8f Mon Sep 17 00:00:00 2001
From: Callum Macrae 
Date: Thu, 3 May 2012 22:30:22 +0100
Subject: [ticket/10855] Added array trailing commas info in js to guidelines.

PHPBB3-10855
---
 phpBB/docs/coding-guidelines.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index fbec59a6ff..be78ad0b3b 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -526,7 +526,7 @@ $post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&amp;start=$start";
 	In SQL statements mixing single and double quotes is partly allowed (following the guidelines listed here about SQL formatting), else one should try to only use one method - mostly single quotes.
 
 	Commas after every array element:
-	If an array is defined with each element on its own line, you still have to modify the previous line to add a comma when appending a new element. PHP allows for trailing (useless) commas in array definitions. These should always be used so each element including the comma can be appended with a single line
+	If an array is defined with each element on its own line, you still have to modify the previous line to add a comma when appending a new element. PHP allows for trailing (useless) commas in array definitions. These should always be used so each element including the comma can be appended with a single line. In JavaScript, you should not use the trailing comma, as IE doesn't like it.
 
 	// wrong
 	-- 
cgit v1.2.1


From 06efa6c0beac3cb4fed0e7412c3b60f91f4181bb Mon Sep 17 00:00:00 2001
From: Callum Macrae 
Date: Thu, 3 May 2012 22:34:35 +0100
Subject: [ticket/10855] Added JS camelCaps info to guidelines.

PHPBB3-10855
---
 phpBB/docs/coding-guidelines.html | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index be78ad0b3b..237bc18d20 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -295,11 +295,17 @@ PHPBB_QA                   (Set board to QA-Mode, which means the updater also c
 	We will not be using any form of hungarian notation in our naming conventions. Many of us believe that hungarian naming is one of the primary code obfuscation techniques currently in use.
 
 	Variable Names:
-	Variable names should be in all lowercase, with words separated by an underscore, example:
+	In PHP, variable names should be in all lowercase, with words separated by an underscore, example:
 
 	
 		$current_user is right, but $currentuser and  $currentUser are not.
 	
+	
+	In JavaScript, variable names should use camel caps:
+	
+	
+		currentUser is right, but currentuser and current_user are not.
+	
 
 	Names should be descriptive, but concise. We don't want huge sentences as our variable names, but typing an extra couple of characters is always better than wondering what exactly a certain variable is for. 
 
@@ -317,7 +323,7 @@ for ($i = 0; $i < $outer_size; $i++)
 	
 
 	Function Names:
-	Functions should also be named descriptively. We're not programming in C here, we don't want to write functions called things like "stristr()". Again, all lower-case names with words separated by a single underscore character. Function names should preferably have a verb in them somewhere. Good function names are print_login_status(), get_user_data(), etc. 
+	Functions should also be named descriptively. We're not programming in C here, we don't want to write functions called things like "stristr()". Again, all lower-case names with words separated by a single underscore character in PHP, and camel caps in JavaScript. Function names should preferably have a verb in them somewhere. Good function names are print_login_status(), get_user_data(), etc. Constructor functions in JavaScript should begin with a capital letter.
 
 	Function Arguments:
 	Arguments are subject to the same guidelines as variable names. We don't want a bunch of functions like: do_stuff($a, $b, $c). In most cases, we'd like to be able to tell how to use a function by just looking at its declaration. 
-- 
cgit v1.2.1


From 22cc7c73fdb26420bdf5b7a509da9a22925e274a Mon Sep 17 00:00:00 2001
From: Callum Macrae 
Date: Tue, 22 May 2012 19:38:30 +0100
Subject: [ticket/10855] Fixed a couple issues in coding guidelines.

PHPBB3-10855
---
 phpBB/docs/coding-guidelines.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'phpBB/docs/coding-guidelines.html')

diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html
index 237bc18d20..ae4655e094 100644
--- a/phpBB/docs/coding-guidelines.html
+++ b/phpBB/docs/coding-guidelines.html
@@ -301,7 +301,7 @@ PHPBB_QA                   (Set board to QA-Mode, which means the updater also c
 		$current_user is right, but $currentuser and  $currentUser are not.

In JavaScript, variable names should use camel caps:

In JavaScript, variable names should use camel case:

currentUser is right, but currentuser and current_user are not.

@@ -532,7 +532,7 @@ $post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&start=$start";

In SQL statements mixing single and double quotes is partly allowed (following the guidelines listed here about SQL formatting), else one should try to only use one method - mostly single quotes.

Commas after every array element:

If an array is defined with each element on its own line, you still have to modify the previous line to add a comma when appending a new element. PHP allows for trailing (useless) commas in array definitions. These should always be used so each element including the comma can be appended with a single line. In JavaScript, you should not use the trailing comma, as IE doesn't like it.

If an array is defined with each element on its own line, you still have to modify the previous line to add a comma when appending a new element. PHP allows for trailing (useless) commas in array definitions. These should always be used so each element including the comma can be appended with a single line. In JavaScript, do not use the trailing comma, as it causes browsers to throw errors.

// wrong

-- 
cgit v1.2.1

Language Tag:

7. VCS Guidelines

7.i. Repository Structure

7.ii. Commit Messages and Repository Rules

9. Copyright and disclaimer

8. Copyright and disclaimer

Associative array keys:

Magic numbers:

Shortcut operators:

SQL Quotes:

sql_build_query():

Use of in_array():

2.v. General Guidelines

Variables:

Errors and messages:

General function usage:

3.2. General Styling Rules

4.i. General Templating

File naming

Variables

Blocks/Loops

Forms

4.ii. Template Inheritance

Encoding:

Coding Guidelines

Coding Guidelines

4.ii. Template Inheritance

4.ii. Styles Tree

3.i. Style Config Files

3.2. General Styling Rules

Including files

Conditionals/Control structures

Special Namings:

2.ii. Code Layout

Special Namings:

2.ii. Code Layout

Where to put the braces:

Use spaces between tokens:

Commas after every array element:

Variable Names:

Function Names:

Function Arguments:

Commas after every array element: