Template structure

This section is about the file structure. You will learn how the different files are organized, but most important of all, how to manage your project with Gulp. Let's dive into the folder structure.

Global structure

nephos/
├── src/
│   ├── assets/
│   │   ├── font/
│   │   ├── img/
│   │   ├── js/
│   │   ├── sass/
│   │   ├── scss/
│   │   │   ├── abstracts/
│   │   │   ├── base/
│   │   │   ├── components/
│   │   │   ├── layout/
│   │   │   ├── pages/
│   │   │   ├── demo.scss
│   │   │   └── main.scss
│   │   └── vendor/
│   ├── data/
│   ├── layouts/
│   ├── pages/
│   └── partials/
├── gulpfile.js
├── package.json
└── pnpm-lock.yaml

The directory structure can seem unusual for someone who is not used to build tools. We will break each part of it, so you understand how everything works.

Assets folder

nephos/
├── src/
│   ├── assets/
│   │   ├── font/
│   │   ├── img/
│   │   ├── js/
│   │   ├── sass/
│   │   ├── scss/
│   │   │   ├── abstracts/
│   │   │   ├── base/
│   │   │   ├── components/
│   │   │   ├── layout/
│   │   │   ├── pages/
│   │   │   ├── demo.scss
│   │   │   └── main.scss

Bulma folder

nephos/
├── src/
│   ├── sass/
│   └── bulma.sass

When you installed the project by doing pnpm install, you also installed Bulma 0.7.5 as a project dependency. All Bulma framework Sass source files are there. You can customize them to fit your needs or leave them as they are. If you do so, you will get the standard Bulma version (identical to the CSS file you can find in the Bulma distribution folder in the official repository) when you build the project. We provided this option as numerous developers want to have control on this for code optimization purposes.

WARNING

Edit the Bulma source files only if you know what you are doing as any faulty customization may completely break the layout.

Layouts folder

nephos/
├── src/
│   └── layouts

All the HTML layouts resides in this folder. For a more concise code, Nephos HTML uses a flat file compiler named Panini, by Zurb. Panini makes it easy to break your layouts into several reusable components, preventing you to go through every page to make your changes. You can find more information about zurb/panini by visiting the official repository. Nephos follows the panini pattern for the HTML file structure.

the layouts folder holds all the template layouts. It is mandatory to have at least one layout, and it should always be named default.html. Additional layouts can have the names you want, but don't forget the .html extension. A layout acts as container providing the same base for a set of similar pages. Nephos uses 3 layouts, we will see the details about them later on. Finally notice the {{> body}} call that is present in each layout file. This is a reference to append the rest of the page content.

Layout files

The html/layouts/ folder holds 3 layout files:

• default.html : The default layout used by all the shop pages.
• components.html : A similar layout, but with additional scripts used by the elements.html page.
• demo.html : A demo layout used for the index.html page.

Pages folder

nephos/
├── src/
│   └── pages/

The pages folder holds all the template pages. Pages are focused on content. They are related to a layout and automatically appended to it by panini when the page is served. You will always find the same statement at the top of each page's code :

---
layout: default
title: This is the page title
---

The layout statement tells panini which layout to use to serve the page. The title element is a string that gets inserted as the page title when panini has finished assembling the page parts together. Now that we had a look to panini's basic features let's dive into the Nephos HTML files :

Page files

All HTML pages live in this folder. Each one of this pages is linked to one of the 3 existing layouts and makes use of partials living in the src/layouts/ folder. There is a total of 29 HTML pages:

1. Index.html : Nephos presentation landing page
2. home.html : Nephos shop homepage with a full screen slider
3. home-alt.html : Nephos shop homepage with a static image
4. shop.html : displays the shop categories
5. products.html : displays a product grid based on cards
6. products-list.html : displays a list version of the products
7. product.html : a single product page
8. product-carousel.html : carousel version of the single product page
9. search-results.html : display search results
10. account.html : displays the user account page
11. account-edit.html : displays the edit account page
12. account-placeholder.html : displays the account placeholder page
13. wishlist.html : displays the user wishlist
14. wishlist-empty.html : displays the wishlist placeholder
15. cart.html : displays the user cart page
16. cart-empty.html : displays an empty version of the cart page
17. orders.html : displays an order tracking page based on a card grid
18. orders-list.html : displays a list version of orders
19. order.html : displays an order details page
20. invoice.html : displays an invoice
21. checkout-step1.html : displays the first step of the checkout process
22. checkout-step2.html : displays the second step of the checkout process
23. checkout-step3.html : displays the third step of the checkout process
24. checkout-step4.html : displays the fourth step of the checkout process
25. checkout-step5.html : displays the fifth step of the checkout process
26. authentication.html : displays the login and register form
27. elements.html : displays the available Nephos elements
28. error-404.html : displays a 404 error page
29. error-500.html : displays a 500 error page

Partials folder

nephos/
├── src/
│   └── partials/

The partials folder holds all your HTML partials. Partials are chunks of code that you want to reuse as is across your application : it can be a button, a navbar, a content section or whatever you want. Note that you can create as many sub-folders as you want to organize your partials. You simply have to make sure that your partial names are unique. Partials are named like HTML files : navbar.html. When you want to call a partial in one of your layouts or pages use the following expression : {{> partial-name}}. You don't have to mention the path, even if it is nested in several sub-folders, panini will find it. Also note that you don't have to add the HTML extension in your partial call.

Partial files

nephos/
├── src/
│   ├── partials/
│   │   ├── demo/
│   │   ├── modals/
│   │   ├── navbars/
│   │   ├── pageloader/
│   │   ├── quickviews/
│   │   ├── search/
│   │   ├── sidebar/
│   │   ├── svg/
│   │   ├── demo-scripts.html
│   │   ├── elements-scripts.html
│   │   └── shop-scripts.html

Demo sub-folder

• footer.html : Holds the footer partial used by the template index.html page.

Modals sub-folder

Each partial inside is a standalone modal that is reused in several parts of the template

Navbars sub-folder

• mobile-navbar-guest.html : Holds the mobile navbar partial used by the majority of Nephos shop pages. This is the guest version.
• mobile-navbar-user.html : Holds the mobile navbar partial used by the majority of Nephos shop pages. This is the logged in user version.

Pageloader sub-folder

• pageloader-full.html : Holds the full width page loader partial used by the template index.html page.
• pageloader.html : Holds the spaced page loader partial used by all Nephos shop pages.

Quickviews sub-folder

• flying-button.html : Holds the FAB button partial used whenever a shop page gives access to the right categories sidebar. Clicking on this button triggers it.
• quickview-cart.html : Holds the cart sidebar partial used by the shop pages.
• quickview-categories.html : Holds the product categories sidebar partial used by a majority of the shop pages.
• quickview-filters.html : Holds the filters sidebar partial used by the product grid and the product list.
• quickview-main.html : Holds the main dark sidebar partial used by all the shop pages.

Search sub-folder

• search-overlay.html : Holds the snippet that controls the global product search and it's overlay. Used by all the shop pages

Sidebar menu items sub-folder

• sidebar-item-cart-active.html : Holds the active cart icon menu item of the shop's main sidebar. Triggers the cart sidebar when clicking on it.
• sidebar-item-filters.html : Holds the filters icon menu item of the shop's main sidebar. Triggers the filters sidebar when clicking on it.
• sidebar-item-auth.html : Holds the user menu item of the shop's main sidebar. Redirects to the login page or logs you out when clicking on it.
• sidebar-item-search.html : Holds the search icon menu item of the shop's main sidebar. opens the search overlay when clicking on it.
• sidebar-item-fold.html : Closes the mobile sidebar when clicking on it. This item is only visible on mobile.

Root files

• demo-scripts.html : Holds a snippet with the scripts declaration for the index.html page.
• element-scripts.html : Holds a snippet with the scripts declaration for the elements.html page.
• shop-scripts.html : Holds a snippet with the scripts declaration for all the shop pages.

Images

nephos/
├── src/
│   ├── assets/
│   │   └── img/

All the project images live in this folder. It can have as many sub-folders as you want. When you build the projects, all these images are automatically transferred to the right location by Gulp. We will see that a bit later.

JS

nephos/
├── src/
│   ├── assets/
│   │   ├── js/
│   │   │   ├── _data-addresses.js
│   │   │   ├── _data-orders.js
│   │   │   ├── _data-wishlists.js
│   │   │   ├── account.js
│   │   │   ├── authentication.js
│   │   │   ├── cart.js
│   │   │   ├── checkout.js
│   │   │   ├── demo.js
│   │   │   ├── elements.js
│   │   │   ├── functions.js
│   │   │   ├── nephos.js
│   │   │   ├── order.js
│   │   │   ├── orders.js
│   │   │   ├── product.js
│   │   │   ├── search.js
│   │   │   └── wishlist.js

All of Nephos own javascript files live in this folder. There are 16 main files :

• _data-*.js : Those files hold some global user variables that are used by the fake customer accounts.
• demo.js : Holds all the functions used by the index.html demonstration page.
• functions.js : Holds all the basic functions that are used across the template.
• elements.js : Holds all the functions needed to operate the elements listed in the elements.html components page.
• nephos.js : Holds all the functions used by the Nephos template.
• account.js : Holds all the functions used by the account pages.
• authentication.js : Holds all the logic for the fake authentication system
• cart.js : Holds all the logic for the shopping cart system (add / remove / update / get cart)
• checkout.js : Holds all the functions used by the checkout pages.
• order.js : Gets order details dynamically.
• orders.js : Holds all the functions used by the order pages.
• product.js : Gets product details dynamically.
• account.js : Holds all the functions used by the search UI elements.
• wishlist.js : Holds all the functions used by the Wishlist pages.

SCSS

nephos/
├── assets
│   ├── scss
│   │   ├── scss
│   │   │   ├── abstracts
│   │   │   │   ├── _animations.scss
│   │   │   │   ├── _mixins.scss
│   │   │   │   └── _variables.scss
│   │   │   ├── base
│   │   │   │   ├── _base_.scss
│   │   │   │   ├── _colors.scss
│   │   │   │   ├── _fonts.scss
│   │   │   │   ├── _helpers.scss
│   │   │   │   ├── _theme-default.scss
│   │   │   │   ├── _theme-green.scss
│   │   │   │   ├── _theme-purple.scss
│   │   │   │   ├── _theme-red.scss
│   │   │   │   ├── _theme-slate.scss
│   │   │   │   ├── _theme-yellow.scss
│   │   │   │   └── _utils.scss
│   │   │   ├── components
│   │   │   │   ├── _alert.scss
│   │   │   │   ├── _buttons.scss
│   │   │   │   ├── _cards.scss
│   │   │   │   ├── _checkboxes.scss
│   │   │   │   ├── _forms.scss
│   │   │   │   ├── _messages.scss
│   │   │   │   ├── _modals.scss
│   │   │   │   ├── _pageloader.scss
│   │   │   │   ├── _quickview.scss
│   │   │   │   ├── _switch.scss
│   │   │   │   └── _tabs_.scss
│   │   │   ├── layout
│   │   │   │   ├── _filters.scss
│   │   │   │   ├── _layout.scss
│   │   │   │   ├── _navbar.scss
│   │   │   │   ├── _responsive.scss
│   │   │   │   └── _sidebar.scss
│   │   │   ├── pages
│   │   │   │   ├── _account.scss
│   │   │   │   ├── _auth.scss
│   │   │   │   ├── _cart_.scss
│   │   │   │   ├── _categories.scss
│   │   │   │   ├── _checkout_.scss
│   │   │   │   ├── _elements.scss
│   │   │   │   ├── _invoice.scss
│   │   │   │   ├── _orders_.scss
│   │   │   │   ├── _product.scss
│   │   │   │   └── _search.scss
│   │   │   ├── main.scss
│   │   │   └── demo.scss

Nephos relies on the powerful Sass features, letting you handle complex styles in a breeze. Nephos relies on a modular SCSS structure. You need to import all the SCSS partials into your core file. This how SCSS files are organized.

Core and partials

There are two main types of SCSS files in Nephos : Core and Partials.

Partial files

Partial SCSS file names always start with an underscore like this: _account.scss . They act as chunks of code that are imported into a core SCSS file. Not only this gives you great control over your code, but it also greatly enhances it's maintainability. Nephos ships with 2 main types of SCSS partials:

• Global partials: partials that are used globally in the Template.
• Theme partials: theme partials share the same naming convention : _theme-* where * stands for the theme name. For en example, the default theme is named _theme-default.scss. Importing a theme partial in your project is mandatory. Otherwise, it won't work.

WARNING

Make sure that you are only importing one theme at a time in your Core file imports. Otherwise, you could experience some strange behavior or break your project.

Core file

The main.scss file centralizes all Nephos styles. Every time you make a change in a partial file, it impacts the outputted main.css file resulting from the compilation process (which is handled by Gulp, as we saw above). The Nephos core SCSS file starts by importing all the needed SCSS partials. Here is the statement:

/*! main.scss │ Nephos │ CSS Ninja */

/* ==========================================================================
Nephos core
========================================================================== */

@import "base/theme-default";
@import "base/base";
@import "base/colors";
@import "base/fonts";
@import "base/helpers";
@import "base/utils";
@import "abstracts/animations";
@import "layout/layout";
@import "layout/navbar";
@import "layout/sidebar";
@import "layout/filters";
@import "components/pageloader";
@import "components/buttons";
@import "components/modals";
@import "components/quickview";
@import "components/cards";
@import "components/messages";
@import "components/tabs";
@import "components/switch";
@import "components/alert";
@import "components/checkboxes";
@import "components/forms";
@import "pages/categories";
@import "pages/account";
@import "pages/cart";
@import "pages/orders";
@import "pages/product";
@import "pages/checkout";
@import "pages/auth";
@import "pages/search";
@import "pages/invoice";
@import "pages/elements";
@import "layout/responsive";

TIP

Notice how partials are imported. Whereas the actual partial file name starts with an underscore and ends with a .scss extension, when you write imports inside your core.scss file, you have to remove the underscore and the .scss extension.

Imports

Let's break a bit the list of imports we saw above, so we can understand how the global stylesheet is structured and how it impacts the final outputted style

1. The first line imports the selected theme. In the example above, the default theme is selected (_theme-default.scss). Make sure to only import one theme at a time.
2. The following lines import all the components and layout elements that are needed to build the template styles.
3. Notice the last import : _responsive.scss. This file mainly holds responsive classes and acts as CSS a modifier. That is why we put it at the very end of our imports.

Remember that CSS stands for Cascading stylesheets. That's why the order also matters in some specific cases.

Link the core

Once you finished writing your imports, and adding the basic CSS resets you want in your core file, you are ready to setup a new page. As we stated before, as soon as Gulp is running, your core file is immediately outputted into a compiled CSS file. The CSS chunks from partials are appended one after another following the order defined in the imports. To import the core, just add a stylesheet link to the compiled CSS inside the head tags of one of your layout files, like html/layouts/default.html:

<link rel="stylesheet" type="text/css" href="{{root}}assets/css/main.css">

TIP

Notice the {{root}} elements which tells panini to get back to the root of the project to find the CSS stylesheet.

Root files

There also a few files sitting at the root of the project that we need to discuss before getting into serious business:

• gulpfile.js : Gulp will use this file to perform all the tasks it is supposed to accomplish.
• package.json : Lists all your project's dependencies and gives useful metadata.
• pnpm-lock.yaml : Automatically generated for any operations where pnpm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.