Difference between revisions of "Sub templates"

From Online Manual

Jump to: navigation, search
m (Yoshi2889 moved page Okay, I'll bite... What's a sub template to Sub templates: Better title)
(Overhaul)
 
Line 1: Line 1:
A sub-template is what the HTML is in. For example, admins can change the admin_login sub-template to make the administrative password prompt look different. They could change the error sub-template to change what is displayed upon an error.
+
The template system in SMF consists of several components. One of them is the sub-template system.
  
It's important to note that sub-templates are grouped within templates. The error sub-template "template_fatal_error()" can be found in the Errors.template.php, just as shown below.
+
== What are Sub templates? ==
 +
A sub-template is what the HTML shown to users is in. For example, the board index is a sub template, found in BoardIndex.template.php. Sub templates consist of a function which gets called after the header, and before the footer. Therefore they make up the main content of the page.
  
 +
Sub templates contain HTML code and small bits of logic. You should not place full blocks of PHP code in the templates.
 +
 +
== Example of a sub template ==
 +
The following code is called as a sub template.
 
{{code|1=<nowiki>// Show an error message...
 
{{code|1=<nowiki>// Show an error message...
 
function template_fatal_error()
 
function template_fatal_error()
 
{
 
{
  global $context, $settings, $options, $txt;
+
global $context, $settings, $options, $txt;
  
  echo '
+
echo '
<table border="0" width="80%" cellspacing="0" align="center"
+
<table border="0" width="80%" cellspacing="0" align="center" cellpadding="4" class="tborder">
cellpadding="4" class="tborder">
+
<tr class="titlebg">
  <tr class="titlebg">
+
<td>', $context['error_title'], '</td>
      <td>', $context['error_title'], '</td>
+
</tr>
  </tr>
+
<tr class="windowbg">
  <tr class="windowbg">
+
<td style="padding-top: 3ex; padding-bottom: 3ex;">
      <td style="padding-top: 3ex; padding-bottom: 3ex;">
+
', $context['error_message'], '
        ', $context['error_message'], '
+
</td>
      </td>
+
</tr>
  </tr>
+
</table>';
</table>';
 
  
  // Show a back button (using javascript.)
+
// Show a back button (using javascript.)
  echo '
+
echo '
<div align="center" style="margin-top: 2ex;">
+
<div align="center" style="margin-top: 2ex;">
<a href="javascript:history.go(-1)">', $txt[250], '</a>
+
<a href="javascript:history.go(-1)">', $txt[250], '</a>
</div>';
+
</div>';
 
}
 
}
 
</nowiki>}}
 
</nowiki>}}
  
'''Breaking it down:'''
+
== Creating and implementing a sub template ==
 +
=== Step 0: Make sure your template is loaded ===
 +
Please use loadTemplate() to load your template in the source files.
  
Code:
+
=== Step 1: Choose a name ===
{{code|1=// Show an error message...}}
+
Name your sub template appropriately. For example, a media player showing a video could have its template called ''media_play_video''.
  
This is used for comments to guide and tell the admin what the following block of code is.
+
=== Step 2: Tell with source files what template you want ===
 +
In your source file, add the following code in the function that shows the video. Note that we are using the example name as set above.
 +
<pre>$context['sub_template'] = 'media_play_video';</pre>
  
Code:
+
=== Step 3: Name your template function ===
{{code|1=function template_fatal_error()
+
Assuming you are still using the example name above, you have to name the function.
 +
 
 +
Sub templates are always prefixed with the ''template_'' prefix. So, for the example name,
 +
<pre>function template_media_play_video()
 
{
 
{
 +
// Your code here...
 +
}</pre>
  
}
+
== Common issues ==
}}
+
=== Unable to load the 'main' template ===
 
+
This error can have two reasons:
In JavaScript, this is the sub-template that will be executed upon encountering an error.
+
* You have not told the sources what template to load. Please refer to step 2 in the guide.
 
+
* You have not loaded your template. Please refer to step 0 in the guide.
Code:
 
{{code|1=global $context, $settings, $options, $txt;}}
 
 
 
This is a PHP declaration of some variables.
 
 
 
Code:
 
{{code|1=<nowiki>echo '
 
<table border="0" width="80%" cellspacing="0" align="center"
 
cellpadding="4" class="tborder">
 
  <tr class="titlebg">
 
      <td>', $context['error_title'], '</td>
 
  </tr>
 
  <tr class="windowbg">
 
      <td style="padding-top: 3ex; padding-bottom: 3ex;">
 
        ', $context['error_message'], '
 
      </td>
 
  </tr>
 
</table>';</nowiki>}}
 
 
 
This is the actual HTML that will be sent to the browser. Note the use of the previously declared variable, $context.
 
 
 
Code:
 
 
 
{{code|1=// Show a back button (using JavaScript.)}}
 
 
 
This is another comment.
 
 
 
Code:
 
{{code|1=    <nowiki>echo '
 
<div align="center" style="margin-top: 2ex;">
 
<a href="javascript:history.go(-1)">', $txt[250], '</a>
 
</div>';</nowiki>}}
 
  
This is some more HTML code that will be sent to the browser.
 
  
 
[[category:Developing SMF]]
 
[[category:Developing SMF]]
 
[[Category:Customizing SMF]]
 
[[Category:Customizing SMF]]

Latest revision as of 12:37, 21 July 2014

The template system in SMF consists of several components. One of them is the sub-template system.

What are Sub templates?

A sub-template is what the HTML shown to users is in. For example, the board index is a sub template, found in BoardIndex.template.php. Sub templates consist of a function which gets called after the header, and before the footer. Therefore they make up the main content of the page.

Sub templates contain HTML code and small bits of logic. You should not place full blocks of PHP code in the templates.

Example of a sub template

The following code is called as a sub template.

// Show an error message...
function template_fatal_error()
{
	global $context, $settings, $options, $txt;

	echo '
	<table border="0" width="80%" cellspacing="0" align="center" cellpadding="4" class="tborder">
		<tr class="titlebg">
			<td>', $context['error_title'], '</td>
		</tr>
		<tr class="windowbg">
			<td style="padding-top: 3ex; padding-bottom: 3ex;">
				', $context['error_message'], '
			</td>
		</tr>
	</table>';

	// Show a back button (using javascript.)
	echo '
	<div align="center" style="margin-top: 2ex;">
		<a href="javascript:history.go(-1)">', $txt[250], '</a>
	</div>';
}

Creating and implementing a sub template

Step 0: Make sure your template is loaded

Please use loadTemplate() to load your template in the source files.

Step 1: Choose a name

Name your sub template appropriately. For example, a media player showing a video could have its template called media_play_video.

Step 2: Tell with source files what template you want

In your source file, add the following code in the function that shows the video. Note that we are using the example name as set above.

$context['sub_template'] = 'media_play_video';

Step 3: Name your template function

Assuming you are still using the example name above, you have to name the function.

Sub templates are always prefixed with the template_ prefix. So, for the example name,

function template_media_play_video()
{
// Your code here...
}

Common issues

Unable to load the 'main' template

This error can have two reasons:

  • You have not told the sources what template to load. Please refer to step 2 in the guide.
  • You have not loaded your template. Please refer to step 0 in the guide.