Structure and contents of a theme
A theme is composed of CSS, Javascript, HTML, components, and graphics files. When working on files, you must store them in the appropriate subfolders within the main theme folder.
Certain files are required as the minimum for any theme. After you have created them, you can add other files to expand the theme.
The Storefront Toolkit supports a setup command that creates a file structure with a sample theme. You can use this as the basis for your own theme. See the base theme overview video for a tour of this file structure.
Top-level folders
There are four top-level folders in a theme, each of which may contain several subfolders for different types of files:
- Assets—Contains subfolders for CSS files, fonts, images, and JavaScript files.
- Content—Contains subfolders for layouts (page layouts that you can extend), macros (components), and pages (storefront pages, such as Home, Listing, and others).
- Header-footer—Contains HTML templates and CSS files specific to the header and footer.
- Translations—Contains YAML localization files for mapping translated text to items on the pages.
If you have enabled custom component creation, your theme may also include the following top-level folders:
- customComponents—Contains subfolders for custom components.
- node_modules—Contains subfolders for Storybook documentation. This folder also contains all the npm libraries that you can install (that is, the @appdirect/sfb-theme-components library).
All the files in your theme should either be saved to the main theme folder, or to a subfolder within one of these top-level folders.
Required files
There are certain files that the marketplace requires as the minimum in any theme in order to present the storefront correctly. These include the following files:
- The
theme-index.css
file inthemes/_themeName_/assets/css/theme/
- The
global-index.css
file inthemes/_themeName_/assets/css/platform-global/
- The
home.html
file inthemes/_themeName_/content/pages/home/
- The
listing.html
file inthemes/_themeName_/content/pages/listing/
- The
profile.html
file inthemes/_themeName_/content/pages/profile/
- The
header-index.css
file inthemes/_themeName_/header-footer/css
- The
design-properties.json
file inthemes/_themeName_/
Note that these files appear in both base themes (classic and Plaza).
The CSS files are generated automatically from the SASS files (see below) when you start the Storefront Toolkit with the theme. The other files are created along with the theme.
When you want to modify a theme, make changes in the SASS files. Do not make changes directly in the CSS files, as they are overwritten when the toolkit is activated or when the theme is packaged for export.
Required style sheets
There are three main cascading style sheet (CSS) files available that you can use to style your theme.
AppDirect provides SASS support with the developer tool, which can make a stylesheet easy to read and update. SASS offers features such as functions, variables, and imports. The SASS files are automatically compiled each time the style sheet is updated when the developer tool is running, or each time the theme is packaged.
The following three main SASS files are required:
- The
header-index.scss
file (inthemes/_themeName_/header-footer/css
)—This file provides completely encapsulated CSS for the header and footer. - The
theme-index.scss
file (inthemes/_themeName_/assets/css/theme/
)—This is the main theme stylesheet. - The
global-index.scss
file (inthemes/_themeName_/assets/css/platform-global/
)—This CSS overrides the administration pages (MyApps page and Dashboard). Note that this file does not affect the storefront display.
These files appear in both base themes (classic and Plaza).
When you want to modify a theme, you make changes in these SASS files. These changes are then written to the corresponding CSS files when the toolkit is activated, or when the theme is packaged for export.
Page objects
The marketplace supports a number of page objects that you can add to your storefront pages to represent variable content, such as the overview text for a product or its starting price. For a list of the page objects available for the different pages in a theme, see Use page objects and its related subtopics.
While working with the Toolkit, you can use the Data Viewer feature of the developer toolbar to import real data (see Use AppDirect data), and then use the data to populate these objects for your storefront display. This feature provides a better idea of what your storefront will look like in production.
Was this page helpful?
Tell us more…
Help us improve our content. Responses are anonymous.
Thanks
We appreciate your feedback!