`
8 | - The document title does NOT need to be included in the document, these are displayed as the page heading based on the Joomla component configuration and would result in duplicated titles if included
9 | - Because the GitHub Markdown parser interprets line breaks as `
` tags, arbitrary line breaks to keep lines from becoming too long should not be used
10 | - Links to documents in this manual should be formatted for use on the Joomla! Developer Network, such as `[a link to the Basic Guidelines page](/coding-standards/basic-guidelines.html)`
11 |
--------------------------------------------------------------------------------
/manual/appendices/analysis.md:
--------------------------------------------------------------------------------
1 | For new contributions we are going to be enforcing coding standards to ensure that the coding style in the source code is consistent. Ensuring that your code meets these standards will make the process of code contribution smoother.
2 |
3 | ### Configuring Code Analysis Tools
4 |
5 | In order to improve the consistency and readability of the source code, the Joomla project runs a coding style analysis tool, PHP_CodeSniffer, everytime changes are pushed to a Joomla project's repository.
6 |
7 | #### Running PHP_CodeSniffer
8 |
9 | The Joomla Coding Standards sniffer rules are written to be used with a tool called PHP CodeSniffer. Please see the [PHP_CodeSniffer PEAR Page](http://pear.php.net/package/PHP_CodeSniffer) for information on installing PHP_CodeSniffer on your system.
10 |
11 | You can run the CodeSniffer by going to the CMS, Framework, or Issue Tracker's root directory and executing
12 |
13 | ```
14 | phpcs --report=checkstyle --report-file=build/logs/checkstyle.xml --standard=/path/to//build/phpcs/Joomla /path/to/
15 | ```
16 |
17 | Alternatively, if you have Ant installed on your system, you may run the CodeSniffer by going to the `` of the Joomla project's code you want to test and executing
18 |
19 | ```
20 | ant phpcs
21 | ```
22 |
23 | ### Other Tools
24 |
25 | Here are some other tools available to developers who are planning to submit source code to the project.
26 |
27 | #### Set up PHP_CodeSniffer
28 |
29 | See in the documentation https://docs.joomla.org/Joomla_CodeSniffer#3._IDE_Integration
30 |
--------------------------------------------------------------------------------
/manual/appendices/examples.md:
--------------------------------------------------------------------------------
1 | Please contribute to this documentation page.
2 |
--------------------------------------------------------------------------------
/manual/basic-guidelines.md:
--------------------------------------------------------------------------------
1 | This chapter outlines the basic guidelines covering files contributed to the Joomla project. The most important rule to remember when coding for the Joomla project, **if in doubt, please ask**.
2 |
3 | ### File Format
4 |
5 | All files contributed to Joomla must be:
6 |
7 | * Stored as ASCII text
8 | Exceptions: languages locales and some test files containing non-ASCII characters
9 | * Use UTF-8 character encoding
10 | * Be Unix formatted following these rules.
11 | 1. Lines must end only with a line feed (LF).
12 | 2. Line feeds are represented as ordinal 10, octal 012 and hex 0A.
13 | 3. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
14 |
15 | ### Spelling
16 |
17 | The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant should generally be in accordance with British English rules (en\_GB). Some exceptions are permitted, for example where common programming names are used that align with the PHP API or other established conventions such as for `color` where is it common practice to maintain US English spelling.
18 |
19 | ### Indenting
20 |
21 | Tabs are used for indenting code (not spaces as required by the PEAR standard). Source code editors or Integrated Development Environments (IDE’s) such as Eclipse must have the tab-stops for indenting measuring four (4) spaces in length.
22 |
23 | ### Line Length
24 |
25 | There is no maximum limit for line lengths in files, however, a notional value of about 150 characters is recommended to achieve a good level of readability without horizontal scrolling. Longer lines are permitted if the nature of the code for individual lines requires it and line breaks would have an adverse affect on the final output (such as for mixed PHP/HTML layout files).
26 |
--------------------------------------------------------------------------------
/manual/css.md:
--------------------------------------------------------------------------------
1 | These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, namely:
2 |
3 | 1. [OOCSS Code Standards](https://github.com/stubbornella/oocss-code-standards)
4 | 2. [Oneweb Style Guide](https://github.com/nternetinspired/OneWeb/blob/master/STYLEGUIDE.md)
5 | 3. [Idiomatic CSS](https://github.com/necolas/idiomatic-css)
6 |
7 | ### Commenting
8 |
9 | #### Major sections
10 | Major code sections should be named in caps and within a full comment block, eg:
11 |
12 | ```css
13 | /* ==========================================================================
14 | PRIMARY NAVIGATION
15 | ========================================================================== */
16 | ```
17 |
18 | #### Sub sections
19 | Subsections should be normally cased and within an open comment block.
20 |
21 | ```css
22 | /* Mobile navigation
23 | ========================================================================== */
24 | ```
25 |
26 | #### Verbose comments
27 |
28 | ```css
29 | /**
30 | * Short description using Doxygen-style comment format
31 | *
32 | * The first sentence of the long description starts here and continues on this
33 | * line for a while finally concluding here at the end of this paragraph.
34 | *
35 | * The long description is ideal for more detailed explanations and
36 | * documentation. It can include example HTML, URLs, or any other information
37 | * that is deemed necessary or useful.
38 | *
39 | * @tag This is a tag named 'tag'
40 | *
41 | * TODO: This is a todo statement that describes an atomic task to be completed
42 | * at a later date. It wraps after 80 characters and following lines are
43 | * indented by 2 spaces.
44 | */
45 | ```
46 |
47 | #### Basic comments
48 |
49 | ```css
50 | /* Basic comment */
51 | ```
52 |
53 | #### Uncompiled LESS/Scss comments
54 |
55 | ```css
56 | // These are stripped on compile.
57 | ```
58 |
59 | ### CSS selectors
60 | Only use classes for CSS selectors, *never IDs* as they introduce unwanted specificity to the cascade. Using an ID as a CSS selector is like firing the first nuke; you begin a specifity war that can only escalate, with terrible consequence.
61 |
62 | To put it another way; Don't use a Sith Lord when just two Storm Troopers will suffice: [CSS Specificity Wars](http://www.stuffandnonsense.co.uk/archives/css_specificity_wars.html)
63 |
64 | #### Class naming convention
65 | Use dashes to create compound class names:
66 |
67 | ```css
68 | /* Good - use dashes */
69 | .compound-class-name {…}
70 |
71 | /* Good - uses camelCase */
72 | .compoundClassName {…}
73 |
74 | /* Bad - uses underscores */
75 | .compound_class_name {…}
76 |
77 | /* Bad - does not use seperators */
78 | .compoundclassname {…}
79 | ```
80 |
81 | #### Indentation
82 | Rules should be indented one tab (equal to 4 spaces):
83 |
84 | ```css
85 | /* Good */
86 | .example {
87 | color: #000;
88 | visibility: hidden;
89 | }
90 |
91 | /* Bad - all on one line */
92 | .example {color: #000; visibility: hidden;}
93 | ```
94 |
95 | #### Alignment
96 | The opening brace must be on the same line as the last selector and preceded by a space. The closing brace must be on its own line after the last property and be indented to the same level as the opening brace.
97 |
98 | ```css
99 | /* Good */
100 | .example {
101 | color: #fff;
102 | }
103 |
104 | /* Bad - closing brace is in the wrong place */
105 | .example {
106 | color: #fff;
107 | }
108 |
109 | /* Bad - opening brace missing space */
110 | .example{
111 | color: #fff;
112 | }
113 | ```
114 |
115 | #### Property Format
116 | Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon.
117 |
118 | ```css
119 | /* Good */
120 | .example {
121 | background: black;
122 | color: #fff;
123 | }
124 |
125 | /* Bad - missing spaces after colons */
126 | .example {
127 | background:black;
128 | color:#fff;
129 | }
130 |
131 | /* Bad - missing last semicolon */
132 | .example {
133 | background: black;
134 | color: #fff
135 | }
136 | ```
137 |
138 | #### HEX values
139 | HEX values must be declared in lowercase and shorthand:
140 |
141 | ```css
142 | /* Good */
143 | .example {
144 | color: #eee;
145 | }
146 |
147 | /* Bad */
148 | .example {
149 | color: #EEEEEE;
150 | }
151 | ```
152 |
153 | #### Attribute selectors
154 | Always use double quotes around attribute selectors.
155 |
156 | ```css
157 | /* Good */
158 | input[type="button"] {
159 | ...
160 | }
161 |
162 | /* Bad - missing quotes */
163 | input[type=button] {
164 | ...
165 | }
166 |
167 | /* Bad - using single quote */
168 | input[type='button'] {
169 | ...
170 | }
171 | ```
172 |
173 | #### Zero value units
174 | Zero values should not carry units.
175 |
176 | ```css
177 | /* Good */
178 | .example {
179 | padding: 0;
180 | }
181 |
182 | /* Bad - uses units */
183 | .example {
184 | padding: 0px;
185 | }
186 | ```
187 |
--------------------------------------------------------------------------------
/manual/docblocks.md:
--------------------------------------------------------------------------------
1 | Documentation headers for PHP code in: files, classes, class properties, methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC.
2 |
3 | These "DocBlocks" borrow from the PEAR standard but have some variations specific for Joomla and the Joomla projects.
4 |
5 | Whereas normal code indenting uses real tabs, all whitespace in a Docblock uses real spaces. This provides better readability in source code browsers. The minimum whitespace between any text elements, such as tags, variable types, variable names and tag descriptions, is two real spaces. Variable types and tag descriptions should be aligned according to the longest Docblock tag and type-plus-variable respectively.
6 |
7 | Code contributed to the Joomla project that will become the copyright of the project is not allowed to include @author tags. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person "owning" any section of code. The @author tags are permitted in third-party libraries that are included in the core libraries.
8 |
9 | Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.
10 |
11 | ### File DocBlock Headers
12 | The file header DocBlock consists of the following required and optional elements in the following order:
13 | Short description (optional unless the file contains more than two classes or functions), followed by a blank line). Long description (optional, followed by a blank line).
14 |
15 | * @version (optional and must be first)
16 | * @category (optional and rarely used)
17 | * @package (generally optional but required when files contain only procedural code. Always optional in namespaced code)
18 | * @subpackage (optional)
19 | * @author (optional but only permitted in non-Joomla source files)
20 | * @copyright (required)
21 | * @license (required and must be compatible with the Joomla license)
22 | * @link (optional)
23 | * @see (optional)
24 | * @since (generally optional but required when files contain only procedural code)
25 | * @deprecated (optional)
26 |
27 | Example of a DocBlock Header:
28 |
29 | ```php
30 | /**
31 | * @package Joomla.Installation
32 | * @subpackage Controller
33 | *
34 | * @copyright Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.
35 | * @license GNU General Public License version 2 or later; see LICENSE.txt
36 | */
37 | ```
38 |
39 | ### Class Definitions
40 | Class definitions start on a new line and the opening and closing braces are also placed on new lines. Class methods must follow the guidelines for Function Definitions. Properties and methods must follow OOP standards and be declared appropriately (using public, protected, private and static as applicable). Class definitions, properties and methods must each be provided with a DocBlock in accordance with the following sections.
41 |
42 | #### Class DocBlock Headers
43 | The class Docblock consists of the following required and optional elements in the following order.
44 | Short description (required, unless the file contains more than two classes or functions), followed by a blank line). Long description (optional, followed by a blank line).
45 |
46 | * @category (optional and rarely used)
47 | * @package (optional)
48 | * @subpackage (optional)
49 | * @author (optional but only permitted in non-Joomla source files)
50 | * @copyright (optional unless different from the file Docblock)
51 | * @license (optional unless different from the file Docblock)
52 | * @link (optional)
53 | * @see (optional)
54 | * @since (required, being the version of the software the class was introduced)
55 | * @deprecated (optional)
56 |
57 | Example of a Class file DocBlock header:
58 | ```php
59 | /**
60 | * Controller class to initialise the database for the Joomla Installer.
61 | *
62 | * @package Joomla.Installation
63 | * @subpackage Controller
64 | * @since 3.1
65 | */
66 | ```
67 |
68 | #### Class Property DocBlocks
69 | The class property Docblock consists of the following required and optional elements in the following order.
70 | Short description (required, followed by a blank line)
71 |
72 | * @var (required, followed by the property type)
73 | * @since (required)
74 | * @deprecated (optional)
75 |
76 | Example of Class property DocBlock:
77 |
78 | ```php
79 | /**
80 | * The generated user ID
81 | *
82 | * @var integer
83 | * @since 3.1
84 | */
85 | protected static $userId = 0;
86 | ```
87 |
88 | #### Class Method DocBlocks and Functions DocBlocks
89 | Function definitions start on a new line and the opening and closing braces are also placed on new lines. An empty line should precede lines specifying the return value.
90 |
91 | Function definitions must include a documentation comment in accordance with the Commenting section of this document.
92 |
93 | * Short description (required, followed by a blank line)
94 | * Long description (optional, followed by a blank line)
95 | * @param (required if there are method or function arguments, the last @param tag is followed by a blank line)
96 | * @return (required, followed by a blank line)
97 | * @since (required, followed by a blank line if there are additional tags)
98 | * @throws (required if method or function arguments throws a specific type of exception)
99 | * All other tags in alphabetical order.
100 |
101 | **Note:**
102 | Commonly a line after the tag @param consists of the following three parts in order of appearance:
103 | * variable type (There must be 3 spaces before variable type.)
104 | * variable name (There must be 2 spaces after the longest type.)
105 | * variable description (There must be 2 spaces after the longest variable name.)
106 |
107 | If there are more than one @param the type, names and description have to be aligned.
108 |
109 | Example of Method DocBlock:
110 | ```php
111 | /**
112 | * Set a controller class suffix for a given HTTP method.
113 | *
114 | * @param string $method The HTTP method for which to set the class suffix.
115 | * @param string $suffix The class suffix to use when fetching the controller name for a given request.
116 | *
117 | * @return JApplicationWebRouter This object for method chaining.
118 | *
119 | * @since 12.2
120 | *
121 | * @throws InvalidArgumentException Thrown if the provided arguments is not of type string.
122 | * @throws \UnexpectedValueException May be thrown if the container has not been set.
123 | */
124 | public function setHttpMethodSuffix($method, $suffix)
125 | ```
126 |
127 | If a function definition goes over multiple lines, all lines must be indented with one tab and the closing bracket must go on the same line as the last parameter.
128 |
129 | ```php
130 | function fooBar($param1, $param2,
131 | $param3, $param4)
132 | {
133 | // Body of method.
134 | }
135 | ```
136 |
--------------------------------------------------------------------------------
/manual/html.md:
--------------------------------------------------------------------------------
1 | These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, and include items from:
2 |
3 | 1. [Google's HTML styleguide](https://google.github.io/styleguide/htmlcssguide.html)
4 | 2. [jQuery's HTML Styleguide](http://contribute.jquery.org/style-guide/html/)
5 | 3. [Nicolas Ghallager's "Principles of writing consistent, idiomatic HTML"](https://github.com/necolas/idiomatic-html)
6 | 4. [Harry Robert's "My HTML/CSS coding style"](http://csswizardry.com/2012/04/my-html-css-coding-style/)
7 | 4. [The BBC's Media Standards and Guidelines](http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml)
8 |
9 | ### Doctype
10 |
11 | Always use the minimal, versionless doctype.
12 |
13 | ```html
14 |
15 | ```
16 |
17 | ### Language
18 |
19 | Always define which language the page is written in.
20 |
21 | ```html
22 |
23 | ```
24 |
25 | ### Encoding
26 |
27 | Always define the character encoding. The encoding should be defined as early as possible. Make sure your editor uses UTF-8 as character encoding, without a byte order mark (UTF-8, no BOM). Do not specify the encoding of style sheets as these assume UTF-8.
28 |
29 | ```html
30 |
31 | ```
32 |
33 | More on encodings and when and how to specify them can be found in [Handling character encodings in HTML and CSS](http://www.w3.org/International/tutorials/tutorial-char-enc/)
34 |
35 | ### Capitalisation
36 | All HTML should be lowercase; element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings). Additionally, there is no need to use CDATA to escape inline JavaScript, formerly a requirement to meet XML strictness in XHTML.
37 |
38 | ```html
39 |
40 | 
41 |
42 |
43 | Home
44 | ```
45 |
46 | ```html
47 |
48 | a {
49 | color: #a3a3a3;
50 | }
51 |
52 |
53 | a {
54 | color: #A3A3A3;
55 | }
56 | ```
57 |
58 | ### Protocol
59 |
60 | Omit the protocol portion (http:, https:) from URLs pointing to images and other media files, style sheets, and scripts unless they are not available over both protocols.
61 |
62 | This prevents mixed content issues and results in minor file size savings.
63 |
64 | ```html
65 |
66 |
67 |
68 |
69 |
70 | ```
71 |
72 | ### Elements and Attributes
73 |
74 | Always include ``, ``, and `` tags.
75 |
76 | ### Type attributes
77 |
78 | Do not use type or attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
79 |
80 | ```html
81 |
82 |
83 |
84 |
85 |
86 | ```
87 |
88 | ### Language attributes
89 |
90 | Do not use language attributes on script tags.
91 | ```html
92 |
93 |
106 |
107 |
108 |
109 | ```
110 |
111 | Use attribute/value pairs for boolean attributes
112 |
113 | ```html
114 |
115 |
116 |
117 |
118 |
119 | ```
120 |
121 | HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.
122 |
123 | 1. class
124 | 2. id
125 | 3. data-*
126 | 4. Everything else
127 |
128 | ```html
129 |
130 | Text
131 |
132 |
133 | Text
134 | ```
135 |
136 | Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs:
137 |
138 | ```html
139 |
143 | Text
144 |
145 | ```
146 |
147 | ### Elements
148 |
149 | Optional closing tags may not be omitted.
150 |
151 | ```html
152 |
153 | The quick brown fox jumps over the lazy dog.
154 |
155 |
156 | The quick brown fox jumps over the lazy dog.
157 | ```
158 |
159 | Self-closing (void) elements should not be closed. Trailing forward slashes and spaces should be omitted.
160 |
161 | ```html
162 |
163 | 
164 |
165 |
166 |
167 | ```
168 |
169 | ### Formatting
170 |
171 | Use a new line for every block, list, or table element, and indent every such child element.
172 |
173 | ```html
174 |
175 |
176 |
177 | - Home
178 | - Blog
179 |
180 |
181 |
182 |
183 |
184 | - Home
185 | - Blog
186 |
187 | ```
188 |
189 | We prefer readability over file-size savings when it comes to maintaining existing files. Plenty of whitespace is encouraged. Use whitespace to visually separate groups of related markup and to improve the readability and maintainability of your HTML. Use two empty lines between larger blocks, and use a single empty line between child blocks of larger blocks. Be consistent. (If you are worried about your document's size, spaces (as well as repeated use of the same strings - for instance class names) are excellent candidates for compression. Also, you may use a markup minifier to decrease your document's file size.)
190 |
191 | Keep line-length to a sensible maximum, e.g., 80 columns.
192 |
193 | Tip: configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.
194 |
195 | ```html
196 |
197 | Space, the final frontier.
198 |
199 |
200 |
201 |
202 | - Moe
203 | - Larry
204 | - Curly
205 |
206 |
207 |
208 |
209 |
210 |
211 | Income
212 | Taxes
213 |
214 |
215 |
216 | $ 5.00
217 | $ 4.50
218 |
219 |
220 |
221 | ```
222 |
223 | ### Indentation
224 |
225 | Don't indent inside ``, ``, `
243 |
248 |
249 |
250 |
251 | Joomla! is awesome!
252 |
253 |
254 |
255 | ```
256 |
257 | ### Trailing Whitespace
258 |
259 | Remove trailing white spaces. Trailing white spaces are unnecessary and can complicate diffs.
260 |
261 | ```html
262 |
263 |
Yes please.
264 |
265 |
266 | No, thank you.
267 | ```
268 |
269 | ### Entity References
270 |
271 | Do not use entity references. There is no need to use entity references like —, ”, or ☺, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
272 |
273 | The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).
274 |
275 | ```html
276 |
277 | The currency symbol for the Euro is “€”.
278 |
279 |
280 | The currency symbol for the Euro is “&eur;”.
281 | ```
282 |
283 | ### Inline CSS
284 |
285 | Inline CSS must be avoided. When altering states using JavaScript, use CSS to define your states, and only use unobtrusive JavaScript to alter class names whenever possible.
286 |
287 | ```html
288 |
289 | Home
290 |
291 |
292 | Home
293 | ```
294 |
295 | @todo more meaningful example.
296 |
297 | ### Style Attributes
298 |
299 | You should not use border, align, valign, or clear attributes. Avoid use of style attributes, except where using syndicated content or internal syndicating systems.
300 |
301 | ### Semantics
302 |
303 | Use HTML according to its purpose. For example, use heading elements for headings, `` elements for paragraphs, `` elements for anchors, etc.
304 |
305 | Using HTML according to its purpose is important for accessibility, reuse, and code efficiency reasons.
306 |
307 | ```html
308 |
309 | View subscriptions
310 |
311 |
312 |
View subscriptions
313 | ```
314 |
315 | ### Markup
316 |
317 | #### Image Tags
318 |
319 | Image elements (`![]()
`) must have an alt attribute. Height and width attributes are optional and may be omitted.
320 |
321 | @todo add examples from here http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml
322 |
323 | ### Comments
324 |
325 | @todo: comment styles in JS, CSS, HTML
326 |
327 | For more complex blocks of HTML, it may be useful to add a comment to the closing tag:
328 |
329 | ```html
330 |
331 |
332 |
333 |
334 |
335 |
336 | ```
337 |
338 | ### Mark todos
339 | Highlight todos by using the keyword TODO, eg:
340 |
341 | ```html
342 |
343 |
344 | - Home
345 | - Blog
346 |
347 | ```
348 |
349 | ### Adding line breaks
350 |
351 | Always use `
` instead of `
` and `
` eg:
352 |
353 | ```html
354 | This text contains
a line break.
355 | ```
356 |
357 | ### Markup validation tools
358 |
359 | @todo: list various testing tools:
360 |
361 | * http://validator.w3.org/nu/
362 | * http://csslint.net/
363 |
--------------------------------------------------------------------------------
/manual/ini.md:
--------------------------------------------------------------------------------
1 | .ini Language Files Format
2 |
3 | An .ini file is composed of strings and comments. See [Specification of language files](https://docs.joomla.org/Specification_of_language_files).
4 |
5 | ### Formatting
6 |
7 | #### Comments
8 | There are 2 types of comments:
9 | - Comments used as sections, to clarify the use of a group of strings.
10 | - Comments used to inform translators of some characteristics of the string(s) just below. These should not be preceded by a blank line.
11 |
12 | #### Strings
13 | - All language strings are in British English (en-GB). See [Joomla! en-GB User Interface Text Guidelines](https://developer.joomla.org/en-gb-user-interface-text-guidelines/introduction.html)
14 | - The lines commented should start with a semi-colon.
15 | - The strings should be alphabetically ordered using the "Standard Alphabetical Order" and not the "ASCII order". This mostly means here that the underscore is sorted BEFORE the letters.
16 |
17 | Example:
18 | ```ini
19 | COM_ABCD_FORMAT_WHATEVER
20 | ```
21 | comes before
22 | ```ini
23 | COM_ABCD_FORMATTING_WHATEVER
24 | ```
25 |
26 | Some specific text editors only sort by "ASCII order" and should not be used.
27 |
28 | ### Plugins
29 | Some IDEs have specific plugins to sort the lines by "Standard Alphabetical Order".
30 |
31 | Examples:
32 | - Atom [Sort selected elements](https://github.com/BlueSilverCat/sort-selected-elements)
33 | - Eclipse [Sortit](https://github.com/channingwalton/eclipse-sortit/tree/master/com.teaminabox.eclipse.sortit)
34 | - NetBeans [Sort line tools](http://plugins.netbeans.org/plugin/45925/sort-line-tools)
35 | - PhpStorm [String Manipulation](https://plugins.jetbrains.com/plugin/2162-string-manipulation)
36 |
37 | It may be necessary to set the sorting to "Case Insensitive Sort" to obtain the correct results.
38 |
39 | ### Online tools
40 | There is also an online tool which lets order this way (among other goodies): https://wordcounter.net/alphabetize
41 |
42 | ### Notes
43 | When the file includes commented sections, the strings should be alphabetically ordered in each section.
44 | Warning: when the comments concern specific strings and sorting has modified the order, the comments should be moved to the right place.
--------------------------------------------------------------------------------
/manual/inline-comments.md:
--------------------------------------------------------------------------------
1 | This chapter covers inline code commenting in more detail. Inline comments are all comments not included in doc blocs. The goal of in line commenting is to explain code in context. Such explanation may take many different forms.
2 |
3 | Comments that are written in a readable and narrative style, especially when explaining a complex process, are encouraged. In general they should be placed close to the code explained rather than before the entire block of code.
4 |
5 | Comments should be as sentence like as possible, which is to say that they should be complete and readable, not in short hand.
6 |
7 | Comments are not a replacement for detailed doc blocks. Comments serve to explain the logic and structure of code itself rather than the use of code.
8 |
9 | ### Formatting of Comments
10 |
11 | Comment blocks that introduce large sections of code and are more than 2 lines long should use `/* */` (C) style and should use `*` on each line with the same space/tab rules as doc blocks. If you need a large introduction consider whether this block should be separated into a method to reduce complexity and therefore providing a full docblock.
12 |
13 | Comments should precede the code they refer to. As a corollary, comments should not be on the same line as the code to which they refer (which puts them after the code they reference). They should be on their own lines.
14 |
15 | Don’t use a blank line between comments and the code they refer to (no space underneath a comment block).
16 |
17 | Always have a single blank line before a comment or block of comments unless the comment (or block) is at the beginning of a code structure. ( You should not have a blank line after a '{' line )
18 |
19 | For example in the following case there is no new line before the first comment (because it follows a '{' line) but we do want a new line before the second comment:
20 |
21 | ```php
22 | while (!$done)
23 | {
24 | // We don't want an infinite loop here.
25 | $done = true;
26 | }
27 |
28 | // Now let's do something interesting.
29 | $result = somethingInteresting();
30 | ```
31 |
32 | Comments should align with the code they refer to, using the same indenting as the line that follows the comment.
33 |
34 | Comments should be indented with tabs (like code, not like doc blocks).
35 |
36 | ### Content of comments
37 |
38 | Comments should use en-GB
39 |
40 | Always have a space between // and the start of comment text.
41 |
42 | New lines should always start with an upper case letter unless:
43 | * The line is a continuation of a complete sentence.
44 | * The term is code and is case sensitive.
45 |
46 | Code that is included specifically to assure compatibility with other software (for example specific browsers or a specific version of the CMS or for backward compatibility reasons) should be clearly marked as such. If there is the intention to remove specific code at a future point, state that but do not use a deprecation tag or specify a release (this can be hard to predict).
47 |
48 | Check spelling and grammar on all comments (see below and [the en-GB guidelines](https://developer.joomla.org/en-gb-user-interface-text-guidelines.html)).
49 |
50 | Only end a line with a period if it is a full sentence.
51 |
52 | Rather than use docblock tags use See:, Link: and Note: for comments if appropriate.
53 |
54 | Do not use HTML in comments unless specifically related to the comment content.
55 |
56 | Do not leave commented code unless there is a clearly explained reason for doing so. In such a case, a comment saying "Code intentionally commented" will prevent accidental removal.
57 |
58 | Comments may include forward looking statements of how something will be extended or modified in the future, but not todos indicating that code is not complete or ready to use.
59 |
60 | Remember that humor and sarcasm are difficult to translate.
61 |
62 | ### Acronyms
63 |
64 | Capitalise all letters of acronyms such as HTML, XML, SQL, GMT, and UTC.
65 |
66 | ### Common spelling and grammar errors for which to check.
67 |
68 | Joomla contributors include many non-native speakers of en-GB which makes it understandable that there are sometimes spelling and grammar errors. At the same time, some people reading comments also are non native speakers and may even use automated translation to understand comments. This makes it very important that comments should follow proper en-GB spelling and grammar rules. Unfortunately, these can be tricky.
69 |
70 | #### S vs Z
71 |
72 | en-GB most commonly uses `ise` where en-US would use `ize`, such as `normalise` instead of `normalize`. (Note that there are some exceptions to this rule.)
73 |
74 | Use of apostrophes is one of the trickier parts of English.
75 |
76 | #### Lets versus let’s
77 |
78 | Lets means permits or allows to:
79 |
80 | ```php
81 | // This lets the user enter data
82 | ```
83 |
84 | Let’s is a contraction for let us and means we are going to do this now:
85 |
86 | ```php
87 | // Let's validate the field
88 | ```
89 |
90 | #### Its versus it’s
91 |
92 | Its is the possessive form of it:
93 |
94 | ```php
95 | // Get its ID
96 | ```
97 |
98 | It’s is a contraction of it is
99 |
100 | ```php
101 | // It's time to save
102 | ```
103 |
104 | #### The correct Joomla spelling of some commonly used words.
105 |
106 | - dependant
107 | - deprecated
108 |
--------------------------------------------------------------------------------
/manual/introduction.md:
--------------------------------------------------------------------------------
1 | Good coding standards are important in any software development project. These standards are even more important when a large, diverse and worldwide community of developers are contributing to a project. One of the things that sets good software apart from great software is not only the features or the actual function the software performs, but the quality of its source code.
2 |
3 | In order to perform in the highly competitive Open Source and proprietary software industries, source code not only needs to be beautifully designed, it also needs to be beautiful and elegant to look at. The Joomla Coding Standards Manual is to help ensure our code is the highest quality which will make it easy to read, debug, and maintain.
4 |
5 | ### Guiding Principles
6 |
7 | Since readable code is more maintainable, the compass that guides us in achieving that goal is a set of well thought out coding standards for the different software languages that are employed in the Joomla software project. Joomla has a solid heritage of striving to support a great looking product with great looking code.
8 |
9 | This manual compiles the collective wisdom of past and present contributors to the project to form the definitive standard for coding in Joomla, whether that is for the core Joomla Framework or an extension that forms part of the stack of the Joomla CMS. This manual also serves as a lighthouse to the Joomla developer community, to safely guide developers around the pitfalls of becoming lackadaisical with respect to writing clean, beautiful code.
10 |
11 | The Joomla Coding Standards borrows heavily from the PEAR coding standard for PHP files, augmenting and diverging where it is deemed sensible to do so.
12 |
13 | There are [tools available](/coding-standards/analysis.html) to help your code conform to our standards.
14 |
15 | ### Contributing to this manual
16 |
17 | If you want to contribute and improve this manual, you can find the source files at [https://github.com/joomla/coding-standards/tree/master/manual](https://github.com/joomla/coding-standards/tree/master/manual).
18 |
--------------------------------------------------------------------------------
/manual/javascript-j3.md:
--------------------------------------------------------------------------------
1 | ### Contents
2 |
3 | 1. [Naming Conventions](#naming-conventions)
4 | - [Variables](#naming-conventions-variables)
5 | - [Functions](#naming-conventions-functions)
6 | - [Reserved Words](#naming-conventions-reserved)
7 | 2. [Syntax Style](#syntax-style)
8 | - [Indentation](#syntax-indentation)
9 | - [Spacing](#syntax-spacing)
10 | - [Commas](#syntax-commas)
11 | - [Semicolons](#syntax-semicolons)
12 | - [Quotes](#syntax-quotes)
13 | 3. [Types](#types)
14 | 4. [Functions](#functions)
15 | 5. [Conditional Statements](#conditional-statements)
16 | 6. [Blocks & Multi-line Statements](#blocks)
17 | 7. [Comments](#comments)
18 |
19 |
20 | ### Naming Conventions
21 |
22 | Use descriptive words or terse phrases for names.
23 |
24 | Variables and Functions should be camel case, starting with a lowercase letter: `likeThis`
25 |
26 |
27 | #### Variables
28 |
29 | **Use names that describe what the variable is:**
30 |
31 | `var element = document.getElementById('elementId');`
32 |
33 | **Iterators are the exception**
34 |
35 | Use i for index in a loop (and subsequent letters when necessary for nested iteration).
36 |
37 |
38 | #### Functions
39 |
40 | **Use names that describe what the function does:**
41 |
42 | ```js
43 | function getSomeData() {
44 | // statements
45 | }
46 | ```
47 |
48 |
49 | #### Reserved Words
50 |
51 | Do not use reserved words for anything other than their intended use. The list of: [Reserved Words](http://es5.github.io/#x7.6.1)
52 |
53 | ---
54 |
55 |
56 | ### Syntax Style
57 |
58 |
59 | #### Indentation
60 | - Don't mix tabs and spaces.
61 | - Tabs, 4 spaces
62 |
63 |
64 | #### Spacing
65 | - No whitespace at the end of line or on blank lines.
66 | - Unary special-character operators (e.g., !, ++) must not have space next to their operand.
67 | - Any , and ; must not have preceding space.
68 | - Any ; used as a statement terminator must be at the end of the line.
69 | - Any : after a property name in an object definition must not have preceding space.
70 | - The ? and : in a ternary conditional must have space on both sides.
71 | - No filler spaces in empty constructs (e.g., {}, [], fn())
72 | - New line at the end of each file.
73 |
74 | **Array:**
75 |
76 | ```js
77 | var array = [ 'foo', 'bar' ];
78 | ```
79 |
80 | **Function call:**
81 |
82 | ```js
83 | foo( arg );
84 | ```
85 |
86 | **Function call with multiple arguments:**
87 |
88 | ```js
89 | foo( 'string', object );
90 | ```
91 |
92 | **Conditional Statements**
93 |
94 | ```js
95 | if ( condition ) {
96 | // statements
97 | } else {
98 | // statements
99 | }
100 | ```
101 |
102 | ```js
103 | while ( condition ) {
104 | // statements
105 | }
106 | ```
107 |
108 | ```js
109 | for ( prop in object ) {
110 | // statements
111 | }
112 | ```
113 |
114 |
115 | ##### Exceptions
116 |
117 | **First or only argument is an object, array or callback function.**
118 |
119 | **No space before the first argument:**
120 |
121 | ```js
122 | foo({
123 | a: 'bar',
124 | b: 'baz'
125 | });
126 | ```
127 |
128 | ```js
129 | foo(function() {
130 | // statements
131 | }, options ); // space after options argument
132 | ```
133 |
134 | **Function with a callback, object, or array as the last argument:**
135 |
136 | No space after the last argument.
137 |
138 | ```js
139 | foo( data, function() {
140 | // statements
141 | });
142 | ```
143 |
144 |
145 | #### Commas
146 |
147 | **Place commas after:**
148 |
149 | - variable declarations
150 | - key/value pairs
151 |
152 | #### Arrays
153 |
154 | Do not include a trailing comma, this will add 1 to your array's length.
155 |
156 | **No:**
157 |
158 | ```js
159 | array = [ 'foo', 'bar', ];
160 | ```
161 |
162 | **Yes:**
163 |
164 | ```js
165 | array = [ 'foo', 'bar' ];
166 | ```
167 |
168 |
169 | #### Semicolons
170 |
171 | Use them where expected.
172 |
173 | Semicolons should be included at the end of function expressions, but not at the end of function declarations.
174 |
175 | **Function Expression:**
176 |
177 | ```js
178 | var foo = function() {
179 | return true;
180 | };
181 | ```
182 |
183 | **Function Declaration:**
184 |
185 | ```js
186 | function foo() {
187 | return true;
188 | }
189 | ```
190 |
191 |
192 | #### Quotes
193 |
194 | Use ' instead of "
195 |
196 |
197 | ---
198 |
199 |
200 | ### Variables
201 |
202 | ### Avoid Global Variables
203 |
204 | **No:**
205 |
206 | ```js
207 | foo = 'bar';
208 | ```
209 |
210 | **No: implied global**
211 |
212 | ```js
213 | function() {
214 | foo = 'bar';
215 | }
216 | ```
217 |
218 | **Yes:**
219 |
220 | ```js
221 | var foo = 'bar';
222 | ```
223 |
224 | #### Multiple Variable Declarations
225 |
226 | Use one `var` declaration and separate each variable on a newline ending with a comma.
227 |
228 | **No:**
229 |
230 | ```js
231 | var foo = 'bar';
232 | var bar = 'baz';
233 | var baz = 'qux';
234 | ```
235 |
236 | **Yes:**
237 |
238 | ```js
239 | var foo = 'bar',
240 | bar = 'baz',
241 | baz = 'qux';
242 | ```
243 |
244 |
245 | ---
246 |
247 |
248 | ### Types
249 |
250 | #### String
251 |
252 | - Concatenate long strings.
253 | - Place space before closing quote at the end of each string.
254 | - Concatenation operator at the end of each subsequent string.
255 |
256 | ```js
257 | var longString = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ' +
258 | 'Sed placerat, tellus eget egestas tincidunt, lectus dui ' +
259 | 'sagittis massa, id mollis est tortor a enim. In hac ' +
260 | 'habitasse platea dictumst. Duis erat justo, tincidunt ac ' +
261 | 'enim iaculis, malesuada condimentum mauris. Vestibulum vel ' +
262 | 'cursus mauris.';
263 | ```
264 |
265 | #### Number
266 |
267 | Use `parseInt()` or `parseFloat()` instead of unary plus, for readability.
268 |
269 | **No:**
270 |
271 | ```js
272 | var count = +document.getElementById('inputId').value;
273 | ```
274 |
275 | **Yes:**
276 |
277 | ```js
278 | var count = parseInt(document.getElementById('inputId').value);
279 | ```
280 |
281 | #### Type Checks
282 |
283 | - String: `typeof object === 'string'`
284 | - Number: `typeof object === 'number'`
285 | - Boolean: `typeof object === 'boolean'`
286 | - Object: `typeof object === 'object'`
287 | - Plain Object: `jQuery.isPlainObject( object )`
288 | - Function: `jQuery.isFunction( object )`
289 | - Array: `jQuery.isArray( object )`
290 | - Element: `object.nodeType`
291 | - null: `object === null`
292 | - null or undefined: `object == null`
293 |
294 | **Undefined:**
295 |
296 | - Global Variables: `typeof variable === 'undefined'`
297 | - Local Variables: `variable === undefined`
298 | - Properties: `object.prop === undefined`
299 |
300 | #### Objects
301 |
302 | Use the literal, not constructor, syntax.
303 |
304 | **No:**
305 |
306 | ```js
307 | var myObj = new Object();
308 | ```
309 |
310 | **Yes:**
311 |
312 | ```js
313 | var myObj = {};
314 | ```
315 |
316 | If an object contains more than one key/value pair or an array as a value, each key/value pair should be on its own line.
317 |
318 | ```js
319 | var myObj = {
320 | foo: 'bar',
321 | bar: 'baz',
322 | baz: 'qux'
323 | };
324 | ```
325 |
326 | #### Arrays
327 |
328 | Use the literal, not constructor, syntax
329 |
330 | **No:**
331 |
332 | ```js
333 | var myArr = new Array();
334 | ```
335 |
336 | **Yes:**
337 |
338 | ```js
339 | var myArr = [];
340 | ```
341 |
342 | If you don't know array length use push method. This will replace the current array.
343 |
344 | ```js
345 | var myArr = [];
346 | myArr.push('foo');
347 | ```
348 |
349 |
350 | ---
351 |
352 |
353 | ### Functions
354 |
355 | #### Chaining Method Calls
356 |
357 | ```js
358 | $('.someElement')
359 | .hide()
360 | .delay(1000)
361 | .fadeIn();
362 | ```
363 |
364 |
365 | ---
366 |
367 |
368 | ### Conditional Statements
369 |
370 | Use ternary syntax if:
371 |
372 | - One condition
373 | - Result of either evaluation is one operation.
374 |
375 | ```js
376 | joomlaRocks ? 'This is true' : 'else it is false';
377 | ```
378 |
379 | Otherwise, use standard syntax:
380 |
381 | ```js
382 | if ( condition ) {
383 | // statements
384 | } else {
385 | // statements
386 | }
387 | ```
388 |
389 | **Cache length in variable for performance:**
390 |
391 | ```js
392 | var i,
393 | j = myArr.length;
394 |
395 | for ( i = 0; i < j; i++ ) {
396 | // statements
397 | }
398 | ```
399 |
400 | **With more than one condition:**
401 |
402 | ```js
403 | if ( condition &&
404 | condition2 &&
405 | condition3 ) {
406 | // statements
407 | } else {
408 | // statements
409 | }
410 | ```
411 |
412 | #### Equality
413 |
414 | Use strict equality operator === so that type is considered in comparison. Using == can produce false positives.
415 |
416 |
417 | ```js
418 | // evaluates true
419 | 1 == "1"
420 | ```
421 |
422 | ```js
423 | // evaluates false
424 | 1 === "1"
425 | ```
426 |
427 |
428 | ---
429 |
430 |
431 | ### Blocks & Multi-line Statements
432 |
433 | Use curly braces on blocks that have more than one statement.
434 |
435 | **Block with one statement:**
436 |
437 | ```js
438 | if ( test ) return false;
439 | ```
440 |
441 | **Block with more than one statement:**
442 |
443 | ```js
444 | if ( test ) {
445 | var foo = 'some string';
446 | return foo;
447 | }
448 | ```
449 |
450 |
451 | ---
452 |
453 |
454 | ### Comments
455 |
456 | **Single Line**
457 |
458 | - Place above the code it refers to.
459 | - A space between double forward slashes and comment text.
460 |
461 | ```js
462 | // I am a single line comment.
463 | ```
464 |
465 |
466 | **Multiline**
467 |
468 | - Place above the code it refers to.
469 | - Opening token placed on the line above first comment line, closing placed below last comment line.
470 | - Each comment line begins with two astericks followed by a space.
471 |
472 | ```js
473 | /*
474 | ** I am a multiline comment.
475 | ** Line two
476 | ** Line three
477 | */
478 | ```
479 |
480 | ---
481 |
482 | ### TODO
483 |
484 | - Switch Statements vs other methods like Objects
485 | - Add jQuery examples
486 | - Double check accuracy of all examples
487 |
488 | **With help from:**
489 |
490 | - [jQuery JS Style Guide](https://contribute.jquery.org/style-guide/js)
491 | - [Idiomatic JS](https://github.com/rwaldron/idiomatic.js)
492 |
--------------------------------------------------------------------------------
/manual/javascript-j4.md:
--------------------------------------------------------------------------------
1 | ### Javascript in Joomla 4
2 |
3 | Joomla 4 uses ES6 syntax where possible. As part of this change we decided to use an industry standard codestyle rules for our JavaScript - the AirBNB coding standards. These can be found [on their GitHub page](https://github.com/airbnb/javascript#table-of-contents).
4 |
5 | We have four modifications to the defaults:
6 |
7 | 1. We allow parameter reassignment of function parameters to allow easier setting of defaults (for examples please see the ESLint rules [here](https://eslint.org/docs/rules/no-param-reassign))
8 |
9 | 2. We only allow the imports of dependencies from NPM in our build directory (`build/`) (rather than in all files)
10 |
11 | 3. We currently allow browser alerts using the `alert()` function (the long term intention is to disable this as we move to our custom element alerts)
12 |
13 | 4. We always enable JavaScript strict mode as we aren't using JavaScript modules at this time
14 |
15 | We also use ESLint to enforce these rules. If you are familiar with JavaScript from other projects you've worked on you can find our ESLint rules [on GitHub](https://github.com/joomla/joomla-cms/blob/4.0-dev/.eslintrc)
16 |
--------------------------------------------------------------------------------
/manual/license.md:
--------------------------------------------------------------------------------
1 | The contents of the Joomla! en-GB User Interface Text Guidelines are subject to copyright law and are made available under the [Joomla! Electronic Documentation License (JEDL)](https://docs.joomla.org/JEDL) unless otherwise stated.
2 |
3 | You may find the [JEDL Frequently Asked Questions](https://docs.joomla.org/JEDL/FAQ) useful in determining if your proposed use of this material is allowed.
4 |
5 | If you have any questions regarding licensing of this material please contact legal@opensourcematters.org.
6 |
7 | If you wish to report a possible violation of the license terms for the material on this site then please contact legal@opensourcematters.org.
8 |
--------------------------------------------------------------------------------
/manual/php.md:
--------------------------------------------------------------------------------
1 | > **Note**
2 | >
3 | > The Joomla! CMS switched in Version 4.2.0 from its own coding standard to the PSR-12 (and later to PER Coding Style) coding standard.
4 | > This document applies to Joomla! < 4.2.0 and parts of it still applies to 4.2.0 and later.
5 | >
6 | > This document will be updated to reflect the PSR-12 coding standard soon.
7 |
8 | ### Language Constructs
9 |
10 | #### PHP Code Tags
11 |
12 | Always use the full `` to delimit PHP code, not the `` shorthand. This is the most portable way to include PHP code on differing operating systems and setups.
13 |
14 | For files that contain only PHP code, the closing tag (`?>`) should not be included. It is not required by PHP. Leaving this out prevents trailing white space from being accidentally injected into the output that can introduce errors in the Joomla session (see the PHP manual on [Instruction separation](https://secure.php.net/basic-syntax.instruction-separation)).
15 |
16 | Files should always end with a blank new line.
17 |
18 | #### General
19 |
20 | Pursuant to PSR-2 [Keywords and True/False/Null][]
21 |
22 | > PHP [keywords][] MUST be in lower case.
23 | > The PHP constants `true`, `false`, and `null` MUST be in lower case.
24 |
25 | [Keywords and True/False/Null]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md#25-keywords-and-truefalsenull
26 | [keywords]: https://secure.php.net/manual/en/reserved.keywords.php
27 |
28 | #### Including Code
29 |
30 | Anywhere you are unconditionally including a file, use `require_once`. Anywhere you are conditionally including a file (for example, factory methods), use `include_once`. Either of these will ensure that files are included only once. They share the same file list, so you don't need to worry about mixing them. A file included with `require_once` will not be included again by `include_once`.
31 |
32 | > **Note**
33 | >
34 | > `include_once` and `require_once` are PHP language statements, not functions. The correct formatting is:
35 | >
36 | >
37 | > `require_once JPATH_COMPONENT . '/helpers/helper.php';`
38 |
39 | You should not enclose the filename in parentheses.
40 |
41 | #### E_STRICT Compatible PHP Code
42 |
43 | As of Joomla version 1.6 and for all versions of the Joomla Platform, adhering to object oriented programming practice as supported by PHP 5.3+ is required. Joomla is committed to progressively making the source code E_STRICT.
44 |
45 | ### Global Variables
46 |
47 | Global variables should not be used. Use static class properties or constants instead of globals, following OOP and factory patterns.
48 |
49 | ### Error Surpression
50 |
51 | The use of the `@` for Error Surpression should be avoided and limited to use when no other approach or workaround is available.
52 |
53 | ### Control Structures (General Code)
54 |
55 | For all control structures there is a space between the keyword and an opening parenthesis, then no space either after the opening parenthesis or before the closing bracket. This is done to distinguish control keywords from function names. All control structures must contain their logic within braces.
56 |
57 | For all all control structures, such as `if`, `else`, `do`, `for`, `foreach`, `try`, `catch`, `switch` and `while`, both the keyword starts a newline and the opening and closing braces are each put on a new line.
58 |
59 | Exclamation mark `!`, the logical operator `not` used in a condition, should not have spaces before or after the exclamation mark as shown in the examples.
60 |
61 | #### An _if-else_ Example
62 |
63 | ```php
64 | if ($test)
65 | {
66 | echo 'True';
67 | }
68 |
69 | // Comments can go here.
70 | // Note that "elseif" as one word is used.
71 | elseif ($test === false)
72 | {
73 | echo 'Really false';
74 | }
75 | elseif (!$condition)
76 | {
77 | echo 'Not Condition';
78 | }
79 | else
80 | {
81 | echo 'A white lie';
82 | }
83 | ```
84 |
85 | If a control structure goes over multiple lines, all lines must be indented with one tab and the closing brace must go on the same line as the last parameter.
86 |
87 | ```php
88 | if ($test1
89 | && $test2)
90 | {
91 | echo 'True';
92 | }
93 | ```
94 |
95 | #### A _do-while_ Example
96 |
97 | ```php
98 | do
99 | {
100 | $i++;
101 | }
102 | while ($i < 10);
103 | ```
104 |
105 | #### A _for_ Example
106 |
107 | ```php
108 | for ($i = 0; $i < $n; $i++)
109 | {
110 | echo 'Increment = ' . $i;
111 | }
112 | ```
113 |
114 | #### A _foreach_ Example
115 |
116 | ```php
117 | foreach ($rows as $index => $row)
118 | {
119 | echo 'Index = ' . $index . ', Value = ' . $row;
120 | }
121 | ```
122 |
123 | #### A _while_ Example
124 |
125 | ```php
126 | while (!$done)
127 | {
128 | $done = true;
129 | }
130 | ```
131 |
132 | #### A _switch_ example
133 |
134 | When using a `switch` statement, the `case` keywords are indented. The `break` statement starts on a newline assuming the indent of the code within the case.
135 |
136 | ```php
137 | switch ($value)
138 | {
139 | case 'a':
140 | echo 'A';
141 | break;
142 |
143 | default:
144 | echo 'I give up';
145 | break;
146 | }
147 | ```
148 |
149 | #### A _try catch_ example
150 | ```php
151 | try
152 | {
153 | $table->bind($data);
154 | }
155 | catch (RuntimeException $e)
156 | {
157 | throw new Exception($e->getMessage(), 500, $e);
158 | }
159 | ```
160 |
161 | ### Mixed language usage (e.g. at the layout files)
162 |
163 | For layout files and all files where we use a mix of PHP and HTML (all PHP files in the `view/tmpl` and `layout` folder) we additionally wrap every line into a `` block and use the alternative syntax for control structures. This should make the code easier to read and make it easier to move blocks around without creating fatal errors due to missing `` tags.
164 |
165 | #### Example Control Structures
166 |
167 | ##### An _if-else_ Example
168 |
169 | ```php
170 |
171 |
172 |
173 |
174 |
175 |
176 |
177 | ```
178 |
179 | ### References
180 |
181 | When using references, there should be a space before the reference operator and no space between it and the function or variable name.
182 |
183 | For example:
184 |
185 | ```php
186 | $ref1 = &$this->sql;
187 | ```
188 |
189 | > **Note**
190 | >
191 | > In PHP 5, reference operators are not required for objects. All objects are handled by reference.
192 |
193 |
194 | ### Concatenation Spacing
195 | There should always be a space before and after the concatenation operator ('.'). For example:
196 |
197 | ```php
198 | $id = 1;
199 | echo JRoute::_('index.php?option=com_foo&task=foo.edit&id=' . (int) $id);
200 | ```
201 |
202 | If the concatenation operator is the first or last character on a line, both spaces are not required. For example:
203 |
204 | ```php
205 | $id = 1
206 | echo JRoute::_(
207 | 'index.php?option=com_foo&task=foo.edit&id=' . (int) $id
208 | . '&layout=special'
209 | );
210 | ```
211 |
212 | ### Arrays
213 |
214 | Assignments (the `=>` operator) in arrays may be aligned with spaces. When splitting array definitions onto several lines, the last value should also have a trailing comma. This is valid PHP syntax and helps to keep code diffs minimal. Joomla 3 prefers `array()` to be backward compatible to 5.3.10 and Joomla 4.0.0 onwards should use the short array syntax `[]` by default. (Short array syntax was introduced in PHP 5.4.)
215 |
216 | For example:
217 |
218 | ```php
219 | $options = [
220 | 'foo' => 'foo',
221 | 'spam' => 'spam',
222 | ];
223 |
224 | ```
225 |
226 | ### Code Commenting
227 |
228 | Inline comments to explain code follow the convention for C (`/* … */`) and C++ single line (`// ...`) comments. C-style blocks are generally restricted to documentation headers for files, classes and functions. The C++ style is generally used for making code notes. Code notes are strongly encouraged to help other people, including your future-self, follow the purpose of the code. Always provide notes where the code is performing particularly complex operations.
229 |
230 | Perl/shell style comments (`#`) are not permitted in PHP files.
231 |
232 | Blocks of code may, of course, be commented out for debugging purposes using any appropriate format, but should be removed before submitting patches for contribution back to the core code.
233 |
234 | For example, do not include feature submissions like:
235 |
236 | ```php
237 | // Must fix this code up one day.
238 | //$code = broken($fixme);
239 | ```
240 |
241 | More details on inline code comments can be found in the chapter on [Inline Code Comments](/coding-standards/inline-code-comments.html).
242 |
243 | #### Comment Docblocks
244 |
245 | Documentation headers for PHP and Javascript code in files, classes, class properties, methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC.
246 |
247 | These "DocBlocks" borrow from the PEAR standard but have some variations specific for Joomla and the Joomla Platform.
248 |
249 | More details on DocBlocks comments can be found in the chapter on [DocBlocks Comments](/coding-standards/docblocks.html).
250 |
251 | ### Function Calls
252 |
253 | Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis. There should be space before and exactly one space after the equals sign. Tab alignment over multiple lines is permitted.
254 |
255 | ```php
256 | // An isolated function call.
257 | $foo = bar($var1, $var2);
258 |
259 | // Multiple aligned function calls.
260 | $short = bar('short');
261 | $medium = bar('medium');
262 | $long = bar('long');
263 | ```
264 |
265 | ### Function Definitions
266 |
267 | Function definitions start on a new line with no spaces between the function name and the opening parenthesis. Additionally, the opening and closing braces are also placed on new lines. An empty line should precede lines specifying the return value.
268 |
269 | Function definitions must include a documentation comment in accordance with the Commenting section of this document. More details on DocBlocks Function comments can be found in the chapter on [DocBlocks Comments](/coding-standards/docblocks.html).
270 |
271 | ```php
272 | /**
273 | * A utility function.
274 | *
275 | * @param string $path The library path in dot notation.
276 | *
277 | * @return void
278 | *
279 | * @since 1.6
280 | */
281 | function jimport($path)
282 | {
283 | // Body of method.
284 | }
285 | ```
286 |
287 | If a function definition goes over multiple lines, all lines must be indented with one tab and the closing brace must go on the same line as the last parameter.
288 |
289 | ```php
290 | function fooBar($param1, $param2,
291 | $param3, $param4)
292 | {
293 | // Body of method.
294 | }
295 | ```
296 |
297 | ### Closures / Anonymous functions
298 | Closures/Anonymous functions should have a space between the Closure's/Anonymous function's name and the opening parenthesis. Method signatures don't have the space.
299 |
300 | ```php
301 | $fieldIds = array_map(
302 | function ($f)
303 | {
304 | return $f->id;
305 | },
306 | $fields
307 | );
308 | ```
309 |
310 | ### Class Definitions
311 |
312 | Class definitions start on a new line and the opening and closing braces are also placed on new lines. Class methods must follow the guidelines for Function Definitions. Properties and methods must follow OOP standards and be declared appropriately (using public, protected, private and static as applicable).
313 |
314 | Class definitions, properties and methods must each be provided with a DocBlock in accordance with the following sections.
315 |
316 | More details on DocBlocks Class comments can be found in the chapter on [DocBlocks Comments](/coding-standards/docblocks.html).
317 |
318 | #### Class Property DocBlocks
319 |
320 | More details on Class Property DocBlocks can be found in the chapter on [DocBlocks Comments](docblocks.md).
321 |
322 | #### Class Method DocBlocks
323 |
324 | The DocBlock for class methods follows the same convention as for PHP functions.
325 |
326 | More details on DocBlocks Class Method comments can be found in the chapter on [DocBlocks Comments](docblocks.md).
327 |
328 | ### Class Definition Example
329 | ```php
330 | /**
331 | * A utility class.
332 | *
333 | * @package Joomla.Platform
334 | * @subpackage XBase
335 | * @since 1.6
336 | */
337 | class JClass extends JObject
338 | {
339 | /**
340 | * Human readable name
341 | *
342 | * @var string
343 | * @since 1.6
344 | */
345 | public $name;
346 |
347 | /**
348 | * Method to get the name of the class.
349 | *
350 | * @param string $case Optionally return in upper/lower case.
351 | *
352 | * @return boolean True if successfully loaded, false otherwise.
353 | *
354 | * @since 1.6
355 | */
356 | public function getName($case = null)
357 | {
358 | // Body of method.
359 | return $this->name;
360 | }
361 | }
362 | ```
363 |
364 | ### Naming Conventions
365 |
366 | #### Classes
367 |
368 | Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla Platform classes which must begin with an uppercase 'J' with the next letter also being uppercase.
369 |
370 | For example:
371 |
372 | - JHtmlHelper
373 | - JXmlParser
374 | - JModel
375 |
376 | #### Functions and Methods
377 |
378 | Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'.
379 |
380 | For example:
381 |
382 | - connect();
383 | - getData();
384 | - buildSomeWidget();
385 | - jImport();
386 | - jDoSomething();
387 |
388 | Private class members (meaning class members that are intended to be used only from within the same class in which they are declared) are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase.
389 |
390 | For example:
391 |
392 | ```php
393 | class JFooHelper
394 | {
395 | protected $field_name = null;
396 |
397 | private $_status = null;
398 |
399 | protected function sort()
400 | {
401 | // Code goes here
402 | }
403 | }
404 | ```
405 |
406 | #### Namespaces
407 |
408 | Namespaces are formatted according to this flow. First there is the file docblock followed by the namespace the file lives in. When required, the namespace is followed by the `defined` check. Lastly, the imported classes using the `use` keyword. All namespace imports must be alphabetically ordered.
409 |
410 | ```php
411 | /**
412 | * @package Joomla.Administrator
413 | * @subpackage mod_quickicon
414 | *
415 | * @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
416 | * @license GNU General Public License version 2 or later; see LICENSE.txt
417 | */
418 |
419 | namespace Joomla\Module\Quickicon\Administrator\Helper;
420 |
421 | defined('_JEXEC') or die;
422 |
423 | use Joomla\CMS\Factory;
424 | use Joomla\CMS\Language\Text;
425 | use Joomla\CMS\Plugin\PluginHelper;
426 | use Joomla\CMS\Router\Route;
427 | use Joomla\Module\Quickicon\Administrator\Event\QuickIconsEvent;
428 | ```
429 |
430 | #### Constants
431 |
432 | Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the `JError` class all begin with `JERROR_`.
433 |
434 | #### Regular Variables and Class Properties
435 |
436 | Regular variables, follow the same conventions as function.
437 |
438 | Class variables should be set to null or some other appropriate default value.
439 |
440 | ### Exception Handling
441 |
442 | Exceptions should be used for error handling.
443 |
444 | The following sections outline how to semantically use [SPL exceptions](https://secure.php.net/manual/en/spl.exceptions.php).
445 |
446 | #### Logic Exceptions
447 |
448 | The LogicException is thrown when there is an explicit problem with the way the API is being used. For example, if a dependency has failed (you try to operate on an object that has not been loaded yet).
449 |
450 | The following child classes can also be used in appropriate situations:
451 |
452 | ##### BadFunctionCallException
453 |
454 | This exception can be thrown if a callback refers to an undefined function or if some arguments are missing. For example if `is_callable()`, or similar, fails on a function.
455 |
456 | ##### BadMethodCallException
457 |
458 | This exception can be thrown if a callback refers to an undefined method or if some arguments are missing. For example `is_callable()`, or similar, fails on a class method. Another example might be if arguments passed to a magic call method are missing.
459 |
460 | ##### InvalidArgumentException
461 |
462 | This exception can be thrown if there is invalid input.
463 |
464 | ##### DomainException
465 |
466 | This exception is similar to the InvalidArgumentException but can be thrown if a value does not adhere to a defined valid data domain. For example trying to load a database driver of type "mongodb" but that driver is not available in the API.
467 |
468 | ##### LengthException
469 |
470 | This exception can be thrown is a length check on an argument fails. For example a file signature was not a specific number of characters.
471 |
472 | ##### OutOfRangeException
473 |
474 | This exception has few practical applications but can be thrown when an illegal index was requested.
475 |
476 | #### Runtime Exceptions
477 |
478 | The RuntimeException is thrown when some sort of external entity or environment causes a problem that is beyond your control providing the input is valid. This exception is the default case for when the cause of an error can't explicitly be determined. For example you tried to connect to a database but the database was not available (server down, etc). Another example might be if an SQL query failed.
479 |
480 | ##### UnexpectedValueException
481 |
482 | This type of exception should be used when an unexpected result is encountered. For example a function call returned a string when a boolean was expected.
483 |
484 | ##### OutOfBoundsException
485 |
486 | This exception has few practical applications but may be thrown if a value is not a valid key.
487 |
488 | ##### OverflowException
489 |
490 | This exception has few practical applications but may be thrown when you add an element into a full container.
491 |
492 | ##### RangeException
493 |
494 | This exception has few practical applications but may be thrown to indicate range errors during program execution. Normally this means there was an arithmetic error other than under/overflow. This is the runtime version of DomainException.
495 |
496 | ##### UnderflowException
497 |
498 | This exception has few practical applications but may thrown when you try to remove an element of an empty container.
499 |
500 | #### Documenting exceptions
501 |
502 | Each function or method must annotate the type of exception that it throws using an @throws tag and any downstream exceptions types that are thrown. Each type of exception need only be annotated once. No description is necessary.
503 |
504 | ### SQL Queries
505 |
506 | SQL keywords are to be written in uppercase, while all other identifiers (with the exception of quoted text obviously) is to be in lowercase.
507 |
508 | All table names should use the `#__` prefix to access Joomla content and allow for the user defined database prefix to be applied. Queries should also use the JDatabaseQuery API. Tables should never have a static prefix such as `jos_`.
509 |
510 | To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.
511 |
512 | Use Query chaining to connect a number of query methods, one after the other, with each method returning an object that can support the next method, This improves readability and simplifies the resulting code. Since the Joomla Framework was introduced "query chaining" is now the recommended method for building database queries.
513 |
514 | Table names and table column names should always be enclosed in the `quoteName()` method to escape the table name and table columns.
515 | Field values checked in a query should always be enclosed in the `quote()` method to escape the value before passing it to the database. Integer field values checked in a query should also be type cast to `(int)`.
516 |
517 | ```php
518 | // Get the database connector.
519 | $db = JFactory::getDbo();
520 |
521 | // Get the query from the database connector.
522 | $query = $db->getQuery(true);
523 |
524 | // Build the query programatically (example with chaining)
525 | // Note: You can use the qn alias for the quoteName method.
526 | $query->select($db->qn('u.*'))
527 | ->from($db->qn('#__users', 'u'));
528 |
529 | // Tell the database connector what query to run.
530 | $db->setQuery($query);
531 |
532 | // Invoke the query or data retrieval helper.
533 | $users = $db->loadObjectList();
534 | ```
535 |
536 | #### Longer Chaining Example
537 | ```php
538 | // Using chaining when possible.
539 | $query->select($db->quoteName(array('user_id', 'profile_key', 'profile_value', 'ordering')))
540 | ->from($db->quoteName('#__user_profiles'))
541 | ->where($db->quoteName('profile_key') . ' LIKE '. $db->quote('\'custom.%\''))
542 | ->order('ordering ASC');
543 | ```
544 |
545 | #### Chaining With Select Array And Type Casting Of Integer Field Value Example
546 | ```php
547 | $query = $db->getQuery(true)
548 | ->select(array(
549 | $db->quoteName('profile_key'),
550 | $db->quoteName('profile_value'),
551 | ))
552 | ->from($db->quoteName('#__user_profiles'))
553 | ->where($db->quoteName('user_id') . ' = ' . (int) $userId)
554 | ->order($db->quoteName('ordering'));
555 | ```
556 |
--------------------------------------------------------------------------------
/manual/scss.md:
--------------------------------------------------------------------------------
1 | These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, namely:
2 |
3 | 1. [Code Guide](http://codeguide.co) (by @mdo)
4 |
5 | ### Commenting
6 |
7 | #### Major sections
8 | Major code sections should be named in caps and within a full comment block, eg:
9 |
10 | ```scss
11 | // Major comment
12 | //
13 | // Major comment description goes here
14 | // and continues here
15 | ```
16 |
17 | #### Sub sections
18 | Subsections should be normally cased and within an open comment block.
19 | ```scss
20 | //
21 | // Sub section comment
22 | //
23 | ```
24 |
25 | #### Basic comments
26 | ```scss
27 | // Basic comment
28 | ```
29 |
30 | ### Class naming
31 | Use dashes to create compound class names:
32 |
33 | ```scss
34 | // Good - use dashes
35 | .compound-class-name {…}
36 |
37 | // Good - uses camelCase
38 | .compoundClassName {…}
39 |
40 | // Bad - uses underscores
41 | .compound_class_name {…}
42 |
43 | // Bad - does not use seperators
44 | .compoundclassname {…}
45 | ```
46 |
47 | ### Indentation
48 | Rules should be indented with 2 spaces:
49 |
50 | ```scss
51 | // Good
52 | .example {
53 | color: #000;
54 | visibility: hidden;
55 | }
56 |
57 | // Bad - using tabs or 4 spaces
58 | .example {
59 | color: #000;
60 | visibility: hidden;
61 | }
62 | ```
63 |
64 | SCSS should also be nested, with child selectors and rules indented again. Nested rules should also be spaced by one line:
65 |
66 | ```scss
67 | // Good
68 | .example {
69 |
70 | > li {
71 | float: none;
72 |
73 | + li {
74 | margin-top: 2px;
75 | margin-left: 0;
76 | }
77 |
78 | }
79 |
80 | }
81 |
82 | // Bad - nested rules indented with tab or 4 spaces
83 | .example {
84 |
85 | > li {
86 | float: none;
87 |
88 | + li {
89 | margin-top: 2px;
90 | margin-left: 0;
91 | }
92 |
93 | }
94 |
95 | }
96 | ```
97 |
98 | ### Alignment
99 | The opening brace must be on the same line as the last selector and preceded by a space. The closing brace must be on its own line after the last property and be indented to the same level as the opening brace.
100 |
101 | ```scss
102 | // Good
103 | .example {
104 | color: #fff;
105 | }
106 |
107 | // Bad - closing brace is in the wrong place
108 | .example {
109 | color: #fff;
110 | }
111 |
112 | // Bad - opening brace missing space
113 | .example{
114 | color: #fff;
115 | }
116 | ```
117 |
118 | ### Declaration order
119 | Related property declarations should be grouped together following the order:
120 |
121 | 1. Positioning
122 | 2. Box model
123 | 3. Typographic
124 | 4. Visual
125 |
126 | ```scss
127 | // Good
128 | .example {
129 | // Positioning
130 | position: absolute;
131 | top: 0;
132 | right: 0;
133 | bottom: 0;
134 | left: 0;
135 | z-index: 100;
136 |
137 | // Box-model
138 | display: block;
139 | float: right;
140 | width: 100px;
141 | height: 100px;
142 |
143 | // Typography
144 | font-family: Arial, sans-serif;
145 | font-size: 14px;
146 | line-height: 1.2;
147 | color: #333;
148 | text-align: center;
149 |
150 | // Visual
151 | background-color: #f5f5f5;
152 | border: 1px solid #e5e5e5;
153 | border-radius: 3px;
154 |
155 | // Misc
156 | opacity: 1;
157 | }
158 | ```
159 |
160 | Within each group, you'll also need to order the properties. If any mistakes are made, the compiler will notify you and provide the correct order
161 |
162 | ### Property Format
163 | Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon.
164 |
165 | ```scss
166 | // Good
167 | .example {
168 | background: black;
169 | color: #fff;
170 | }
171 |
172 | // Bad - missing spaces after colons
173 | .example {
174 | background:black;
175 | color:#fff;
176 | }
177 |
178 | // Bad - missing last semicolon
179 | .example {
180 | background: black;
181 | color: #fff
182 | }
183 | ```
184 |
185 | ### HEX values
186 | HEX values must be declared in lowercase and shorthand:
187 |
188 | ```scss
189 | // Good
190 | .example {
191 | color: #eee;
192 | }
193 |
194 | // Bad
195 | .example {
196 | color: #EEEEEE;
197 | }
198 | ```
199 |
200 | ### Attribute selectors
201 | Always use double quotes around attribute selectors.
202 |
203 | ```scss
204 | // Good
205 | input[type="button"] {
206 | ...
207 | }
208 |
209 | // Bad - missing quotes
210 | input[type=button] {
211 | ...
212 | }
213 |
214 | // Bad - using single quote
215 | input[type='button'] {
216 | ...
217 | }
218 | ```
219 |
220 | ### Zero value units
221 | Zero values should not carry units.
222 |
223 | ```scss
224 | // Good
225 | .example {
226 | padding: 0;
227 | }
228 |
229 | // Bad - uses units
230 | .example {
231 | padding: 0px;
232 | }
233 | ```
234 |
235 | ### Prefixing properties
236 | There is no need to prefix properties, as this will be automatically taken care of when compiling your code
237 |
238 | ```scss
239 | // Good
240 | .example {
241 | transform: rotate(30px);
242 | }
243 |
244 | // Bad - uses prefix
245 | .example {
246 | -webkit-transform: rotate(30px);
247 | transform: rotate(30px);
248 | }
249 | ```
250 |
251 | ### End of file
252 | The end of the SCSS file should always have a blank line
253 |
254 | ```scss
255 | .example {
256 | padding: 0;
257 | }
258 | <<< Leave empty line here
259 | ```
260 |
--------------------------------------------------------------------------------
/manual/source-code-management.md:
--------------------------------------------------------------------------------
1 | Before we start talking about what Joomla! code should look like, it is appropriate to look at how and where the source code is stored. All serious software projects, whether driven by an Open Source community or developed within a company for proprietary purposes will manage the source code is some sort of source or version management system. The Joomla! project uses a Distributed Version Control System (DVCS) called Git hosted at [GitHub](https://github.com).
2 |
3 | ### The Joomla! Framework
4 |
5 | The [Joomla! Framework](https://github.com/joomla-framework) is a PHP framework that is designed to serve as a foundation for not only web applications (like a CMS) but other types of software such as command line applications. The files that form the Joomla! Framework are stored in a Distributed Version Control System (DVCS) called Git hosted at [GitHub](https://github.com).
6 |
7 | You can learn about how to get the Joomla Framework source code from the GitHub organisation, https://github.com/joomla-framework.
8 |
9 | Because Git treats the concepts of file revision numbers differently than Subversion, the repository revision number is not required in files (that is, the `@version` tag is not necessary).
10 |
11 | ### The Joomla! CMS
12 |
13 | The [Joomla! CMS](https://github.com/joomla/joomla-cms) is a Content Management System (CMS) which enables you to build Web sites and powerful online applications. It's a free and OpenSource software, distributed under the GNU General Public License version 2 or later. The files that form the Joomla! CMS are stored in a Distributed Version Control System (DVCS) called Git hosted at [GitHub](https://github.com).
14 |
15 | You can learn about how to get the Joomla CMS source code from the Git repository, https://github.com/joomla/joomla-cms.
16 |
17 | Because Git treats the concepts of file revision numbers differently than Subversion, the repository revision number is not required in files (that is, the `@version` tag is not necessary).
18 |
19 | ### Compliance Tool
20 |
21 | The standards in this manual have been adopted across the Joomla project, including the [Joomla! Framework](https://github.com/joomla-framework), the [Joomla! CMS](https://github.com/joomla/joomla-cms) and any other applications or extensions maintained by the project. These standards apply to source code, tests and (where applicable) documentation.
22 |
23 | A custom Joomla sniff standard for PHP files is maintained by the Joomla! project and available from the [coding standards](https://github.com/joomla/coding-standards) repository. The Sniff is based on the standard outlined in this document. For more information about how code standards are enforced see the analysis appendix of the manual. For information on using the Sniff see the documentation stored in its repository.
24 |
--------------------------------------------------------------------------------
/manual/version.md:
--------------------------------------------------------------------------------
1 | Version 1.0
--------------------------------------------------------------------------------
/manual/xml.md:
--------------------------------------------------------------------------------
1 | ### Attributes
2 |
3 | * Each attribute is on its own line.
4 | * The four attributes `name`, `type`, `label` and `description` should be written in this order and at the top of the element definition.
5 |
6 | ### Closing Elements
7 |
8 | Elements should be closed with the closing tag on a new line.
9 |
10 | #### Exception
11 |
12 | When the element only has few attributes, then the whole element can stay on the same line. A max line length of 100 characters is recommended for good reading.
13 |
14 | ### Examples
15 |
16 | #### Element is **empty**:
17 | ```xml
18 |
34 |
35 |
36 |
37 |
38 |
44 |
50 |
53 |
54 | ```
55 |
56 | #### Element with only a few attributes
57 |
58 | ```xml
59 |
60 | ```
61 |
--------------------------------------------------------------------------------
/notes.txt:
--------------------------------------------------------------------------------
1 | ==========
2 | The Joomla coding-standards for PHP_CodeSniffer has been derived from the Generic, PEAR, Squiz, PSR2, and Zend standards.
3 | Differences are noted below.
4 | ==========
5 |
6 | ruleset.xml
7 | - Increased notional limit to 150 chars.
8 | - Include/exclude additional sniffs from various standards (see file for specifics)
9 |
10 | Classes/InstantiateNewClassesSniff.php
11 | Classes/MemberVarScopeSniff.php
12 | Classes/MethodScopeSniff.php
13 | Classes/StaticThisUsageSniff.php
14 |
15 | Commenting/ClassCommentSniff.php
16 | - Added tags to check (copyright, etc not required in classes).
17 | - @package tag optional.
18 | Commenting/FileCommentSniff.php
19 | - If not short description is provided then the blank line check is not done.
20 | - Removed check on subpackage name in processSubpackage
21 | - Removed space checking after @ tags in processTags
22 | - Allowed any characters to appear before the copyright year in processCopyrights
23 | - @package tag optional.
24 | Commenting/FunctionCommentSniff.php
25 | - Remove check for one space before var type.
26 | - Remove check for 1 space after the longest type.
27 | - Remove check for 1 space after the variable name.
28 | - Remove check for variable name alignment.
29 | - Remove check for variable comment alignment.
30 | Commenting/SingleCommentSniff.php
31 |
32 | ControlStructures/ControlSignatureSniff.php
33 | ControlStructures/ElseIfDeclarationSniff.php
34 | - based on PSR2.ControlStructures.ElseIfDeclaration
35 | - Changed from WARNING to ERROR
36 | ControlStructures/InlineControlStructureSniff.php
37 | - Changed from WARNING to ERROR
38 | - Added exception if the file is a layout (ie, under a /tmpl/ folder).
39 | ControlStructures/MultiLineConditionSniff.php
40 | ControlStructures/WhiteSpaceBeforeSniff.php
41 |
42 | Functions/FunctionCallSignatureSniff.php
43 | Functions/FunctionDeclarationSniff.php
44 | Functions/StatementNotFunctionSniff.php
45 |
46 | NamingConventions/ValidFunctionNameSniff.php
47 | NamingConventions/ValidVariableNameSniff.php
48 |
49 | PHP/LowerCaseConstantSniff.php
50 | - Based on Generic.PHP.LowerCaseConstantSniff
51 |
52 | WhiteSpace/CastSpacingSniff.php
53 | - Squiz.WhiteSpace.CastSpacing
54 | WhiteSpace/ConcatenationSpacingSniff.php
55 | WhiteSpace/ControlStructureSpacingSniff.php
56 | WhiteSpace/DisallowSpaceIndentSniff.php
57 | - Based on Generic.WhiteSpace.DisallowSpaceIndent
58 | WhiteSpace/MemberVarSpacingSniff.php
59 | - Based on Squiz.WhiteSpace.MemberVarSpacing
60 | WhiteSpace/ObjectOperatorIndentSniff.php
61 | - Based on PEAR.WhiteSpace.ObjectOperatorIndent
62 | WhiteSpace/OperatorSpacingSniff.php
63 | WhiteSpace/SemicolonSpacingSniff.php
64 | - Based on Squiz.WhiteSpace.SemicolonSpacing
65 | WhiteSpace/SpaceAfterCastSniff.php
66 | WhiteSpace/SuperfluousWhitespaceSniff.php
67 |
--------------------------------------------------------------------------------
41 |
42 |
43 | Home
44 | ```
45 |
46 | ```html
47 |
48 | a {
49 | color: #a3a3a3;
50 | }
51 |
52 |
53 | a {
54 | color: #A3A3A3;
55 | }
56 | ```
57 |
58 | ### Protocol
59 |
60 | Omit the protocol portion (http:, https:) from URLs pointing to images and other media files, style sheets, and scripts unless they are not available over both protocols.
61 |
62 | This prevents mixed content issues and results in minor file size savings.
63 |
64 | ```html
65 |
66 |
67 |
68 |
69 |
70 | ```
71 |
72 | ### Elements and Attributes
73 |
74 | Always include ``, ``, and `` tags.
75 |
76 | ### Type attributes
77 |
78 | Do not use type or attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
79 |
80 | ```html
81 |
82 |
83 |
84 |
85 |
86 | ```
87 |
88 | ### Language attributes
89 |
90 | Do not use language attributes on script tags.
91 | ```html
92 |
93 |
106 |
107 |
108 |
109 | ```
110 |
111 | Use attribute/value pairs for boolean attributes
112 |
113 | ```html
114 |
115 |
116 |
117 |
118 |
119 | ```
120 |
121 | HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.
122 |
123 | 1. class
124 | 2. id
125 | 3. data-*
126 | 4. Everything else
127 |
128 | ```html
129 |
130 | Text
131 |
132 |
133 | Text
134 | ```
135 |
136 | Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs:
137 |
138 | ```html
139 |
143 | Text
144 |
145 | ```
146 |
147 | ### Elements
148 |
149 | Optional closing tags may not be omitted.
150 |
151 | ```html
152 |
153 | The quick brown fox jumps over the lazy dog.
154 | 155 | 156 |The quick brown fox jumps over the lazy dog.
157 | ```
158 |
159 | Self-closing (void) elements should not be closed. Trailing forward slashes and spaces should be omitted.
160 |
161 | ```html
162 |
163 | 
164 |
165 |
166 |
167 | ```
168 |
169 | ### Formatting
170 |
171 | Use a new line for every block, list, or table element, and indent every such child element.
172 |
173 | ```html
174 |
175 |
176 |
181 |
182 |
183 | -
177 |
- Home 178 |
- Blog 179 |
-
184 |
- Home 185 |
- Blog 186 |
197 |199 | 200 | 201 |Space, the final frontier.
198 |
-
202 |
- Moe 203 |
- Larry 204 |
- Curly 205 |
| Income | 212 |Taxes | 213 |
|---|---|
| $ 5.00 | 217 |$ 4.50 | 218 |
Joomla! is awesome!
252 | 253 | 254 | 255 | ``` 256 | 257 | ### Trailing Whitespace 258 | 259 | Remove trailing white spaces. Trailing white spaces are unnecessary and can complicate diffs. 260 | 261 | ```html 262 | 263 |
Yes please.
264 | 265 | 266 |No, thank you.
267 | ``` 268 | 269 | ### Entity References 270 | 271 | Do not use entity references. There is no need to use entity references like —, ”, or ☺, assuming the same encoding (UTF-8) is used for files and editors as well as among teams. 272 | 273 | The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces). 274 | 275 | ```html 276 | 277 |The currency symbol for the Euro is “€”.
278 | 279 | 280 |The currency symbol for the Euro is “&eur;”.
281 | ``` 282 | 283 | ### Inline CSS 284 | 285 | Inline CSS must be avoided. When altering states using JavaScript, use CSS to define your states, and only use unobtrusive JavaScript to alter class names whenever possible. 286 | 287 | ```html 288 | 289 | Home 290 | 291 | 292 | Home 293 | ``` 294 | 295 | @todo more meaningful example. 296 | 297 | ### Style Attributes 298 | 299 | You should not use border, align, valign, or clear attributes. Avoid use of style attributes, except where using syndicated content or internal syndicating systems. 300 | 301 | ### Semantics 302 | 303 | Use HTML according to its purpose. For example, use heading elements for headings, `` elements for paragraphs, `` elements for anchors, etc. 304 | 305 | Using HTML according to its purpose is important for accessibility, reuse, and code efficiency reasons. 306 | 307 | ```html 308 | 309 | View subscriptions 310 | 311 | 312 |
View subscriptions
313 | ```
314 |
315 | ### Markup
316 |
317 | #### Image Tags
318 |
319 | Image elements (`
331 |
332 |
336 | ```
337 |
338 | ### Mark todos
339 | Highlight todos by using the keyword TODO, eg:
340 |
341 | ```html
342 |
343 |
333 |
334 |
335 | -
344 |
- Home 345 |
- Blog 346 |
` instead of `
` and `
` eg: 352 | 353 | ```html 354 | This text contains
a line break. 355 | ``` 356 | 357 | ### Markup validation tools 358 | 359 | @todo: list various testing tools: 360 | 361 | * http://validator.w3.org/nu/ 362 | * http://csslint.net/ 363 | -------------------------------------------------------------------------------- /manual/ini.md: -------------------------------------------------------------------------------- 1 | .ini Language Files Format 2 | 3 | An .ini file is composed of strings and comments. See [Specification of language files](https://docs.joomla.org/Specification_of_language_files). 4 | 5 | ### Formatting 6 | 7 | #### Comments 8 | There are 2 types of comments: 9 | - Comments used as sections, to clarify the use of a group of strings. 10 | - Comments used to inform translators of some characteristics of the string(s) just below. These should not be preceded by a blank line. 11 | 12 | #### Strings 13 | - All language strings are in British English (en-GB). See [Joomla! en-GB User Interface Text Guidelines](https://developer.joomla.org/en-gb-user-interface-text-guidelines/introduction.html) 14 | - The lines commented should start with a semi-colon. 15 | - The strings should be alphabetically ordered using the "Standard Alphabetical Order" and not the "ASCII order". This mostly means here that the underscore is sorted BEFORE the letters. 16 | 17 | Example: 18 | ```ini 19 | COM_ABCD_FORMAT_WHATEVER 20 | ``` 21 | comes before 22 | ```ini 23 | COM_ABCD_FORMATTING_WHATEVER 24 | ``` 25 | 26 | Some specific text editors only sort by "ASCII order" and should not be used. 27 | 28 | ### Plugins 29 | Some IDEs have specific plugins to sort the lines by "Standard Alphabetical Order". 30 | 31 | Examples: 32 | - Atom [Sort selected elements](https://github.com/BlueSilverCat/sort-selected-elements) 33 | - Eclipse [Sortit](https://github.com/channingwalton/eclipse-sortit/tree/master/com.teaminabox.eclipse.sortit) 34 | - NetBeans [Sort line tools](http://plugins.netbeans.org/plugin/45925/sort-line-tools) 35 | - PhpStorm [String Manipulation](https://plugins.jetbrains.com/plugin/2162-string-manipulation) 36 | 37 | It may be necessary to set the sorting to "Case Insensitive Sort" to obtain the correct results. 38 | 39 | ### Online tools 40 | There is also an online tool which lets order this way (among other goodies): https://wordcounter.net/alphabetize 41 | 42 | ### Notes 43 | When the file includes commented sections, the strings should be alphabetically ordered in each section. 44 | Warning: when the comments concern specific strings and sorting has modified the order, the comments should be moved to the right place. -------------------------------------------------------------------------------- /manual/inline-comments.md: -------------------------------------------------------------------------------- 1 | This chapter covers inline code commenting in more detail. Inline comments are all comments not included in doc blocs. The goal of in line commenting is to explain code in context. Such explanation may take many different forms. 2 | 3 | Comments that are written in a readable and narrative style, especially when explaining a complex process, are encouraged. In general they should be placed close to the code explained rather than before the entire block of code. 4 | 5 | Comments should be as sentence like as possible, which is to say that they should be complete and readable, not in short hand. 6 | 7 | Comments are not a replacement for detailed doc blocks. Comments serve to explain the logic and structure of code itself rather than the use of code. 8 | 9 | ### Formatting of Comments 10 | 11 | Comment blocks that introduce large sections of code and are more than 2 lines long should use `/* */` (C) style and should use `*` on each line with the same space/tab rules as doc blocks. If you need a large introduction consider whether this block should be separated into a method to reduce complexity and therefore providing a full docblock. 12 | 13 | Comments should precede the code they refer to. As a corollary, comments should not be on the same line as the code to which they refer (which puts them after the code they reference). They should be on their own lines. 14 | 15 | Don’t use a blank line between comments and the code they refer to (no space underneath a comment block). 16 | 17 | Always have a single blank line before a comment or block of comments unless the comment (or block) is at the beginning of a code structure. ( You should not have a blank line after a '{' line ) 18 | 19 | For example in the following case there is no new line before the first comment (because it follows a '{' line) but we do want a new line before the second comment: 20 | 21 | ```php 22 | while (!$done) 23 | { 24 | // We don't want an infinite loop here. 25 | $done = true; 26 | } 27 | 28 | // Now let's do something interesting. 29 | $result = somethingInteresting(); 30 | ``` 31 | 32 | Comments should align with the code they refer to, using the same indenting as the line that follows the comment. 33 | 34 | Comments should be indented with tabs (like code, not like doc blocks). 35 | 36 | ### Content of comments 37 | 38 | Comments should use en-GB 39 | 40 | Always have a space between // and the start of comment text. 41 | 42 | New lines should always start with an upper case letter unless: 43 | * The line is a continuation of a complete sentence. 44 | * The term is code and is case sensitive. 45 | 46 | Code that is included specifically to assure compatibility with other software (for example specific browsers or a specific version of the CMS or for backward compatibility reasons) should be clearly marked as such. If there is the intention to remove specific code at a future point, state that but do not use a deprecation tag or specify a release (this can be hard to predict). 47 | 48 | Check spelling and grammar on all comments (see below and [the en-GB guidelines](https://developer.joomla.org/en-gb-user-interface-text-guidelines.html)). 49 | 50 | Only end a line with a period if it is a full sentence. 51 | 52 | Rather than use docblock tags use See:, Link: and Note: for comments if appropriate. 53 | 54 | Do not use HTML in comments unless specifically related to the comment content. 55 | 56 | Do not leave commented code unless there is a clearly explained reason for doing so. In such a case, a comment saying "Code intentionally commented" will prevent accidental removal. 57 | 58 | Comments may include forward looking statements of how something will be extended or modified in the future, but not todos indicating that code is not complete or ready to use. 59 | 60 | Remember that humor and sarcasm are difficult to translate. 61 | 62 | ### Acronyms 63 | 64 | Capitalise all letters of acronyms such as HTML, XML, SQL, GMT, and UTC. 65 | 66 | ### Common spelling and grammar errors for which to check. 67 | 68 | Joomla contributors include many non-native speakers of en-GB which makes it understandable that there are sometimes spelling and grammar errors. At the same time, some people reading comments also are non native speakers and may even use automated translation to understand comments. This makes it very important that comments should follow proper en-GB spelling and grammar rules. Unfortunately, these can be tricky. 69 | 70 | #### S vs Z 71 | 72 | en-GB most commonly uses `ise` where en-US would use `ize`, such as `normalise` instead of `normalize`. (Note that there are some exceptions to this rule.) 73 | 74 | Use of apostrophes is one of the trickier parts of English. 75 | 76 | #### Lets versus let’s 77 | 78 | Lets means permits or allows to: 79 | 80 | ```php 81 | // This lets the user enter data 82 | ``` 83 | 84 | Let’s is a contraction for let us and means we are going to do this now: 85 | 86 | ```php 87 | // Let's validate the field 88 | ``` 89 | 90 | #### Its versus it’s 91 | 92 | Its is the possessive form of it: 93 | 94 | ```php 95 | // Get its ID 96 | ``` 97 | 98 | It’s is a contraction of it is 99 | 100 | ```php 101 | // It's time to save 102 | ``` 103 | 104 | #### The correct Joomla spelling of some commonly used words. 105 | 106 | - dependant 107 | - deprecated 108 | -------------------------------------------------------------------------------- /manual/introduction.md: -------------------------------------------------------------------------------- 1 | Good coding standards are important in any software development project. These standards are even more important when a large, diverse and worldwide community of developers are contributing to a project. One of the things that sets good software apart from great software is not only the features or the actual function the software performs, but the quality of its source code. 2 | 3 | In order to perform in the highly competitive Open Source and proprietary software industries, source code not only needs to be beautifully designed, it also needs to be beautiful and elegant to look at. The Joomla Coding Standards Manual is to help ensure our code is the highest quality which will make it easy to read, debug, and maintain. 4 | 5 | ### Guiding Principles 6 | 7 | Since readable code is more maintainable, the compass that guides us in achieving that goal is a set of well thought out coding standards for the different software languages that are employed in the Joomla software project. Joomla has a solid heritage of striving to support a great looking product with great looking code. 8 | 9 | This manual compiles the collective wisdom of past and present contributors to the project to form the definitive standard for coding in Joomla, whether that is for the core Joomla Framework or an extension that forms part of the stack of the Joomla CMS. This manual also serves as a lighthouse to the Joomla developer community, to safely guide developers around the pitfalls of becoming lackadaisical with respect to writing clean, beautiful code. 10 | 11 | The Joomla Coding Standards borrows heavily from the PEAR coding standard for PHP files, augmenting and diverging where it is deemed sensible to do so. 12 | 13 | There are [tools available](/coding-standards/analysis.html) to help your code conform to our standards. 14 | 15 | ### Contributing to this manual 16 | 17 | If you want to contribute and improve this manual, you can find the source files at [https://github.com/joomla/coding-standards/tree/master/manual](https://github.com/joomla/coding-standards/tree/master/manual). 18 | -------------------------------------------------------------------------------- /manual/javascript-j3.md: -------------------------------------------------------------------------------- 1 | ### Contents 2 | 3 | 1. [Naming Conventions](#naming-conventions) 4 | - [Variables](#naming-conventions-variables) 5 | - [Functions](#naming-conventions-functions) 6 | - [Reserved Words](#naming-conventions-reserved) 7 | 2. [Syntax Style](#syntax-style) 8 | - [Indentation](#syntax-indentation) 9 | - [Spacing](#syntax-spacing) 10 | - [Commas](#syntax-commas) 11 | - [Semicolons](#syntax-semicolons) 12 | - [Quotes](#syntax-quotes) 13 | 3. [Types](#types) 14 | 4. [Functions](#functions) 15 | 5. [Conditional Statements](#conditional-statements) 16 | 6. [Blocks & Multi-line Statements](#blocks) 17 | 7. [Comments](#comments) 18 | 19 | 20 | ### Naming Conventions 21 | 22 | Use descriptive words or terse phrases for names. 23 | 24 | Variables and Functions should be camel case, starting with a lowercase letter: `likeThis` 25 | 26 | 27 | #### Variables 28 | 29 | **Use names that describe what the variable is:** 30 | 31 | `var element = document.getElementById('elementId');` 32 | 33 | **Iterators are the exception** 34 | 35 | Use i for index in a loop (and subsequent letters when necessary for nested iteration). 36 | 37 | 38 | #### Functions 39 | 40 | **Use names that describe what the function does:** 41 | 42 | ```js 43 | function getSomeData() { 44 | // statements 45 | } 46 | ``` 47 | 48 | 49 | #### Reserved Words 50 | 51 | Do not use reserved words for anything other than their intended use. The list of: [Reserved Words](http://es5.github.io/#x7.6.1) 52 | 53 | --- 54 | 55 | 56 | ### Syntax Style 57 | 58 | 59 | #### Indentation 60 | - Don't mix tabs and spaces. 61 | - Tabs, 4 spaces 62 | 63 | 64 | #### Spacing 65 | - No whitespace at the end of line or on blank lines. 66 | - Unary special-character operators (e.g., !, ++) must not have space next to their operand. 67 | - Any , and ; must not have preceding space. 68 | - Any ; used as a statement terminator must be at the end of the line. 69 | - Any : after a property name in an object definition must not have preceding space. 70 | - The ? and : in a ternary conditional must have space on both sides. 71 | - No filler spaces in empty constructs (e.g., {}, [], fn()) 72 | - New line at the end of each file. 73 | 74 | **Array:** 75 | 76 | ```js 77 | var array = [ 'foo', 'bar' ]; 78 | ``` 79 | 80 | **Function call:** 81 | 82 | ```js 83 | foo( arg ); 84 | ``` 85 | 86 | **Function call with multiple arguments:** 87 | 88 | ```js 89 | foo( 'string', object ); 90 | ``` 91 | 92 | **Conditional Statements** 93 | 94 | ```js 95 | if ( condition ) { 96 | // statements 97 | } else { 98 | // statements 99 | } 100 | ``` 101 | 102 | ```js 103 | while ( condition ) { 104 | // statements 105 | } 106 | ``` 107 | 108 | ```js 109 | for ( prop in object ) { 110 | // statements 111 | } 112 | ``` 113 | 114 | 115 | ##### Exceptions 116 | 117 | **First or only argument is an object, array or callback function.** 118 | 119 | **No space before the first argument:** 120 | 121 | ```js 122 | foo({ 123 | a: 'bar', 124 | b: 'baz' 125 | }); 126 | ``` 127 | 128 | ```js 129 | foo(function() { 130 | // statements 131 | }, options ); // space after options argument 132 | ``` 133 | 134 | **Function with a callback, object, or array as the last argument:** 135 | 136 | No space after the last argument. 137 | 138 | ```js 139 | foo( data, function() { 140 | // statements 141 | }); 142 | ``` 143 | 144 | 145 | #### Commas 146 | 147 | **Place commas after:** 148 | 149 | - variable declarations 150 | - key/value pairs 151 | 152 | #### Arrays 153 | 154 | Do not include a trailing comma, this will add 1 to your array's length. 155 | 156 | **No:** 157 | 158 | ```js 159 | array = [ 'foo', 'bar', ]; 160 | ``` 161 | 162 | **Yes:** 163 | 164 | ```js 165 | array = [ 'foo', 'bar' ]; 166 | ``` 167 | 168 | 169 | #### Semicolons 170 | 171 | Use them where expected. 172 | 173 | Semicolons should be included at the end of function expressions, but not at the end of function declarations. 174 | 175 | **Function Expression:** 176 | 177 | ```js 178 | var foo = function() { 179 | return true; 180 | }; 181 | ``` 182 | 183 | **Function Declaration:** 184 | 185 | ```js 186 | function foo() { 187 | return true; 188 | } 189 | ``` 190 | 191 | 192 | #### Quotes 193 | 194 | Use ' instead of " 195 | 196 | 197 | --- 198 | 199 | 200 | ### Variables 201 | 202 | ### Avoid Global Variables 203 | 204 | **No:** 205 | 206 | ```js 207 | foo = 'bar'; 208 | ``` 209 | 210 | **No: implied global** 211 | 212 | ```js 213 | function() { 214 | foo = 'bar'; 215 | } 216 | ``` 217 | 218 | **Yes:** 219 | 220 | ```js 221 | var foo = 'bar'; 222 | ``` 223 | 224 | #### Multiple Variable Declarations 225 | 226 | Use one `var` declaration and separate each variable on a newline ending with a comma. 227 | 228 | **No:** 229 | 230 | ```js 231 | var foo = 'bar'; 232 | var bar = 'baz'; 233 | var baz = 'qux'; 234 | ``` 235 | 236 | **Yes:** 237 | 238 | ```js 239 | var foo = 'bar', 240 | bar = 'baz', 241 | baz = 'qux'; 242 | ``` 243 | 244 | 245 | --- 246 | 247 | 248 | ### Types 249 | 250 | #### String 251 | 252 | - Concatenate long strings. 253 | - Place space before closing quote at the end of each string. 254 | - Concatenation operator at the end of each subsequent string. 255 | 256 | ```js 257 | var longString = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ' + 258 | 'Sed placerat, tellus eget egestas tincidunt, lectus dui ' + 259 | 'sagittis massa, id mollis est tortor a enim. In hac ' + 260 | 'habitasse platea dictumst. Duis erat justo, tincidunt ac ' + 261 | 'enim iaculis, malesuada condimentum mauris. Vestibulum vel ' + 262 | 'cursus mauris.'; 263 | ``` 264 | 265 | #### Number 266 | 267 | Use `parseInt()` or `parseFloat()` instead of unary plus, for readability. 268 | 269 | **No:** 270 | 271 | ```js 272 | var count = +document.getElementById('inputId').value; 273 | ``` 274 | 275 | **Yes:** 276 | 277 | ```js 278 | var count = parseInt(document.getElementById('inputId').value); 279 | ``` 280 | 281 | #### Type Checks 282 | 283 | - String: `typeof object === 'string'` 284 | - Number: `typeof object === 'number'` 285 | - Boolean: `typeof object === 'boolean'` 286 | - Object: `typeof object === 'object'` 287 | - Plain Object: `jQuery.isPlainObject( object )` 288 | - Function: `jQuery.isFunction( object )` 289 | - Array: `jQuery.isArray( object )` 290 | - Element: `object.nodeType` 291 | - null: `object === null` 292 | - null or undefined: `object == null` 293 | 294 | **Undefined:** 295 | 296 | - Global Variables: `typeof variable === 'undefined'` 297 | - Local Variables: `variable === undefined` 298 | - Properties: `object.prop === undefined` 299 | 300 | #### Objects 301 | 302 | Use the literal, not constructor, syntax. 303 | 304 | **No:** 305 | 306 | ```js 307 | var myObj = new Object(); 308 | ``` 309 | 310 | **Yes:** 311 | 312 | ```js 313 | var myObj = {}; 314 | ``` 315 | 316 | If an object contains more than one key/value pair or an array as a value, each key/value pair should be on its own line. 317 | 318 | ```js 319 | var myObj = { 320 | foo: 'bar', 321 | bar: 'baz', 322 | baz: 'qux' 323 | }; 324 | ``` 325 | 326 | #### Arrays 327 | 328 | Use the literal, not constructor, syntax 329 | 330 | **No:** 331 | 332 | ```js 333 | var myArr = new Array(); 334 | ``` 335 | 336 | **Yes:** 337 | 338 | ```js 339 | var myArr = []; 340 | ``` 341 | 342 | If you don't know array length use push method. This will replace the current array. 343 | 344 | ```js 345 | var myArr = []; 346 | myArr.push('foo'); 347 | ``` 348 | 349 | 350 | --- 351 | 352 | 353 | ### Functions 354 | 355 | #### Chaining Method Calls 356 | 357 | ```js 358 | $('.someElement') 359 | .hide() 360 | .delay(1000) 361 | .fadeIn(); 362 | ``` 363 | 364 | 365 | --- 366 | 367 | 368 | ### Conditional Statements 369 | 370 | Use ternary syntax if: 371 | 372 | - One condition 373 | - Result of either evaluation is one operation. 374 | 375 | ```js 376 | joomlaRocks ? 'This is true' : 'else it is false'; 377 | ``` 378 | 379 | Otherwise, use standard syntax: 380 | 381 | ```js 382 | if ( condition ) { 383 | // statements 384 | } else { 385 | // statements 386 | } 387 | ``` 388 | 389 | **Cache length in variable for performance:** 390 | 391 | ```js 392 | var i, 393 | j = myArr.length; 394 | 395 | for ( i = 0; i < j; i++ ) { 396 | // statements 397 | } 398 | ``` 399 | 400 | **With more than one condition:** 401 | 402 | ```js 403 | if ( condition && 404 | condition2 && 405 | condition3 ) { 406 | // statements 407 | } else { 408 | // statements 409 | } 410 | ``` 411 | 412 | #### Equality 413 | 414 | Use strict equality operator === so that type is considered in comparison. Using == can produce false positives. 415 | 416 | 417 | ```js 418 | // evaluates true 419 | 1 == "1" 420 | ``` 421 | 422 | ```js 423 | // evaluates false 424 | 1 === "1" 425 | ``` 426 | 427 | 428 | --- 429 | 430 | 431 | ### Blocks & Multi-line Statements 432 | 433 | Use curly braces on blocks that have more than one statement. 434 | 435 | **Block with one statement:** 436 | 437 | ```js 438 | if ( test ) return false; 439 | ``` 440 | 441 | **Block with more than one statement:** 442 | 443 | ```js 444 | if ( test ) { 445 | var foo = 'some string'; 446 | return foo; 447 | } 448 | ``` 449 | 450 | 451 | --- 452 | 453 | 454 | ### Comments 455 | 456 | **Single Line** 457 | 458 | - Place above the code it refers to. 459 | - A space between double forward slashes and comment text. 460 | 461 | ```js 462 | // I am a single line comment. 463 | ``` 464 | 465 | 466 | **Multiline** 467 | 468 | - Place above the code it refers to. 469 | - Opening token placed on the line above first comment line, closing placed below last comment line. 470 | - Each comment line begins with two astericks followed by a space. 471 | 472 | ```js 473 | /* 474 | ** I am a multiline comment. 475 | ** Line two 476 | ** Line three 477 | */ 478 | ``` 479 | 480 | --- 481 | 482 | ### TODO 483 | 484 | - Switch Statements vs other methods like Objects 485 | - Add jQuery examples 486 | - Double check accuracy of all examples 487 | 488 | **With help from:** 489 | 490 | - [jQuery JS Style Guide](https://contribute.jquery.org/style-guide/js) 491 | - [Idiomatic JS](https://github.com/rwaldron/idiomatic.js) 492 | -------------------------------------------------------------------------------- /manual/javascript-j4.md: -------------------------------------------------------------------------------- 1 | ### Javascript in Joomla 4 2 | 3 | Joomla 4 uses ES6 syntax where possible. As part of this change we decided to use an industry standard codestyle rules for our JavaScript - the AirBNB coding standards. These can be found [on their GitHub page](https://github.com/airbnb/javascript#table-of-contents). 4 | 5 | We have four modifications to the defaults: 6 | 7 | 1. We allow parameter reassignment of function parameters to allow easier setting of defaults (for examples please see the ESLint rules [here](https://eslint.org/docs/rules/no-param-reassign)) 8 | 9 | 2. We only allow the imports of dependencies from NPM in our build directory (`build/`) (rather than in all files) 10 | 11 | 3. We currently allow browser alerts using the `alert()` function (the long term intention is to disable this as we move to our custom element alerts) 12 | 13 | 4. We always enable JavaScript strict mode as we aren't using JavaScript modules at this time 14 | 15 | We also use ESLint to enforce these rules. If you are familiar with JavaScript from other projects you've worked on you can find our ESLint rules [on GitHub](https://github.com/joomla/joomla-cms/blob/4.0-dev/.eslintrc) 16 | -------------------------------------------------------------------------------- /manual/license.md: -------------------------------------------------------------------------------- 1 | The contents of the Joomla! en-GB User Interface Text Guidelines are subject to copyright law and are made available under the [Joomla! Electronic Documentation License (JEDL)](https://docs.joomla.org/JEDL) unless otherwise stated. 2 | 3 | You may find the [JEDL Frequently Asked Questions](https://docs.joomla.org/JEDL/FAQ) useful in determining if your proposed use of this material is allowed. 4 | 5 | If you have any questions regarding licensing of this material please contact legal@opensourcematters.org. 6 | 7 | If you wish to report a possible violation of the license terms for the material on this site then please contact legal@opensourcematters.org. 8 | -------------------------------------------------------------------------------- /manual/php.md: -------------------------------------------------------------------------------- 1 | > **Note** 2 | > 3 | > The Joomla! CMS switched in Version 4.2.0 from its own coding standard to the PSR-12 (and later to PER Coding Style) coding standard. 4 | > This document applies to Joomla! < 4.2.0 and parts of it still applies to 4.2.0 and later. 5 | > 6 | > This document will be updated to reflect the PSR-12 coding standard soon. 7 | 8 | ### Language Constructs 9 | 10 | #### PHP Code Tags 11 | 12 | Always use the full `` to delimit PHP code, not the `` shorthand. This is the most portable way to include PHP code on differing operating systems and setups. 13 | 14 | For files that contain only PHP code, the closing tag (`?>`) should not be included. It is not required by PHP. Leaving this out prevents trailing white space from being accidentally injected into the output that can introduce errors in the Joomla session (see the PHP manual on [Instruction separation](https://secure.php.net/basic-syntax.instruction-separation)). 15 | 16 | Files should always end with a blank new line. 17 | 18 | #### General 19 | 20 | Pursuant to PSR-2 [Keywords and True/False/Null][] 21 | 22 | > PHP [keywords][] MUST be in lower case. 23 | > The PHP constants `true`, `false`, and `null` MUST be in lower case. 24 | 25 | [Keywords and True/False/Null]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md#25-keywords-and-truefalsenull 26 | [keywords]: https://secure.php.net/manual/en/reserved.keywords.php 27 | 28 | #### Including Code 29 | 30 | Anywhere you are unconditionally including a file, use `require_once`. Anywhere you are conditionally including a file (for example, factory methods), use `include_once`. Either of these will ensure that files are included only once. They share the same file list, so you don't need to worry about mixing them. A file included with `require_once` will not be included again by `include_once`. 31 | 32 | > **Note** 33 | > 34 | > `include_once` and `require_once` are PHP language statements, not functions. The correct formatting is: 35 | > 36 | > 37 | > `require_once JPATH_COMPONENT . '/helpers/helper.php';` 38 | 39 | You should not enclose the filename in parentheses. 40 | 41 | #### E_STRICT Compatible PHP Code 42 | 43 | As of Joomla version 1.6 and for all versions of the Joomla Platform, adhering to object oriented programming practice as supported by PHP 5.3+ is required. Joomla is committed to progressively making the source code E_STRICT. 44 | 45 | ### Global Variables 46 | 47 | Global variables should not be used. Use static class properties or constants instead of globals, following OOP and factory patterns. 48 | 49 | ### Error Surpression 50 | 51 | The use of the `@` for Error Surpression should be avoided and limited to use when no other approach or workaround is available. 52 | 53 | ### Control Structures (General Code) 54 | 55 | For all control structures there is a space between the keyword and an opening parenthesis, then no space either after the opening parenthesis or before the closing bracket. This is done to distinguish control keywords from function names. All control structures must contain their logic within braces. 56 | 57 | For all all control structures, such as `if`, `else`, `do`, `for`, `foreach`, `try`, `catch`, `switch` and `while`, both the keyword starts a newline and the opening and closing braces are each put on a new line. 58 | 59 | Exclamation mark `!`, the logical operator `not` used in a condition, should not have spaces before or after the exclamation mark as shown in the examples. 60 | 61 | #### An _if-else_ Example 62 | 63 | ```php 64 | if ($test) 65 | { 66 | echo 'True'; 67 | } 68 | 69 | // Comments can go here. 70 | // Note that "elseif" as one word is used. 71 | elseif ($test === false) 72 | { 73 | echo 'Really false'; 74 | } 75 | elseif (!$condition) 76 | { 77 | echo 'Not Condition'; 78 | } 79 | else 80 | { 81 | echo 'A white lie'; 82 | } 83 | ``` 84 | 85 | If a control structure goes over multiple lines, all lines must be indented with one tab and the closing brace must go on the same line as the last parameter. 86 | 87 | ```php 88 | if ($test1 89 | && $test2) 90 | { 91 | echo 'True'; 92 | } 93 | ``` 94 | 95 | #### A _do-while_ Example 96 | 97 | ```php 98 | do 99 | { 100 | $i++; 101 | } 102 | while ($i < 10); 103 | ``` 104 | 105 | #### A _for_ Example 106 | 107 | ```php 108 | for ($i = 0; $i < $n; $i++) 109 | { 110 | echo 'Increment = ' . $i; 111 | } 112 | ``` 113 | 114 | #### A _foreach_ Example 115 | 116 | ```php 117 | foreach ($rows as $index => $row) 118 | { 119 | echo 'Index = ' . $index . ', Value = ' . $row; 120 | } 121 | ``` 122 | 123 | #### A _while_ Example 124 | 125 | ```php 126 | while (!$done) 127 | { 128 | $done = true; 129 | } 130 | ``` 131 | 132 | #### A _switch_ example 133 | 134 | When using a `switch` statement, the `case` keywords are indented. The `break` statement starts on a newline assuming the indent of the code within the case. 135 | 136 | ```php 137 | switch ($value) 138 | { 139 | case 'a': 140 | echo 'A'; 141 | break; 142 | 143 | default: 144 | echo 'I give up'; 145 | break; 146 | } 147 | ``` 148 | 149 | #### A _try catch_ example 150 | ```php 151 | try 152 | { 153 | $table->bind($data); 154 | } 155 | catch (RuntimeException $e) 156 | { 157 | throw new Exception($e->getMessage(), 500, $e); 158 | } 159 | ``` 160 | 161 | ### Mixed language usage (e.g. at the layout files) 162 | 163 | For layout files and all files where we use a mix of PHP and HTML (all PHP files in the `view/tmpl` and `layout` folder) we additionally wrap every line into a `` block and use the alternative syntax for control structures. This should make the code easier to read and make it easier to move blocks around without creating fatal errors due to missing `` tags. 164 | 165 | #### Example Control Structures 166 | 167 | ##### An _if-else_ Example 168 | 169 | ```php 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | ``` 178 | 179 | ### References 180 | 181 | When using references, there should be a space before the reference operator and no space between it and the function or variable name. 182 | 183 | For example: 184 | 185 | ```php 186 | $ref1 = &$this->sql; 187 | ``` 188 | 189 | > **Note** 190 | > 191 | > In PHP 5, reference operators are not required for objects. All objects are handled by reference. 192 | 193 | 194 | ### Concatenation Spacing 195 | There should always be a space before and after the concatenation operator ('.'). For example: 196 | 197 | ```php 198 | $id = 1; 199 | echo JRoute::_('index.php?option=com_foo&task=foo.edit&id=' . (int) $id); 200 | ``` 201 | 202 | If the concatenation operator is the first or last character on a line, both spaces are not required. For example: 203 | 204 | ```php 205 | $id = 1 206 | echo JRoute::_( 207 | 'index.php?option=com_foo&task=foo.edit&id=' . (int) $id 208 | . '&layout=special' 209 | ); 210 | ``` 211 | 212 | ### Arrays 213 | 214 | Assignments (the `=>` operator) in arrays may be aligned with spaces. When splitting array definitions onto several lines, the last value should also have a trailing comma. This is valid PHP syntax and helps to keep code diffs minimal. Joomla 3 prefers `array()` to be backward compatible to 5.3.10 and Joomla 4.0.0 onwards should use the short array syntax `[]` by default. (Short array syntax was introduced in PHP 5.4.) 215 | 216 | For example: 217 | 218 | ```php 219 | $options = [ 220 | 'foo' => 'foo', 221 | 'spam' => 'spam', 222 | ]; 223 | 224 | ``` 225 | 226 | ### Code Commenting 227 | 228 | Inline comments to explain code follow the convention for C (`/* … */`) and C++ single line (`// ...`) comments. C-style blocks are generally restricted to documentation headers for files, classes and functions. The C++ style is generally used for making code notes. Code notes are strongly encouraged to help other people, including your future-self, follow the purpose of the code. Always provide notes where the code is performing particularly complex operations. 229 | 230 | Perl/shell style comments (`#`) are not permitted in PHP files. 231 | 232 | Blocks of code may, of course, be commented out for debugging purposes using any appropriate format, but should be removed before submitting patches for contribution back to the core code. 233 | 234 | For example, do not include feature submissions like: 235 | 236 | ```php 237 | // Must fix this code up one day. 238 | //$code = broken($fixme); 239 | ``` 240 | 241 | More details on inline code comments can be found in the chapter on [Inline Code Comments](/coding-standards/inline-code-comments.html). 242 | 243 | #### Comment Docblocks 244 | 245 | Documentation headers for PHP and Javascript code in files, classes, class properties, methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC. 246 | 247 | These "DocBlocks" borrow from the PEAR standard but have some variations specific for Joomla and the Joomla Platform. 248 | 249 | More details on DocBlocks comments can be found in the chapter on [DocBlocks Comments](/coding-standards/docblocks.html). 250 | 251 | ### Function Calls 252 | 253 | Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis. There should be space before and exactly one space after the equals sign. Tab alignment over multiple lines is permitted. 254 | 255 | ```php 256 | // An isolated function call. 257 | $foo = bar($var1, $var2); 258 | 259 | // Multiple aligned function calls. 260 | $short = bar('short'); 261 | $medium = bar('medium'); 262 | $long = bar('long'); 263 | ``` 264 | 265 | ### Function Definitions 266 | 267 | Function definitions start on a new line with no spaces between the function name and the opening parenthesis. Additionally, the opening and closing braces are also placed on new lines. An empty line should precede lines specifying the return value. 268 | 269 | Function definitions must include a documentation comment in accordance with the Commenting section of this document. More details on DocBlocks Function comments can be found in the chapter on [DocBlocks Comments](/coding-standards/docblocks.html). 270 | 271 | ```php 272 | /** 273 | * A utility function. 274 | * 275 | * @param string $path The library path in dot notation. 276 | * 277 | * @return void 278 | * 279 | * @since 1.6 280 | */ 281 | function jimport($path) 282 | { 283 | // Body of method. 284 | } 285 | ``` 286 | 287 | If a function definition goes over multiple lines, all lines must be indented with one tab and the closing brace must go on the same line as the last parameter. 288 | 289 | ```php 290 | function fooBar($param1, $param2, 291 | $param3, $param4) 292 | { 293 | // Body of method. 294 | } 295 | ``` 296 | 297 | ### Closures / Anonymous functions 298 | Closures/Anonymous functions should have a space between the Closure's/Anonymous function's name and the opening parenthesis. Method signatures don't have the space. 299 | 300 | ```php 301 | $fieldIds = array_map( 302 | function ($f) 303 | { 304 | return $f->id; 305 | }, 306 | $fields 307 | ); 308 | ``` 309 | 310 | ### Class Definitions 311 | 312 | Class definitions start on a new line and the opening and closing braces are also placed on new lines. Class methods must follow the guidelines for Function Definitions. Properties and methods must follow OOP standards and be declared appropriately (using public, protected, private and static as applicable). 313 | 314 | Class definitions, properties and methods must each be provided with a DocBlock in accordance with the following sections. 315 | 316 | More details on DocBlocks Class comments can be found in the chapter on [DocBlocks Comments](/coding-standards/docblocks.html). 317 | 318 | #### Class Property DocBlocks 319 | 320 | More details on Class Property DocBlocks can be found in the chapter on [DocBlocks Comments](docblocks.md). 321 | 322 | #### Class Method DocBlocks 323 | 324 | The DocBlock for class methods follows the same convention as for PHP functions. 325 | 326 | More details on DocBlocks Class Method comments can be found in the chapter on [DocBlocks Comments](docblocks.md). 327 | 328 | ### Class Definition Example 329 | ```php 330 | /** 331 | * A utility class. 332 | * 333 | * @package Joomla.Platform 334 | * @subpackage XBase 335 | * @since 1.6 336 | */ 337 | class JClass extends JObject 338 | { 339 | /** 340 | * Human readable name 341 | * 342 | * @var string 343 | * @since 1.6 344 | */ 345 | public $name; 346 | 347 | /** 348 | * Method to get the name of the class. 349 | * 350 | * @param string $case Optionally return in upper/lower case. 351 | * 352 | * @return boolean True if successfully loaded, false otherwise. 353 | * 354 | * @since 1.6 355 | */ 356 | public function getName($case = null) 357 | { 358 | // Body of method. 359 | return $this->name; 360 | } 361 | } 362 | ``` 363 | 364 | ### Naming Conventions 365 | 366 | #### Classes 367 | 368 | Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla Platform classes which must begin with an uppercase 'J' with the next letter also being uppercase. 369 | 370 | For example: 371 | 372 | - JHtmlHelper 373 | - JXmlParser 374 | - JModel 375 | 376 | #### Functions and Methods 377 | 378 | Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. 379 | 380 | For example: 381 | 382 | - connect(); 383 | - getData(); 384 | - buildSomeWidget(); 385 | - jImport(); 386 | - jDoSomething(); 387 | 388 | Private class members (meaning class members that are intended to be used only from within the same class in which they are declared) are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. 389 | 390 | For example: 391 | 392 | ```php 393 | class JFooHelper 394 | { 395 | protected $field_name = null; 396 | 397 | private $_status = null; 398 | 399 | protected function sort() 400 | { 401 | // Code goes here 402 | } 403 | } 404 | ``` 405 | 406 | #### Namespaces 407 | 408 | Namespaces are formatted according to this flow. First there is the file docblock followed by the namespace the file lives in. When required, the namespace is followed by the `defined` check. Lastly, the imported classes using the `use` keyword. All namespace imports must be alphabetically ordered. 409 | 410 | ```php 411 | /** 412 | * @package Joomla.Administrator 413 | * @subpackage mod_quickicon 414 | * 415 | * @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved. 416 | * @license GNU General Public License version 2 or later; see LICENSE.txt 417 | */ 418 | 419 | namespace Joomla\Module\Quickicon\Administrator\Helper; 420 | 421 | defined('_JEXEC') or die; 422 | 423 | use Joomla\CMS\Factory; 424 | use Joomla\CMS\Language\Text; 425 | use Joomla\CMS\Plugin\PluginHelper; 426 | use Joomla\CMS\Router\Route; 427 | use Joomla\Module\Quickicon\Administrator\Event\QuickIconsEvent; 428 | ``` 429 | 430 | #### Constants 431 | 432 | Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the `JError` class all begin with `JERROR_`. 433 | 434 | #### Regular Variables and Class Properties 435 | 436 | Regular variables, follow the same conventions as function. 437 | 438 | Class variables should be set to null or some other appropriate default value. 439 | 440 | ### Exception Handling 441 | 442 | Exceptions should be used for error handling. 443 | 444 | The following sections outline how to semantically use [SPL exceptions](https://secure.php.net/manual/en/spl.exceptions.php). 445 | 446 | #### Logic Exceptions 447 | 448 | The LogicException is thrown when there is an explicit problem with the way the API is being used. For example, if a dependency has failed (you try to operate on an object that has not been loaded yet). 449 | 450 | The following child classes can also be used in appropriate situations: 451 | 452 | ##### BadFunctionCallException 453 | 454 | This exception can be thrown if a callback refers to an undefined function or if some arguments are missing. For example if `is_callable()`, or similar, fails on a function. 455 | 456 | ##### BadMethodCallException 457 | 458 | This exception can be thrown if a callback refers to an undefined method or if some arguments are missing. For example `is_callable()`, or similar, fails on a class method. Another example might be if arguments passed to a magic call method are missing. 459 | 460 | ##### InvalidArgumentException 461 | 462 | This exception can be thrown if there is invalid input. 463 | 464 | ##### DomainException 465 | 466 | This exception is similar to the InvalidArgumentException but can be thrown if a value does not adhere to a defined valid data domain. For example trying to load a database driver of type "mongodb" but that driver is not available in the API. 467 | 468 | ##### LengthException 469 | 470 | This exception can be thrown is a length check on an argument fails. For example a file signature was not a specific number of characters. 471 | 472 | ##### OutOfRangeException 473 | 474 | This exception has few practical applications but can be thrown when an illegal index was requested. 475 | 476 | #### Runtime Exceptions 477 | 478 | The RuntimeException is thrown when some sort of external entity or environment causes a problem that is beyond your control providing the input is valid. This exception is the default case for when the cause of an error can't explicitly be determined. For example you tried to connect to a database but the database was not available (server down, etc). Another example might be if an SQL query failed. 479 | 480 | ##### UnexpectedValueException 481 | 482 | This type of exception should be used when an unexpected result is encountered. For example a function call returned a string when a boolean was expected. 483 | 484 | ##### OutOfBoundsException 485 | 486 | This exception has few practical applications but may be thrown if a value is not a valid key. 487 | 488 | ##### OverflowException 489 | 490 | This exception has few practical applications but may be thrown when you add an element into a full container. 491 | 492 | ##### RangeException 493 | 494 | This exception has few practical applications but may be thrown to indicate range errors during program execution. Normally this means there was an arithmetic error other than under/overflow. This is the runtime version of DomainException. 495 | 496 | ##### UnderflowException 497 | 498 | This exception has few practical applications but may thrown when you try to remove an element of an empty container. 499 | 500 | #### Documenting exceptions 501 | 502 | Each function or method must annotate the type of exception that it throws using an @throws tag and any downstream exceptions types that are thrown. Each type of exception need only be annotated once. No description is necessary. 503 | 504 | ### SQL Queries 505 | 506 | SQL keywords are to be written in uppercase, while all other identifiers (with the exception of quoted text obviously) is to be in lowercase. 507 | 508 | All table names should use the `#__` prefix to access Joomla content and allow for the user defined database prefix to be applied. Queries should also use the JDatabaseQuery API. Tables should never have a static prefix such as `jos_`. 509 | 510 | To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code. 511 | 512 | Use Query chaining to connect a number of query methods, one after the other, with each method returning an object that can support the next method, This improves readability and simplifies the resulting code. Since the Joomla Framework was introduced "query chaining" is now the recommended method for building database queries. 513 | 514 | Table names and table column names should always be enclosed in the `quoteName()` method to escape the table name and table columns. 515 | Field values checked in a query should always be enclosed in the `quote()` method to escape the value before passing it to the database. Integer field values checked in a query should also be type cast to `(int)`. 516 | 517 | ```php 518 | // Get the database connector. 519 | $db = JFactory::getDbo(); 520 | 521 | // Get the query from the database connector. 522 | $query = $db->getQuery(true); 523 | 524 | // Build the query programatically (example with chaining) 525 | // Note: You can use the qn alias for the quoteName method. 526 | $query->select($db->qn('u.*')) 527 | ->from($db->qn('#__users', 'u')); 528 | 529 | // Tell the database connector what query to run. 530 | $db->setQuery($query); 531 | 532 | // Invoke the query or data retrieval helper. 533 | $users = $db->loadObjectList(); 534 | ``` 535 | 536 | #### Longer Chaining Example 537 | ```php 538 | // Using chaining when possible. 539 | $query->select($db->quoteName(array('user_id', 'profile_key', 'profile_value', 'ordering'))) 540 | ->from($db->quoteName('#__user_profiles')) 541 | ->where($db->quoteName('profile_key') . ' LIKE '. $db->quote('\'custom.%\'')) 542 | ->order('ordering ASC'); 543 | ``` 544 | 545 | #### Chaining With Select Array And Type Casting Of Integer Field Value Example 546 | ```php 547 | $query = $db->getQuery(true) 548 | ->select(array( 549 | $db->quoteName('profile_key'), 550 | $db->quoteName('profile_value'), 551 | )) 552 | ->from($db->quoteName('#__user_profiles')) 553 | ->where($db->quoteName('user_id') . ' = ' . (int) $userId) 554 | ->order($db->quoteName('ordering')); 555 | ``` 556 | -------------------------------------------------------------------------------- /manual/scss.md: -------------------------------------------------------------------------------- 1 | These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, namely: 2 | 3 | 1. [Code Guide](http://codeguide.co) (by @mdo) 4 | 5 | ### Commenting 6 | 7 | #### Major sections 8 | Major code sections should be named in caps and within a full comment block, eg: 9 | 10 | ```scss 11 | // Major comment 12 | // 13 | // Major comment description goes here 14 | // and continues here 15 | ``` 16 | 17 | #### Sub sections 18 | Subsections should be normally cased and within an open comment block. 19 | ```scss 20 | // 21 | // Sub section comment 22 | // 23 | ``` 24 | 25 | #### Basic comments 26 | ```scss 27 | // Basic comment 28 | ``` 29 | 30 | ### Class naming 31 | Use dashes to create compound class names: 32 | 33 | ```scss 34 | // Good - use dashes 35 | .compound-class-name {…} 36 | 37 | // Good - uses camelCase 38 | .compoundClassName {…} 39 | 40 | // Bad - uses underscores 41 | .compound_class_name {…} 42 | 43 | // Bad - does not use seperators 44 | .compoundclassname {…} 45 | ``` 46 | 47 | ### Indentation 48 | Rules should be indented with 2 spaces: 49 | 50 | ```scss 51 | // Good 52 | .example { 53 | color: #000; 54 | visibility: hidden; 55 | } 56 | 57 | // Bad - using tabs or 4 spaces 58 | .example { 59 | color: #000; 60 | visibility: hidden; 61 | } 62 | ``` 63 | 64 | SCSS should also be nested, with child selectors and rules indented again. Nested rules should also be spaced by one line: 65 | 66 | ```scss 67 | // Good 68 | .example { 69 | 70 | > li { 71 | float: none; 72 | 73 | + li { 74 | margin-top: 2px; 75 | margin-left: 0; 76 | } 77 | 78 | } 79 | 80 | } 81 | 82 | // Bad - nested rules indented with tab or 4 spaces 83 | .example { 84 | 85 | > li { 86 | float: none; 87 | 88 | + li { 89 | margin-top: 2px; 90 | margin-left: 0; 91 | } 92 | 93 | } 94 | 95 | } 96 | ``` 97 | 98 | ### Alignment 99 | The opening brace must be on the same line as the last selector and preceded by a space. The closing brace must be on its own line after the last property and be indented to the same level as the opening brace. 100 | 101 | ```scss 102 | // Good 103 | .example { 104 | color: #fff; 105 | } 106 | 107 | // Bad - closing brace is in the wrong place 108 | .example { 109 | color: #fff; 110 | } 111 | 112 | // Bad - opening brace missing space 113 | .example{ 114 | color: #fff; 115 | } 116 | ``` 117 | 118 | ### Declaration order 119 | Related property declarations should be grouped together following the order: 120 | 121 | 1. Positioning 122 | 2. Box model 123 | 3. Typographic 124 | 4. Visual 125 | 126 | ```scss 127 | // Good 128 | .example { 129 | // Positioning 130 | position: absolute; 131 | top: 0; 132 | right: 0; 133 | bottom: 0; 134 | left: 0; 135 | z-index: 100; 136 | 137 | // Box-model 138 | display: block; 139 | float: right; 140 | width: 100px; 141 | height: 100px; 142 | 143 | // Typography 144 | font-family: Arial, sans-serif; 145 | font-size: 14px; 146 | line-height: 1.2; 147 | color: #333; 148 | text-align: center; 149 | 150 | // Visual 151 | background-color: #f5f5f5; 152 | border: 1px solid #e5e5e5; 153 | border-radius: 3px; 154 | 155 | // Misc 156 | opacity: 1; 157 | } 158 | ``` 159 | 160 | Within each group, you'll also need to order the properties. If any mistakes are made, the compiler will notify you and provide the correct order 161 | 162 | ### Property Format 163 | Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon. 164 | 165 | ```scss 166 | // Good 167 | .example { 168 | background: black; 169 | color: #fff; 170 | } 171 | 172 | // Bad - missing spaces after colons 173 | .example { 174 | background:black; 175 | color:#fff; 176 | } 177 | 178 | // Bad - missing last semicolon 179 | .example { 180 | background: black; 181 | color: #fff 182 | } 183 | ``` 184 | 185 | ### HEX values 186 | HEX values must be declared in lowercase and shorthand: 187 | 188 | ```scss 189 | // Good 190 | .example { 191 | color: #eee; 192 | } 193 | 194 | // Bad 195 | .example { 196 | color: #EEEEEE; 197 | } 198 | ``` 199 | 200 | ### Attribute selectors 201 | Always use double quotes around attribute selectors. 202 | 203 | ```scss 204 | // Good 205 | input[type="button"] { 206 | ... 207 | } 208 | 209 | // Bad - missing quotes 210 | input[type=button] { 211 | ... 212 | } 213 | 214 | // Bad - using single quote 215 | input[type='button'] { 216 | ... 217 | } 218 | ``` 219 | 220 | ### Zero value units 221 | Zero values should not carry units. 222 | 223 | ```scss 224 | // Good 225 | .example { 226 | padding: 0; 227 | } 228 | 229 | // Bad - uses units 230 | .example { 231 | padding: 0px; 232 | } 233 | ``` 234 | 235 | ### Prefixing properties 236 | There is no need to prefix properties, as this will be automatically taken care of when compiling your code 237 | 238 | ```scss 239 | // Good 240 | .example { 241 | transform: rotate(30px); 242 | } 243 | 244 | // Bad - uses prefix 245 | .example { 246 | -webkit-transform: rotate(30px); 247 | transform: rotate(30px); 248 | } 249 | ``` 250 | 251 | ### End of file 252 | The end of the SCSS file should always have a blank line 253 | 254 | ```scss 255 | .example { 256 | padding: 0; 257 | } 258 | <<< Leave empty line here 259 | ``` 260 | -------------------------------------------------------------------------------- /manual/source-code-management.md: -------------------------------------------------------------------------------- 1 | Before we start talking about what Joomla! code should look like, it is appropriate to look at how and where the source code is stored. All serious software projects, whether driven by an Open Source community or developed within a company for proprietary purposes will manage the source code is some sort of source or version management system. The Joomla! project uses a Distributed Version Control System (DVCS) called Git hosted at [GitHub](https://github.com). 2 | 3 | ### The Joomla! Framework 4 | 5 | The [Joomla! Framework](https://github.com/joomla-framework) is a PHP framework that is designed to serve as a foundation for not only web applications (like a CMS) but other types of software such as command line applications. The files that form the Joomla! Framework are stored in a Distributed Version Control System (DVCS) called Git hosted at [GitHub](https://github.com). 6 | 7 | You can learn about how to get the Joomla Framework source code from the GitHub organisation, https://github.com/joomla-framework. 8 | 9 | Because Git treats the concepts of file revision numbers differently than Subversion, the repository revision number is not required in files (that is, the `@version` tag is not necessary). 10 | 11 | ### The Joomla! CMS 12 | 13 | The [Joomla! CMS](https://github.com/joomla/joomla-cms) is a Content Management System (CMS) which enables you to build Web sites and powerful online applications. It's a free and OpenSource software, distributed under the GNU General Public License version 2 or later. The files that form the Joomla! CMS are stored in a Distributed Version Control System (DVCS) called Git hosted at [GitHub](https://github.com). 14 | 15 | You can learn about how to get the Joomla CMS source code from the Git repository, https://github.com/joomla/joomla-cms. 16 | 17 | Because Git treats the concepts of file revision numbers differently than Subversion, the repository revision number is not required in files (that is, the `@version` tag is not necessary). 18 | 19 | ### Compliance Tool 20 | 21 | The standards in this manual have been adopted across the Joomla project, including the [Joomla! Framework](https://github.com/joomla-framework), the [Joomla! CMS](https://github.com/joomla/joomla-cms) and any other applications or extensions maintained by the project. These standards apply to source code, tests and (where applicable) documentation. 22 | 23 | A custom Joomla sniff standard for PHP files is maintained by the Joomla! project and available from the [coding standards](https://github.com/joomla/coding-standards) repository. The Sniff is based on the standard outlined in this document. For more information about how code standards are enforced see the analysis appendix of the manual. For information on using the Sniff see the documentation stored in its repository. 24 | -------------------------------------------------------------------------------- /manual/version.md: -------------------------------------------------------------------------------- 1 | Version 1.0 -------------------------------------------------------------------------------- /manual/xml.md: -------------------------------------------------------------------------------- 1 | ### Attributes 2 | 3 | * Each attribute is on its own line. 4 | * The four attributes `name`, `type`, `label` and `description` should be written in this order and at the top of the element definition. 5 | 6 | ### Closing Elements 7 | 8 | Elements should be closed with the closing tag on a new line. 9 | 10 | #### Exception 11 | 12 | When the element only has few attributes, then the whole element can stay on the same line. A max line length of 100 characters is recommended for good reading. 13 | 14 | ### Examples 15 | 16 | #### Element is **empty**: 17 | ```xml 18 |