wordpress_theme_code_style

wordpress_theme_code_style-v2.md

Naming & Organizing WordPress Theme Code - Version 2

A while ago I wrote a gist on how I style theme code. I recently updated my starter theme. In doing so, some of my ideas have evolved.

Core Tenants

1. No abstractions! All code should be explicit, meaning it can be explained to developers of all skill types.
2. When possible, follow DRY (Don’t Repeat Yourself) fundamentals.

Structure

Themes should be modular. Each file has a unique purpose and can be organized into specific folders based on that purpose.

• JavaScript elements are into the /scripts folder.
• Images are in the /images folder.
• Style (written in SCSS) is in the /styles folder (compiled through style.scss).
• PHP functions are in the /includes folder (compiled through functions.php).
• template_parts includes each unique of the theme (all pulled into index.php).

Code with a purpose that can't fit into any of those folders, like style-tinymce.css, can be added to the theme’s home directory.

Basic Theme Architecture:

/theme_name
├── index.php
├── functions.php
├── /includes
├── /scripts
├── style.css
├── style.scss
├── /styles
│   ├── _document.scss
│   ├── _variables.scss
│   ├── /etc
│   │   ├── _animate.scss
│   │   ├── _fancybox.scss
│   │   ├── _image_scrolling.scss
│   │   ├── _includes.scss
│   │   └── _wordpress.scss
│   ├── /fonts
│   │   └── /font-awesome
│   ├── /mixins
│   │   ├── _backgrounds.scss
│   │   ├── _buttons.scss
│   │   └── _responsive.scss
│   └──template_parts/
│       ├── _footer.scss
│       ├── _header.scss
│       ├── _layouts.scss
│       ├── _loop_content.scss
│       ├── _media.scss
│       └── _segments.scss
├── template_parts/
│       ├── footer.php
│       ├── header.php
│       ├── layouts-{{element_name}}.php
│       ├── loop_content-{{name}}.php
│       ├── media-{{element_name}}.php
│       └── segments-{{element_name}}.php
└── footer.php

Adding a Template Part

Template parts help with organization and avoid code redundancy.

Each template part falls into one of seven types:

1. layout : Site layouts (ie- layout-front_page).
2. loop_content: Element with content that requires the loop.
3. media: Element with media content that requires the loop.
4. segment: Sub elements within a loop_content element that requires the loop.
5. header: The site's header.
6. footer: The site's footer.

The template part naming convention is: <type>-<name>.php.

For instance, a template part that we use to recent posts is named feature-recent_posts.php.

Naming HTML within Template Parts

All template parts include a parent wrapper div with a class reference to the template part in this format class="<type>-<name>

Example:

<div class="feature-recent_posts">
  ...
</div>

Child elements should reference their parent's name before referencing their own name. All names should be unique and descriptive. The format is class="<parent/type>-<name>.

Example:

<div class="feature-recent_posts">
  <div class="recent_posts-single_post">
     ...
  </div>
</div>

Avoid referencing style helper classes in class name.

Do this:

<div class="feature-recent_posts">...</div>

Don't Do This:

<div class="feature-recent_posts responsive-container"></div>

Mixins can do what style classes once did.

Example:

.feature-recent_posts{
  @include responsive-container();
}

Everything else..

If you're building somethat isn't quite a template part, I suggest you create a function and place it in /includes. There's also an _includes.scss to style elements within the included function.

---

For guidance on code styling, checkout @mdo's Code Guide.