Sub templates: Difference between revisions From Online Manual

Jump to: navigation, search
No edit summary
 
(Overhaul)
 
(12 intermediate revisions by 8 users not shown)
Line 1: Line 1:
I'm glad you asked. A sub template is what actually has the html in it. You can change, for example, the admin_login sub template to make the administrative password prompt look different. You 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.


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>// Show an error message...
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...
function template_fatal_error()
function template_fatal_error()
{
{
&nbsp;&nbsp;&nbsp;global $context, $settings, $options, $txt;
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>';


&nbsp;&nbsp;&nbsp;echo &#039;
// Show a back button (using javascript.)
&lt;table border=&quot;0&quot; width=&quot;80%&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;
echo '
cellpadding=&quot;4&quot; class=&quot;tborder&quot;&gt;
<div align="center" style="margin-top: 2ex;">
&nbsp;&nbsp;&nbsp;&lt;tr class=&quot;titlebg&quot;&gt;
<a href="javascript:history.go(-1)">', $txt[250], '</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;td&gt;&#039;, $context&#91;&#039;error_title&#039;], &#039;&lt;/td&gt;
</div>';
&nbsp;&nbsp;&nbsp;&lt;/tr&gt;
}
&nbsp;&nbsp;&nbsp;&lt;tr class=&quot;windowbg&quot;&gt;
</nowiki>}}
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;td style=&quot;padding-top: 3ex; padding-bottom: 3ex;&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#039;, $context&#91;&#039;error_message&#039;], &#039;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/td&gt;
&nbsp;&nbsp;&nbsp;&lt;/tr&gt;
&lt;/table&gt;&#039;;


&nbsp;&nbsp;&nbsp;// Show a back button (using javascript.)
== Creating and implementing a sub template ==
&nbsp;&nbsp;&nbsp;echo &#039;
=== Step 0: Make sure your template is loaded ===
&lt;div align=&quot;center&quot; style=&quot;margin-top: 2ex;&quot;&gt;
Please use loadTemplate() to load your template in the source files.
&lt;a href=&quot;javascript:history.go(-1)&quot;&gt;&#039;, $txt[250], &#039;&lt;/a&gt;
&lt;/div&gt;&#039;;
}</code>
Breaking it a part:


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>// Show an error message...</code>
=== Step 1: Choose a name ===
Is used for comments to guide and tell you what the following block of code is.
Name your sub template appropriately. For example, a media player showing a video could have its template called ''media_play_video''.


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>function template_fatal_error()
=== 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>
This is the sub template that will be executed upon an error.


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>global $context, $settings, $options, $txt;</code>
=== Step 3: Name your template function ===
This is a php declaration of some variables.
Assuming you are still using the example name above, you have to name the function.


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>echo &#039;
Sub templates are always prefixed with the ''template_'' prefix. So, for the example name,
&lt;table border=&quot;0&quot; width=&quot;80%&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;
<pre>function template_media_play_video()
cellpadding=&quot;4&quot; class=&quot;tborder&quot;&gt;
{
&nbsp;&nbsp;&nbsp;&lt;tr class=&quot;titlebg&quot;&gt;
// Your code here...
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;td&gt;&#039;, $context&#91;&#039;error_title&#039;], &#039;&lt;/td&gt;
}</pre>
&nbsp;&nbsp;&nbsp;&lt;/tr&gt;
&nbsp;&nbsp;&nbsp;&lt;tr class=&quot;windowbg&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;td style=&quot;padding-top: 3ex; padding-bottom: 3ex;&quot;&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#039;, $context&#91;&#039;error_message&#039;], &#039;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/td&gt;
&nbsp;&nbsp;&nbsp;&lt;/tr&gt;
&lt;/table&gt;&#039;;
</code>This is the actual HTML that will be shown (echo) to the browser. Note the use of $context there.


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>// Show a back button (using javascript.)</code>
== Common issues ==
Another comment.
=== 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.


<div class="codeheader">: <a href="javascript:void(0);" onclick="return smfSelectText(this);" class="codeoperation"></a></div><code>&nbsp;&nbsp;&nbsp;echo &#039;
&lt;div align=&quot;center&quot; style=&quot;margin-top: 2ex;&quot;&gt;
&lt;a href=&quot;javascript:history.go(-1)&quot;&gt;&#039;, $txt[250], &#039;&lt;/a&gt;
&lt;/div&gt;&#039;;</code>
Another block of HTML.


'''Next:''' [[http://docs.simplemachines.org/index.php?topic=226|" class="bbc_link">Where do I find the templates and sub templates?]]
[[category:Developing SMF]]
[[Category:Customizing SMF]]

Latest revision as of 16: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.


Advertisement: