Joomla! Documentation™

Under Construction

Abstract

This tutorial guides new Joomla administrators step-by-step through the implementation of a Custom Site Module. Along the way, simple HTML, CSS, JavaScript and testing options are explained.

Introduction

In some countries, there are legal requirements to issue a warning on websites when cookies are created. The page Cookie notification explains what a cookie is.

Joomla automatically creates such cookies to track the session of visitors. Therefore, it might be necessary to provide appropriate notices. Joomla itself does not offer such a feature.

A simple option would be to install one of the many Joomla extensions that offer to present such a warning.

The installation of extensions bears certain risks

• What exactly is being installed?
• How does the extension influence the rest of the system?
• How to remove the extension if it does not suit?
• Is there an uninstall function and is it complete or does it leave residues that affect the system?
• Does the extension even do something else that is not wanted?

All these risks would not exist creating an own cookie warning. Moreover, full control and learning a lot about Joomla, HTML, CSS and JavaScript would be the outcome.

This tutorial assumes that Joomla version 4 is installed and the administrator has a rough overview of the administration interface Atum, which is the default backend template for Joomla 4. (This tutorial should also be suitable for older Joomla versions, but is not tested in this context.)

Even though there are not so many differences in the procedure, this tutorial assumes that no extensions are installed. This means that the end user interface is Cassiopeia, the default site template for end users and Joomla 4.

Presumably there is already a main menu and a few articles. (In a very fresh test installation the sample data could be installed).

Beginners don't have to worry, everything that is created can be deactivated and also deleted with a few mouse clicks. That way restoring the original state.

So no more foreplay, let's get started.

Create a Site Module for the warning message

In administrator interface click Contents and besides Site Modules click the + sign. Or click Site Modules and then click New. This starts creation of a new module. (A module is a small component, which generates output on a Joomla web page.)

• Click Custom to create a Custom Site Module.
• Enter a Module Title (for Example: Cookie Warning).
• In the editor field write a message. Let's start with: By using this site you accept cookies! (We are going to enhance this later)
• Select the Position main-top (That would be right under the page header before the content)
• Select to publish the warning. (If later anything gets messed up, just unpublish the module. Only published components are seen by end users.)
• Leave everything else in it's default settings and click Save & Close at the top of the page

That's it. We have our warning. After opening the site view of the Joomla Website in a new browser window the warning should be displayed.

Create a button to hide the message

The way the Cookie Warning works by now is, that it is shown on every page. So lets add a button to hide the message.

• Open the Site Module again under Content -> Site Modules -> Cookie Warning
• Below the editor field click the button Toggle Editor to switch the editor to display the HTML source code of the cookie warning
• Now take the following code snippet and insert it below the existing message (Maybe a Carrige Return is needed to open a new line.)

<button class="btn btn-primary" type="button" onclick="
  document.getElementById('cookieWarning').style.display='none';
  document.cookie='cookies=accepted;max-age=315360000;path=/;';
">

I accept

</button>
<script>
   if (document.cookie == 'cookies=accepted')
      {document.getElementById('cookieWarning').style.display='none';}
</script>

• Now click Toggle Editor again and the I accept button should be visible. (If it looks ugly, the editor is not using Bootstrap)
• Click Save at the top of the page to store the change without closing the Modules: Custom page.
• Now switch to the browser window viewing the site view and refresh. You should not only see the warning, but also the button.

After clicking the button ...

Debugging the Cookie Warning

What happend? Nothing? Shouldn't the warning disappear when the button is clicked?

Before debugging, take a brief look at what the code is doing

• There is a HTML button tag with the attribute class="btn btn-primary" (these classes are used by bootstrap to format a nice button in the primary color).
• Following is an onclick="" attribute.
• There are two JavaScript commands, each terminated with a semicolon ";" inside of the onclick attribute.
• The first statement finds the HTML Tag with the ID #cookieWarning and gives it a CSS style of display: none; (it is in single quotes, because die double quotes are already used by the onclick="" surrounding it.
• The second statement sets a cookie in the clients browser with the content accepted.
• Last, the button gets a label of I accept and the HTML closing tag for the button.

So when the button is clicked by the end user, it finds the container of the Cookie Warning by looking for its ID, hides this from the user and than sets a marker in the uses browser to remember that he accepted the cookies.

The next part is a HTML tag which includes JavaScript. It is executed every time the brouser wants to display the Cookie Warning.

• The starting HTML <script> tag.
• An if statement whith test in the round brackets ()
• It tests for a cookie in the browser of the end user which says accepted.
• If that cookie exists, it executes the commands in the curly brackets.
• And that command wie already know. Hide the Cookie Warning.

So what all of this is doing: If there is no cookie in the end users browser, it displays the warning on every page displayed. If somewhen the user gets bored and clicks the button it hides the warning and remembers to hide it everytime the end user is visiting the website.

Now start debugging

So in the browser open the developer tools. In firefox that is Shift+Ctrl+I. In the Inspector tab search for Cookie Warning. Check if the title, the message, the button and the script tag are all there. Should be fine.

Now check if the class cookieWarning is used. -- Ups, all kinds of classes, but no class named cookieWarning!

That is easy to solve:

• Open up the Site Module Cookie Warning again, if it is not still open.
• Select the Advanced tab.
• In the Module Class field enter cookieWarning
• Save the changes.
• Refresh your browser.

Now it should work! Great!

A big warning

There are templates out there which do not take all those attributes and convert it into HTML. That means, if you are using such templates you might get alot of trouble debugging your code and the template is just not showing it to the browser.

If you have a add-on template installed always have a hidden menu by hand (a menue which is defined and has at least one Menu Item), but which is not connected to any Template Position. (And therefore not shown on the website) Then have this Menu Item displayed in the Cassiopeia template. By typing the Alias of this Menu Item behind the domain name in the browsers address field, it is always possible to access this testpage with Cassiopeia template for debugging.