Skip to content

Instantly share code, notes, and snippets.

@newloong

newloong/Development.md

Forked from bfintal/Development.md
Created April 8, 2019 03:37
Show Gist options
  • Save newloong/3a09aa48ad7e5c2a98398f2f781cc2e6 to your computer and use it in GitHub Desktop.
Save newloong/3a09aa48ad7e5c2a98398f2f781cc2e6 to your computer and use it in GitHub Desktop.
Download ZIP
Creating a Custom Client WordPress Website from A PSD Design - A Gambit Technologies, Inc. Developer Guide
Raw
Development.md

Creating a Custom Client WordPress Website from A PSD Design

(This is a Gambit Technologies, Inc. Developer Guide)

Development of a website from scratch is done by:

  1. Creating a customized WordPress theme using Sage by Roots,
  2. Creating the pages then creating the content either using a page builder, or by adding pure HTML content, then adding styles into the customized theme,
  3. Installing plugins from the WordPress plugin directory for added functionality, configuring them and customizing their styles.

We will use the following tools/projects/code bases:

The steps below are on how to create a customized WordPress theme using Sage

Starting Development

Make sure environment is ready for development

Here's what we use to create the site:

  • MAMP PRO or Vagrant or any local web server with WordPress
  • Brew
  • Yarn
    • Check using: $ yarn --version
    • Install using: $ brew install yarn
  • Composer
    • Check using: $ composer --version
    • Install using: $ brew install composer

For the purposes of this tutorial, I will assume that your local dev site will reside in http://localhost:8888 and the name of the site you're building is client-x

Create a local host for the project using MAMP PRO

  1. Open MAMP PRO
  2. Create a new host for the site. For this example, we'll name it localhost
  3. Go to the new host's Extras tab and install the latest version of WordPress

Create the theme (For Sage v9.0.1)

In your /wp-content/themes path, do:

$ composer create-project roots/sage client-x

During the Q&A while running the above command, use these answers:

  • Local development URL of WP site: http://localhost:8888 (for MAMP users)
  • Path to theme directory: /wp-content/themes/client-x
  • Which framework would you like to load? Bulma
  • Are you sure you want to overwrite the following files? yes

Then do this to initialize the newly created theme:

$ cd client-x
$ yarn && yarn build

This video may help, but it's a little outdated: https://www.youtube.com/watch?v=bQACE1hPhz8

Apply these fixes for some theme issues:

1. Loosen the strictness of 2-spaces soft tabs vs hard tabs.

Customize the package.json add these properties:

"stylelint": {
    "rules": {
        "indentation": null,
    }
}

2. Fix Bootstrap + production build SCSS issues

In resources/assets/styles/common/_variables.scss, add:

$navbar-dark-toggler-icon-bg: none;
$navbar-light-toggler-icon-bg: none;

Activate the Sage theme

Log into your website http://localhost:8888, and activate the Sage theme.

Running the Sage theme

The theme's assets (CSS & JS) will need to be built in order for the changes to be applied.

To run the theme:

  • Turn on MAMP (or any local web server you have),
  • Run $ yarn run start

The browser will open http://localhost:3000 where on-the-fly changes will show up. (If you view the site using the normal url http://localhost:8888, you will only see changes after building)

Try it out Open up the Sage theme in your IDE, edit the file /resources/assets/styles/common/_global.scss and add the line body { background: orange; }. Hit save, then check your browser.

Developing / customizing the Sage theme

This video will help: https://youtu.be/ZSUe01S4zJY?t=4m57s

Viewing the built Sage theme (for debugging)

  1. Build the theme with:
$ yarn run build
  1. View the site in http://localhost:8888
  2. Optionally zip the whole folder except for the /node_modules/, then upload, install and activate the theme in the remote server (should only be done during debugging)
$ zip -9 -r client-x.zip client-x -x "*/.*" "*/node_modules/*" "*/vendor/bin/*"

Deploying the customized Sage theme in a WordPress site

  1. Build the production theme with:
$ yarn build:production
  1. Zip the whole folder except for /node_modules/
$ zip -9 -r client-x.zip client-x -x "*/.*" "*/node_modules/*" "*/vendor/bin/*"
  1. Upload, install and activate the zip in the remote server

Development - File System Script Locations

The website/theme development is based on Sage - PHP/JS/CSS code and images should be placed in the correct files based on Sage's file structure.

PHP

PHP scripts should be placed in:

  • /app/admin.php - for all admin/backend related PHP scripts - e.g. add_action( 'admin_head', ... )
  • /app/filters.php - for all frontend related PHP scripts - e.g. add_action( 'wp_content', ...)
  • /app/helpers.php - for all helper functions - e.g. function rgba_to_hex( $color ) { ... }
  • /resources/views - for all frontend template scripts - e.g. modifying the header/footer/blog

CSS

CSS rules should be placed in:

  • /resources/assets/styles/common/_variables.scss - Bulma variables or CSS custom properties
  • /resources/assets/styles/components - Component styles - e.g. buttons customizations, input field customizations
  • /resources/assets/styles/layouts - Layout styles - e.g. header/footer styles, individual page styles

Add a new file in /resources/assets/styles/layouts for new pages (e.g. about-us.scss for the "About Us" page), then add the @import statement (e.g. @import "layouts/about-us"; in /resources/assets/styles/main.scss

Images

Images should be placed in:

  • /resources/assets/images

Adding images in PHP templates:

<img src="@asset('images/example.jpg')">

Adding images in CSS rules:

.background {
  background-image: url(../images/image.jpg);
}

Javascript

Javascript should be placed in:

  • /resources/assets/scripts/routes/common.js - JS that will run on every frontend page (put code inside the init() function
  • /resources/assets/scripts/routes/home.js - JS that will run on the frontpage (put code inside the init() function
  • /resources/assets/scripts/routes/about.js - JS that will run on the page with the body class about-us (put code inside the init() function

To write Javascript that would only run on a specific page, first create a page with a title, then view it in the frontend, then pick a unique body class. For example:

class="singular-data page-about-data"

To create a script that would only run when the page has a body class of page-about-data, create the new file /resources/assets/scripts/routes/pageAboutData.js, with the contents:

export default {
  init() {
    // Put code here that will run on DOM ready.
    alert( 'Will run if body has the class "page-about-data"' );
  },
};

then in /resources/assets/scripts/main.js, add these new lines:

// Add near the top along with the other imports.
import pageAboutData from './routes/pageAboutData';

and

const routes = new Router({
    // All pages
    common,
    // Home page
    home,
    // About Us page, note the change from about-us to aboutUs.
    aboutUs,
    // Add our page-about-data script.
    pageAboutData,
});

Development - Prepare Sage/Bulma/Theme

We need to change some items first in the Sage theme:

  1. Remove the container class in the page's body. In /resources/views/layouts/app.blade.php remove the container class in the main content wrapper:

Change:

<div class="wrap container" role="document">

To:

<div class="wrap" role="document">
  1. Apply reset/base styles to the theme. In /resources/assets/styles/common/_global.scss add the following:
html {
	font-size: 18px;
}

body {
	line-height: 1.5;
}

h1 {
	font-size: $size-1;
}

h2 {
	font-size: $size-2;
}

h3 {
	font-size: $size-3;
}

h4 {
	font-size: $size-4;
}

h5 {
	font-size: $size-5;
}

h6 {
	font-size: $size-6;
}

Development - Creating a Base Style Guide

Quick introduction to Bulma: https://scotch.io/bar-talk/get-to-know-bulma-my-current-favorite-css-framework

In this step, you will need to study the mockup designs of the website and come up with a collection of styles that will become the foundation of the website. This collection of styles will need to be gathered and serve as the overall "theme" of the site, and so that they can easily be re-used throughout the different pages.

Open (or print out) all the mockup designs of the website and gather the following styles:

  1. Background and container colors
  2. Text styles - heading colors, body text color and sizes
  3. Fonts used for headings and various body text
  4. The website's primary color (used for links, buttons, and primary areas like notifications or hero heading backgrounds)
  5. Other styles used more than once throughout the site

Place the styles in these locations:

  • /resources/assets/styles/common/_variables.scss - Bulma customizations or CSS custom properties
  • /resources/assets/styles/common/_global.scss - Site-wide non-component-specific styles e.g. headings, body background
  • /resources/assets/styles/components/ - Individual component styles e.g. buttons, read more links, input fields
  • /resources/assets/styles/layouts/ - Layout styles e.g. heading, footer, sidebar

For example, let's use this mockup and assume that the other mockup pages look very similar.

screenshot From https://getbedtimestories.com/

I can imagine that the mockup above would be created in the future using the following markup:

<h1 class="title">The storytelling app for families</h1>
<p class="subtitle">Awake the inner...</p>
<div class="buttons">
    <a href="#" class="button is-primary">How does it work?</a>
    <a href="#" class="button is-primary is-outlined">Explore Library</a>
</div>
<p class="has-text-primary has-text-weight-semibold">
    <span class="icon"><i class="fab fa-github"></i></span>
    Parents' Choice Approved App
</p>

Because we're using Bulma, a lot of the styling has been handled by Bulma's classes, so we will only need a few customized styles in this case.

The classes .title .subtitle .buttons .button .is-primary .is-outlined .has-text-primary and has-text-weight-semibold are defined by Bulma. Check the documentation.

If I was to create a website based on the mockup above, I can gather the following styles:

In /resources/assets/styles/common/_variables.scss:

$purple: #8e51c7;
$purple-invert: #fff;

// This color gets applied to the button and other elements that use the primary color.
$primary: $purple;
$primary-invert: $purple-invert;

Those are Bulma variables. Using this as basis https://bulma.io/documentation/overview/customize/

In /resources/assets/styles/common/_global.scss:

@import url('https://fonts.googleapis.com/css?family=Allerta');
html {
    font-size: 18px;
}
body {
    font-family: 'Allerta', sans-serif;
    color: #998da0;
}
h1, h2, h3, h4, h5, h6 {
    font-family: 'Allerta', sans-serif;
    color: #463853;
}

In /resources/assets/styles/components/_buttons.scss:

// Add to Bulma's default button element styles.
.button {
    border-radius: 8px;
}
.button.is-outlined {
    border-width: 2px;
}

With only those styles above, we now have a base style for our entire site.

That's it for now...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment