diff options
| author | Nathan Guse <nathaniel.guse@gmail.com> | 2013-09-05 13:56:57 -0500 |
|---|---|---|
| committer | Nathan Guse <nathaniel.guse@gmail.com> | 2013-09-05 13:56:57 -0500 |
| commit | e8ab8fe0bc7d087fe3c9b5d2a3e545f228bb3096 (patch) | |
| tree | 6a053afa0a156204112b480707608cac60770ac5 /phpBB/docs/coding-guidelines.html | |
| parent | abaa53b0b295358efcf591587485c01a027cd5cb (diff) | |
| parent | dd86e8d0ae0179cf50076cdb1a8020266b6432a5 (diff) | |
| download | forums-e8ab8fe0bc7d087fe3c9b5d2a3e545f228bb3096.tar forums-e8ab8fe0bc7d087fe3c9b5d2a3e545f228bb3096.tar.gz forums-e8ab8fe0bc7d087fe3c9b5d2a3e545f228bb3096.tar.bz2 forums-e8ab8fe0bc7d087fe3c9b5d2a3e545f228bb3096.tar.xz forums-e8ab8fe0bc7d087fe3c9b5d2a3e545f228bb3096.zip | |
Merge branch 'develop' of github.com:phpbb/phpbb3 into ticket/8323
# By Joas Schilling (613) and others
# Via Andreas Fischer (214) and others
* 'develop' of github.com:phpbb/phpbb3: (2494 commits)
[ticket/11825] Move schema_data.php into includes/ instead of phpbb/
[ticket/11215] Remove unnecessary comment
[ticket/11755] MySQL upgrader out of date
[prep-release-3.0.12] Update Changelog for 3.0.12-RC3 release.
[prep-release-3.0.12] Bumping version number for 3.0.12-RC3.
[ticket/11823] Set up nginx server to match PHP files with characters after .php
[ticket/11812] Fix empty define
[ticket/11818] Update Symfony dependencies to 2.3.*
[ticket/11791] Load adm/ events from styles/adm/event/
[ticket/11215] Fix helper_url_test.php tests
[ticket/11215] Add newline back to .htaccess, fix wording
[ticket/11215] Update comment in .htaccess
[ticket/11215] Uncomment rewrite rules in .htaccess
[ticket/11215] Make controller helper url() method use correct format
[ticket/11215] Add commented-out URL rewrite capability to .htaccess
[ticket/11821] Fix comma usage next to "You are receiving this notification".
[ticket/11769] Allow using 0 as poster name
[ticket/11769] Allow '0' as username
[ticket/11215] Use new URL structure for controllers
[ticket/11215] Everything appears to be working...
...
Conflicts:
phpBB/includes/functions_privmsgs.php
Diffstat (limited to 'phpBB/docs/coding-guidelines.html')
| -rw-r--r-- | phpBB/docs/coding-guidelines.html | 80 |
1 files changed, 67 insertions, 13 deletions
diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index eb569d12d5..6cd2627f43 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -72,6 +72,7 @@ <ol style="list-style-type: lower-roman;"> <li><a href="#templates">General Templating</a></li> <li><a href="#stylestree">Styles Tree</a></li> + <li><a href="#template-events">Template Events</a></li> </ol></li> <li><a href="#charsets">Character Sets and Encodings</a></li> <li><a href="#translation">Translation (<abbr title="Internationalisation">i18n</abbr>/<abbr title="Localisation">L10n</abbr>) Guidelines</a> @@ -831,7 +832,7 @@ $sql = 'SELECT * $sql_ary = array( 'somedata' => $my_string, 'otherdata' => $an_int, - 'moredata' => $another_int + 'moredata' => $another_int, ); $db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary)); @@ -843,7 +844,7 @@ $db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('I $sql_ary = array( 'somedata' => $my_string, 'otherdata' => $an_int, - 'moredata' => $another_int + 'moredata' => $another_int, ); $sql = 'UPDATE ' . SOME_TABLE . ' @@ -936,20 +937,20 @@ $sql_array = array( 'FROM' => array( FORUMS_WATCH_TABLE => 'fw', - FORUMS_TABLE => 'f' + FORUMS_TABLE => 'f', ), 'LEFT_JOIN' => array( array( 'FROM' => array(FORUMS_TRACK_TABLE => 'ft'), - 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id' - ) + 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id', + ), ), 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' AND f.forum_id = fw.forum_id', - 'ORDER_BY' => 'left_id' + 'ORDER_BY' => 'left_id', ); $sql = $db->sql_build_query('SELECT', $sql_array); @@ -963,13 +964,13 @@ $sql_array = array( 'FROM' => array( FORUMS_WATCH_TABLE => 'fw', - FORUMS_TABLE => 'f' + FORUMS_TABLE => 'f', ), 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' AND f.forum_id = fw.forum_id', - 'ORDER_BY' => 'left_id' + 'ORDER_BY' => 'left_id', ); if ($config['load_db_lastread']) @@ -977,8 +978,8 @@ if ($config['load_db_lastread']) $sql_array['LEFT_JOIN'] = array( array( 'FROM' => array(FORUMS_TRACK_TABLE => 'ft'), - 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id' - ) + 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id', + ), ); $sql_array['SELECT'] .= ', ft.mark_time '; @@ -1059,6 +1060,8 @@ $action_ary = request_var('action', array('' => 0)); <h4>Login checks/redirection: </h4> <p>To show a forum login box use <code>login_forum_box($forum_data)</code>, else use the <code>login_box()</code> function.</p> + <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> + <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> <h4>Sensitive Operations: </h4> @@ -1312,7 +1315,7 @@ parent = prosilver <span class="comment"><!-- INCLUDEPHP somefile.php --></span> </pre></div> -<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="http://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> +<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> <h4>Conditionals/Control structures</h4> <p>The most significant addition to 3.x are conditions or control structures, "if something then do this else do that". The system deployed is very similar to Smarty. This may confuse some people at first but it offers great potential and great flexibility with a little imagination. In their most simple form these constructs take the form:</p> @@ -1678,6 +1681,57 @@ version = 3.1.0 parent = prosilver </pre></div> + <a name="template-events"></a><h3>4.iii. Template Events</h3> + <p>Template events must follow this format: <code><!-- EVENT event_name --></code></p> + <p>Using the above example, files named <code>event_name.html</code> located within extensions will be injected into the location of the event.</p> + + <h4>Template event naming guidelines:</h4> + <ul> + <li>An event name must be all lowercase, with each word separated by an underscore.</li> + <li>An event name must briefly describe the location and purpose of the event.</li> + <li>An event name must end with one of the following suffixes:</li> + <ul> + <li><code>_prepend</code> - This event adds an item to the beginning of a block of related items, or adds to the beginning of individual items in a block.</li> + <li><code>_append</code> - This event adds an item to the end of a block of related items, or adds to the end of individual items in a block.</li> + <li><code>_before</code> - This event adds content directly before the specified block</li> + <li><code>_after</code> - This event adds content directly after the specified block</li> + </ul> + </ul> + + <h4>Template event documentation</h4> + <p>Events must be documented in <code>phpBB/docs/events.md</code> in alphabetical order based on the event name. The format is as follows:</p> + + <ul><li>An event found in only one template file: + <div class="codebox"><pre>event_name +=== +* Location: styles/<style_name>/template/filename.html +* Purpose: A brief description of what this event should be used for. +This may span multiple lines. +</pre></div></li> + <li>An event found in multiple template files: + <div class="codebox"><pre>event_name +=== +* Locations: + + first/file/path.html + + second/file/path.html +* Purpose: Same as above. +</pre></div> + <li>An event that is found multiple times in a file should have the number of instances in parenthesis next to the filename. + <div class="codebox"><pre>event_name +=== +* Locations: + + first/file/path.html (2) + + second/file/path.html +* Purpose: Same as above. +</pre></div></li> + <li>An actual example event documentation: + <div class="codebox"><pre>forumlist_body_last_post_title_prepend +==== +* Locations: + + styles/prosilver/template/forumlist_body.html + + styles/subsilver2/template/forumlist_body.html +* Purpose: Add content before the post title of the latest post in a forum on the forum list.</pre></div></ul><br /> + </div> <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div> @@ -2438,14 +2492,14 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) <hr /> -<a name="disclaimer"></a><h2>8. Copyright and disclaimer</h2> +<a name="disclaimer"></a><h2>7. Copyright and disclaimer</h2> <div class="paragraph"> <div class="inner"><span class="corners-top"><span></span></span> <div class="content"> - <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="http://www.phpbb.com/">phpBB Group</a>, All Rights Reserved.</p> + <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> </div> |