Manipulating Sections in Gantry

Currently Sections in Gantry, adding, removing, moving and to some extent the styling has to be done manually. Some Preconfigured Sections can has some of their CSS styling set in the admin area under ‘Section Styles’ on the Styles page.

This process outlines how you can manipulate or style the Sections as you want.

Clone the Base Outline (common)

Create your own Outline that you can alter which will leave the core files alone and mean your changes will not get wiped out upon update. You need to do this no matter how you want to manipulate sections.

• Within Joomla, click on any joomla gantry template (ie. Helium - Default) in the 'Template: Styles' section of joomla, it does not matter which
• Click on Outlines (at the top)
• Clone the 'Base Outline'. Give it a suitable title and untick the inherit option (we do not want to inherit because we want to fully edit this template)
• The new outline/Template should be called something like 'Helium - Test'. It will be given an ID number. When saved this will create a new Joomla Template with this name in the 'Template: Styles' section of joomla with the same ID number. Make a note of this ID.

Change the Outline Preview Image

Changing the outline preview image is a useful thing to do by quickly showing the end user what the layout will be like.

• Gantry Docs – Preset Images
• The current Layout Preset images are stored at SITE_ROOT/administrator/components/com_gantry5/images/layouts/
• They are 200 x 250
• You can use the other ones that are already present in the template by just altering the link in the g5_helium/custom/config/{ID Number}/layout.yaml

Custom Image

• Place a preview image(200 x 250) g5_helium/custom/images/admin/layouts/example.png
• Edit the file g5_helium/custom/config/{ID Number}/layout.yaml
• Find image: 'gantry-admin://images/layouts/default.png' and change it to gantry-media://admin/layouts/example.png
  

Clone Notes

We now have a template file that we can alter as needed but you should just read these notes before continuing

• Edit the file g5_helium/custom/config/{ID Number}/layout.yaml to add/remove/move the sections as required. This has to be done via text editor currently.
• You can add modules, module positions, particles and lots of other things by editing the layout.yaml directly but I would only do this for sections as you can edit most other things through the Gantry admin visually and this is not only easier means there will be no errors in your text editing and as the scss pre-processor is very picky things could break.
• Edit the new Theme Outline 'Helium - Test' via the gantry admin to add sections and modules positions visually
• The ‘Base Outline’ (g5_helium/layouts/default.yaml) is already overridden by (g5_helium/custom/config/default/layout.yaml) so you can edit the Base Outline to your requirements without those changes getting wiped out upon upgrade.
• You cannot just edit g5_helium/custom/config/default/layout.yaml (Base Outline) to add/remove sections and see the changes immediately because although is editable, these sections will not be added to child outlines that have already been created. Child themes look at their sections and if set to inherit settings from the ‘base outline’ go and get those settings from the Base Outline. However adding/removing a section to the Base outline does not apply that operation to any Child Outline’s layout (any Outline inheriting from the Base Outline) which is a separate entity and is not updated by this process meaning the changes to sections you have just made will not be reflected.
• If you clone the ‘Base Outline’ after adding/removing sections then these changes would be reflected in the new child outline.
  

Add Sections

• Adding a Section to an Existing Layout Preset (Official Doc)
• Creating Layout Presets (Official Docs)

The process

Using the example we created above, look at the 2 files

• g5_helium/custom/config/{ID}/index.yaml (this file is updated when you save the layout in gantry admin with configuration settings and also stores the preview image location)
• g5_helium/custom/config/{ID}/layout.yaml (this is the text based layout file)

Looking at the layout.yaml there are 2 areas where sections are referenced, we only need to alter 1 as Gantry creates the other.

At the top there is the 'layout:' section and here you add a reference where you want to put your section, we will call our new section ‘testsection’. You need to put this reference where you want the section to appear. Refer to the Gantry documentation for further information.

The 'structure:' section at the bottom will be populated by gantry when you save the layout in the gantry admin. You can write this in manually but why bother if Gantry will do it. The 'structure:' is just styling information for the section

Don’t Use Tabs

Examples

## An empty testsection
layout:
/testsection/: { }

## testsection with a branding particle
layout:
/testsection/:
   -
     - branding-2200

Once you have made your changes, save the text file and browse to the layout page of the ‘Helium – Test’ outline and you should see your new section.

Styling using custom.scss

This is by far the easiest method of stying the section. The section id is always the same as the section name with ‘g-‘ prepended:

<section id="g-testsection">…</section>

So you would just use a the custom.scss for adding either CSS or SCSS styling the element as normal. This file should be placed at g5_helium/custom/scss/custom.scss and it will get parsed by gantry

.g-testsection{
   background-color: red;
}

If you style by this method you do not needs to style via the admin method shown below but you can mix and match however you want.

• create a file at THEME_DIR/custom/scss/custom.scss (use normal css or scss , less?)
• Adding a Custom Style Sheet (official doc)
  

Add Section to Gantry’s Section Styles (optional)

When designing a template for the end user you might like to configure the Gantry admin to allow the user to edit the new section’s settings just like the others in the backend rather than a text file. This takes a little more effort but is fairly easy to achieve.

1. Create a Admin Styles Config File for testsection . This contains the input types and their default values (when not inheriting).

1. Copy the file g5_helium/blueprints/styles/above.yaml to g5_helium/custom/blueprints/styles/testsection.yaml
2. You can just create this file from scratch if you know what you are doing but copying one that is already done is easier
3. Edit g5_helium/custom/blueprints/styles/testsection.yaml and change the name to ‘Test Section’ or whatever you want and also change the description.

2. Create a SCSS file for the config options. This is the SCSS code that will use the values you set to make the final CSS

1. Copy g5_helium/scss/helium/sections/_above.css to g5_helium/custom/scss/helium/sections/_testsection.scss
2. You can just create this file from scratch if you know what you are doing but copying one that is already done is easier
3. Change the CSS / SCSS identifiers so they match for testsection

• #g-above à #g-above
• $above-background à $testsection-background
• $above-text-color à $testsection-text-color

3. These _testsection.scss now needs to be picked up by Gantry. Override the helium.scss which controls scss file imports and add a reference to your section in it.

1. Copy g5_helium/scss/ helium.scss to g5_helium/custom/scss/helium.scss
2. edit g5_helium/custom/scss/helium.scss
3. find the // SECTIONS STYLING and add the following at the end of that section.
   

    // Test Section
    @import "helium/sections/testsection";

4. you will notice it does not point at the _testsection.scss override file we created earlier. It is not required to either create a file in the defined location shown above or point it directly to the override file (you can if you want) as Gantry will always look for overrides of these files first in the correct override locations, and in this case it finds one.
   

Preset Styles for Sections

Style settings that are configured in Gantry admin can also be subject to Preset Styles where you can quickly change colour schemes. These settings work as long as you have not configured any overrides in the style settings and you allow the presets to be inherited. Only the ones where you have set to specific values will not be affected.

The sections you have created will not have any settings configured in the when using the Preset Styles. This is not a problem as they still work as expected.

You cannot override the g5_helium/gantry/presets.yaml , you would need to edit it directly which is not advised.

https://github.com/gantry/gantry5/issues/306 - the issue is logged at GitHub

Remove Sections

When you have removed sections from the Helium template you will still have the section configs in the Gantry admin. This is how to remove them without altering core files of your Gantry template. These instructions use 1 example section but you need to do it for all sections you want to remove.

I will be using the Above Section as an example.

1. Remove the section from the layout / Outline File

1. edit the file g5_helium/custom/config/{ID}/layout.yaml
2. remove the following section code from ‘layout:’
   

   /above/: { }
   
   or it might look like
   
   /above/:
      -
        - custom-4582

2. Remove ‘structure:’ code. You have 2 options.

• Manually remove by finding and removing the code shown below in ‘structure:’ section.
  

  above:
     type: section
     attributes:
       boxed: ''

• Or once you have removed the ‘layout:’ part of the code as shown above and saved it, you can go to the layout page in the Gantry admin and save the layout there and then Gantry will remove the corresponding ‘structure:’ code for you.

3. Remove the Gantry Admin Section Styles

• Create an empty file at g5_helium/custom/blueprints/styles/above.yaml
• This overrides basically overrides the above admin settings but with nothing

4. Remove the SCSS code (optional, just for completeness seeing as it is not used anymore)

1. Copy g5_helium/scss/ helium.scss to g5_helium/custom/scss/helium.scss
   (if not already done)
2. edit g5_helium/custom/scss/helium.scss
3. find the // SECTIONS STYLING and comment out or remove the following section.
   

   // Above
   @import "helium/sections/above";

   You can in theory override the section SCSS files with an empty file which should have the same effect but it is not a preferred option as you get loads of files you don’t want.

Nested Sections

These are not used all that often in basic sites but I will show you an example. Without a clear example this process can be tricky and the only file involved is listed below. I thinks a nested section's primary role is to allow you to specify section width such as a left and right column.

• g5_helium/custom/config/{ID}/layout.yaml (this is the text based layout file)

Nested Sections shown on the layout page

You can see that there is an area called 'Container' and this holds the nested sections (Content-left, Mainbar, Content-right).

Nested Sections Yaml

I have only included the section shown above. Dont forget the indentations are done by spaces and not tabs

  /content-top/:
    -
      - position-position-6933
  /container-main/:
    -
      -
        'content-left 25':
          -
            - position-position-4734
      -
        'mainbar 50':
          -
            - position-position-2880
          -
            - system-messages-7485
          -
            - system-content-1587
          -
            - position-position-8425
      -
        'content-right 25':
          -
            - position-position-3949
  /content-bottom/:
    -
      - position-position-8044

How To

Just use the format above. I am not sure how to describe the exact syntax but 2 spaces is the indentation size you can see in the example above, which works.

Override System Outlines

Gantry comes with outlines for some system pages

• Body Only
• Error
• Offline

You need to override these and configure them how you wish because they probably will not fit in with your new layout. Things will still work if you do not. Use the Gantry Admin to make these changes.

Sections are referenced

For some reason sections are referenced in the following files that are not directly part of the outline layout.

• g5_helium/gantry/presets.yaml – Preset Style values (which includes sections)
• g5_helium/gantry/theme.yaml – not sure why they are referenced here, maybe a legacy thing

I don’t think I need to alter any of these for my options above but just incase I have listed them here.

Replace the Default template with my new layout

Now I have created my new layout with my new admin configurations (optional) I want to make it the ‘Base Outline’. You do not have to do this but it probably is better if you are going to distribute the template.

NB I should just be able to copy my new theme over the top of the /default/ , but be aware that the other outlines might stop working properly?

• Then delete all other templates
• Clone the base outline and inherit
• You now have your new template with sections and you can alter the base outline and all changes will be reflected