Skip to content

Developer's Guide

Jump to bottom
dmitrychuba edited this page Jan 30, 2020 · 2 revisions

Welcome! This guide contains instructions aimed to help you to write clean, consistent, and understandable code! Which is very important for product development

General rules/notes:

  • Don't repeat yourself (DRY code)
  • Create reusable components, elements instead of huge files containing all components
  • Use functions/mixins described below
  • Use EXPLICIT names (understandable, readable, self describing) for variables, classes, id, function, etc... Do not be lazy typing full names as possible instead of ugly abbreviations
    • css: ID - camelCase, class - hyphenated-words
    • php: functions - camelCase for class methods, variables and helper functions - underscore_separators
  • Write code as simple as possible, use common sense

Bootstrap

Project includes bootstrap v4, which can be customized by editing resources/assets/styles/partials/bootstrap-custom.scss

Bootstrap rules/notes:

Note: you should not follow exactly inconsistent padding of PSD template but correct it and use consistent spacing of bootstrap across all pages

Template:

Theme is based on roots/sage starter theme all the docs can be found at https://roots.io/sage/docs/theme-installation/

Extensions

what is added to base theme

Controllers

soberwp/controller package is added, that allows use controllers per page (docs are available at https://github.com/soberwp/controller)

ACF

MWDelaney/sage-advanced-custom-fields package is added that allows accessing acf fields as variables (docs are available at https://github.com/MWDelaney/sage-advanced-custom-fields)

Shortcodes

In order to add shortcode just add a file to a resources/views/shortcodes folder, it will be available as a shortcode by its name for example:

hello-world.blade.php - can be used as [hello-world] shortcode, all attributes of this shortcode is availavle as variables inside the *.blade.php file, if shortcode has content (e.g. [hello-world] content [/hello-world]), this content cab access as $content variable inside the *.blade.php file

REST Endpoints

In order to add REST endpoints you can add public static methods to the app/Services/RestEndpoints.php file which will be automatically accessible at http://example.com/theme-endpoints/v1/[endpoint name], where endpoint name translates from camelCase to hyphenated-words (e.g. public static function getPosts() will available at http://example.com/theme-endpoints/v1/get-posts)

Extending

to extend the functionality of a theme you can out your custom classes to app/Services/ folder

Setup

OG tags, Google Analytics, Favicons can be configured in app/setup.php

custom filters can be added at app/filters.php

custom function can be added at app/custom_helpers.php

SCSS

Directory structure

SASS files are located at resources/assets/styles:

[base]
    _common.scss
    _typography.scss
[helpers]
    _functions.scss
    _include-media.scss
    _mixins.scss
[layout]
    _footer.scss
    _header.scss
    _logo.scss
[pages]
    _page.scss
    home.scss
[partials]
    bootstrap-custom.scss
    section.scss
[utils]
    _submenu.scss
    menu-dropdown.scss
    sticky-header.scss
_variables.scss
app.scss
editor-styles.scss

Mixins:

Font

@include f($params...);

used to define font-size, line-height, font-family, font-weight, color (passed as optional arguments in any order)

Advantages: converts units from px to rem, adds font-family fallbacks, reduces amount of lines in favor of readability

Examples:

  • Font-size

     @include f(16px);

  • Font-size and line-height (note the quotes)

     @include f("16px/25px");

  • Font-size, line-height, font-family, font-weight(text or number), color

     @include f("16px/25px", Futura, bold, #eee);
 or
 @include f("16px/25px", Futura, 800, rgba(#000, .3));

Custom Font

To add Custom Fonts make sure that following files are present:

.resources/fonts/YOUR_FONT_NAME/YOUR_FONT_NAME.eot
.resources/fonts/YOUR_FONT_NAME/YOUR_FONT_NAME.ttf
.resources/fonts/YOUR_FONT_NAME/YOUR_FONT_NAME.woff
.resources/fonts/YOUR_FONT_NAME/YOUR_FONT_NAME.woff2
.resources/fonts/YOUR_FONT_NAME/YOUR_FONT_NAME.svg

Then add YOUR_FONT_NAME to resources/styles/base/_typography.scss to array $fonts-list after that you're able to use it as follows: @include f(YOUR_FONT_NAME);

Background

@include bg($params...);

used to define background-image[-color,-repeat,-size,-position,-attachment] (passed as optional arguments in any order)

Advantages: reduces amount of lines in favor of readability and reduces amount of text to type, no need to type full path to images directory as it uses project's default assets/images/*

Examples:

  • background-size, background-image, background-repeat, background-position, background-color, background-attachment 
     @include bg(cover, 'my-image.png', no-repeat, 50% 50%, #ddd, fixed);
    Note: in case you want to set background size as number(like: 20px 10px), you'll need to list it after background position

Absolute cover

@include abs-cover;

used as a shortcut for:

.selector {
	top      : 0;
	left     : 0;
	width    : 100%;
	height   : 100%;
	position : absolute;
}

Advantages: reduces amount of lines in favor of readability and reduces amount of text to type

JavaScripts

JavaScripts files are located at resources/assets/scripts:

Directory Structure

[autoload] - contains js files/modules that will be automatically loaded
[components] - contains VUE.js components (backgroundSlider.vue is a background slider used on homepage, can be found in resources/views/partials/section.blade.php)
[routes] - contains files/modules that are loaded per page, file name appropriate to page name turned to cammelCase
[utils] - contains utils and helper functions
app.js - entry point
customizer.js - relted to wp theme customizer
Clone this wiki locally