Skip to main content

Setup

Find & Replace​

This can be done automatically by running npm run setup and then npm run config in terminal. Answer the few questions, and the below will be done for you. This is the preferred method. You will still need to manually edit the style.css in the theme root with the correct information. Then skip to step #2.

If you prefer to do it manually, follow the below steps.

  1. Navigate to the theme and you'll need to change all instances of the name: jaws.
  • Search for: jaws.pot and replace with: project-name.pot in composer.json
  • Search for: , 'text-domain' and replace with: , 'projectName' (inside backticks) to capture the text domain
  • Update Text Domain: text-domain to: Text Domain: projectName in style.css
  • Update "jaws" to: "projectName" (with double quotes) in phpcs.xml.dist and package.json
  • Update 'jaws' to: 'projectName' (with single quotes) in inc/setup/setup.php
  • Search for: jaws- and replace with: 'projectName- to capture prefixed handles
  • Search for: jaws/blockname and replace with: projectName/blockname in the block foundation directories
  • Search for: jaws-wp-starter and replace with: project-name in package.json
  • Search for projectNameUrl.local and replace with: projectName.local to match your local development URL. This should be the same url for each developer to keep environments consistent.
  • Edit the theme information in the header of style.css to meet your needs
  • Search for jaws just to make sure you caught everything.

  1. From the command line, change directories to the theme's directory. cd path/to/theme

  2. Install theme dependencies and trigger an initial build.

    Note: You will need to have Composer and NPM installed first.

    npm run setup

    This command will run composer install and npm install, so that all the necessary modules are installed for the theme and build tools to work correctly.

  3. Feel free to delete the /setup directory and npm uninstall inquirer shelljs.

Development​

The local url for this website should be https://websiteName.local. To keep environments across the board, consistent, the same url should be used whenever someone setups a site on an environment. This way, the package.json will not have to change. However, if one changes the url in the package.json, do not commit that change to the repo as it could break other developer's builds. This is the URL used in package.json for browsersync functionality.

From the command line, type any of the following to perform an action:

Command | Action

npm run watch | Builds assets and starts Live Reload and Browsersync servers

npm run start | Builds assets and starts Live Reload server

npm run build | Builds production-ready assets for a deployment

npm run lint | Check all CSS, JS, MD, and PHP files for errors

npm run format | Fix all CSS, JS, MD, and PHP formatting errors automatically

Directory Structure​

📦
├─ .vscode - VSCode Settings and extension recs
├─ build - Created when the site compiles
├─ components - a.k.a php partials
├─ inc
│  ├─ blocks - Register and whitelist blocks
│  ├─ function - Get type of functions
│  ├─ hooks - Filters and actions
│  ├─ post-layouts - Gutenberg templates for post types
│  ├─ setup - WordPress theme setup, eg, scripts, styles, thumbnails, etc
│  ├─ shortcodes
│  └─ template-tags - Functions that print data
├─ setup - Config files for theme setup
└─ src
   ├─ block-filters - Filters for blocks
   ├─ block-styles - Styles for blocks
   ├─ block-variations - Variations for blocks
   ├─ blocks - Custom Gutenberg Blocks
   ├─ fonts - Webfonts
   ├─ images - Images
   │  └─ icons - SVG Icons
   ├─ js - JavaScript
   └─ scss - Styling

Included PHP Files​

Navigate to the /inc folder to declare any theme functionality. All files in this folder are imported inside of functions.php.

Adding New Functions​

Is it a hook? The /inc/hooks folder makes sense. A general function? It probably should go into /inc/functions. Feel free to add new folders as you see fit for organizational purposes.

New functions added as files will automatically be available to the theme. However, remember to correctly prefix the function.

Filenames​

As a general rule, each .php file should contain a single function/action which should match the name of the file (replacing underscores with hyphens in the filename).

For example, function bite_boat() {...} would be declared in a file named bite-boat.php and stored inside an appropriate /inc subfolder.

Function Naming Conventions​

If you're getting a value (ie: expecting a return), name function (and file) appropriately: get_sailor_name() & get-sailor-name.php.

If you're displaying something, use the term print: print_warning() & print-warning.php.

The goal is to use action words where possible to indicate what the function was doing, ie: get, print, disable, include, is, has, etc.

Function Prefixing​

All functions should be prefixed with jaws_ to avoid function conflicts and to specify which functions are custom.

Source Assets​

Frontend CSS and JS​

src/index.js is the main source for frontend CSS and JS. The compiled files are only enqueued on the frontend.

Frontend Critical CSS​

src/critical.js imports the css that will be inlined on page load. This is where you'd ideally place "above-the-fold" styling, so users have less of a FOUC.

Admin CSS and JS​

src/admin.js is the main source for admin CSS and JS. The compiled files are only enqueued on the admin.

Building Assets​

There is one directory that gets compiled and created, /build. All code from within the /src directory will be output into /build. Include assets accordingly, always reference the /build directory.