| [ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en" xml:lang="en"> 3 <head> 4 5 <meta http-equiv="content-type" content="text/html; charset=utf-8" /> 6 <meta http-equiv="content-style-type" content="text/css" /> 7 <meta http-equiv="content-language" content="en" /> 8 <meta http-equiv="imagetoolbar" content="no" /> 9 <meta name="resource-type" content="document" /> 10 <meta name="distribution" content="global" /> 11 <meta name="copyright" content="phpBB Group" /> 12 <meta name="keywords" content="" /> 13 <meta name="description" content="Olympus coding guidelines document" /> 14 <title>phpBB3 • Coding Guidelines</title> 15 16 <link href="stylesheet.css" rel="stylesheet" type="text/css" media="screen, projection" /> 17 18 </head> 19 20 <body id="phpbb" class="section-docs"> 21 22 <div id="wrap"> 23 <a id="top" name="top" accesskey="t"></a> 24 <div id="page-header"> 25 <div class="headerbar"> 26 <div class="inner"><span class="corners-top"><span></span></span> 27 28 <div id="doc-description"> 29 <a href="../index.php" id="logo"><img src="site_logo.gif" alt="" /></a> 30 <h1>Coding Guidelines</h1> 31 <p>Olympus coding guidelines document</p> 32 <p style="display: none;"><a href="#start_here">Skip</a></p> 33 </div> 34 35 <span class="corners-bottom"><span></span></span></div> 36 </div> 37 </div> 38 39 <a name="start_here"></a> 40 41 <div id="page-body"> 42 43 <!-- BEGIN DOCUMENT --> 44 45 <p>These are the phpBB Coding Guidelines for Olympus, all attempts should be made to follow them as closely as possible.</p> 46 47 <h1>Coding Guidelines</h1> 48 49 <div class="paragraph menu"> 50 <div class="inner"><span class="corners-top"><span></span></span> 51 52 <div class="content"> 53 54 <ol> 55 <li><a href="#defaults">Defaults</a> 56 <ol style="list-style-type: lower-roman;"> 57 <li><a href="#editorsettings">Editor Settings</a></li> 58 <li><a href="#fileheader">File Header</a></li> 59 <li><a href="#locations">File Locations</a></li> 60 <li><a href="#constants">Special Constants</a></li> 61 </ol> 62 </li> 63 <li><a href="#code">Code Layout/Guidelines</a> 64 <ol style="list-style-type: lower-roman;"> 65 <li><a href="#namingvars">Variable/Function Naming</a></li> 66 <li><a href="#codelayout">Code Layout</a></li> 67 <li><a href="#sql">SQL/SQL Layout</a></li> 68 <li><a href="#optimizing">Optimizations</a></li> 69 <li><a href="#general">General Guidelines</a></li> 70 </ol> 71 </li> 72 <li><a href="#styling">Styling</a> 73 <ol style="list-style-type: lower-roman;"> 74 <li><a href="#cfgfiles">Style Config Files</a></li> 75 <li><a href="#genstyling">General Styling Rules</a></li> 76 </ol></li> 77 <li><a href="#templating">Templating</a> 78 <ol style="list-style-type: lower-roman;"> 79 <li><a href="#templates">General Templating</a></li> 80 <li><a href="#inheritance">Template Inheritance</a></li> 81 </ol></li> 82 <li><a href="#charsets">Character Sets and Encodings</a></li> 83 <li><a href="#translation">Translation (<abbr title="Internationalisation">i18n</abbr>/<abbr title="Localisation">L10n</abbr>) Guidelines</a> 84 <ol style="list-style-type: lower-roman;"> 85 <li><a href="#standardisation">Standardisation</a></li> 86 <li><a href="#otherconsiderations">Other considerations</a></li> 87 <li><a href="#writingstyle">Writing Style</a></li> 88 </ol> 89 </li> 90 <li><a href="#disclaimer">Copyright and disclaimer</a></li> 91 </ol> 92 93 </div> 94 95 <span class="corners-bottom"><span></span></span></div> 96 </div> 97 98 <hr /> 99 100 <a name="defaults"></a><h2>1. Defaults</h2> 101 102 <div class="paragraph"> 103 <div class="inner"><span class="corners-top"><span></span></span> 104 105 <div class="content"> 106 107 <a name="editorsettings"></a><h3>1.i. Editor Settings</h3> 108 109 <h4>Tabs vs Spaces:</h4> 110 <p>In order to make this as simple as possible, we will be using tabs, not spaces. We enforce 4 (four) spaces for one tab - therefore you need to set your tab width within your editor to 4 spaces. Make sure that when you <strong>save</strong> the file, it's saving tabs and not spaces. This way, we can each have the code be displayed the way we like it, without breaking the layout of the actual files.</p> 111 <p>Tabs in front of lines are no problem, but having them within the text can be a problem if you do not set it to the amount of spaces every one of us uses. Here is a short example of how it should look like:</p> 112 113 <div class="codebox"><pre> 114 {TAB}$mode{TAB}{TAB}= request_var('mode', ''); 115 {TAB}$search_id{TAB}= request_var('search_id', ''); 116 </pre></div> 117 118 <p>If entered with tabs (replace the {TAB}) both equal signs need to be on the same column.</p> 119 120 <h3>Linefeeds:</h3> 121 <p>Ensure that your editor is saving files in the UNIX (LF) line ending format. This means that lines are terminated with a newline, not with Windows Line endings (CR/LF combo) as they are on Win32 or Classic Mac (CR) Line endings. Any decent editor should be able to do this, but it might not always be the default setting. Know your editor. If you want advice for an editor for your Operating System, just ask one of the developers. Some of them do their editing on Win32.</p> 122 123 <a name="fileheader"></a><h3>1.ii. File Header</h3> 124 125 <h4>Standard header for new files:</h4> 126 <p>This template of the header must be included at the start of all phpBB files: </p> 127 128 <div class="codebox"><pre> 129 /** 130 * 131 * @package {PACKAGENAME} 132 * @copyright (c) 2007 phpBB Group 133 * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2 134 * 135 */ 136 </pre></div> 137 138 <p>Please see the <a href="#locations">File Locations section</a> for the correct package name.</p> 139 140 <h4>Files containing inline code:</h4> 141 142 <p>For those files you have to put an empty comment directly after the header to prevent the documentor assigning the header to the first code element found.</p> 143 144 <div class="codebox"><pre> 145 /** 146 * {HEADER} 147 */ 148 149 /** 150 */ 151 {CODE} 152 </pre></div> 153 154 <h4>Files containing only functions:</h4> 155 156 <p>Do not forget to comment the functions (especially the first function following the header). Each function should have at least a comment of what this function does. For more complex functions it is recommended to document the parameters too.</p> 157 158 <h4>Files containing only classes:</h4> 159 160 <p>Do not forget to comment the class. Classes need a separate @package definition, it is the same as the header package name. Apart from this special case the above statement for files containing only functions needs to be applied to classes and it's methods too.</p> 161 162 <h4>Code following the header but only functions/classes file:</h4> 163 164 <p>If this case is true, the best method to avoid documentation confusions is adding an ignore command, for example:</p> 165 166 <div class="codebox"><pre> 167 /** 168 * {HEADER} 169 */ 170 171 /** 172 * @ignore 173 */ 174 Small code snipped, mostly one or two defines or an if statement 175 176 /** 177 * {DOCUMENTATION} 178 */ 179 class ... 180 </pre></div> 181 182 <a name="locations"></a><h3>1.iii. File Locations</h3> 183 184 <p>Functions used by more than one page should be placed in functions.php, functions specific to one page should be placed on that page (at the bottom) or within the relevant sections functions file. Some files in <code>/includes</code> are holding functions responsible for special sections, for example uploading files, displaying "things", user related functions and so forth.</p> 185 186 <p>The following packages are defined, and related new features/functions should be placed within the mentioned files/locations, as well as specifying the correct package name. The package names are bold within this list:</p> 187 188 <ul> 189 <li><strong>phpBB3</strong><br />Core files and all files not assigned to a separate package</li> 190 <li><strong>acm</strong><br /><code>/includes/acm</code>, <code>/includes/cache.php</code><br />Cache System</li> 191 <li><strong>acp</strong><br /><code>/adm</code>, <code>/includes/acp</code>, <code>/includes/functions_admin.php</code><br />Administration Control Panel</li> 192 <li><strong>dbal</strong><br /><code>/includes/db</code><br />Database Abstraction Layer.<br />Base class is <code>dbal</code> 193 <ul> 194 <li><code>/includes/db/dbal.php</code><br />Base DBAL class, defining the overall framework</li> 195 <li><code>/includes/db/firebird.php</code><br />Firebird/Interbase Database Abstraction Layer</li> 196 <li><code>/includes/db/msssql.php</code><br />MSSQL Database Abstraction Layer</li> 197 <li><code>/includes/db/mssql_odbc.php</code><br />MSSQL ODBC Database Abstraction Layer for MSSQL</li> 198 <li><code>/includes/db/mysql.php</code><br />MySQL Database Abstraction Layer for MySQL 3.x/4.0.x/4.1.x/5.x</li> 199 <li><code>/includes/db/mysqli.php</code><br />MySQLi Database Abstraction Layer</li> 200 <li><code>/includes/db/oracle.php</code><br />Oracle Database Abstraction Layer</li> 201 <li><code>/includes/db/postgres.php</code><br />PostgreSQL Database Abstraction Layer</li> 202 <li><code>/includes/db/sqlite.php</code><br />Sqlite Database Abstraction Layer</li> 203 </ul> 204 </li> 205 <li><strong>diff</strong><br /><code>/includes/diff</code><br />Diff Engine</li> 206 <li><strong>docs</strong><br /><code>/docs</code><br />phpBB Documentation</li> 207 <li><strong>images</strong><br /><code>/images</code><br />All global images not connected to styles</li> 208 <li><strong>install</strong><br /><code>/install</code><br />Installation System</li> 209 <li><strong>language</strong><br /><code>/language</code><br />All language files</li> 210 <li><strong>login</strong><br /><code>/includes/auth</code><br />Login Authentication Plugins</li> 211 <li><strong>VC</strong><br /><code>/includes/captcha</code><br />CAPTCHA</li> 212 <li><strong>mcp</strong><br /><code>mcp.php</code>, <code>/includes/mcp</code>, <code>report.php</code><br />Moderator Control Panel</li> 213 <li><strong>ucp</strong><br /><code>ucp.php</code>, <code>/includes/ucp</code><br />User Control Panel</li> 214 <li><strong>utf</strong><br /><code>/includes/utf</code><br />UTF8-related functions/classes</li> 215 <li><strong>search</strong><br /><code>/includes/search</code>, <code>search.php</code><br />Search System</li> 216 <li><strong>styles</strong><br /><code>/styles</code>, <code>style.php</code><br />phpBB Styles/Templates/Themes/Imagesets</li> 217 </ul> 218 219 <a name="constants"></a><h3>1.iv. Special Constants</h3> 220 221 <p>There are some special constants application developers are able to utilize to bend some of phpBB's internal functionality to suit their needs.</p> 222 223 <div class="codebox"><pre> 224 PHPBB_MSG_HANDLER (overwrite message handler) 225 PHPBB_DB_NEW_LINK (overwrite new_link parameter for sql_connect) 226 PHPBB_ROOT_PATH (overwrite $phpbb_root_path) 227 PHPBB_ADMIN_PATH (overwrite $phpbb_admin_path) 228 PHPBB_USE_BOARD_URL_PATH (use generate_board_url() for image paths instead of $phpbb_root_path) 229 PHPBB_DISABLE_ACP_EDITOR (disable ACP style editor for templates) 230 PHPBB_DISABLE_CONFIG_CHECK (disable ACP config.php writeable check) 231 232 PHPBB_ACM_MEMCACHE_PORT (overwrite memcached port, default is 11211) 233 PHPBB_ACM_MEMCACHE_COMPRESS (overwrite memcached compress setting, default is disabled) 234 PHPBB_ACM_MEMCACHE_HOST (overwrite memcached host name, default is localhost) 235 236 PHPBB_ACM_REDIS_HOST (overwrite redis host name, default is localhost) 237 PHPBB_ACM_REDIS_PORT (overwrite redis port, default is 6379) 238 PHPBB_ACM_REDIS_PASSWORD (overwrite redis password, default is empty) 239 PHPBB_ACM_REDIS_DB (overwrite redis default database) 240 241 PHPBB_QA (Set board to QA-Mode, which means the updater also checks for RC-releases) 242 </pre></div> 243 244 <h4>PHPBB_USE_BOARD_URL_PATH</h4> 245 246 <p>If the <code>PHPBB_USE_BOARD_URL_PATH</code> 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:</p> 247 248 <ul> 249 <li>/includes/session.php - user::img()</li> 250 <li>/includes/functions_content.php - smiley_text()</li> 251 </ul> 252 253 <p>Path locations for the following template variables are affected by this too:</p> 254 255 <ul> 256 <li>{T_THEME_PATH} - styles/xxx/theme</li> 257 <li>{T_TEMPLATE_PATH} - styles/xxx/template</li> 258 <li>{T_SUPER_TEMPLATE_PATH} - styles/xxx/template</li> 259 <li>{T_IMAGESET_PATH} - styles/xxx/imageset</li> 260 <li>{T_IMAGESET_LANG_PATH} - styles/xxx/imageset/yy</li> 261 <li>{T_IMAGES_PATH} - images/</li> 262 <li>{T_SMILIES_PATH} - $config['smilies_path']/</li> 263 <li>{T_AVATAR_PATH} - $config['avatar_path']/</li> 264 <li>{T_AVATAR_GALLERY_PATH} - $config['avatar_gallery_path']/</li> 265 <li>{T_ICONS_PATH} - $config['icons_path']/</li> 266 <li>{T_RANKS_PATH} - $config['ranks_path']/</li> 267 <li>{T_UPLOAD_PATH} - $config['upload_path']/</li> 268 <li>{T_STYLESHEET_LINK} - styles/xxx/theme/stylesheet.css (or link to style.php if css is parsed dynamically)</li> 269 <li>New template variable {BOARD_URL} for the board url + script path.</li> 270 </ul> 271 272 </div> 273 274 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 275 276 <span class="corners-bottom"><span></span></span></div> 277 </div> 278 279 <hr /> 280 281 <a name="code"></a><h2>2. Code Layout/Guidelines</h2> 282 283 <div class="paragraph"> 284 <div class="inner"><span class="corners-top"><span></span></span> 285 286 <div class="content"> 287 288 <p>Please note that these guidelines apply to all php, html, javascript and css files.</p> 289 290 <a name="namingvars"></a><h3>2.i. Variable/Function Naming</h3> 291 292 <p>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.</p> 293 294 <h4>Variable Names:</h4> 295 <p>Variable names should be in all lowercase, with words separated by an underscore, example:</p> 296 297 <div class="indent"> 298 <p><code>$current_user</code> is right, but <code>$currentuser</code> and <code> $currentUser</code> are not.</p> 299 </div> 300 301 <p>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. </p> 302 303 <h4>Loop Indices:</h4> 304 <p>The <em>only</em> situation where a one-character variable name is allowed is when it's the index for some looping construct. In this case, the index of the outer loop should always be $i. If there's a loop inside that loop, its index should be $j, followed by $k, and so on. If the loop is being indexed by some already-existing variable with a meaningful name, this guideline does not apply, example:</p> 305 306 <div class="codebox"><pre> 307 for ($i = 0; $i < $outer_size; $i++) 308 { 309 for ($j = 0; $j < $inner_size; $j++) 310 { 311 foo($i, $j); 312 } 313 } 314 </pre></div> 315 316 <h4>Function Names:</h4> 317 <p>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 <code>print_login_status()</code>, <code>get_user_data()</code>, etc. </p> 318 319 <h4>Function Arguments:</h4> 320 <p>Arguments are subject to the same guidelines as variable names. We don't want a bunch of functions like: <code>do_stuff($a, $b, $c)</code>. In most cases, we'd like to be able to tell how to use a function by just looking at its declaration. </p> 321 322 <h4>Summary:</h4> 323 <p>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; <code>print_login_status_for_a_given_user()</code> goes too far, for example -- that function would be better named <code>print_user_login_status()</code>, or just <code>print_login_status()</code>.</p> 324 325 <h4>Special Namings: </h4> 326 <p>For all emoticons use the term <code>smiley</code> in singular and <code>smilies</code> in plural.</p> 327 328 <a name="codelayout"></a><h3>2.ii. Code Layout</h3> 329 330 <h4>Always include the braces:</h4> 331 <p>This is another case of being too lazy to type 2 extra characters causing problems with code clarity. Even if the body of some construct is only one line long, do <em>not</em> drop the braces. Just don't, examples:</p> 332 333 <p class="bad">// These are all wrong. </p> 334 335 <div class="codebox"><pre> 336 if (condition) do_stuff(); 337 338 if (condition) 339 do_stuff(); 340 341 while (condition) 342 do_stuff(); 343 344 for ($i = 0; $i < size; $i++) 345 do_stuff($i); 346 </pre></div> 347 348 <p class="good">// These are all right. </p> 349 <div class="codebox"><pre> 350 if (condition) 351 { 352 do_stuff(); 353 } 354 355 while (condition) 356 { 357 do_stuff(); 358 } 359 360 for ($i = 0; $i < size; $i++) 361 { 362 do_stuff(); 363 } 364 </pre></div> 365 366 <h4>Where to put the braces:</h4> 367 <p>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:</p> 368 369 <div class="codebox"><pre> 370 if (condition) 371 { 372 while (condition2) 373 { 374 ... 375 } 376 } 377 else 378 { 379 ... 380 } 381 382 for ($i = 0; $i < $size; $i++) 383 { 384 ... 385 } 386 387 while (condition) 388 { 389 ... 390 } 391 392 function do_stuff() 393 { 394 ... 395 } 396 </pre></div> 397 398 <h4>Use spaces between tokens:</h4> 399 <p>This is another simple, easy step that helps keep code readable without much effort. Whenever you write an assignment, expression, etc.. Always leave <em>one</em> 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:</p> 400 401 <p>// Each pair shows the wrong way followed by the right way. </p> 402 403 <div class="codebox"><pre> 404 $i=0; 405 $i = 0; 406 407 if($i<7) ... 408 if ($i < 7) ... 409 410 if ( ($i < 7)&&($j > 8) ) ... 411 if ($i < 7 && $j > 8) ... 412 413 do_stuff( $i, 'foo', $b ); 414 do_stuff($i, 'foo', $b); 415 416 for($i=0; $i<$size; $i++) ... 417 for ($i = 0; $i < $size; $i++) ... 418 419 $i=($j < $size)?0:1; 420 $i = ($j < $size) ? 0 : 1; 421 </pre></div> 422 423 <h4>Operator precedence:</h4> 424 <p>Do you know the exact precedence of all the operators in PHP? Neither do I. Don't guess. Always make it obvious by using brackets to force the precedence of an equation so you know what it does. Remember to not over-use this, as it may harden the readability. Basically, do not enclose single expressions. Examples:</p> 425 426 <p class="bad">// what's the result? who knows. </p> 427 <div class="codebox"><pre> 428 $bool = ($i < 7 && $j > 8 || $k == 4); 429 </pre></div> 430 431 <p class="bad">// now you can be certain what I'm doing here.</p> 432 <div class="codebox"><pre> 433 $bool = (($i < 7) && (($j < 8) || ($k == 4))); 434 </pre></div> 435 436 <p class="good">// But this one is even better, because it is easier on the eye but the intention is preserved</p> 437 <div class="codebox"><pre> 438 $bool = ($i < 7 && ($j < 8 || $k == 4)); 439 </pre></div> 440 441 <h4>Quoting strings:</h4> 442 <p>There are two different ways to quote strings in PHP - either with single quotes or with double quotes. The main difference is that the parser does variable interpolation in double-quoted strings, but not in single quoted strings. Because of this, you should <em>always</em> use single quotes <em>unless</em> you specifically need variable interpolation to be done on that string. This way, we can save the parser the trouble of parsing a bunch of strings where no interpolation needs to be done.</p> 443 <p>Also, if you are using a string variable as part of a function call, you do not need to enclose that variable in quotes. Again, this will just make unnecessary work for the parser. Note, however, that nearly all of the escape sequences that exist for double-quoted strings will not work with single-quoted strings. Be careful, and feel free to break this guideline if it's making your code easier to read, examples:</p> 444 445 <p class="bad">// wrong </p> 446 <div class="codebox"><pre> 447 $str = "This is a really long string with no variables for the parser to find."; 448 449 do_stuff("$str"); 450 </pre></div> 451 452 <p class="good">// right</p> 453 <div class="codebox"><pre> 454 $str = 'This is a really long string with no variables for the parser to find.'; 455 456 do_stuff($str); 457 </pre></div> 458 459 <p class="bad">// Sometimes single quotes are just not right</p> 460 <div class="codebox"><pre> 461 $post_url = $phpbb_root_path . 'posting.' . $phpEx . '?mode=' . $mode . '&amp;start=' . $start; 462 </pre></div> 463 464 <p class="good">// Double quotes are sometimes needed to not overcrowd the line with concatenations.</p> 465 <div class="codebox"><pre> 466 $post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&amp;start=$start"; 467 </pre></div> 468 469 <p>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.</p> 470 471 <h4>Associative array keys:</h4> 472 <p>In PHP, it's legal to use a literal string as a key to an associative array without quoting that string. We don't want to do this -- the string should always be quoted to avoid confusion. Note that this is only when we're using a literal, not when we're using a variable, examples:</p> 473 474 <p class="bad">// wrong</p> 475 <div class="codebox"><pre> 476 $foo = $assoc_array[blah]; 477 </pre></div> 478 479 <p class="good">// right </p> 480 <div class="codebox"><pre> 481 $foo = $assoc_array['blah']; 482 </pre></div> 483 484 <p class="bad">// wrong</p> 485 <div class="codebox"><pre> 486 $foo = $assoc_array["$var"]; 487 </pre></div> 488 489 <p class="good">// right </p> 490 <div class="codebox"><pre> 491 $foo = $assoc_array[$var]; 492 </pre></div> 493 494 <h4>Comments:</h4> 495 <p>Each complex function should be preceded by a comment that tells a programmer everything they need to know to use that function. The meaning of every parameter, the expected input, and the output are required as a minimal comment. The function's behaviour in error conditions (and what those error conditions are) should also be present - but mostly included within the comment about the output.<br /><br />Especially important to document are any assumptions the code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what's going on in a reasonable amount of time.<br /><br />Avoid using <code>/* */</code> comment blocks for one-line comments, <code>//</code> should be used for one/two-liners.</p> 496 497 <h4>Magic numbers:</h4> 498 <p>Don't use them. Use named constants for any literal value other than obvious special cases. Basically, it's ok to check if an array has 0 elements by using the literal 0. It's not ok to assign some special meaning to a number and then use it everywhere as a literal. This hurts readability AND maintainability. The constants <code>true</code> and <code>false</code> should be used in place of the literals 1 and 0 -- even though they have the same values (but not type!), it's more obvious what the actual logic is when you use the named constants. Typecast variables where it is needed, do not rely on the correct variable type (PHP is currently very loose on typecasting which can lead to security problems if a developer does not keep a very close eye on it).</p> 499 500 <h4>Shortcut operators:</h4> 501 <p>The only shortcut operators that cause readability problems are the shortcut increment <code>$i++</code> and decrement <code>$j--</code> operators. These operators should not be used as part of an expression. They can, however, be used on their own line. Using them in expressions is just not worth the headaches when debugging, examples:</p> 502 503 <p class="bad">// wrong </p> 504 <div class="codebox"><pre> 505 $array[++$i] = $j; 506 $array[$i++] = $k; 507 </pre></div> 508 509 <p class="good">// right </p> 510 <div class="codebox"><pre> 511 $i++; 512 $array[$i] = $j; 513 514 $array[$i] = $k; 515 $i++; 516 </pre></div> 517 518 <h4>Inline conditionals:</h4> 519 <p>Inline conditionals should only be used to do very simple things. Preferably, they will only be used to do assignments, and not for function calls or anything complex at all. They can be harmful to readability if used incorrectly, so don't fall in love with saving typing by using them, examples:</p> 520 521 <p class="bad">// Bad place to use them</p> 522 <div class="codebox"><pre> 523 ($i < $size && $j > $size) ? do_stuff($foo) : do_stuff($bar); 524 </pre></div> 525 526 <p class="good">// OK place to use them </p> 527 <div class="codebox"><pre> 528 $min = ($i < $j) ? $i : $j; 529 </pre></div> 530 531 <h4>Don't use uninitialized variables.</h4> 532 <p>For phpBB3, we intend to use a higher level of run-time error reporting. This will mean that the use of an uninitialized variable will be reported as a warning. These warnings can be avoided by using the built-in isset() function to check whether a variable has been set - but preferably the variable is always existing. For checking if an array has a key set this can come in handy though, examples:</p> 533 534 <p class="bad">// Wrong </p> 535 <div class="codebox"><pre> 536 if ($forum) ... 537 </pre></div> 538 539 <p class="good">// Right </p> 540 <div class="codebox"><pre> 541 if (isset($forum)) ... 542 </pre></div> 543 544 <p class="good">// Also possible</p> 545 <div class="codebox"><pre> 546 if (isset($forum) && $forum == 5) 547 </pre></div> 548 549 <p>The <code>empty()</code> function is useful if you want to check if a variable is not set or being empty (an empty string, 0 as an integer or string, NULL, false, an empty array or a variable declared, but without a value in a class). Therefore empty should be used in favor of <code>isset($array) && sizeof($array) > 0</code> - this can be written in a shorter way as <code>!empty($array)</code>.</p> 550 551 <h4>Switch statements:</h4> 552 <p>Switch/case code blocks can get a bit long sometimes. To have some level of notice and being in-line with the opening/closing brace requirement (where they are on the same line for better readability), this also applies to switch/case code blocks and the breaks. An example:</p> 553 554 <p class="bad">// Wrong </p> 555 <div class="codebox"><pre> 556 switch ($mode) 557 { 558 case 'mode1': 559 // I am doing something here 560 break; 561 case 'mode2': 562 // I am doing something completely different here 563 break; 564 } 565 </pre></div> 566 567 <p class="good">// Good </p> 568 <div class="codebox"><pre> 569 switch ($mode) 570 { 571 case 'mode1': 572 // I am doing something here 573 break; 574 575 case 'mode2': 576 // I am doing something completely different here 577 break; 578 579 default: 580 // Always assume that a case was not caught 581 break; 582 } 583 </pre></div> 584 585 <p class="good">// Also good, if you have more code between the case and the break </p> 586 <div class="codebox"><pre> 587 switch ($mode) 588 { 589 case 'mode1': 590 591 // I am doing something here 592 593 break; 594 595 case 'mode2': 596 597 // I am doing something completely different here 598 599 break; 600 601 default: 602 603 // Always assume that a case was not caught 604 605 break; 606 } 607 </pre></div> 608 609 <p>Even if the break for the default case is not needed, it is sometimes better to include it just for readability and completeness.</p> 610 611 <p>If no break is intended, please add a comment instead. An example:</p> 612 613 <p class="good">// Example with no break </p> 614 <div class="codebox"><pre> 615 switch ($mode) 616 { 617 case 'mode1': 618 619 // I am doing something here 620 621 // no break here 622 623 case 'mode2': 624 625 // I am doing something completely different here 626 627 break; 628 629 default: 630 631 // Always assume that a case was not caught 632 633 break; 634 } 635 </pre></div> 636 637 <a name="sql"></a><h3>2.iii. SQL/SQL Layout</h3> 638 639 <h4>Common SQL Guidelines: </h4> 640 <p>All SQL should be cross-DB compatible, if DB specific SQL is used alternatives must be provided which work on all supported DB's (MySQL3/4/5, MSSQL (7.0 and 2000), PostgreSQL (7.0+), Firebird, SQLite, Oracle8, ODBC (generalised if possible)).</p> 641 <p>All SQL commands should utilise the DataBase Abstraction Layer (DBAL)</p> 642 643 <h4>SQL code layout:</h4> 644 <p>SQL Statements are often unreadable without some formatting, since they tend to be big at times. Though the formatting of sql statements adds a lot to the readability of code. SQL statements should be formatted in the following way, basically writing keywords: </p> 645 646 <div class="codebox"><pre> 647 $sql = 'SELECT * 648 <-one tab->FROM ' . SOME_TABLE . ' 649 <-one tab->WHERE a = 1 650 <-two tabs->AND (b = 2 651 <-three tabs->OR b = 3) 652 <-one tab->ORDER BY b'; 653 </pre></div> 654 655 <p>Here the example with the tabs applied:</p> 656 657 <div class="codebox"><pre> 658 $sql = 'SELECT * 659 FROM ' . SOME_TABLE . ' 660 WHERE a = 1 661 AND (b = 2 662 OR b = 3) 663 ORDER BY b'; 664 </pre></div> 665 666 <h4>SQL Quotes: </h4> 667 <p>Use double quotes where applicable. (The variables in these examples are typecasted to integers beforehand.) Examples: </p> 668 669 <p class="bad">// These are wrong.</p> 670 <div class="codebox"><pre> 671 "UPDATE " . SOME_TABLE . " SET something = something_else WHERE a = $b"; 672 673 'UPDATE ' . SOME_TABLE . ' SET something = ' . $user_id . ' WHERE a = ' . $something; 674 </pre></div> 675 676 <p class="good">// These are right. </p> 677 678 <div class="codebox"><pre> 679 'UPDATE ' . SOME_TABLE . " SET something = something_else WHERE a = $b"; 680 681 'UPDATE ' . SOME_TABLE . " SET something = $user_id WHERE a = $something"; 682 </pre></div> 683 684 <p>In other words use single quotes where no variable substitution is required or where the variable involved shouldn't appear within double quotes. Otherwise use double quotes.</p> 685 686 <h4>Avoid DB specific SQL: </h4> 687 <p>The "not equals operator", as defined by the SQL:2003 standard, is "<>"</p> 688 689 <p class="bad">// This is wrong.</p> 690 <div class="codebox"><pre> 691 $sql = 'SELECT * 692 FROM ' . SOME_TABLE . ' 693 WHERE a != 2'; 694 </pre></div> 695 696 <p class="good">// This is right. </p> 697 <div class="codebox"><pre> 698 $sql = 'SELECT * 699 FROM ' . SOME_TABLE . ' 700 WHERE a <> 2'; 701 </pre></div> 702 703 <h4>Common DBAL methods: </h4> 704 705 <h4>sql_escape():</h4> 706 707 <p>Always use <code>$db->sql_escape()</code> if you need to check for a string within an SQL statement (even if you are sure the variable cannot contain single quotes - never trust your input), for example:</p> 708 709 <div class="codebox"><pre> 710 $sql = 'SELECT * 711 FROM ' . SOME_TABLE . " 712 WHERE username = '" . $db->sql_escape($username) . "'"; 713 </pre></div> 714 715 <h4>sql_query_limit():</h4> 716 717 <p>We do not add limit statements to the sql query, but instead use <code>$db->sql_query_limit()</code>. You basically pass the query, the total number of lines to retrieve and the offset.</p> 718 719 <p><strong>Note: </strong> Since Oracle handles limits differently and because of how we implemented this handling you need to take special care if you use <code>sql_query_limit</code> with an sql query retrieving data from more than one table.</p> 720 721 <p>Make sure when using something like "SELECT x.*, y.jars" that there is not a column named jars in x; make sure that there is no overlap between an implicit column and the explicit columns.</p> 722 723 <h4>sql_build_array():</h4> 724 725 <p>If you need to UPDATE or INSERT data, make use of the <code>$db->sql_build_array()</code> function. This function already escapes strings and checks other types, so there is no need to do this here. The data to be inserted should go into an array - <code>$sql_ary</code> - or directly within the statement if one or two variables needs to be inserted/updated. An example of an insert statement would be:</p> 726 727 <div class="codebox"><pre> 728 $sql_ary = array( 729 'somedata' => $my_string, 730 'otherdata' => $an_int, 731 'moredata' => $another_int 732 ); 733 734 $db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary)); 735 </pre></div> 736 737 <p>To complete the example, this is how an update statement would look like:</p> 738 739 <div class="codebox"><pre> 740 $sql_ary = array( 741 'somedata' => $my_string, 742 'otherdata' => $an_int, 743 'moredata' => $another_int 744 ); 745 746 $sql = 'UPDATE ' . SOME_TABLE . ' 747 SET ' . $db->sql_build_array('UPDATE', $sql_ary) . ' 748 WHERE user_id = ' . (int) $user_id; 749 $db->sql_query($sql); 750 </pre></div> 751 752 <p>The <code>$db->sql_build_array()</code> function supports the following modes: <code>INSERT</code> (example above), <code>INSERT_SELECT</code> (building query for <code>INSERT INTO table (...) SELECT value, column ...</code> statements), <code>UPDATE</code> (example above) and <code>SELECT</code> (for building WHERE statement [AND logic]).</p> 753 754 <h4>sql_multi_insert():</h4> 755 756 <p>If you want to insert multiple statements at once, please use the separate <code>sql_multi_insert()</code> method. An example:</p> 757 758 <div class="codebox"><pre> 759 $sql_ary = array(); 760 761 $sql_ary[] = array( 762 'somedata' => $my_string_1, 763 'otherdata' => $an_int_1, 764 'moredata' => $another_int_1, 765 ); 766 767 $sql_ary[] = array( 768 'somedata' => $my_string_2, 769 'otherdata' => $an_int_2, 770 'moredata' => $another_int_2, 771 ); 772 773 $db->sql_multi_insert(SOME_TABLE, $sql_ary); 774 </pre></div> 775 776 <h4>sql_in_set():</h4> 777 778 <p>The <code>$db->sql_in_set()</code> function should be used for building <code>IN ()</code> and <code>NOT IN ()</code> constructs. Since (specifically) MySQL tend to be faster if for one value to be compared the <code>=</code> and <code><></code> operator is used, we let the DBAL decide what to do. A typical example of doing a positive match against a number of values would be:</p> 779 780 <div class="codebox"><pre> 781 $sql = 'SELECT * 782 FROM ' . FORUMS_TABLE . ' 783 WHERE ' . $db->sql_in_set('forum_id', $forum_ids); 784 $db->sql_query($sql); 785 </pre></div> 786 787 <p>Based on the number of values in $forum_ids, the query can look differently.</p> 788 789 <p class="good">// SQL Statement if $forum_ids = array(1, 2, 3);</p> 790 791 <div class="codebox"><pre> 792 SELECT FROM phpbb_forums WHERE forum_id IN (1, 2, 3) 793 </pre></div> 794 795 <p class="good">// SQL Statement if $forum_ids = array(1) or $forum_ids = 1</p> 796 797 <div class="codebox"><pre> 798 SELECT FROM phpbb_forums WHERE forum_id = 1 799 </pre></div> 800 801 <p>Of course the same is possible for doing a negative match against a number of values:</p> 802 803 <div class="codebox"><pre> 804 $sql = 'SELECT * 805 FROM ' . FORUMS_TABLE . ' 806 WHERE ' . $db->sql_in_set('forum_id', $forum_ids, <strong>true</strong>); 807 $db->sql_query($sql); 808 </pre></div> 809 810 <p>Based on the number of values in $forum_ids, the query can look differently here too.</p> 811 812 <p class="good">// SQL Statement if $forum_ids = array(1, 2, 3);</p> 813 814 <div class="codebox"><pre> 815 SELECT FROM phpbb_forums WHERE forum_id <strong>NOT</strong> IN (1, 2, 3) 816 </pre></div> 817 818 <p class="good">// SQL Statement if $forum_ids = array(1) or $forum_ids = 1</p> 819 820 <div class="codebox"><pre> 821 SELECT FROM phpbb_forums WHERE forum_id <strong><></strong> 1 822 </pre></div> 823 824 <p>If the given array is empty, an error will be produced.</p> 825 826 <h4>sql_build_query():</h4> 827 828 <p>The <code>$db->sql_build_query()</code> function is responsible for building sql statements for SELECT and SELECT DISTINCT queries if you need to JOIN on more than one table or retrieve data from more than one table while doing a JOIN. This needs to be used to make sure the resulting statement is working on all supported db's. Instead of explaining every possible combination, I will give a short example:</p> 829 830 <div class="codebox"><pre> 831 $sql_array = array( 832 'SELECT' => 'f.*, ft.mark_time', 833 834 'FROM' => array( 835 FORUMS_WATCH_TABLE => 'fw', 836 FORUMS_TABLE => 'f' 837 ), 838 839 'LEFT_JOIN' => array( 840 array( 841 'FROM' => array(FORUMS_TRACK_TABLE => 'ft'), 842 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id' 843 ) 844 ), 845 846 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' 847 AND f.forum_id = fw.forum_id', 848 849 'ORDER_BY' => 'left_id' 850 ); 851 852 $sql = $db->sql_build_query('SELECT', $sql_array); 853 </pre></div> 854 855 <p>The possible first parameter for sql_build_query() is SELECT or SELECT_DISTINCT. As you can see, the logic is pretty self-explaining. For the LEFT_JOIN key, just add another array if you want to join on to tables for example. The added benefit of using this construct is that you are able to easily build the query statement based on conditions - for example the above LEFT_JOIN is only necessary if server side topic tracking is enabled; a slight adjustement would be:</p> 856 857 <div class="codebox"><pre> 858 $sql_array = array( 859 'SELECT' => 'f.*', 860 861 'FROM' => array( 862 FORUMS_WATCH_TABLE => 'fw', 863 FORUMS_TABLE => 'f' 864 ), 865 866 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' 867 AND f.forum_id = fw.forum_id', 868 869 'ORDER_BY' => 'left_id' 870 ); 871 872 if ($config['load_db_lastread']) 873 { 874 $sql_array['LEFT_JOIN'] = array( 875 array( 876 'FROM' => array(FORUMS_TRACK_TABLE => 'ft'), 877 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id' 878 ) 879 ); 880 881 $sql_array['SELECT'] .= ', ft.mark_time '; 882 } 883 else 884 { 885 // Here we read the cookie data 886 } 887 888 $sql = $db->sql_build_query('SELECT', $sql_array); 889 </pre></div> 890 891 <a name="optimizing"></a><h3>2.iv. Optimizations</h3> 892 893 <h4>Operations in loop definition: </h4> 894 <p>Always try to optimize your loops if operations are going on at the comparing part, since this part is executed every time the loop is parsed through. For assignments a descriptive name should be chosen. Example:</p> 895 896 <p class="bad">// On every iteration the sizeof function is called</p> 897 <div class="codebox"><pre> 898 for ($i = 0; $i < sizeof($post_data); $i++) 899 { 900 do_something(); 901 } 902 </pre></div> 903 904 <p class="good">// You are able to assign the (not changing) result within the loop itself</p> 905 <div class="codebox"><pre> 906 for ($i = 0, $size = sizeof($post_data); $i < $size; $i++) 907 { 908 do_something(); 909 } 910 </pre></div> 911 912 <h4>Use of in_array(): </h4> 913 <p>Try to avoid using in_array() on huge arrays, and try to not place them into loops if the array to check consist of more than 20 entries. in_array() can be very time consuming and uses a lot of cpu processing time. For little checks it is not noticeable, but if checked against a huge array within a loop those checks alone can take several seconds. If you need this functionality, try using isset() on the arrays keys instead, actually shifting the values into keys and vice versa. A call to <code>isset($array[$var])</code> is a lot faster than <code>in_array($var, array_keys($array))</code> for example.</p> 914 915 916 <a name="general"></a><h3>2.v. General Guidelines</h3> 917 918 <h4>General things:</h4> 919 <p>Never trust user input (this also applies to server variables as well as cookies).</p> 920 <p>Try to sanitize values returned from a function.</p> 921 <p>Try to sanitize given function variables within your function.</p> 922 <p>The auth class should be used for all authorisation checking.</p> 923 <p>No attempt should be made to remove any copyright information (either contained within the source or displayed interactively when the source is run/compiled), neither should the copyright information be altered in any way (it may be added to).</p> 924 925 <h4>Variables: </h4> 926 <p>Make use of the <code>request_var()</code> function for anything except for submit or single checking params.</p> 927 <p>The request_var function determines the type to set from the second parameter (which determines the default value too). If you need to get a scalar variable type, you need to tell this the request_var function explicitly. Examples:</p> 928 929 <p class="bad">// Old method, do not use it</p> 930 <div class="codebox"><pre> 931 $start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']); 932 $submit = (isset($HTTP_POST_VARS['submit'])) ? true : false; 933 </pre></div> 934 935 <p class="good">// Use request var and define a default variable (use the correct type)</p> 936 <div class="codebox"><pre> 937 $start = request_var('start', 0); 938 $submit = (isset($_POST['submit'])) ? true : false; 939 </pre></div> 940 941 <p class="bad">// $start is an int, the following use of request_var therefore is not allowed</p> 942 <div class="codebox"><pre> 943 $start = request_var('start', '0'); 944 </pre></div> 945 946 <p class="good">// Getting an array, keys are integers, value defaults to 0</p> 947 <div class="codebox"><pre> 948 $mark_array = request_var('mark', array(0)); 949 </pre></div> 950 951 <p class="good">// Getting an array, keys are strings, value defaults to 0</p> 952 <div class="codebox"><pre> 953 $action_ary = request_var('action', array('' => 0)); 954 </pre></div> 955 956 <h4>Login checks/redirection: </h4> 957 <p>To show a forum login box use <code>login_forum_box($forum_data)</code>, else use the <code>login_box()</code> function.</p> 958 959 <p><code>$forum_data</code> should contain at least the <code>forum_id</code> and <code>forum_password</code> fields. If the field <code>forum_name</code> is available, then it is displayed on the forum login page.</p> 960 961 <p>The <code>login_box()</code> function can have a redirect as the first parameter. As a thumb of rule, specify an empty string if you want to redirect to the users current location, else do not add the <code>$SID</code> to the redirect string (for example within the ucp/login we redirect to the board index because else the user would be redirected to the login screen).</p> 962 963 <h4>Sensitive Operations: </h4> 964 <p>For sensitive operations always let the user confirm the action. For the confirmation screens, make use of the <code>confirm_box()</code> function.</p> 965 966 <h4>Altering Operations: </h4> 967 <p>For operations altering the state of the database, for instance posting, always verify the form token, unless you are already using <code>confirm_box()</code>. To do so, make use of the <code>add_form_key()</code> and <code>check_form_key()</code> functions. </p> 968 <div class="codebox"><pre> 969 add_form_key('my_form'); 970 971 if ($submit) 972 { 973 if (!check_form_key('my_form')) 974 { 975 trigger_error('FORM_INVALID'); 976 } 977 } 978 </pre></div> 979 980 <p>The string passed to <code>add_form_key()</code> needs to match the string passed to <code>check_form_key()</code>. Another requirement for this to work correctly is that all forms include the <code>{S_FORM_TOKEN}</code> template variable.</p> 981 982 983 <h4>Sessions: </h4> 984 <p>Sessions should be initiated on each page, as near the top as possible using the following code:</p> 985 986 <div class="codebox"><pre> 987 $user->session_begin(); 988 $auth->acl($user->data); 989 $user->setup(); 990 </pre></div> 991 992 <p>The <code>$user->setup()</code> call can be used to pass on additional language definition and a custom style (used in viewforum).</p> 993 994 <h4>Errors and messages: </h4> 995 <p>All messages/errors should be outputted by calling <code>trigger_error()</code> using the appropriate message type and language string. Example:</p> 996 997 <div class="codebox"><pre> 998 trigger_error('NO_FORUM'); 999 </pre></div> 1000 1001 <div class="codebox"><pre> 1002 trigger_error($user->lang['NO_FORUM']); 1003 </pre></div> 1004 1005 <div class="codebox"><pre> 1006 trigger_error('NO_MODE', E_USER_ERROR); 1007 </pre></div> 1008 1009 <h4>Url formatting</h4> 1010 1011 <p>All urls pointing to internal files need to be prepended by the <code>$phpbb_root_path</code> variable. Within the administration control panel all urls pointing to internal files need to be prepended by the <code>$phpbb_admin_path</code> variable. This makes sure the path is always correct and users being able to just rename the admin folder and the acp still working as intended (though some links will fail and the code need to be slightly adjusted).</p> 1012 1013 <p>The <code>append_sid()</code> function from 2.0.x is available too, though it does not handle url alterations automatically. Please have a look at the code documentation if you want to get more details on how to use append_sid(). A sample call to append_sid() can look like this:</p> 1014 1015 <div class="codebox"><pre> 1016 append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&amp;g=' . $row['group_id']) 1017 </pre></div> 1018 1019 <h4>General function usage: </h4> 1020 1021 <p>Some of these functions are only chosen over others because of personal preference and have no benefit other than maintaining consistency throughout the code.</p> 1022 1023 <ul> 1024 <li> 1025 <p>Use <code>sizeof</code> instead of <code>count</code></p> 1026 </li> 1027 <li> 1028 <p>Use <code>strpos</code> instead of <code>strstr</code></p> 1029 </li> 1030 <li> 1031 <p>Use <code>else if</code> instead of <code>elseif</code></p> 1032 </li> 1033 <li> 1034 <p>Use <code>false</code> (lowercase) instead of <code>FALSE</code></p> 1035 </li> 1036 <li> 1037 <p>Use <code>true</code> (lowercase) instead of <code>TRUE</code></p> 1038 </li> 1039 </ul> 1040 1041 <h4>Exiting</h4> 1042 1043 <p>Your page should either call <code>page_footer()</code> in the end to trigger output through the template engine and terminate the script, or alternatively at least call the <code>exit_handler()</code>. That call is necessary because it provides a method for external applications embedding phpBB to be called at the end of the script.</p> 1044 1045 </div> 1046 1047 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 1048 1049 <span class="corners-bottom"><span></span></span></div> 1050 </div> 1051 1052 <hr /> 1053 1054 <a name="styling"></a><h2>3. Styling</h2> 1055 <div class="paragraph"> 1056 <div class="inner"><span class="corners-top"><span></span></span> 1057 1058 <div class="content"> 1059 <a name="cfgfiles"></a><h3>3.i. Style Config Files</h3> 1060 <p>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.</p> 1061 <div class="codebox"><pre> 1062 # General Information about this style 1063 name = prosilver_duplicate 1064 copyright = © phpBB Group, 2007 1065 version = 3.0.3 1066 required_template = prosilver 1067 required_theme = prosilver 1068 required_imageset = prosilver 1069 </pre></div> 1070 <a name="genstyling"></a><h3>3.2. General Styling Rules</h3> 1071 <p>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.</p> 1072 1073 <p>The outer table class <code>forumline</code> has gone and is replaced with <code>tablebg</code>.</p> 1074 <p>When writing <code><table></code> the order <code><table class="" cellspacing="" cellpadding="" border="" align=""></code> creates consistency and allows everyone to easily see which table produces which "look". The same applies to most other tags for which additional parameters can be set, consistency is the major aim here.</p> 1075 <p>Each block level element should be indented by one tab, same for tabular elements, e.g. <code><tr></code> <code><td></code> etc., whereby the intendiation of <code><table></code> and the following/ending <code><tr></code> should be on the same line. This applies not to div elements of course.</p> 1076 <p>Don't use <code><span></code> more than is essential ... the CSS is such that text sizes are dependent on the parent class. So writing <code><span class="gensmall"><span class="gensmall">TEST</span></span></code> will result in very very small text. Similarly don't use span at all if another element can contain the class definition, e.g.</p> 1077 1078 <div class="codebox"><pre> 1079 <td><span class="gensmall">TEST</span></td> 1080 </pre></div> 1081 1082 <p>can just as well become:</p> 1083 <div class="codebox"><pre> 1084 <td class="gensmall">TEST</td> 1085 </pre></div> 1086 1087 <p>Try to match text class types with existing useage, e.g. don't use the nav class where viewtopic uses gensmall for example.</p> 1088 1089 <p>Row colours/classes are now defined by the template, use an <code>IF S_ROW_COUNT</code> switch, see viewtopic or viewforum for an example.</p> 1090 1091 <p>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.</p> 1092 1093 <p>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.</p> 1094 1095 <p><strong>Use div container/css for styling and table for data representation.</strong></p> 1096 1097 <p>The separate catXXXX and thXXX classes are gone. When defining a header cell just use <code><th></code> rather than <code><th class="thHead"></code> etc. Similarly for cat, don't use <code><td class="catLeft"></code> use <code><td class="cat"></code> etc.</p> 1098 1099 <p>Try to retain consistency of basic layout and class useage, i.e. _EXPLAIN text should generally be placed below the title it explains, e.g. <code>{L_POST_USERNAME}<br /><span class="gensmall">{L_POST_USERNAME_EXPLAIN}</span></code> is the typical way of handling this ... there may be exceptions and this isn't a hard and fast rule.</p> 1100 1101 <p>Try to keep template conditional and other statements tabbed in line with the block to which they refer.</p> 1102 1103 <p class="good">this is correct</p> 1104 <div class="codebox"><pre> 1105 <span class="comment"><!-- BEGIN test --></span> 1106 <tr> 1107 <td>{test.TEXT}</td> 1108 </tr> 1109 <span class="comment"><!-- END test --></span> 1110 </pre></div> 1111 1112 <p class="good">this is also correct:</p> 1113 <div class="codebox"><pre> 1114 <span class="comment"><!-- BEGIN test --></span> 1115 <tr> 1116 <td>{test.TEXT}</td> 1117 </tr> 1118 <span class="comment"><!-- END test --></span> 1119 </pre></div> 1120 1121 <p>it gives immediate feedback on exactly what is looping - decide which way to use based on the readability.</p> 1122 1123 </div> 1124 1125 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 1126 1127 <span class="corners-bottom"><span></span></span></div> 1128 </div> 1129 1130 <hr /> 1131 1132 <a name="templating"></a><h2>4. Templating</h2> 1133 <div class="paragraph"> 1134 <div class="inner"><span class="corners-top"><span></span></span> 1135 1136 <div class="content"> 1137 <a name="templates"></a><h3>4.i. General Templating</h3> 1138 1139 <h4>File naming</h4> 1140 <p>Firstly templates now take the suffix ".html" rather than ".tpl". This was done simply to make the lives of some people easier wrt syntax highlighting, etc.</p> 1141 1142 <h4>Variables</h4> 1143 <p>All template variables should be named appropriately (using underscores for spaces), language entries should be prefixed with L_, system data with S_, urls with U_, javascript urls with UA_, language to be put in javascript statements with LA_, all other variables should be presented 'as is'.</p> 1144 1145 <p>L_* template variables are automatically mapped to the corresponding language entry if the code does not set (and therefore overwrite) this variable specifically and if the language entry exists. For example <code>{L_USERNAME}</code> maps to <code>$user->lang['USERNAME']</code>. The LA_* template variables are handled within the same way, but properly escaped so they can be put in javascript code. This should reduce the need to assign loads of new language variables in MODifications. 1146 </p> 1147 1148 <h4>Blocks/Loops</h4> 1149 <p>The basic block level loop remains and takes the form:</p> 1150 <div class="codebox"><pre> 1151 <span class="comment"><!-- BEGIN loopname --></span> 1152 markup, {loopname.X_YYYYY}, etc. 1153 <span class="comment"><!-- END loopname --></span> 1154 </pre></div> 1155 1156 <p>A bit later loops will be explained further. To not irritate you we will explain conditionals as well as other statements first.</p> 1157 1158 <h4>Including files</h4> 1159 <p>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:</p> 1160 1161 <div class="codebox"><pre> 1162 <span class="comment"><!-- INCLUDE filename --></span> 1163 </pre></div> 1164 1165 <p>You will note in the 3.0 templates the major sources start with <code><!-- INCLUDE overall_header.html --></code> or <code><!-- INCLUDE simple_header.html --></code>, 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.</p> 1166 1167 <p>Added in <strong>3.0.6</strong> 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).</p> 1168 <div class="codebox"><pre> 1169 <span class="comment"><!-- INCLUDE {FILE_VAR} --></span> 1170 </pre></div> 1171 1172 <p>Template defined variables can also be utilised.</p> 1173 1174 <div class="codebox"><pre> 1175 <span class="comment"><!-- DEFINE $SOME_VAR = 'my_file.html' --></span> 1176 <span class="comment"><!-- INCLUDE {$SOME_VAR} --></span> 1177 </pre></div> 1178 1179 <h4>PHP</h4> 1180 <p>A contentious decision has seen the ability to include PHP within the template introduced. This is achieved by enclosing the PHP within relevant tags:</p> 1181 1182 <div class="codebox"><pre> 1183 <span class="comment"><!-- PHP --></span> 1184 echo "hello!"; 1185 <span class="comment"><!-- ENDPHP --></span> 1186 </pre></div> 1187 1188 <p>You may also include PHP from an external file using:</p> 1189 1190 <div class="codebox"><pre> 1191 <span class="comment"><!-- INCLUDEPHP somefile.php --></span> 1192 </pre></div> 1193 1194 <p>it will be included and executed inline.<br /><br />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 <!-- w --><a href="https://www.phpbb.com">www.phpbb.com</a><!-- w --> will <strong>not</strong> 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).</p> 1195 1196 <h4>Conditionals/Control structures</h4> 1197 <p>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:</p> 1198 1199 <div class="codebox"><pre> 1200 <span class="comment"><!-- IF expr --></span> 1201 markup 1202 <span class="comment"><!-- ENDIF --></span> 1203 </pre></div> 1204 1205 <p>expr can take many forms, for example:</p> 1206 1207 <div class="codebox"><pre> 1208 <span class="comment"><!-- IF loop.S_ROW_COUNT is even --></span> 1209 markup 1210 <span class="comment"><!-- ENDIF --></span> 1211 </pre></div> 1212 1213 <p>This will output the markup if the S_ROW_COUNT variable in the current iteration of loop is an even value (i.e. the expr is TRUE). You can use various comparison methods (standard as well as equivalent textual versions noted in square brackets) including (<code>not, or, and, eq, neq, is</code> should be used if possible for better readability):</p> 1214 1215 <div class="codebox"><pre> 1216 == [eq] 1217 != [neq, ne] 1218 <> (same as !=) 1219 !== (not equivalent in value and type) 1220 === (equivalent in value and type) 1221 > [gt] 1222 < [lt] 1223 >= [gte] 1224 <= [lte] 1225 && [and] 1226 || [or] 1227 % [mod] 1228 ! [not] 1229 + 1230 - 1231 * 1232 / 1233 , 1234 << (bitwise shift left) 1235 >> (bitwise shift right) 1236 | (bitwise or) 1237 ^ (bitwise xor) 1238 & (bitwise and) 1239 ~ (bitwise not) 1240 is (can be used to join comparison operations) 1241 </pre></div> 1242 1243 <p>Basic parenthesis can also be used to enforce good old BODMAS rules. Additionally some basic comparison types are defined:</p> 1244 1245 <div class="codebox"><pre> 1246 even 1247 odd 1248 div 1249 </pre></div> 1250 1251 <p>Beyond the simple use of IF you can also do a sequence of comparisons using the following:</p> 1252 1253 <div class="codebox"><pre> 1254 <span class="comment"><!-- IF expr1 --></span> 1255 markup 1256 <span class="comment"><!-- ELSEIF expr2 --></span> 1257 markup 1258 . 1259 . 1260 . 1261 <span class="comment"><!-- ELSEIF exprN --></span> 1262 markup 1263 <span class="comment"><!-- ELSE --></span> 1264 markup 1265 <span class="comment"><!-- ENDIF --></span> 1266 </pre></div> 1267 1268 <p>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".<br /><br />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:</p> 1269 1270 <div class="codebox"><pre> 1271 <table> 1272 <span class="comment"><!-- IF loop.S_ROW_COUNT is even --></span> 1273 <tr class="row1"> 1274 <span class="comment"><!-- ELSE --></span> 1275 <tr class="row2"> 1276 <span class="comment"><!-- ENDIF --></span> 1277 <td>HELLO!</td> 1278 </tr> 1279 </table> 1280 </pre></div> 1281 1282 <p>This will cause the row cell to be output using class row1 when the row count is even, and class row2 otherwise. The S_ROW_COUNT parameter gets assigned to loops by default. Another example would be the following: </p> 1283 1284 <div class="codebox"><pre> 1285 <table> 1286 <span class="comment"><!-- IF loop.S_ROW_COUNT > 10 --></span> 1287 <tr bgcolor="#FF0000"> 1288 <span class="comment"><!-- ELSEIF loop.S_ROW_COUNT > 5 --></span> 1289 <tr bgcolor="#00FF00"> 1290 <span class="comment"><!-- ELSEIF loop.S_ROW_COUNT > 2 --></span> 1291 <tr bgcolor="#0000FF"> 1292 <span class="comment"><!-- ELSE --></span> 1293 <tr bgcolor="#FF00FF"> 1294 <span class="comment"><!-- ENDIF --></span> 1295 <td>hello!</td> 1296 </tr> 1297 </table> 1298 </pre></div> 1299 1300 <p>This will output the row cell in purple for the first two rows, blue for rows 2 to 5, green for rows 5 to 10 and red for remainder. So, you could produce a "nice" gradient effect, for example.<br /><br />What else can you do? Well, you could use IF to do common checks on for example the login state of a user:</p> 1301 1302 <div class="codebox"><pre> 1303 <span class="comment"><!-- IF S_USER_LOGGED_IN --></span> 1304 markup 1305 <span class="comment"><!-- ENDIF --></span> 1306 </pre></div> 1307 1308 <p>This replaces the existing (fudged) method in 2.0.x using a zero length array and BEGIN/END.</p> 1309 1310 <h4>Extended syntax for Blocks/Loops</h4> 1311 1312 <p>Back to our loops - they had been extended with the following additions. Firstly you can set the start and end points of the loop. For example:</p> 1313 1314 <div class="codebox"><pre> 1315 <span class="comment"><!-- BEGIN loopname(2) --></span> 1316 markup 1317 <span class="comment"><!-- END loopname --></span> 1318 </pre></div> 1319 1320 <p>Will start the loop on the third entry (note that indexes start at zero). Extensions of this are: 1321 <br /><br /> 1322 <code>loopname(2)</code>: Will start the loop on the 3rd entry<br /> 1323 <code>loopname(-2)</code>: Will start the loop two entries from the end<br /> 1324 <code>loopname(3,4)</code>: Will start the loop on the fourth entry and end it on the fifth<br /> 1325 <code>loopname(3,-4)</code>: Will start the loop on the fourth entry and end it four from last<br /> 1326 </p> 1327 1328 <p>A further extension to begin is BEGINELSE:</p> 1329 1330 <div class="codebox"><pre> 1331 <span class="comment"><!-- BEGIN loop --></span> 1332 markup 1333 <span class="comment"><!-- BEGINELSE --></span> 1334 markup 1335 <span class="comment"><!-- END loop --></span> 1336 </pre></div> 1337 1338 <p>This will cause the markup between <code>BEGINELSE</code> and <code>END</code> to be output if the loop contains no values. This is useful for forums with no topics (for example) ... in some ways it replaces "bits of" the existing "switch_" type control (the rest being replaced by conditionals).</p> 1339 1340 <p>Another way of checking if a loop contains values is by prefixing the loops name with a dot:</p> 1341 1342 <div class="codebox"><pre> 1343 <span class="comment"><!-- IF .loop --></span> 1344 <span class="comment"><!-- BEGIN loop --></span> 1345 markup 1346 <span class="comment"><!-- END loop --></span> 1347 <span class="comment"><!-- ELSE --></span> 1348 markup 1349 <span class="comment"><!-- ENDIF --></span> 1350 </pre></div> 1351 1352 <p>You are even able to check the number of items within a loop by comparing it with values within the IF condition:</p> 1353 1354 <div class="codebox"><pre> 1355 <span class="comment"><!-- IF .loop > 2 --></span> 1356 <span class="comment"><!-- BEGIN loop --></span> 1357 markup 1358 <span class="comment"><!-- END loop --></span> 1359 <span class="comment"><!-- ELSE --></span> 1360 markup 1361 <span class="comment"><!-- ENDIF --></span> 1362 </pre></div> 1363 1364 <p>Nesting loops cause the conditionals needing prefixed with all loops from the outer one to the inner most. An illustration of this:</p> 1365 1366 <div class="codebox"><pre> 1367 <span class="comment"><!-- BEGIN firstloop --></span> 1368 {firstloop.MY_VARIABLE_FROM_FIRSTLOOP} 1369 1370 <span class="comment"><!-- BEGIN secondloop --></span> 1371 {firstloop.secondloop.MY_VARIABLE_FROM_SECONDLOOP} 1372 <span class="comment"><!-- END secondloop --></span> 1373 <span class="comment"><!-- END firstloop --></span> 1374 </pre></div> 1375 1376 <p>Sometimes it is necessary to break out of nested loops to be able to call another loop within the current iteration. This sounds a little bit confusing and it is not used very often. The following (rather complex) example shows this quite good - it also shows how you test for the first and last row in a loop (i will explain the example in detail further down):</p> 1377 1378 <div class="codebox"><pre> 1379 <span class="comment"><!-- BEGIN l_block1 --></span> 1380 <span class="comment"><!-- IF l_block1.S_SELECTED --></span> 1381 <strong>{l_block1.L_TITLE}</strong> 1382 <span class="comment"><!-- IF S_PRIVMSGS --></span> 1383 1384 <span class="comment"><!-- the ! at the beginning of the loop name forces the loop to be not a nested one of l_block1 --></span> 1385 <span class="comment"><!-- BEGIN !folder --></span> 1386 <span class="comment"><!-- IF folder.S_FIRST_ROW --></span> 1387 <ul class="nav"> 1388 <span class="comment"><!-- ENDIF --></span> 1389 1390 <li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li> 1391 1392 <span class="comment"><!-- IF folder.S_LAST_ROW --></span> 1393 </ul> 1394 <span class="comment"><!-- ENDIF --></span> 1395 <span class="comment"><!-- END !folder --></span> 1396 1397 <span class="comment"><!-- ENDIF --></span> 1398 1399 <ul class="nav"> 1400 <span class="comment"><!-- BEGIN l_block2 --></span> 1401 <li> 1402 <span class="comment"><!-- IF l_block1.l_block2.S_SELECTED --></span> 1403 <strong>{l_block1.l_block2.L_TITLE}</strong> 1404 <span class="comment"><!-- ELSE --></span> 1405 <a href="{l_block1.l_block2.U_TITLE}">{l_block1.l_block2.L_TITLE}</a> 1406 <span class="comment"><!-- ENDIF --></span> 1407 </li> 1408 <span class="comment"><!-- END l_block2 --></span> 1409 </ul> 1410 <span class="comment"><!-- ELSE --></span> 1411 <a class="nav" href="{l_block1.U_TITLE}">{l_block1.L_TITLE}</a> 1412 <span class="comment"><!-- ENDIF --></span> 1413 <span class="comment"><!-- END l_block1 --></span> 1414 </pre></div> 1415 1416 <p>Let us first concentrate on this part of the example:</p> 1417 1418 <div class="codebox"><pre> 1419 <span class="comment"><!-- BEGIN l_block1 --></span> 1420 <span class="comment"><!-- IF l_block1.S_SELECTED --></span> 1421 markup 1422 <span class="comment"><!-- ELSE --></span> 1423 <a class="nav" href="{l_block1.U_TITLE}">{l_block1.L_TITLE}</a> 1424 <span class="comment"><!-- ENDIF --></span> 1425 <span class="comment"><!-- END l_block1 --></span> 1426 </pre></div> 1427 1428 <p>Here we open the loop l_block1 and do some things if the value S_SELECTED within the current loop iteration is true, else we write the blocks link and title. Here, you see <code>{l_block1.L_TITLE}</code> referenced - you remember that L_* variables get automatically assigned the corresponding language entry? This is true, but not within loops. The L_TITLE variable within the loop l_block1 is assigned within the code itself.</p> 1429 1430 <p>Let's have a closer look at the markup:</p> 1431 1432 <div class="codebox"><pre> 1433 <span class="comment"><!-- BEGIN l_block1 --></span> 1434 . 1435 . 1436 <span class="comment"><!-- IF S_PRIVMSGS --></span> 1437 1438 <span class="comment"><!-- BEGIN !folder --></span> 1439 <span class="comment"><!-- IF folder.S_FIRST_ROW --></span> 1440 <ul class="nav"> 1441 <span class="comment"><!-- ENDIF --></span> 1442 1443 <li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li> 1444 1445 <span class="comment"><!-- IF folder.S_LAST_ROW --></span> 1446 </ul> 1447 <span class="comment"><!-- ENDIF --></span> 1448 <span class="comment"><!-- END !folder --></span> 1449 1450 <span class="comment"><!-- ENDIF --></span> 1451 . 1452 . 1453 <span class="comment"><!-- END l_block1 --></span> 1454 </pre></div> 1455 1456 <p>The <code><!-- IF S_PRIVMSGS --></code> statement clearly checks a global variable and not one within the loop, since the loop is not given here. So, if S_PRIVMSGS is true we execute the shown markup. Now, you see the <code><!-- BEGIN !folder --></code> statement. The exclamation mark is responsible for instructing the template engine to iterate through the main loop folder. So, we are now within the loop folder - with <code><!-- BEGIN folder --></code> we would have been within the loop <code>l_block1.folder</code> automatically as is the case with l_block2:</p> 1457 1458 <div class="codebox"><pre> 1459 <span class="comment"><!-- BEGIN l_block1 --></span> 1460 . 1461 . 1462 <ul class="nav"> 1463 <span class="comment"><!-- BEGIN l_block2 --></span> 1464 <li> 1465 <span class="comment"><!-- IF l_block1.l_block2.S_SELECTED --></span> 1466 <strong>{l_block1.l_block2.L_TITLE}</strong> 1467 <span class="comment"><!-- ELSE --></span> 1468 <a href="{l_block1.l_block2.U_TITLE}">{l_block1.l_block2.L_TITLE}</a> 1469 <span class="comment"><!-- ENDIF --></span> 1470 </li> 1471 <span class="comment"><!-- END l_block2 --></span> 1472 </ul> 1473 . 1474 . 1475 <span class="comment"><!-- END l_block1 --></span> 1476 </pre></div> 1477 1478 <p>You see the difference? The loop l_block2 is a member of the loop l_block1 but the loop folder is a main loop.</p> 1479 1480 <p>Now back to our folder loop:</p> 1481 1482 <div class="codebox"><pre> 1483 <span class="comment"><!-- IF folder.S_FIRST_ROW --></span> 1484 <ul class="nav"> 1485 <span class="comment"><!-- ENDIF --></span> 1486 1487 <li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li> 1488 1489 <span class="comment"><!-- IF folder.S_LAST_ROW --></span> 1490 </ul> 1491 <span class="comment"><!-- ENDIF --></span> 1492 </pre></div> 1493 1494 <p>You may have wondered what the comparison to S_FIRST_ROW and S_LAST_ROW is about. If you haven't guessed already - it is checking for the first iteration of the loop with <code>S_FIRST_ROW</code> and the last iteration with <code>S_LAST_ROW</code>. This can come in handy quite often if you want to open or close design elements, like the above list. Let us imagine a folder loop build with three iterations, it would go this way:</p> 1495 1496 <div class="codebox"><pre> 1497 <ul class="nav"> <span class="comment"><!-- written on first iteration --></span> 1498 <li>first element</li> <span class="comment"><!-- written on first iteration --></span> 1499 <li>second element</li> <span class="comment"><!-- written on second iteration --></span> 1500 <li>third element</li> <span class="comment"><!-- written on third iteration --></span> 1501 </ul> <span class="comment"><!-- written on third iteration --></span> 1502 </pre></div> 1503 1504 <p>As you can see, all three elements are written down as well as the markup for the first iteration and the last one. Sometimes you want to omit writing the general markup - for example:</p> 1505 1506 <div class="codebox"><pre> 1507 <span class="comment"><!-- IF folder.S_FIRST_ROW --></span> 1508 <ul class="nav"> 1509 <span class="comment"><!-- ELSEIF folder.S_LAST_ROW --></span> 1510 </ul> 1511 <span class="comment"><!-- ELSE --></span> 1512 <li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li> 1513 <span class="comment"><!-- ENDIF --></span> 1514 </pre></div> 1515 1516 <p>would result in the following markup:</p> 1517 1518 <div class="codebox"><pre> 1519 <ul class="nav"> <span class="comment"><!-- written on first iteration --></span> 1520 <li>second element</li> <span class="comment"><!-- written on second iteration --></span> 1521 </ul> <span class="comment"><!-- written on third iteration --></span> 1522 </pre></div> 1523 1524 <p>Just always remember that processing is taking place from top to bottom.</p> 1525 1526 <h4>Forms</h4> 1527 <p>If a form is used for a non-trivial operation (i.e. more than a jumpbox), then it should include the <code>{S_FORM_TOKEN}</code> template variable.</p> 1528 <div class="codebox"><pre> 1529 <form method="post" id="mcp" action="{U_POST_ACTION}"> 1530 1531 <fieldset class="submit-buttons"> 1532 <input type="reset" value="{L_RESET}" name="reset" class="button2" /> 1533 <input type="submit" name="action[add_warning]" value="{L_SUBMIT}" class="button1" /> 1534 {S_FORM_TOKEN} 1535 </fieldset> 1536 </form> 1537 </pre></div><br /> 1538 1539 <a name="inheritance"></a><h3>4.ii. Template Inheritance</h3> 1540 <p>When basing a new style on an existing one, it is not necessary to provide all the template files. By declaring the base style name in the <strong>inherit_from</strong> field in the template configuration file, the style can be set to inherit template files from the base style. The limitation on this is that the base style has to be installed and complete, meaning that it is not itself inheriting.</p> 1541 1542 <p>The effect of doing so is that the template engine will use the template files in the new style where they exist, but fall back to files in the base style otherwise. Declaring a style to inherit from another also causes it to use some of the configuration settings of the base style, notably database storage.</p> 1543 1544 <p>We strongly encourage the use of inheritance for styles based on the bundled styles, as it will ease the update procedure.</p> 1545 1546 <div class="codebox"><pre> 1547 # General Information about this template 1548 name = inherits 1549 copyright = © phpBB Group, 2007 1550 version = 3.0.3 1551 1552 # Defining a different template bitfield 1553 template_bitfield = lNg= 1554 1555 # Are we inheriting? 1556 inherit_from = prosilver 1557 </pre></div> 1558 1559 </div> 1560 1561 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 1562 1563 <span class="corners-bottom"><span></span></span></div> 1564 </div> 1565 1566 <hr /> 1567 1568 1569 1570 <a name="charsets"></a><h2>5. Character Sets and Encodings</h2> 1571 1572 <div class="paragraph"> 1573 <div class="inner"><span class="corners-top"><span></span></span> 1574 1575 <div class="content"> 1576 1577 1578 1579 <h4>What are Unicode, UCS and UTF-8?</h4> 1580 <p>The <a href="http://en.wikipedia.org/wiki/Universal_Character_Set">Universal Character Set (UCS)</a> described in ISO/IEC 10646 consists of a large amount of characters. Each of them has a unique name and a code point which is an integer number. <a href="http://en.wikipedia.org/wiki/Unicode">Unicode</a> - which is an industry standard - complements the Universal Character Set with further information about the characters' properties and alternative character encodings. More information on Unicode can be found on the <a href="http://www.unicode.org/">Unicode Consortium's website</a>. One of the Unicode encodings is the <a href="http://en.wikipedia.org/wiki/UTF-8">8-bit Unicode Transformation Format (UTF-8)</a>. It encodes characters with up to four bytes aiming for maximum compatibility with the <a href="http://en.wikipedia.org/wiki/ASCII">American Standard Code for Information Interchange</a> which is a 7-bit encoding of a relatively small subset of the UCS.</p> 1581 1582 <h4>phpBB's use of Unicode</h4> 1583 <p>Unfortunately PHP does not faciliate the use of Unicode prior to version 6. Most functions simply treat strings as sequences of bytes assuming that each character takes up exactly one byte. This behaviour still allows for storing UTF-8 encoded text in PHP strings but many operations on strings have unexpected results. To circumvent this problem we have created some alternative functions to PHP's native string operations which use code points instead of bytes. These functions can be found in <code>/includes/utf/utf_tools.php</code>. They are also covered in the <a href="http://area51.phpbb.com/docs/code/">phpBB3 Sourcecode Documentation</a>. A lot of native PHP functions still work with UTF-8 as long as you stick to certain restrictions. For example <code>explode</code> still works as long as the first and the last character of the delimiter string are ASCII characters.</p> 1584 1585 <p>phpBB only uses the ASCII and the UTF-8 character encodings. Still all Strings are UTF-8 encoded because ASCII is a subset of UTF-8. The only exceptions to this rule are code sections which deal with external systems which use other encodings and character sets. Such external data should be converted to UTF-8 using the <code>utf8_recode()</code> function supplied with phpBB. It supports a variety of other character sets and encodings, a full list can be found below.</p> 1586 1587 <p>With <code>request_var()</code> you can either allow all UCS characters in user input or restrict user input to ASCII characters. This feature is controlled by the function's third parameter called <code>$multibyte</code>. You should allow multibyte characters in posts, PMs, topic titles, forum names, etc. but it's not necessary for internal uses like a <code>$mode</code> variable which should only hold a predefined list of ASCII strings anyway.</p> 1588 1589 <div class="codebox"><pre> 1590 // an input string containing a multibyte character 1591 $_REQUEST['multibyte_string'] = 'Käse'; 1592 1593 // print request variable as a UTF-8 string allowing multibyte characters 1594 echo request_var('multibyte_string', '', true); 1595 // print request variable as ASCII string 1596 echo request_var('multibyte_string', ''); 1597 </pre></div> 1598 1599 <p>This code snippet will generate the following output:</p> 1600 1601 <div class="codebox"><pre> 1602 Käse 1603 K??se 1604 </pre></div> 1605 1606 <h4>Unicode Normalization</h4> 1607 1608 <p>If you retrieve user input with multibyte characters you should additionally normalize the string using <code>utf8_normalize_nfc()</code> before you work with it. This is necessary to make sure that equal characters can only occur in one particular binary representation. For example the character Å can be represented either as <code>U+00C5</code> (LATIN CAPITAL LETTER A WITH RING ABOVE) or as <code>U+212B</code> (ANGSTROM SIGN). phpBB uses Normalization Form Canonical Composition (NFC) for all text. So the correct version of the above example would look like this:</p> 1609 1610 <div class="codebox"><pre> 1611 $_REQUEST['multibyte_string'] = 'Käse'; 1612 1613 // normalize multibyte strings 1614 echo utf8_normalize_nfc(request_var('multibyte_string', '', true)); 1615 // ASCII strings do not need to be normalized 1616 echo request_var('multibyte_string', ''); 1617 </pre></div> 1618 1619 <h4>Case Folding</h4> 1620 1621 <p>Case insensitive comparison of strings is no longer possible with <code>strtolower</code> or <code>strtoupper</code> as some characters have multiple lower case or multiple upper case forms depending on their position in a word. The <code>utf8_strtolower</code> and the <code>utf8_strtoupper</code> functions suffer from the same problem so they can only be used to display upper/lower case versions of a string but they cannot be used for case insensitive comparisons either. So instead you should use case folding which gives you a case insensitive version of the string which can be used for case insensitive comparisons. An NFC normalized string can be case folded using <code>utf8_case_fold_nfc()</code>.</p> 1622 1623 <p class="bad">// Bad - The strings might be the same even if strtolower differs</p> 1624 1625 <div class="codebox"><pre> 1626 if (strtolower($string1) == strtolower($string2)) 1627 { 1628 echo '$string1 and $string2 are equal or differ in case'; 1629 } 1630 </pre></div> 1631 1632 <p class="good">// Good - Case folding is really case insensitive</p> 1633 1634 <div class="codebox"><pre> 1635 if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) 1636 { 1637 echo '$string1 and $string2 are equal or differ in case'; 1638 } 1639 </pre></div> 1640 1641 <h4>Confusables Detection</h4> 1642 1643 <p>phpBB offers a special method <code>utf8_clean_string</code> which can be used to make sure string identifiers are unique. This method uses Normalization Form Compatibility Composition (NFKC) instead of NFC and replaces similarly looking characters with a particular representative of the equivalence class. This method is currently used for usernames and group names to avoid confusion with similarly looking names.</p> 1644 1645 </div> 1646 1647 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 1648 1649 <span class="corners-bottom"><span></span></span></div> 1650 </div> 1651 1652 <hr /> 1653 1654 <a name="translation"></a><h2>6. Translation (<abbr title="Internationalisation">i18n</abbr>/<abbr title="Localisation">L10n</abbr>) Guidelines</h2> 1655 1656 <div class="paragraph"> 1657 <div class="inner"><span class="corners-top"><span></span></span> 1658 1659 <div class="content"> 1660 1661 <a name="standardisation"></a><h3>6.i. Standardisation</h3> 1662 1663 <h4>Reason:</h4> 1664 1665 <p>phpBB is one of the most translated open-source projects, with the current stable version being available in over 60 localisations. Whilst the ad hoc approach to the naming of language packs has worked, for phpBB3 and beyond we hope to make this process saner which will allow for better interoperation with current and future web browsers.</p> 1666 1667 <h4>Encoding:</h4> 1668 1669 <p>With phpBB3, the output encoding for the forum in now UTF-8, a Universal Character Encoding by the Unicode Consortium that is by design a superset to US-ASCII and ISO-8859-1. By using one character set which simultaenously supports all scripts which previously would have required different encodings (eg: ISO-8859-1 to ISO-8859-15 (Latin, Greek, Cyrillic, Thai, Hebrew, Arabic); GB2312 (Simplified Chinese); Big5 (Traditional Chinese), EUC-JP (Japanese), EUC-KR (Korean), VISCII (Vietnamese); et cetera), we remove the need to convert between encodings and improves the accessibility of multilingual forums.</p> 1670 1671 <p>The impact is that the language files for phpBB must now also be encoded as UTF-8, with a caveat that the files must <strong>not contain</strong> a <acronym title="Byte-Order-Mark">BOM</acronym> for compatibility reasons with non-Unicode aware versions of PHP. For those with forums using the Latin character set (ie: most European languages), this change is transparent since UTF-8 is superset to US-ASCII and ISO-8859-1.</p> 1672 1673 <h4>Language Tag:</h4> 1674 1675 <p>The <abbr title="Internet Engineering Task Force">IETF</abbr> recently published <a href="http://tools.ietf.org/html/rfc4646">RFC 4646</a> for tags used to identify languages, which in combination with <a href="http://tools.ietf.org/html/rfc4647">RFC 4647</a> obseletes the older <a href="http://tools.ietf.org/html/rfc3066">RFC 3006</a> and older-still <a href="http://tools.ietf.org/html/rfc1766">RFC 1766</a>. <a href="http://tools.ietf.org/html/rfc4646">RFC 4646</a> uses <a href="http://www.loc.gov/standards/iso639-2/php/English_list.php">ISO 639-1/ISO 639-2</a>, <a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 3166-1 alpha-2</a>, <a href="http://www.unicode.org/iso15924/iso15924-codes.html">ISO 15924</a> and <a href="http://unstats.un.org/unsd/methods/m49/m49.htm">UN M.49</a> to define a language tag. Each complete tag is composed of subtags which are not case sensitive and can also be empty.</p> 1676 1677 <p>Ordering of the subtags in the case that they are all non-empty is: <code>language</code>-<code>script</code>-<code>region</code>-<code>variant</code>-<code>extension</code>-<code>privateuse</code>. Should any subtag be empty, its corresponding hyphen would also be ommited. Thus, the language tag for English will be <code>en</code> <strong>and not</strong> <code>en-----</code>.</p> 1678 1679 <p>Most language tags consist of a two- or three-letter language subtag (from <a href="http://www.loc.gov/standards/iso639-2/php/English_list.php">ISO 639-1/ISO 639-2</a>). Sometimes, this is followed by a two-letter or three-digit region subtag (from <a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 3166-1 alpha-2</a> or <a href="http://unstats.un.org/unsd/methods/m49/m49.htm">UN M.49</a>). Some examples are:</p> 1680 1681 <table summary="Examples of various possible language tags as described by RFC 4646 and RFC 4647"> 1682 <caption>Language tag examples</caption> 1683 <thead> 1684 <tr> 1685 <th scope="col">Language tag</th> 1686 <th scope="col">Description</th> 1687 <th scope="col">Component subtags</th> 1688 </tr> 1689 </thead> 1690 <tbody> 1691 <tr> 1692 <td><code>en</code></td> 1693 <td>English</td> 1694 <td><code>language</code></td> 1695 </tr> 1696 <tr> 1697 <td><code>mas</code></td> 1698 <td>Masai</td> 1699 <td><code>language</code></td> 1700 </tr> 1701 <tr> 1702 <td><code>fr-CA</code></td> 1703 <td>French as used in Canada</td> 1704 <td><code>language</code>+<code>region</code></td> 1705 </tr> 1706 <tr> 1707 <td><code>en-833</code></td> 1708 <td>English as used in the Isle of Man</td> 1709 <td><code>language</code>+<code>region</code></td> 1710 </tr> 1711 <tr> 1712 <td><code>zh-Hans</code></td> 1713 <td>Chinese written with Simplified script</td> 1714 <td><code>language</code>+<code>script</code></td> 1715 </tr> 1716 <tr> 1717 <td><code>zh-Hant-HK</code></td> 1718 <td>Chinese written with Traditional script as used in Hong Kong</td> 1719 <td><code>language</code>+<code>script</code>+<code>region</code></td> 1720 </tr> 1721 <tr> 1722 <td><code>de-AT-1996</code></td> 1723 <td>German as used in Austria with 1996 orthography</td> 1724 <td><code>language</code>+<code>region</code>+<code>variant</code></td> 1725 </tr> 1726 </tbody> 1727 </table> 1728 1729 <p>The ultimate aim of a language tag is to convey the needed <strong>useful distingushing information</strong>, whilst keeping it as <strong>short as possible</strong>. So for example, use <code>en</code>, <code>fr</code> and <code>ja</code> as opposed to <code>en-GB</code>, <code>fr-FR</code> and <code>ja-JP</code>, since we know English, French and Japanese are the native language of Great Britain, France and Japan respectively.</p> 1730 1731 <p>Next is the <a href="http://www.unicode.org/iso15924/iso15924-codes.html">ISO 15924</a> language script code and when one should or shouldn't use it. For example, whilst <code>en-Latn</code> is syntaxically correct for describing English written with Latin script, real world English writing is <strong>more-or-less exclusively in the Latin script</strong>. For such languages like English that are written in a single script, the <a href="http://www.iana.org/assignments/language-subtag-registry"><abbr title="Internet Assigned Numbers Authority">IANA</abbr> Language Subtag Registry</a> has a "Suppress-Script" field meaning the script code <strong>should be ommitted</strong> unless a specific language tag requires a specific script code. Some languages are <strong>written in more than one script</strong> and in such cases, the script code <strong>is encouraged</strong> since an end-user may be able to read their language in one script, but not the other. Some examples are:</p> 1732 1733 <table summary="Examples of using a language subtag in combination with a script subtag"> 1734 <caption>Language subtag + script subtag examples</caption> 1735 <thead> 1736 <tr> 1737 <th scope="col">Language tag</th> 1738 <th scope="col">Description</th> 1739 <th scope="col">Component subtags</th> 1740 </tr> 1741 </thead> 1742 <tbody> 1743 <tr> 1744 <td><code>en-Brai</code></td> 1745 <td>English written in Braille script</td> 1746 <td><code>language</code>+<code>script</code></td> 1747 </tr> 1748 <tr> 1749 <td><code>en-Dsrt</code></td> 1750 <td>English written in Deseret (Mormon) script</td> 1751 <td><code>language</code>+<code>script</code></td> 1752 </tr> 1753 <tr> 1754 <td><code>sr-Latn</code></td> 1755 <td>Serbian written in Latin script</td> 1756 <td><code>language</code>+<code>script</code></td> 1757 </tr> 1758 <tr> 1759 <td><code>sr-Cyrl</code></td> 1760 <td>Serbian written in Cyrillic script</td> 1761 <td><code>language</code>+<code>script</code></td> 1762 </tr> 1763 <tr> 1764 <td><code>mn-Mong</code></td> 1765 <td>Mongolian written in Mongolian script</td> 1766 <td><code>language</code>+<code>script</code></td> 1767 </tr> 1768 <tr> 1769 <td><code>mn-Cyrl</code></td> 1770 <td>Mongolian written in Cyrillic script</td> 1771 <td><code>language</code>+<code>script</code></td> 1772 </tr> 1773 <tr> 1774 <td><code>mn-Phag</code></td> 1775 <td>Mongolian written in Phags-pa script</td> 1776 <td><code>language</code>+<code>script</code></td> 1777 </tr> 1778 <tr> 1779 <td><code>az-Cyrl-AZ</code></td> 1780 <td>Azerbaijani written in Cyrillic script as used in Azerbaijan</td> 1781 <td><code>language</code>+<code>script</code>+<code>region</code></td> 1782 </tr> 1783 <tr> 1784 <td><code>az-Latn-AZ</code></td> 1785 <td>Azerbaijani written in Latin script as used in Azerbaijan</td> 1786 <td><code>language</code>+<code>script</code>+<code>region</code></td> 1787 </tr> 1788 <tr> 1789 <td><code>az-Arab-IR</code></td> 1790 <td>Azerbaijani written in Arabic script as used in Iran</td> 1791 <td><code>language</code>+<code>script</code>+<code>region</code></td> 1792 </tr> 1793 </tbody> 1794 </table> 1795 1796 <p>Usage of the three-digit <a href="http://unstats.un.org/unsd/methods/m49/m49.htm">UN M.49</a> code over the two-letter <a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 3166-1 alpha-2</a> code should hapen if a macro-geographical entity is required and/or the <a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 3166-1 alpha-2</a> is ambiguous.</p> 1797 1798 <p>Examples of English using marco-geographical regions:</p> 1799 1800 <table summary="Examples for English of ISO 3166-1 alpha-2 vs. UN M.49 code"> 1801 <caption>Coding for English using macro-geographical regions</caption> 1802 <thead> 1803 <tr> 1804 <th scope="col">ISO 639-1/ISO 639-2 + ISO 3166-1 alpha-2</th> 1805 <th scope="col" colspan="2">ISO 639-1/ISO 639-2 + UN M.49 (Example macro regions)</th> 1806 </tr> 1807 </thead> 1808 <tbody> 1809 <tr> 1810 <td><dl><dt><code>en-AU</code></dt><dd>English as used in <strong>Australia</strong></dd></dl></td> 1811 <td rowspan="2"><dl><dt><code>en-053</code></dt><dd>English as used in <strong>Australia & New Zealand</strong></dd></dl></td> 1812 <td rowspan="3"><dl><dt><code>en-009</code></dt><dd>English as used in <strong>Oceania</strong></dd></dl></td> 1813 </tr> 1814 <tr> 1815 <td><dl><dt><code>en-NZ</code></dt><dd>English as used in <strong>New Zealand</strong></dd></dl></td> 1816 </tr> 1817 <tr> 1818 <td><dl><dt><code>en-FJ</code></dt><dd>English as used in <strong>Fiji</strong></dd></dl></td> 1819 <td><dl><dt><code>en-054 </code></dt><dd>English as used in <strong>Melanesia</strong></dd></dl></td> 1820 </tr> 1821 </tbody> 1822 </table> 1823 1824 <p>Examples of Spanish using marco-geographical regions:</p> 1825 1826 <table summary="Examples for Spanish of ISO 3166-1 alpha-2 vs. UN M.49 code"> 1827 <caption>Coding for Spanish macro-geographical regions</caption> 1828 <thead> 1829 <tr> 1830 <th scope="col">ISO 639-1/ISO 639-2 + ISO 3166-1 alpha-2</th> 1831 <th scope="col" colspan="2">ISO 639-1/ISO 639-2 + UN M.49 (Example macro regions)</th> 1832 </tr> 1833 </thead> 1834 <tbody> 1835 <tr> 1836 <td><dl><dt><code>es-PR</code></dt><dd>Spanish as used in <strong>Puerto Rico</strong></dd></dl></td> 1837 <td rowspan="3"><dl><dt><code>es-419</code></dt><dd>Spanish as used in <strong>Latin America & the Caribbean</strong></dd></dl></td> 1838 <td rowspan="4"><dl><dt><code>es-019</code></dt><dd>Spanish as used in <strong>the Americas</strong></dd></dl></td> 1839 </tr> 1840 <tr> 1841 <td><dl><dt><code>es-HN</code></dt><dd>Spanish as used in <strong>Honduras</strong></dd></dl></td> 1842 </tr> 1843 <tr> 1844 <td><dl><dt><code>es-AR</code></dt><dd>Spanish as used in <strong>Argentina</strong></dd></dl></td> 1845 </tr> 1846 <tr> 1847 <td><dl><dt><code>es-US</code></dt><dd>Spanish as used in <strong>United States of America</strong></dd></dl></td> 1848 <td><dl><dt><code>es-021</code></dt><dd>Spanish as used in <strong>North America</strong></dd></dl></td> 1849 </tr> 1850 </tbody> 1851 </table> 1852 1853 <p>Example of where the <a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 3166-1 alpha-2</a> is ambiguous and why <a href="http://unstats.un.org/unsd/methods/m49/m49.htm">UN M.49</a> might be preferred:</p> 1854 1855 <table summary="Example where the ISO 3166-1 alpha-2 is ambiguous"> 1856 <caption>Coding for ambiguous ISO 3166-1 alpha-2 regions</caption> 1857 <thead> 1858 <tr> 1859 <th scope="col" colspan="2"><code>CS</code> assignment pre-1994</th> 1860 <th scope="col" colspan="2"><code>CS</code> assignment post-1994</th> 1861 </tr> 1862 </thead> 1863 <tbody> 1864 <tr> 1865 <td colspan="2"> 1866 <dl> 1867 <dt><code>CS</code></dt><dd><strong>Czechoslovakia</strong> (ISO 3166-1)</dd> 1868 <dt><code>200</code></dt><dd><strong>Czechoslovakia</strong> (UN M.49)</dd> 1869 </dl> 1870 </td> 1871 <td colspan="2"> 1872 <dl> 1873 <dt><code>CS</code></dt><dd><strong>Serbian & Montenegro</strong> (ISO 3166-1)</dd> 1874 <dt><code>891</code></dt><dd><strong>Serbian & Montenegro</strong> (UN M.49)</dd> 1875 </dl> 1876 </td> 1877 </tr> 1878 <tr> 1879 <td> 1880 <dl> 1881 <dt><code>CZ</code></dt><dd><strong>Czech Republic</strong> (ISO 3166-1)</dd> 1882 <dt><code>203</code></dt><dd><strong>Czech Republic</strong> (UN M.49)</dd> 1883 </dl> 1884 </td> 1885 <td> 1886 <dl> 1887 <dt><code>SK</code></dt><dd><strong>Slovakia</strong> (ISO 3166-1)</dd> 1888 <dt><code>703</code></dt><dd><strong>Slovakia</strong> (UN M.49)</dd> 1889 </dl> 1890 </td> 1891 <td> 1892 <dl> 1893 <dt><code>RS</code></dt><dd><strong>Serbia</strong> (ISO 3166-1)</dd> 1894 <dt><code>688</code></dt><dd><strong>Serbia</strong> (UN M.49)</dd> 1895 </dl> 1896 </td> 1897 <td> 1898 <dl> 1899 <dt><code>ME</code></dt><dd><strong>Montenegro</strong> (ISO 3166-1)</dd> 1900 <dt><code>499</code></dt><dd><strong>Montenegro</strong> (UN M.49)</dd> 1901 </dl> 1902 </td> 1903 </tr> 1904 </tbody> 1905 </table> 1906 1907 <h4>Macro-languages & Topolects:</h4> 1908 1909 <p><a href="http://tools.ietf.org/html/rfc4646">RFC 4646</a> anticipates features which shall be available in (currently draft) <a href="http://www.sil.org/iso639-3/">ISO 639-3</a> which aims to provide as complete enumeration of languages as possible, including living, extinct, ancient and constructed languages, whether majour, minor or unwritten. A new feature of <a href="http://www.sil.org/iso639-3/">ISO 639-3</a> compared to the previous two revisions is the concept of <a href="http://www.sil.org/iso639-3/macrolanguages.asp">macrolanguages</a> where Arabic and Chinese are two such examples. In such cases, their respective codes of <code>ar</code> and <code>zh</code> is very vague as to which dialect/topolect is used or perhaps some terse classical variant which may be difficult for all but very educated users. For such macrolanguages, it is recommended that the sub-language tag is used as a suffix to the macrolanguage tag, eg:</p> 1910 1911 <table summary="Examples of macrolanguages used with sub-language subtags"> 1912 <caption>Macrolanguage subtag + sub-language subtag examples</caption> 1913 <thead> 1914 <tr> 1915 <th scope="col">Language tag</th> 1916 <th scope="col">Description</th> 1917 <th scope="col">Component subtags</th> 1918 </tr> 1919 </thead> 1920 <tbody> 1921 <tr> 1922 <td><code>zh-cmn</code></td> 1923 <td>Mandarin (Putonghau/Guoyu) Chinese</td> 1924 <td><code>macrolanguage</code>+<code>sublanguage</code></td> 1925 </tr> 1926 <tr> 1927 <td><code>zh-yue</code></td> 1928 <td>Yue (Cantonese) Chinese</td> 1929 <td><code>macrolanguage</code>+<code>sublanguage</code></td> 1930 </tr> 1931 <tr> 1932 <td><code>zh-cmn-Hans</code></td> 1933 <td>Mandarin (Putonghau/Guoyu) Chinese written in Simplified script</td> 1934 <td><code>macrolanguage</code>+<code>sublanguage</code>+<code>script</code></td> 1935 </tr> 1936 <tr> 1937 <td><code>zh-cmn-Hant</code></td> 1938 <td>Mandarin (Putonghau/Guoyu) Chinese written in Traditional script</td> 1939 <td><code>macrolanguage</code>+<code>sublanguage</code>+<code>script</code></td> 1940 </tr> 1941 <tr> 1942 <td><code>zh-nan-Latn-TW</code></td> 1943 <td>Minnan (Hoklo) Chinese written in Latin script (POJ Romanisation) as used in Taiwan</td> 1944 <td><code>macrolanguage</code>+<code>sublanguage</code>+<code>script</code>+<code>region</code></td> 1945 </tr> 1946 </tbody> 1947 </table> 1948 1949 <a name="otherconsiderations"></a><h3>6.ii. Other considerations</h3> 1950 1951 <h4>Normalisation of language tags for phpBB:</h4> 1952 1953 <p>For phpBB, the language tags are <strong>not</strong> used in their raw form and instead converted to all lower-case and have the hyphen <code>-</code> replaced with an underscore <code>_</code> where appropriate, with some examples below:</p> 1954 1955 <table summary="Normalisation of language tags for usage in phpBB"> 1956 <caption>Language tag normalisation examples</caption> 1957 <thead> 1958 <tr> 1959 <th scope="col">Raw language tag</th> 1960 <th scope="col">Description</th> 1961 <th scope="col">Value of <code>USER_LANG</code><br />in <code>./common.php</code></th> 1962 <th scope="col">Language pack directory<br />name in <code>/language/</code></th> 1963 </tr> 1964 </thead> 1965 <tbody> 1966 <tr> 1967 <td><code>en</code></td> 1968 <td>British English</td> 1969 <td><code>en</code></td> 1970 <td><code>en</code></td> 1971 </tr> 1972 <tr> 1973 <td><code>de-AT</code></td> 1974 <td>German as used in Austria</td> 1975 <td><code>de-at</code></td> 1976 <td><code>de_at</code></td> 1977 </tr> 1978 <tr> 1979 <td><code>es-419</code></td> 1980 <td>Spanish as used in Latin America & Caribbean</td> 1981 <td><code>en-419</code></td> 1982 <td><code>en_419</code></td> 1983 </tr> 1984 <tr> 1985 <td><code>zh-yue-Hant-HK</code></td> 1986 <td>Cantonese written in Traditional script as used in Hong Kong</td> 1987 <td><code>zh-yue-hant-hk</code></td> 1988 <td><code>zh_yue_hant_hk</code></td> 1989 </tr> 1990 </tbody> 1991 </table> 1992 1993 <h4>How to use <code>iso.txt</code>:</h4> 1994 1995 <p>The <code>iso.txt</code> file is a small UTF-8 encoded plain-text file which consists of three lines:</p> 1996 1997 <ol> 1998 <li><code>Language's English name</code></li> 1999 <li><code>Language's local name</code></li> 2000 <li><code>Authors information</code></li> 2001 </ol> 2002 2003 <p><code>iso.txt</code> is automatically generated by the language pack submission system on phpBB.com. You don't have to create this file yourself if you plan on releasing your language pack on phpBB.com, but do keep in mind that phpBB itself does require this file to be present.</p> 2004 2005 <p>Because language tags themselves are meant to be machine read, they can be rather obtuse to humans and why descriptive strings as provided by <code>iso.txt</code> are needed. Whilst <code>en-US</code> could be fairly easily deduced to be "English as used in the United States", <code>de-CH</code> is more difficult less one happens to know that <code>de</code> is from "<span lang="de">Deutsch</span>", German for "German" and <code>CH</code> is the abbreviation of the official Latin name for Switzerland, "<span lang="la">Confoederatio Helvetica</span>".</p> 2006 2007 <p>For the English language description, the language name is always first and any additional attributes required to describe the subtags within the language code are then listed in order separated with commas and enclosed within parentheses, eg:</p> 2008 2009 <table summary="English language description examples of iso.txt for usage in phpBB"> 2010 <caption>English language description examples for iso.txt</caption> 2011 <thead> 2012 <tr> 2013 <th scope="col">Raw language tag</th> 2014 <th scope="col">English description within <code>iso.txt</code></th> 2015 </tr> 2016 </thead> 2017 <tbody> 2018 <tr> 2019 <td><code>en</code></td> 2020 <td>British English</td> 2021 </tr> 2022 <tr> 2023 <td><code>en-US</code></td> 2024 <td>English (United States)</td> 2025 </tr> 2026 <tr> 2027 <td><code>en-053</code></td> 2028 <td>English (Australia & New Zealand)</td> 2029 </tr> 2030 <tr> 2031 <td><code>de</code></td> 2032 <td>German</td> 2033 </tr> 2034 <tr> 2035 <td><code>de-CH-1996</code></td> 2036 <td>German (Switzerland, 1996 orthography)</td> 2037 </tr> 2038 <tr> 2039 <td><code>gws-1996</code></td> 2040 <td>Swiss German (1996 orthography)</td> 2041 </tr> 2042 <tr> 2043 <td><code>zh-cmn-Hans-CN</code></td> 2044 <td>Mandarin Chinese (Simplified, Mainland China)</td> 2045 </tr> 2046 <tr> 2047 <td><code>zh-yue-Hant-HK</code></td> 2048 <td>Cantonese Chinese (Traditional, Hong Kong)</td> 2049 </tr> 2050 </tbody> 2051 </table> 2052 2053 <p>For the localised language description, just translate the English version though use whatever appropriate punctuation typical for your own locale, assuming the language uses punctuation at all.</p> 2054 2055 <h4>Unicode bi-directional considerations:</h4> 2056 2057 <p>Because phpBB is now UTF-8, all translators must take into account that certain strings may be shown when the directionality of the document is either opposite to normal or is ambiguous.</p> 2058 2059 <p>The various Unicode control characters for bi-directional text and their HTML enquivalents where appropriate are as follows:</p> 2060 2061 <table summary="Table of the various Unicode bidirectional control characters"> 2062 <caption>Unicode bidirectional control characters & HTML elements/entities</caption> 2063 <thead> 2064 <tr> 2065 <th scope="col">Unicode character<br />abbreviation</th> 2066 <th scope="col">Unicode<br />code-point</th> 2067 <th scope="col">Unicode character<br />name</th> 2068 <th scope="col">Equivalent HTML<br />markup/entity</th> 2069 <th scope="col">Raw character<br />(enclosed between '')</th> 2070 </tr> 2071 </thead> 2072 <tbody> 2073 <tr> 2074 <td><code>LRM</code></td> 2075 <td><code>U+200E</code></td> 2076 <td>Left-to-Right Mark</td> 2077 <td><code>&lrm;</code></td> 2078 <td>'‎'</td> 2079 </tr> 2080 <tr> 2081 <td><code>RLM</code></td> 2082 <td><code>U+200F</code></td> 2083 <td>Right-to-Left Mark</td> 2084 <td><code>&rlm;</code></td> 2085 <td>'‏'</td> 2086 </tr> 2087 <tr> 2088 <td><code>LRE</code></td> 2089 <td><code>U+202A</code></td> 2090 <td>Left-to-Right Embedding</td> 2091 <td><code>dir="ltr"</code></td> 2092 <td>'‪'</td> 2093 </tr> 2094 <tr> 2095 <td><code>RLE</code></td> 2096 <td><code>U+202B</code></td> 2097 <td>Right-to-Left Embedding</td> 2098 <td><code>dir="rtl"</code></td> 2099 <td>'‫'</td> 2100 </tr> 2101 <tr> 2102 <td><code>PDF</code></td> 2103 <td><code>U+202C</code></td> 2104 <td>Pop Directional Formatting</td> 2105 <td><code></bdo></code></td> 2106 <td>'‬'</td> 2107 </tr> 2108 <tr> 2109 <td><code>LRO</code></td> 2110 <td><code>U+202D</code></td> 2111 <td>Left-to-Right Override</td> 2112 <td><code><bdo dir="ltr"></code></td> 2113 <td>'‭'</td> 2114 </tr> 2115 <tr> 2116 <td><code>RLO</code></td> 2117 <td><code>U+202E</code></td> 2118 <td>Right-to-Left Override</td> 2119 <td><code><bdo dir="rtl"></code></td> 2120 <td>'‮'</td> 2121 </tr> 2122 </tbody> 2123 </table> 2124 2125 <p>For <code>iso.txt</code>, the directionality of the text can be explicitly set using special Unicode characters via any of the three methods provided by left-to-right/right-to-left markers/embeds/overrides, as without them, the ordering of characters will be incorrect, eg:</p> 2126 2127 <table summary="Effect of using Unicode bidirectional control characters within iso.txt"> 2128 <caption>Unicode bidirectional control characters iso.txt</caption> 2129 <thead> 2130 <tr> 2131 <th scope="col">Directionality</th> 2132 <th scope="col">Raw character view</th> 2133 <th scope="col">Display of localised<br />description in <code>iso.txt</code></th> 2134 <th scope="col">Ordering</th> 2135 </tr> 2136 </thead> 2137 <tbody> 2138 <tr> 2139 <td><code>dir="ltr"</code></td> 2140 <td>English (Australia & New Zealand)</td> 2141 <td dir="ltr">English (Australia & New Zealand)</td> 2142 <td class="good">Correct</td> 2143 </tr> 2144 <tr> 2145 <td><code>dir="rtl"</code></td> 2146 <td>English (Australia & New Zealand)</td> 2147 <td dir="rtl">English (Australia & New Zealand)</td> 2148 <td class="bad">Incorrect</td> 2149 </tr> 2150 <tr> 2151 <td><code>dir="rtl"</code> with <code>LRM</code></td> 2152 <td>English (Australia & New Zealand)<code>U+200E</code></td> 2153 <td dir="rtl">English (Australia & New Zealand)‎</td> 2154 <td class="good">Correct</td> 2155 </tr> 2156 <tr> 2157 <td><code>dir="rtl"</code> with <code>LRE</code> & <code>PDF</code></td> 2158 <td><code>U+202A</code>English (Australia & New Zealand)<code>U+202C</code></td> 2159 <td dir="rtl">‪English (Australia & New Zealand)‬</td> 2160 <td class="good">Correct</td> 2161 </tr> 2162 <tr> 2163 <td><code>dir="rtl"</code> with <code>LRO</code> & <code>PDF</code></td> 2164 <td><code>U+202D</code>English (Australia & New Zealand)<code>U+202C</code></td> 2165 <td dir="rtl">‭English (Australia & New Zealand)‬</td> 2166 <td class="good">Correct</td> 2167 </tr> 2168 </tbody> 2169 </table> 2170 2171 <p>In choosing which of the three methods to use, in the majority of cases, the <code>LRM</code> or <code>RLM</code> to put a "strong" character to fully enclose an ambiguous punctuation character and thus make it inherit the correct directionality is sufficient.</p> 2172 <p>Within some cases, there may be mixed scripts of a left-to-right and right-to-left direction, so using <code>LRE</code> & <code>RLE</code> with <code>PDF</code> may be more appropriate. Lastly, in very rare instances where directionality must be forced, then use <code>LRO</code> & <code>RLO</code> with <code>PDF</code>.</p> 2173 <p>For further information on authoring techniques of bi-directional text, please see the W3C tutorial on <a href="http://www.w3.org/International/tutorials/bidi-xhtml/">authoring techniques for XHTML pages with bi-directional text</a>.</p> 2174 2175 <h4>Working with placeholders:</h4> 2176 2177 <p>As phpBB is translated into languages with different ordering rules to that of English, it is possible to show specific values in any order deemed appropriate. Take for example the extremely simple "Page <em>X</em> of <em>Y</em>", whilst in English this could just be coded as:</p> 2178 2179 <div class="codebox"><pre> 2180 ... 2181 'PAGE_OF' => 'Page %s of %s', 2182 /* Just grabbing the replacements as they 2183 come and hope they are in the right order */ 2184 ... 2185 </pre></div> 2186 2187 <p>… a clearer way to show explicit replacement ordering is to do:</p> 2188 2189 <div class="codebox"><pre> 2190 ... 2191 'PAGE_OF' => 'Page %1$s of %2$s', 2192 /* Explicit ordering of the replacements, 2193 even if they are the same order as English */ 2194 ... 2195 </pre></div> 2196 2197 <p>Why bother at all? Because some languages, the string transliterated back to English might read something like:</p> 2198 2199 <div class="codebox"><pre> 2200 ... 2201 'PAGE_OF' => 'Total of %2$s pages, currently on page %1$s', 2202 /* Explicit ordering of the replacements, 2203 reversed compared to English as the total comes first */ 2204 ... 2205 </pre></div> 2206 2207 <a name="writingstyle"></a><h3>6.iii. Writing Style</h3> 2208 2209 <h4>Miscellaneous tips & hints:</h4> 2210 2211 <p>As the language files are PHP files, where the various strings for phpBB are stored within an array which in turn are used for display within an HTML page, rules of syntax for both must be considered. Potentially problematic characters are: <code>'</code> (straight quote/apostrophe), <code>"</code> (straight double quote), <code><</code> (less-than sign), <code>></code> (greater-than sign) and <code>&</code> (ampersand).</p> 2212 2213 <p class="bad">// Bad - The un-escapsed straight-quote/apostrophe will throw a PHP parse error</p> 2214 2215 <div class="codebox"><pre> 2216 ... 2217 'CONV_ERROR_NO_AVATAR_PATH' 2218 => 'Note to developer: you must specify $convertor['avatar_path'] to use %s.', 2219 ... 2220 </pre></div> 2221 2222 <p class="good">// Good - Literal straight quotes should be escaped with a backslash, ie: \</p> 2223 2224 <div class="codebox"><pre> 2225 ... 2226 'CONV_ERROR_NO_AVATAR_PATH' 2227 => 'Note to developer: you must specify $convertor[\'avatar_path\'] to use %s.', 2228 ... 2229 </pre></div> 2230 2231 <p>However, because phpBB3 now uses UTF-8 as its sole encoding, we can actually use this to our advantage and not have to remember to escape a straight quote when we don't have to:</p> 2232 2233 <p class="bad">// Bad - The un-escapsed straight-quote/apostrophe will throw a PHP parse error</p> 2234 2235 <div class="codebox"><pre> 2236 ... 2237 'USE_PERMISSIONS' => 'Test out user's permissions', 2238 ... 2239 </pre></div> 2240 2241 <p class="good">// Okay - However, non-programmers wouldn't type "user\'s" automatically</p> 2242 2243 <div class="codebox"><pre> 2244 ... 2245 'USE_PERMISSIONS' => 'Test out user\'s permissions', 2246 ... 2247 </pre></div> 2248 2249 <p class="good">// Best - Use the Unicode Right-Single-Quotation-Mark character</p> 2250 2251 <div class="codebox"><pre> 2252 ... 2253 'USE_PERMISSIONS' => 'Test out user’s permissions', 2254 ... 2255 </pre></div> 2256 2257 <p>The <code>"</code> (straight double quote), <code><</code> (less-than sign) and <code>></code> (greater-than sign) characters can all be used as displayed glyphs or as part of HTML markup, for example:</p> 2258 2259 <p class="bad">// Bad - Invalid HTML, as segments not part of elements are not entitised</p> 2260 2261 <div class="codebox"><pre> 2262 ... 2263 'FOO_BAR' => 'PHP version < 4.3.3.<br /> 2264 Visit "Downloads" at <a href="http://www.php.net/">www.php.net</a>.', 2265 ... 2266 </pre></div> 2267 2268 <p class="good">// Okay - No more invalid HTML, but "&quot;" is rather clumsy</p> 2269 2270 <div class="codebox"><pre> 2271 ... 2272 'FOO_BAR' => 'PHP version &lt; 4.3.3.<br /> 2273 Visit &quot;Downloads&quot; at <a href="http://www.php.net/">www.php.net</a>.', 2274 ... 2275 </pre></div> 2276 2277 <p class="good">// Best - No more invalid HTML, and usage of correct typographical quotation marks</p> 2278 2279 <div class="codebox"><pre> 2280 ... 2281 'FOO_BAR' => 'PHP version &lt; 4.3.3.<br /> 2282 Visit “Downloads” at <a href="http://www.php.net/">www.php.net</a>.', 2283 ... 2284 </pre></div> 2285 2286 <p>Lastly, the <code>&</code> (ampersand) must always be entitised regardless of where it is used:</p> 2287 2288 <p class="bad">// Bad - Invalid HTML, none of the ampersands are entitised</p> 2289 2290 <div class="codebox"><pre> 2291 ... 2292 'FOO_BAR' => '<a href="http://somedomain.tld/?foo=1&bar=2">Foo & Bar</a>.', 2293 ... 2294 </pre></div> 2295 2296 <p class="good">// Good - Valid HTML, amperands are correctly entitised in all cases</p> 2297 2298 <div class="codebox"><pre> 2299 ... 2300 'FOO_BAR' => '<a href="http://somedomain.tld/?foo=1&amp;bar=2">Foo &amp; Bar</a>.', 2301 ... 2302 </pre></div> 2303 2304 <p>As for how these charcters are entered depends very much on choice of Operating System, current language locale/keyboard configuration and native abilities of the text editor used to edit phpBB language files. Please see <a href="http://en.wikipedia.org/wiki/Unicode#Input_methods">http://en.wikipedia.org/wiki/Unicode#Input_methods</a> for more information.</p> 2305 2306 <h4>Spelling, punctuation, grammar, et cetera:</h4> 2307 2308 <p>The default language pack bundled with phpBB is <strong>British English</strong> using <a href="http://www.cambridge.org/">Cambridge University Press</a> spelling and is assigned the language code <code>en</code>. The style and tone of writing tends towards formal and translations <strong>should</strong> emulate this style, at least for the variant using the most compact language code. Less formal translations or those with colloquialisms <strong>must</strong> be denoted as such via either an <code>extension</code> or <code>privateuse</code> tag within its language code.</p> 2309 2310 </div> 2311 2312 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 2313 2314 <span class="corners-bottom"><span></span></span></div> 2315 </div> 2316 2317 <hr /> 2318 2319 <a name="disclaimer"></a><h2>7. Copyright and disclaimer</h2> 2320 2321 <div class="paragraph"> 2322 <div class="inner"><span class="corners-top"><span></span></span> 2323 2324 <div class="content"> 2325 2326 <p>This application is opensource software released under the <a href="http://opensource.org/licenses/gpl-2.0.php">GNU General Public License v2</a>. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) <a href="https://www.phpbb.com/">phpBB Group</a>, All Rights Reserved.</p> 2327 2328 </div> 2329 2330 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> 2331 2332 <span class="corners-bottom"><span></span></span></div> 2333 </div> 2334 2335 <!-- END DOCUMENT --> 2336 2337 <div id="page-footer"> 2338 <div class="version"> </div> 2339 </div> 2340 </div></div> 2341 2342 <div> 2343 <a id="bottom" name="bottom" accesskey="z"></a> 2344 </div> 2345 2346 </body> 2347 </html>
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Oct 2 15:03:47 2013 | Cross-referenced by PHPXref 0.7.1 |