Shopyo Theme Tutorial

Shopyo comes with a powerful built-in theming engine located in the shopyo_theme module. This allows you to separate the visual presentation of your application from its logic, and switch between different designs on the fly.

This tutorial will guide you through understanding, using, and creating themes in Shopyo.

Concepts

Shopyo distinguishes between two types of themes:

1. Front Theme: The theme used for the public-facing side of your website (e.g., landing pages, blog posts, store front).

2. Back Theme: The theme used for the administration dashboard and internal tools.

Theme Location

All themes are stored in the static/themes/ directory of your project root.

your_project/
├── static/
│   └── themes/
│       ├── front/
│       │   ├── default/
│       │   └── dark_mode/
│       └── back/
│           ├── default/
│           └── modern_admin/

Creating a Theme

Let’s create a new Front theme called ocean_blue.

1. Create the Directory: Navigate to static/themes/front/ and create a folder named ocean_blue.

2. Add Metadata: Inside ocean_blue, create a file named info.json. This file tells Shopyo about your theme.

   {
       "display_string": "Ocean Blue",
       "author": {
           "name": "Jane Doe",
           "website": "https://example.com",
           "mail": "jane@example.com"
       },
       "version": "1.0.0",
       "description": "A calming blue theme for the store."
   }
   

3. Add Styles: Create a styles.css file in the same directory. This will be the main entry point for your theme’s CSS.

   body {
       background-color: #e0f7fa;
       color: #01579b;
       font-family: sans-serif;
   }
   
   .navbar {
       background-color: #0277bd !important;
   }
   

Using Themes in Templates

To make sure your templates load the CSS from the currently active theme, use the shopyo_theme helper in your base template (usually shopyo_base/templates/shopyo_base/blocks/resources.html or similar).

For the Back Theme (Admin):

<link rel="stylesheet" href="{{ shopyo_theme.get_active_back_theme_styles_url() }}">

For the Front Theme (Public):

<link rel="stylesheet" href="{{ shopyo_theme.get_active_front_theme_styles_url() }}">

Activating a Theme

1. Run your Shopyo application: flask run --debug.

2. Log in as an administrator.

3. Go to the Theme module (typically found in the dashboard sidebar or at /shopyo_theme).

4. You will see your new “Ocean Blue” theme listed under Front Themes.

5. Click the Activate button.

The page should reload, and if your templates are set up correctly, you will see your new blue background applied!

Advanced: Theme Assets

If your theme needs images or JavaScript files, simply place them inside your theme folder (e.g., static/themes/front/ocean_blue/assets/).

You can reference them in your CSS relative to the CSS file:

.hero-banner {
    background-image: url('assets/banner.jpg');
}

Or if you need to link to them from Jinja templates, you might need to construct the path manually or use a helper, but typically themes are self-contained via their CSS.