Joomla 4.x-Tutorial - Entwicklung von Erweiterungen - Template - Parameters and Variables

Modify this post

Parameters make the template flexibly configurable in the backend. Perhaps a colour selection should be possible? The standard template Cassiopeia offers, among others, logoFile, siteTitle and siteDescription as parameters. We add a banner and social media icons.

For the impatient

Take a look at the changed programme code in the Diff Viewgithub.com/astridx/boilerplate/compare/t37...t38 and incorporate these changes into your development version.

Step by step

In this section we will look at parameters and see that there are circumstances where they work more intuitively than module chromes.

In the following overview, the newly added files are marked with a background and the changed ones are outlined.

Overview of the files edited in this chapter

New files

In this chapter only the image templates/facile/images/banner.jpg is added, which is displayed in the banner via CSS. I took this from the demo images of html5up.net and it is from unsplash.com.

Template

templates/facile/ index.php

We add code to the file templates/facile/ index.php so that a banner and social media icons can be inserted via parameters.

In HTML some characters, for example the less than sign < or the greater-than-sign >, have a special meaning. They are therefore written as HTML entitiesen.wikipedia.org/wiki/list_of_xml_and_html_character_entity_references if they are to be displayed as text. For example, &lt; is written instead of < and &gt; is written instead of >. When processing strings, it may happen that they contain such specific characters. These must then be converted so that they can be further processed as plain text. We offer in the tempalte a text input option via a form in the backend. However, we do not want HTML code to be injected via this. This is a security risk. To prevent this, we use the function htmlspecialchars(https://www.php.net/manual/en/function.htmlspecialchars.php). This ensures that the characters that have a special meaning in HTML are converted to plain text.

Take a look at the code snippet below. I think the HTML code is self-explanatory.

templates/facile/ index.php

         </nav>
         <?php endif; ?>

       <?php if ($this->params->get('showBanner')) : ?>
       <section id="banner">
           <div class="content">
               <h2><?php echo htmlspecialchars($this->params->get('bannerTitle')); ?></h2>
               <p><?php echo htmlspecialchars($this->params->get('bannerDescription')); ?></p>
               <a href="#main"
                   class="button scrolly"><?php echo htmlspecialchars($this->params->get('bannerButton')); ?></a>
           </div>
       </section>
       <?php endif; ?>

         <section id="main">
             <div class="container">
                 <div class="row gtr-200">

         </section>

         <footer id="footer">
           <?php if ($this->params->get('showFooter')) : ?>
           <div class="col-12">
               <section>
                   <?php
                       $fieldValues = $this->params->get('showFooterTouchFields');

                       if (empty($fieldValues))
                       {
                           return;
                       }

                       $html = '<ul class="contact">';

                       foreach ($fieldValues as $value)
                       {
                           $html .= '<li><a class="icon brands ' . $value->touchsubicon . '" href="' . $value->touchsuburl . '"><span class="label">' . $value->touchsubname . '</span></a></li>';

                       }

                       $html .= '</ul>';

                       echo $html;

                   ?>
               </section>
           </div>
           <?php endif; ?>


             <?php if ($this->countModules('footer', true)) : ?>
             <div id="copyright">
                 <jdoc:include type="modules" name="footer" />
templates/facile/language/en-GB/tpl_facile.ini

We use the language files for the labels of our backend form. This way the texts can be translated into different languages.

templates/facile/language/en-GB/tpl_facile.ini

 TPL_FACILE_XML_DESCRIPTION="Facile is a Joomla 4 template."
;params
TPL_FACILE_BANNER_FIELDSET_LABEL="Banner"
TPL_FACILE_BANNER_FIELDSET_DESC="Please copy banner image file to /templates/facile/images/banner.jpg"
TPL_FACILE_BANNER_LABEL="Show Banner"
TPL_FACILE_BANNER_TITLE="Title text"
TPL_FACILE_BANNER_TAGLINE="Tagline text"
TPL_FACILE_BANNER_BUTTON="Button text"
TPL_FACILE_FOOTER_FIELDSET_LABEL="Social Footer"
TPL_FACILE_FOOTER_FIELDSET_DESC="For example: https://fontawesome.com/icons/facebook?style=brands"
TPL_FACILE_FOOTER_LABEL="Show Social Footer"
TPL_FACILE_GET_IN_TOUCH="Social Link"
TPL_FACILE_GET_IN_TOUCH_SUBNAME="Name"
TPL_FACILE_GET_IN_TOUCH_SUBICON="Icon"
TPL_FACILE_GET_IN_TOUCH_SUBURL="URL"
templates/facile/templateDetails.xml

Since Joomla supports us in creating the form fields, it is enough to define the fields via an XML file.

In order to display one form field in dependency to another, we use showon. showon="showBanner:1" ensures that the current field is only shown if the showBanner field has the value 1.

The field of type type="subform" provides the possibility to flexibly define the number of values in the backend form. Thus, with one form field it is possible to insert either only one link to Facebook or to display many social media channels.

templates/facile/templateDetails.xml

 		<position>footer</position>
 		<position>debug</position>
 	</positions>
	<config>
		<fields name="params">
			<fieldset name="banner" label="TPL_FACILE_BANNER_FIELDSET_LABEL" description="TPL_FACILE_BANNER_FIELDSET_DESC">
				<field
					name="showBanner"
					type="radio"
					label="TPL_FACILE_BANNER_LABEL"
					layout="joomla.form.field.radio.switcher"
					default="0"
					filter="integer"
					>
					<option value="0">JNO</option>
					<option value="1">JYES</option>
				</field>

				<field
					name="bannerTitle"
					type="text"
					default="Welcome to the Joomla version of TXT by HTML5 UP"
					label="TPL_FACILE_BANNER_TITLE"
					filter="string"
					showon="showBanner:1"
				/>

				<field
					name="bannerDescription"
					type="text"
					default="A free responsive site template built on HTML5, CSS3, and some other stuff"
					label="TPL_FACILE_BANNER_TAGLINE"
					filter="string"
					showon="showBanner:1"
				/>

				<field
					name="bannerButton"
					type="text"
					default="Alright let's go"
					label="TPL_FACILE_BANNER_BUTTON"
					filter="string"
					showon="showBanner:1"
				/>
			</fieldset>
			<fieldset name="footer" label="TPL_FACILE_FOOTER_FIELDSET_LABEL" description="TPL_FACILE_FOOTER_FIELDSET_DESC">
				<field
					name="showFooter"
					type="radio"
					label="TPL_FACILE_FOOTER_LABEL"
					layout="joomla.form.field.radio.switcher"
					default="0"
					filter="integer"
					>
					<option value="0">JNO</option>
					<option value="1">JYES</option>
				</field>

				<field
					name="showFooterTouchFields"
					type="subform"
					label="TPL_FACILE_GET_IN_TOUCH"
					multiple="true"
					max="10"
					showon="showFooter:1"
					>
					<form>
						<field
							name="touchsubname"
							type="text"
							label="TPL_FACILE_GET_IN_TOUCH_SUBNAME"
							/>
						<field
							name="touchsubicon"
							type="text"
							label="TPL_FACILE_GET_IN_TOUCH_SUBICON"
							/>
						<field
							name="touchsuburl"
							type="url"
							label="TPL_FACILE_GET_IN_TOUCH_SUBURL"
							size="30"
							filter="url"
							validate="url"
							/>
					</form>
				</field>
			</fieldset>
		</fields>
	</config>
 </extension>

The Joomla documentation docs.joomla.org/Form_field provides an overview of all possible form fields.

Test your Joomla template

  1. install your template in Joomla version 4 to test it:

Copy the files in the templates folder to the templates folder of your Joomla 4 installation.

A new installation is not necessary. Continue using the ones from the previous part. In any case you should make sure that the template style Facile is active. In my examples the Blog sample files are installed.

  1. activate the banner in the template style of Facile and see the result in the frontend.

Create Joomla Template - Banner via parameters in the frontend

Create Joomla Template - Banner via parameters in the backend

  1. activate the social media display in the template style of Facile and see the result in the frontend.

Create Joomla Template - Social Media Backend

Create Joomla Template - Social Media Frontend

Modify this post

Comments