Theme directory structure is predefined. Every piece of your theme has it’s own named location. The directory structure is as follows:
| Path | Description |
|---|---|
| assets | Includes all the custom styles. Every .liquid file will be compiled against settings_data.json. Read more about assets compilation in themes from below. |
| blocks | Reusable blocks to be used in sections. |
| config | Theme configuration files live here. |
| layout | Your layouts go here. You can define the layout at the very beginning of your template file with the layout tag {% layout 'layout_name' %}. |
| locales | All the translations. Locale for the messages is automatically detected from the store context. |
| public | All the publicly accessible files can be found from here. |
| sections | Reusable section definitions. |
| snippets | Reusable stuff goes here, snippets can be renderer with the render tag {% render 'snippet_name' %} |
| templates | The actual page templates. |
Assets
Include all the assets your theme uses here. Assets can be images, stylesheets or javascript files. Finqu doesn’t automatically copy files from this directory to the public directory. For this purpose it is recommended to use a bundler like webpack. If you don’t want to use bundler you can move all your files to the public directory. Finqu does however compile all the Liquid files found from this folder and copy the compiled file to the public directory. For example, your my_svg_file.svg.liquid would be run through Liquid templating engine and copied to the public directory with a filename my_svg_file.content_hash.svg, where content_hash is MD5 hash calculated from the result content. You don’t have to worry about the hash, you can reference your file in the theme simply using asset_url filter {{ 'my_svg_file.svg' | asset_url }}. This way the content can be efficiently cached and fresh content is always served to the customers.
Sass
Sass files are an exception - Finqu compiles your Sass files using Dart Sass. Every .scss or .scss.liquid (yes, you can access your theme configuration) is compiled and cachebusted to the public directory. So don’t bundle those files with your bundler.
Blocks
Blocks are a crucial concept in Finqu themes. They are reusable small components that can have their own settings for user to edit. They are meant to be used inside sections. They can be added dynamically with the container tag or be placed statically with the block tag.
Config
This directory must contain two different files, settings_schema.json for settings schema and settings_data.json for storing actual settings. This directory also contains sometimes .data directory which is used for storing drafts by the Finqu editor.
Layout
Your theme must include theme.liquid layout file. You can also define other layout files like campaign.liquid and then you can use it in your template like this:
{%- layout 'campaign' -%}
Locales
For every language you wish to support you must include a locale file. If the matching locale is not found Finqu will default to English. There is an translation tool in the Finqu administration that can help you create correct locales. But if you wish to add new translations you can do so by adding new keys to translation files like this:
locales/en.json
{
// ...
"my_key": "My translation"
}
and then you can use it in your template like this:
{{ 'my_key' | t }}
It’s also possible to include variables in the translations like this:
locales/en.json
{
// ...
"greeting": "Hi {{ name }}!"
}
and then you can use it in your template like this:
{%- assign name = "Example Name" -%}
{{ 'greeting' | t: name: name }}
which would output
Hi Example Name!
Public
This is the publicly accessible content. Every file that is here can be accessed with a browser. You can choose to compile this directory with a bundler or store your files directly here. Remember that Finqu compiles every Liquid file from asset directory here.
Sections
Sections are elements that take up the whole page. They can be seen as standalone building elements for the theme or as a container for blocks. Sections are only read from the theme directory and cannot be added by apps whereas blocks can be created outside the theme. Take this in consideration when designing your theme.
Snippets
These can be whatever you want or you don’t have to use them at all. A simple example would be using snippet as a wrapper for a icon loader. Snippet is rendered in it’s own context and the variable assigns won’t affect the outer context and outer context variables won’t be visible to the snippet context. Therefore you need to pass every variable to the snippet that you wish to use in the snippet.
snippets/icon.liquid
<i class="my-icon-framework my-icon-framework-{{ icon }}"></i>
This could then be used in your templates like this:
{% render 'icon' icon: 'cart' %}
which would then ouput:
<i class="my-icon-framework my-icon-framework-cart"></i>
Templates
There is a template for every single page type of the online store. If user visits the frontpage of the store, then the renderer would render the frontpage.liquid template. If user visits the cart, then the cart.liquid template would be rendered.