Template structure

This section is about the Friendkit File structure. Each Project / Kit follows the same file structure. Learning more about it will help setup any of the provided projects quickly and easily.

Global structure

frientkit/
├── src/
│   ├── assets/
│   │   ├── font/
│   │   ├── img/
│   │   ├── js/
│   │   ├── sass/
│   │   ├── scss/
│   │   │   ├── _dark/
│   │   │   ├── abstracts/
│   │   │   ├── components/
│   │   │   ├── layout/
│   │   │   ├── navigation/
│   │   │   ├── pages/
│   │   │   └── core.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

frientkit/
├── src/
│   ├── assets/
│   │   ├── font/
│   │   ├── img/
│   │   ├── js/
│   │   ├── sass/
│   │   ├── scss/
│   │   │   ├── _dark/
│   │   │   ├── abstracts/
│   │   │   ├── components/
│   │   │   ├── layout/
│   │   │   ├── navigation/
│   │   │   ├── pages/
│   │   │   └── core.scss
│   │   └── vendor

Bulma folder

frientkit/
├── sass/
│   ├── sass/
│   └── bulma.sass

When you installed the project by doing pnpm install, you also installed Bulma 0.9.1 as a project dependency. All Bulma framework Sass source files are there. The Bulma source is imported by Friendkit's core.scss file. You can override Bulma default variables by duplicating them and changing the value in /abstracts/_variables.scss.

WARNING

Edit the Bulma source files only if you know what you are doing as any faulty customization may completely break the layout. Try to avoid it since you can now customize the source from Friendkit's variables.

Layouts folder

frientkit/
├── src/
│   └── layouts/

All the HTML layouts resides in this folder. For a more concise code, Friendkit 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. Friendkit 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.

Pages folder

frientkit/
├── 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
---

Partials folder

frientkit/
├── 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.

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.

Layouts

The src/layouts/ folder generally holds a single layout files: default.html, which is used by almost all pages. This is not true in the case of Friendkit, which uses multiple layouts, because some pages are very different from others.

Pages

All HTML pages live in this folder. Each one of this pages is linked to one of the existing layouts and makes use of partials living in the src/partials/ folder. Each page is generally part of a "set" that includes 2 or 3 pages (e.g "videos", "feed", "profile" etc...). Sets generally use the same layout but this is not a golden rule.

Images

frientkit/
├── 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

frientkit/
├── src/
│   ├── assets/
│   │   ├── js/
│   │   │   ├── components/
│   │   │   ├── navigation/
│   │   │   ├── pages/
│   │   │   ├── global.js
│   │   │   ├── main.js
│   │   │   ├── touch.js
│   │   │   └── tour.js

All of Friendkit own javascript files live in this folder. Edit them to change thee template functionality.

All of Friendkit's own javascript files live in this folder. The main javascript files are main.js and global.js. They hold all the global template functions. But let's look more into the details as javascript is heavily used in Friendkit.

global.js

This file holds all the reusable functions, written in the jQuery plugin style to make a difference with the other common functions. These functions are mainly used by the main.js file to be able to initialize all layout elements that require javascript.

main.js

This file is in charge of running the main template functions and is used by every single Friendkit page. Some other notable files are:

popovers-users.js

This file is in charge of displaying dynamic popovers when you hover a user image, it also uses a demo JSON file that it pulls from the assets folder to fetch the data. The file also relies on the "web-uipopovers" library to actually display the popovers.

popovers-pages.js

This file is in charge of displaying dynamic popovers when you hover a page/company image, it also uses a demo JSON file that it pulls from the assets folder to fetch the data. The file also relies on the "web-uipopovers" library to actually display the popovers.

autocompletes.js

This file is in charge of all autocomplete initialization, to be able to get the one that you want quickly.

chat.js

This file holds all the javascript that the chat widget/page needs to run properly.

events.js

This file holds all the javascript that the events page needs to run properly.

explorer.js

This file controls the behavior of the explorer menu, that you can trigger from the main navbar.

feed.js

This file holds all the javascript that the feed page needs to run properly.

profile.js

This file holds all the javascript that the profile/company pages needs to run properly.

friends.js

This file holds all the javascript that the friends page needs to run properly.

inbox.js

This file holds all the javascript that the inbox page needs to run properly.

news.js

This file holds all the javascript that the news page needs to run properly.

questions.js

This file holds all the javascript that the questions pages needs to run properly.

videos.js

This file holds all the javascript that the videos pages needs to run properly.

signup.js

This file holds all the javascript that the signup wizard needs to run properly.

widgets.js

This file holds all the javascript needed by some widgets to work properly.

go-live.js

This file controls the feed modal from where you can run the webcam.

modal-uploader.js

This file controls the behavior of the modal uploader that can be triggered from the feed or the photos page.

lightbox.js

This file controls the behavior of the custom lightboxes used by the feed and profile pages. Those lightboxes use Fancybox3, a premium javascript plugin included with Friendkit.

touch.js

This file holds all the touch gestures implemented with hammer.js.

elements.js

This file holds demo functions that are used by the elements page.

landing.js

This file holds demo functions that are used by the landing page.

tour.js

This file holds the logic for the template tour that you can take from the landing page.

SCSS

frientkit/
├── assets/
│   ├── scss/
│   │   ├── _dark/
│   │   │   └── _*-dark.scss
│   │   ├── abstracts/
│   │   │   └── _*.scss
│   │   ├── components/
│   │   │   └── _*.scss
│   │   ├── layout/
│   │   │   └── _-*.scss
│   │   ├── pages/
│   │   │   └── _*.scss
│   │   └── core.scss

Friendkit leverages the powerful Sass features, letting you handle complex styles in a breeze. Friendkit 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 Friendkit : Core files and Partial files.

Partial files

Partial SCSS file names always start with an underscore like this: _popovers.scss . They act as chunks of code that you can import only if you need them. Of course some of them are mandatory for the project to work. For example, if you need to display cards in your project, you can import scss/partials/_cards.scss to have access to that component in your layout. SCSS partials are of several types:

• Layout partials: Always start with _*.scss. Layout partials are all mandatory. You have to import them in order to setup a basic layout for your app.
• Component partials: Always start with _*.scss. Component partials are optional. However, you will need to add some to your project to hold the content you are planning publish. Friendkit's approach is modular, so you pick only what you use.
• App partials: Always start with _*.scss. Page partials are related to specific pages. Each set of pages has its own styles partial.

Core file

The Core file is the heart of Friendkit's styles. It's main purpose is to centralize all styles. Every time you make a change in a partial file, it impacts the outputted core.css file resulting from the compilation process. The Core file start with imports of other partial SCSS files. Here are all the import statements:

/*! core.scss | Friendkit | © CSS Ninja. 2020-2021 */

/* ==========================================================================
Core SCSS file
========================================================================== */

/*
    0. Imports
*/

/* ==========================================================================
0. Imports
========================================================================== */

//Main variables
@import "abstracts/variables";

//Bulma source import
@import "../sass/bulma.sass";

//Layout imports
@import "layout/all";

//Navigation imports
@import "navigation/all";

//Components imports
@import "components/all";

//Pages imports
@import "pages/all";

//Layout imports dark
@import "_dark/layout/all";

//Navigation imports dark
@import "_dark/navigation/all";

//Components imports dark
@import "_dark/components/all";

//Pages imports dark
@import "_dark/pages/all";

$slick-font-path: "/assets/fonts/";
$slick-loader-path: "/assets/fonts/";

@import "../../../node_modules/slick-carousel/slick/slick.scss";
@import "../../../node_modules/slick-carousel/slick/slick-theme.scss";

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 scss/abstracts/_variables.scss. Importing this file is mandatory since it contains all core color variables. Without it, nothing will work and your page will be broken.
2. The following lines import layout partials from scss/layout/_*.scss. All of these imports are mandatory for the theme to work, as they handle all navbars, sections, footer and even the pre-loader.
3. The components imports are up to you. However all of them like scss/components/_forms.scss should normally be imported if you intend to use the project as is. But it is still up to you to decide which components you will need or not in your project. The component imports are followed by extensions imports, if you need to use some special features.
4. Before closing the imports, it's time to get the page specific partials. In the above imports, we can see that the page stylesheets.
5. You can also notice the last imports from the _dark folder. Those imports handle the dark mode styles. If you do not intend to use the dark mode, simply remove those imports.

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 src/layouts/default.html:

<link rel="stylesheet" type="text/css" href="{{root}}assets/css/core.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.

Dark Mode

The 1.4.0 update added Dark Mode to the existing codebase. Dark Mode is implemented with a class that gets added to the page <body> element, using the .is-dark CSS global modifier. For a more convenient usage, the theme variable (light or dark) is stored in the browser local storage. You can of course change that behavior. The dark mode styles have been put separate from the rest in their own folder structure: /src/assets/scss/_dark/**/*.scss. Files are organized into sub-folders, following the same logic. Remove dark stylesheets imports from your main SCSS file if you do not want to use dark mode.