Add a homepage to your theme

In this tutorial we will explain how to add a nice-looking homepage to your empty theme.

Prerequisities

You have created your first theme (see the chapter Create the first empty theme)
You have some HTML template available (e.g. from Free CSS Templates, TemplateMonster or ThemeForest)

Introduction

In this tutorial we will build a homepage based on the theme created in Create the first empty theme tutorial. This means:

We'll use MyFirst as the theme name.
We'll use the WithoutSidebar layout.
We'll work with following sections in that layout: Header, Navigation, Section 1 and Footer.

If you are not familiar with layouts or sections, read the chapter Page - Layouts - Sections - Templates first.

Step 1: Copy all assets from the template to the theme

Copy all assets (Javascripts, CSS, fonts, images, ...) to following folder:

  src/
    Themes/
      MyFirst/
        Assets/

The structure and content of this Assets folder is completely up to you. You will link these files later in TWIG templates. However, we recommend to make it a bit of standard, so at least subfolders like js/, css/, fonts/, images/ will be created.

Step 2: Modify the Header.twig file

Open the file src/Themes/MyFirst/Templates/Plugins/WAI/Common/Header.twig in your preferred editor and modify it based on your template. This instruction seems to be quite easy but keep in mind:

You should use as many attributes from {{header}} variable, as possible
Links to your assets must be built using {{rootUrl}}/theme/assets prefix. If you are not sure, read the chapter Working with assets.
Do not forget to make your theme configurable using CSS variables like -theme-main-color: {{ settings.design.themeMainColor }};.

Debugging tip

If you want to see which attributes you have avaiable in the {{header}} variable, use dump(variableName) function:

<!DOCTYPE html>
<html class="no-js" lang="en">
<head>
  <!-- YOUR HTML HEAD -->
</head>
<body>
  {{ dump(header) }}
  <!-- REST OF YOUR HTML CODE -->

What you've learned

You have modified the Header.twig file using Surikata.io's some core template variables (the {{rootUrl}}) and some plugin's variables (like {{header}}). This file is a template for a WAI/Common/Header plugin that is used in the default installation.

Don't forget:

Core template variables are available in each template. For more information read the chapter List of default variables available in TWIG templates.
Each plugin can prepare its own variables. Check this list of default plugins.
If you would be a Surikata master, you could create your own plugin for rendering the header.

Step 3: Modify the Navigation.twig file

This step is pretty much the same only a bit more complex. The principles remain the same as in the Step 2 with these differences:

This is the template for WAI/Common/Navigation plugin. Different variables are available.
The content is rendered into the Navigation section

Debugging tip

If you want to see which variables you have avaiable, dump the {{system.availableVariables}}:

<!DOCTYPE html>
<html class="no-js" lang="en">
<head>
  <!-- YOUR HTML HEAD -->
</head>
<body>
  {{ dump(system.availableVariables) }}
  <!-- REST OF YOUR HTML CODE -->

Step 4: Create the content of the first section

If you remember, the default installation of the HelloWorld theme creates a website called "Home" with a slug "home". In the administration panel navigate to Websites -> HelloWorld -> Pages and open this page Home.

You should see the structure of the layout selected for this page (which is WithoutSidebar in our case) and the list of plugins that are configured to render the sections.

Finally, you should see that a WAI/SimpleContent/OneColumn plugin is used to render the Section 1.

Now a check question: Do you already know which template file you must modify to change the design of this section?

Congratulations, you're right! :-) Open the src/Themes/MyFirst/Template/Plugins/WAI/Common/SimpleContent/OneColumn.twig file and make your changes.

That's all, folks!

What you've learned:

Where in the administration panel is the content of the page configured.
Modifying template files is now a routine for you.

Step 5: Finalize your changes

Now it's only about the footer. Modify the template file for the WAI/Common/Footer plugin.

Conclusion

Congratulations! You have successfuly modified templates for default plugins in the MyFirst theme which has been created as a copy of the HelloWorld theme. Now it's time to dive deeper into which default plugins are avaiable and what design hacks you can do with them.

For example, you did not use any Surikata.io's core Javascript API, Javascript API of Plugins or Javascript for your theme so far.

Surikata

E-commerce development framework