Theme Development

This documentation provides a comprehensive guide to theme development in YSCP. It covers the essential concepts, techniques, and best practices required to create custom themes for CraftCms stores.

Please note that this documentation assumes a familiarity with programming concepts, particularly PHP and CraftCms. If you are new to CraftCms or programming, it is recommended to familiarize yourself with these topics before proceeding further.

Theme Anatomy

Before diving into theme development, it is essential to understand the structure and components of a CraftCms theme. A theme consists of the following main elements:

1. Theme Files: These include layout files, template files (.twig), CSS files, JavaScript files, and other assets.
2. Theme Inheritance: Themes can inherit from other themes (plugins), allowing for customization and extension of existing themes.
3. Theme Layouts: Layout files control the structure and composition of pages in a YSCP store.
4. Theme Templates: Template files define the HTML structure and content of various components in a theme.
5. Theme CSS and JavaScript: CSS and JavaScript files control the appearance and behavior of a theme.

Creating a Custom Theme

You can create a custom theme on your own, but it's easier to get started with our predefined template set, downloadable from: Theme Boilerplate Template.

warning

When creating a new template, ensure that all scripts and dependencies are loaded, and please do not force all templates/codes into one directory structure.

Theme Inheritance

It's possible to override legacy templates, components, or blocks. You just need to specify the exact path to the legacy file.

Example:

We are creating a brand new Cart page experience, with a custom empty page displaying a banner image. First, we see how the original structure is used. The original file is:

yui/components/cart/no-items.twig

<div class="empty-cart-wrapper">
    <div class="empty-cart-message">
        <img width="235" height="205"
             loading="lazy"
             src="./empty-cart.jpg"
             alt="Ohhh.."/>
        <h2>{{ "Ohhh... Your cart is empty"|t('yui') }}</h2>
        <p>{{ "You currently have no items in your shopping cart. Choose something from our offer!"|t('yui') }}</p>

        <a class="btn btn-primary" href="{{ craft.app.sites.primarySite.baseUrl }}">
            {{ "Continue shopping"|t('yui') }}
        </a>
    </div>
</div>

Now we know that the target file is located at yui/components/cart/no-items.twig, so we just need to recreate it in our own theme and add a banner div before the empty-cart-message div.

~/templates/yui/components/cart/no-items.twig

<div class="dummy-banner-wrapper">
    <img width="1400" height="450" src="./banners/dummy-banner.jpg" alt="Dummy banner"/>
</div>

<div class="empty-cart-wrapper">
    <div class="empty-cart-message">
        <img width="235" height="205"
             loading="lazy"
             src="./empty-cart.jpg"
             alt="Ohhh.."/>
        <h2>{{ "Ohhh... Your cart is empty"|t('yui') }}</h2>
        <p>{{ "You currently have no items in your shopping cart. Choose something from our offer!"|t('yui') }}</p>

        <a class="btn btn-primary" href="{{ craft.app.sites.primarySite.baseUrl }}">
            {{ "Continue shopping"|t('yui') }}
        </a>
    </div>
</div>

Note that this time we are creating the template at the ~/templates/... path to override the default one.

Theme Layouts

The base layout is always the 1column.twig layout. If you want to override this layout, follow the same steps as mentioned above. If you want to create a new layout, you can take inspiration from our layouts. You can read more about our layouts clicking here.

Theme Templates

Templates are crucial parts of a theme, separated into components and blocks that are inserted inside pages/templates. It is good practice to separate these files, so do not force them into one big file.

Theme CSS and JavaScript

CSS & JavaScript files are located in the assets/css and assets/js folders. CSS files are also separated into blocks and components, mostly having the same name as their Twig template to make it easier to find these files.

Conclusion

This documentation has covered the fundamental concepts and techniques required for theme development. By understanding the theme anatomy, creating custom themes, leveraging theme inheritance, working with layouts, templates, CSS, JavaScript, and overriding core theme files, you can create visually appealing and customized themes for your store.

Remember to adhere to best practices, maintain separation between custom and core code, and regularly test your themes to ensure compatibility and performance. With these skills and knowledge, you are well-equipped to build stunning and engaging themes in Craft CMS.