Joomla! Documentation™

Joomla! 

4.x

Content is Incomplete

Suggestions etc

Suggestions are always welcome!

Just do not directly enter it into the page. Rather switch to the talk page and write down your thoughts. Or send an email to the author. Thanks

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 article Cookie notification explains what a cookie is.

Joomla! automatically creates such cookies to track the session and other information of visitors. Therefore, it might be necessary to provide appropriate notices. The Joomla! Framework itself does not include a feature to display cookie warnings.

A simple option would be to install one of the many Joomla! extensions that offer to present such a warning. extensions.joomla.org is the official Joomla! Extensions Directory^TM. The word cookie entered into the search field of this page will provide a multitude of free or paid extensions to handle cookies.

The installation of extensions bears certain risks

• What exactly is being installed?
• How does the extension influence the rest of the system?
• Does the extension conflict with other installed extensions?
• 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?
• How does the extension behave in the next major upgrade?
• Will the extension still be supported in the next version?
• Does the extension cost extra money and how much, once or repeating?

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

This tutorial assumes that Joomla! Version 4.x (in short J4) is installed and the administrator has a rough overview of the administration interface Atum, which is the default backend template for J4. (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 in 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 and leaving no residues.

Browser specifics in this tutorial refer to FireFox in a fairly current version.

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. A Site Module creates output for the end users. An Administrtor Module would create outbut in the administration interface.)

1. Click Custom to create a Custom Site Module.
2. Enter a Module Title (for Example: Cookie Warning).
3. 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.)
4. To define where to display the warning in the web page select the Position main-top. (That would be right under the page header before the content.)
5. Select to publish the warning. (If later anything gets messed up, just unpublish the module. Only published components are seen by end users.)
6. 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.

1. Open the Site Module again under Content -> Site Modules -> Cookie Warning.
2. Below the editor field click the button Toggle Editor to switch the editor to display the HTML source code of the cookie warning.
3. Notice the text in the editor field: <p>By using this site you accept cookies!</p>. (The surrounding <p> and </p> tags define the text as a paragraph in HTML.)
4. Add a Return or new line at the end of the existing code. Maybe add another one to make it look better.
5. Now copy the following code snippet below the existing text of the message.

<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>

We will discuss later what this code exactly is doing.

1. Now click Toggle Editor again and the I accept button should be visible. (If it looks ugly, the editor is not using Bootstrap.)
2. Click Save at the top of the page to store the change without closing the Modules: Custom page.
3. Now switch to the browser window showing the site view and refresh. You should not only see the warning, but also the button. (Refreshing may be done by clicking the circular icon or by pressing the F5 key. If it does not help try pressing Ctrl-F5.)

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

1. 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).
2. Following is an onclick="" attribute.
3. The onclick contains two JavaScript commands, each terminated with a ; (semicolon).
4. 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 the double quotes are already used by the onclick="" surrounding it.
5. The second statement sets a cookie in the clients browser with the name cookies and the content accepted.
6. 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 then sets a marker in the users browser to remember that he accepted the cookies.

The next part is a HTML tag which defines it's content to be JavaScript. This JavaScript is executed every time the browser wants to display the Cookie Warning.

The JavaScript tag is composed from the following:

1. The opening HTML <script> tag.
2. An if statement with a test in the round brackets ().
3. It tests for a cookie in the cache of the end users browser which is named cookies and has a content of accepted.
4. If that cookie exists the test result ist positive (true) and the commands in the curly brackets are executed.
5. In the curly braces is a command we already know. Hide the Cookie Warning.
6. The closing HTML </script> tag.

So what all of this is doing: If there is no such 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 every time the end user is visiting the website.

Start debugging

In the browser open the developer tools. In FireFox that is done with the key combination: Shift+Ctrl+I

At the very top of the debuging window select the Inspector tab and search for Cookie Warning. Check if the title, the message, the button and the script tag are all there. Should be fine.

Check if the cookie is created

1. Again at the very top of the debuging window select the Storage tab.
2. Open the Cookies file
3. Open your domain name, it should be there.
4. In the content area there should be at least 2 cookies. One is the Joomla! cookie for tracking your session. The other should be the cookie just set by clicking the I accept button.

Everything is fine until now.

Check if the class cookieWarning is used

There is only one more thing. If the cookie is there, the JavaScript tag is not doing its job correct.

1. Switch back to the Inspector tab of the debugging tools.
2. Enter #cookieWarning into the search field and press Return to jump to the Cookie Warning.

-- Ups, an Error! OK, let us try to enter Cookie Warning into the search field again. and analyse the HTML.

All kinds of classes, but no ID named cookieWarning!

That is easy to solve:

1. Open up the Site Module Cookie Warning in the administator window again, if it is not still open.
2. Toggle the editor to see the HTML code.
3. Notice that the editor added some more <p>...</p> tags. No problem, if it likes to see everything as a paragraph.
4. At the very top insert the following: <div id="cookieWarning">
5. Right above the <script> tag insert: </div>
6. So we gave our HTML a surrounding division tag with an ID of #cookieWarning.
7. Save the changes.
8. Refresh your browser end user browser window.

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.