[4.0] Cassopeia template and blog sample data fixes and improvements

[richard67]

Pull Request for Issues #30812 , #30680 , #30515 , #30442 , #30426 , #29504 , #29311 , #29138 , #25239 , #24129 and possibly more which haven't been identified yet.

Summary of Changes

Introduction

This pull request (PR) is the result of the work of the Frontend Template Working Group (JEDT - FT) in the recent few months for improving Cassiopeia, the default site template of Joomla 4.0.

Beside fixing template-specific issues and bugs, our task was to make Cassiopeia be a good showcase for new features in Joomla 4.0, together with improved sample data and without introducing any additional third-party dependencies.

Development took place in the Cassiopeia repository on GitHub, so there you can find why things have been done like you can see them here.

The implementation was mainly done by following contributors (in alphabetical order):
@chmst , @drmenzelit , @hans2103 and @richard67

But of course we had some help, therefore our special thanks goes to (in alphabetical order)
@brianteeman , @ciar4n , @helvecio , @infograf768 and @N6REJ
for advice, support, testing and contribution.

Improved Template Structure - HTML and SCSS

The structure of the template has got countless small changes and a new, clear structure for SCSS files. The header has got a new structure. Module positions are the same as before.

New Error and Offline Site

The error and offline pages have been rewritten so they match the structure of the template's index.php and use the new features like colour themes or fonts schemes.

Accessibility Improvements

Not only for the template itself (colours, font sizes), but also in layouts of the Joomla core many improvements for accessibility have been made, especially in the search module and search result page.

• Colour contrast ratio is AA over the whole template.
• Font Size and Line Height are user friendly.
• For icons and images, aria labels and alt-texts are carefully used .
• All elements are included in landmarks .
• The elements and the dropdown menu (metismenu) are accessible also for keyboard users.
• Font size and family for frontend editing have been improved.

Many a11y improvements which we have found during this project were made in layouts of the Joomla core with other pull requests, but there are still some issues left in the Joomla frontend (e.g. structure of headings) where further improvement is needed.

Accessible Dropdown Menu

Currently Joomla 4 and the Cassiopeia template don't provide an accessible dropdown menu which can be used in horizontal or vertical orientation. Bootstrap classes like e.g nav-pills don't work like they did in Joomla 3.

Because the impact on the default layout of the menu module would have been to large and possibly not b/c, we have decided not to fix that.

Instead of this we have decided to provide an accessible dropdown menu with the template as alternative layout for the menu module:

There was much discussion with pros and cons if we should have made it an alternative layout provided by the module, so it can be used by other templates, too, without having to copy the files.

We have decided against it, but if it is desired to change it that way, it can be done with a future PR.

And we have decided to use metismenujs, the vanilla JS variant of metismenu, because it is already used in the Atum backend template.

Fonts Schemes

In the Protostar template in Joomla 3 it is possible to switch off Google Fonts. When switched on, the necessary CSS is added as inline CSS, when switched off, the default font-family from Bootstrap CSS is used.

In Joomla 4 inline CSS has been removed, and so the Google Fonts can't be switched off. This is not compliant to GDPR. Also for GDPR compliance, people might want to use previously downloaded web fonts from a local folder.

To make both possible, we have implemented Fonts Schemes.

A Fonts Scheme is nothing else than an (S)CSS file which imports the CSS for local fonts or web fonts and sets CSS variables (instead of creating inline CSS) for font family and weight for headings and text.

"Fonts Scheme" and not "Font Scheme" because different fonts can be used for headings and body.

To have some example for everything, we have decided to provide following Fonts Schemes:

• "None" means loading any local fonts or web fonts is switched off, and the font-family from CSS is used like it would be set by Bootstrap 4. This might look different on different browser and OS but is compliant with GDPR and doesn't have any impact on page load times or server load. This is the default setting on a new installation.
• "Roboto (local)" uses the local Roboto font which is already used for the Atum backend template.
• "Fira Sans (web)" uses the "Fira Sans" font from Google Fonts, like is is now in the Cassiopeia template without this PR.
• "Roboto + Noto Sans (web)" uses the "Roboto" fonts for headings and the "Noto Sans" font for other text, both from Google Fonts. In opposite to the other fonts schemes, headings have normal font weight here for a more tiny look and to have an example for that.

Using local fonts is compliant with GDPR but may have an impact on server load and (if not HTTP/2) on page load times.

Using fonts from web might not be compliant with privacy regulations like GDPR but doesn't have such performance impacts.

Fonts Schemes can also be defined to use other web fonts than Google Fonts.

Colour Themes

In the Protostar template in Joomla 3 it is possible to switch on or off template-specific colours. If switched on, some inline CSS is added for some basic colouring, but without certain effects as you can have without template colours like e.g. gradients.

In Joomla 4 inline CSS has been removed, and so there is no way to change template colours.

Therefore we have implemented Colour Themes.

A Colour Theme is nothing else than an (S)CSS file which sets CSS variables for the template.

The template comes with 2 Colour Themes:

• Standard
  This is the default theme for which we have optimized colours so everything looks well together.
• Alternative
  This is just an example on how to implement another colour scheme. It can be optimized with future PRs, if desired.

New Template Style Parameters in backend

For the 2 new features "Fonts Schemes" and "Colour Themes", new fields have been added to Cassiopeia's template style parameters.

Blog Sample Data (English)

Blog Sample Data has been updated by new images and a dropdown menu example and has been extended by examples for tags, custom fields and different list and blog views, and a typography page has been added.

Other Improvements

The back-to-top link which can be switched on in template style parameters has been improved so that it appears when scrolling down, then remains on a fixed position while further scrolling, and disappears after having scrolled up to the top.

Testing Instructions

Preparation

Attention: This PR can't be tested with Patchtester because the patch is too big.

If you have a development environment for Joomla 4, i.e. a git client and composer and npm, checkout the 4.0-dev-cassiopeia-development branch from my fork, run "composer install" and "npm ci" and then make a new installation.

If you don't have that, use the following package to make a new installation: https://ci.joomla.org/artifacts/joomla/joomla-cms/4.0-dev/31520/downloads/38001/Joomla_4.0.0-beta6-dev+pr.31520-Development-Full_Package.zip

Optionally, set up a multilingual site.

After setup has completed, log in to backend.

On a multilingual site, either install "Multilingual Sample Data" or do the necessary steps (enable language filter plugin, publish content languages, create home menu items) manually.

Finally install "Blog Sample Data". On a multilingual site, change backend language and install "Blog Sample Data" again a few times to have it at least installed for some of the content languages.

Basic Tests

• Check which js files and css files are loaded in the frontend.
• Explore what is available in the Main Menu Blog dropdown menu in the header area.
• Check the different types of layouts. Change layout parameters in backend and check again.
• Play with template style options in backend, not only those added by this PR, and check the result in frontend.
• Test both without being logged in to the frontend and also as logged user with edit permissions.
• Test everything also RTL, either by using an RTL language in frontend, or by editing language/en-GB/langmetadata.xml and changing <rtl>0</rtl> to <rtl>1</rtl>.
• Test everything also with small screen sizes for mobile clients.
• Check also the error and the offline page.

Tests for Dropdown Menu

Modify the "Main Menu Blog" so that it has a deeper structure, i.e. more levels of submenus.

Make several copies of the "Main Menu Blog" module. Publish these copies at different module positions, e.g. "top-a", "breadcrumbs", "main top", "sidebar-left" or "sidebar-right" and "footer".

At different module positions where horizontal menus make sense, i.e. mainly not in the sidebars, add module class "menu-horizontal" in advanced module parameters, and check the result in frontend.

Check that the horizontal menus become vertical on small screens for mobile clients.

Test all dropdown menus with different module styles like "card", "noCard" and others.

And don't forget to test RTL for any kind of menu, horizontal or vertical.

For Advanced Testers: Modify the template

In backend, go to "System -> Site templates -> Cassipeia Details and Files", and create a copy of the template.

Modify the copy e.g. by adding a user.css or using your own fonts, images, own css framework and own modules.

You can add a new fonts scheme by copying and modifying one of the existing files /templates/cassiopeia/scss/global/fonts-local_*.scss or /templates/cassiopeia/scss/global/fonts-web_*.scss, depending if fonts shall be loaded from a local folder or from web, if you can compile SCSS files. If you can't compile SCSS files, you can copy and modified the CSS files /templates/cassiopeia/css/global/fonts-local_*.css or /templates/cassiopeia/css/global/fonts-web_*.css instead. Finally add a new value to the right group (local fonts of web fonts) of the useFontScheme field in the template's templateDetails.xml file, and you are done.

Same with colour themes: Either copy and modify one of the existing files /templates/cassiopeia/scss/global/colors_*.scss if you can compile SCSS files, or do that with one of the CSS files /templates/cassiopeia/css/global/colors_*.css.

The (S)CSS files are more or less self-explaining.

Actual result BEFORE applying this Pull Request

After installing blog sample data you get following out of the box:

You can not really see much of the advantages and improvements of Joomla 4.

After moving the "Main Menu Blog" module to module position "menu" and adding a Smart Search module on position "search":

As you can see, the colour of the search button doesn't really fit to the template.

The default menu layout is not really usable when having horizontal orientation, which is only possible on module positions in the header section of the template, e.g. position "menu".

The template always loads the Fira Sans font from Google Fonts in web, there is no way to switch that off or change to locally hosted fonts.

The error page looks as follows with the "Main Menu Blog" module configured as before:

Expected result AFTER applying this Pull Request

After installing blog sample data you get following out of the box, here on the "Home" page:

Blog view:

There are no fonts loaded because the Font Scheme is set to "None". Therefore the fonts may differ between browsers, but this is safe regarding GDPR and site performance.

The same blog view with Font Scheme "Roboto + Noto Sans (web)":

Dropdown menu and available sample layouts:

In the sidebars, the dropdown menu behaves like an accordion:

Horizontal dropdown menu at main-top:

Same without title and with module layout "noCards":

The error page:

We could add a lot more screenshots, but we think the result speaks for itself.

Documentation Changes Required

The new template style parameters should be described in some documentation about the Cassiopeia template.

The dropdown menu should be described at a suitable place in documentation.

[richard67]

@Scrabble96 We have separator lines now when a separator item is not a parent.

Now only the overflow / word wrap issues are remaining.

[richard67]

@drmenzelit Thanks a lot for the separator fixes in the last commit.

[richard67]

Link to package in testing instructions will be updated as soon as the new package is ready.

[richard67]

Done.

[wilsonge]

@HLeithner has just told me he's tested this. I know for sure it's a step in the right direction. So merging this so that we have some incremental improvement and it starts being distributed in the nightlies

[chmst]

Thank you very much!

[richard67]

Now I need a holiday.

[alikon]

installing latest 4.0-dev.... got this one

[richard67]

Can't reproduce on a clean 4.0-dev branch.

Can it be you have old files on your branch?

Maybe a git clean -d -x -f and git checkout . and the run npm again will help?

[richard67]

@wilsonge We might have to update the list of files and folders to be deleted in script.php soon, latest before the next Beta (or RC?).

[alikon]

it's already a clean install

[richard67]

@alikon If you are working on the 4.0-dev branch of your fork, the following command sequence on your local git client's command line will reset the 4.0-dev branch of your fork (locally and remote) to the 4.0-dev branch of the CMS:

git checkout 4.0-dev
git remote update
git clean -d -x -f
git reset --hard upstream/4.0-dev
git push origin +4.0-dev

(assuming that the remote for your fork is called "origin" and the remote for the CMS repo is called "upstream")

[wilsonge]

I have no issues either running an install

[Magnytu2]

Hello everyone, I am currently testing this version in beta 6 with the new cassiopeia. I notice that the images that I resize in 16: 9 keep this proportion in the intro of the article, but that they are distorted in full article. I think it's a template issue. Can you check please?

[chmst]

@Magnytu2 This PR is already merged. Would you please open a new issue for that in the issue tracker, than it is active. Thank you!