phpBB

Development Wiki

Difference between revisions of "New Template Commands in 3.1"

From phpBB Development Wiki

(Update usage for event hooks and extensions)
(Add INCLUDECSS Information)
 
Line 8: Line 8:
 
<!-- INCLUDEJS {$DEFINEDVARIABLE} --></pre>
 
<!-- INCLUDEJS {$DEFINEDVARIABLE} --></pre>
  
Path to .js file should be relative to style directory. Function can accept template variables, as displayed in sample code above.
+
Path to .js file should be relative to style's template directory. Function can accept template variables, as displayed in sample code above.
  
 
Unlike using &lt;script&gt; tag, this command will put your script in the footer of the page between the inclusion of jQuery and &lt;/body&gt;, allowing you to use jQuery in your script. It will also check styles tree for location of your file, which works similar to template inheritance. Scripts will be outputted in the same order as they were parsed via INCLUDEJS.
 
Unlike using &lt;script&gt; tag, this command will put your script in the footer of the page between the inclusion of jQuery and &lt;/body&gt;, allowing you to use jQuery in your script. It will also check styles tree for location of your file, which works similar to template inheritance. Scripts will be outputted in the same order as they were parsed via INCLUDEJS.
Line 49: Line 49:
  
 
Only one template file per extension is included, so having template in ext/your_extension_vendor_name/package_name/styles/all/template and ext/your_extension_vendor_name/package_name/styles/prosilver/template will not include it twice.
 
Only one template file per extension is included, so having template in ext/your_extension_vendor_name/package_name/styles/all/template and ext/your_extension_vendor_name/package_name/styles/prosilver/template will not include it twice.
 +
 +
== INCLUDECSS ==
 +
This command queues external CSS files for inclusion in header.
 +
 +
Syntax: <pre><!-- INCLUDECSS file.css -->
 +
<!-- INCLUDECSS {VARNAME} -->
 +
<!-- INCLUDECSS {$DEFINEDVARIABLE} --></pre>
 +
 +
Path to .css file should be relative to style's template directory. Function can accept template variables, as displayed in sample code above.
 +
 +
Unlike using &lt;link&gt; tag, this command will put your CSS links in the header of the page before the closing head tag. It will also check styles tree for location of your file, which works similar to template inheritance. CSS files will be outputted in the same order as they were parsed via INCLUDECSS.
 +
 +
Example (used inside of the template event &lt;!-- EVENT overall_header_head_append --&gt;): <pre>header stuff here
 +
<!-- INCLUDECSS ../theme/custom1.css -->
 +
Some additional content
 +
<!-- INCLUDECSS ../theme/custom2.css --></pre>
 +
This will result in following HTML output:<pre>header stuff here
 +
Some additional content
 +
<link href="./ext/vendor/package/styles/prosilver/theme/custom1.css?assets_version=1" rel="stylesheet" type="text/css" media="screen, projection" />
 +
<link href="./ext/vendor/package/styles/prosilver/theme/custom2.css?assets_version=1" rel="stylesheet" type="text/css" media="screen, projection" /></pre>
 +
CSS files that were included via INCLUDECSS were placed in header, the same order as they were in the markup, before &lt;/head&gt; and path was changed to correct relative path to the .css file.

Latest revision as of 13:31, 8 August 2014

This article lists new template commands available in phpBB 3.1

INCLUDEJS

This command queues external javascript file for inclusion in footer.

Syntax:
<!-- INCLUDEJS file.js -->
<!-- INCLUDEJS {VARNAME} -->
<!-- INCLUDEJS {$DEFINEDVARIABLE} -->

Path to .js file should be relative to style's template directory. Function can accept template variables, as displayed in sample code above.

Unlike using <script> tag, this command will put your script in the footer of the page between the inclusion of jQuery and </body>, allowing you to use jQuery in your script. It will also check styles tree for location of your file, which works similar to template inheritance. Scripts will be outputted in the same order as they were parsed via INCLUDEJS.

Example (full sample page, so you could see where code will appear):
<!-- overall_header.html -->
	header stuff here
	<!-- INCLUDEJS custom1.js -->
<!-- end of overall_header.html -->
<!-- custom template -->
	Some content
	<!-- INCLUDEJS custom2.js -->
<!-- end of custom template -->
<!-- overall_footer.html -->
	<!-- INCLUDEJS {T_ASSETS_PATH}/javascript/custom3.js -->
	footer code here
	jQuery is included here
	</body>
</html>
<!-- end of overall_footer.html -->
This will result in following HTML output:
header stuff here
some content
footer code here
jQuery is included here
<script src="./styles/prosilver/template/custom1.js"></script>
<script src="./styles/prosilver/template/custom2.js"></script>
<script src="./assets/javascript/custom3.js"></script>
</body>
</html>

Script tag that was included via INCLUDEJS was moved to footer, the same order as they were in the markup, before </body> and path was changed to correct relative path to the .js file.

EVENT

This command is for event hooks.

Syntax:
<!-- INCLUDEJS @vendor_package/file.js -->
<!-- EVENT acp_overall_header_head_append -->

It will include code from overall_header_head.html template from current style and all extensions, allowing extensions to insert code without editing template files.

In extensions you should place such templates in directory ext/your_extension_vendor_name/package_name/styles/all/template If you want to include different templates for different styles, in addition to styles/all/ create directories for those styles, such as ext/your_extension_vendor_name/package_name/styles/prosilver/template. Those directories take priority when template is included, with "all" being lowest priority.

Only one template file per extension is included, so having template in ext/your_extension_vendor_name/package_name/styles/all/template and ext/your_extension_vendor_name/package_name/styles/prosilver/template will not include it twice.

INCLUDECSS

This command queues external CSS files for inclusion in header.

Syntax:
<!-- INCLUDECSS file.css -->
<!-- INCLUDECSS {VARNAME} -->
<!-- INCLUDECSS {$DEFINEDVARIABLE} -->

Path to .css file should be relative to style's template directory. Function can accept template variables, as displayed in sample code above.

Unlike using <link> tag, this command will put your CSS links in the header of the page before the closing head tag. It will also check styles tree for location of your file, which works similar to template inheritance. CSS files will be outputted in the same order as they were parsed via INCLUDECSS.

Example (used inside of the template event <!-- EVENT overall_header_head_append -->):
header stuff here
<!-- INCLUDECSS ../theme/custom1.css -->
Some additional content
<!-- INCLUDECSS ../theme/custom2.css -->
This will result in following HTML output:
header stuff here
Some additional content
<link href="./ext/vendor/package/styles/prosilver/theme/custom1.css?assets_version=1" rel="stylesheet" type="text/css" media="screen, projection" />
<link href="./ext/vendor/package/styles/prosilver/theme/custom2.css?assets_version=1" rel="stylesheet" type="text/css" media="screen, projection" />

CSS files that were included via INCLUDECSS were placed in header, the same order as they were in the markup, before </head> and path was changed to correct relative path to the .css file.