Video Walkthrough¶

If you like, you can watch a video walkthrough below covering steps of this chapter setup.

There is also another video covering “Project setup” and basic git workflow.

Download Tools¶

Here are the links to necessary tools. Please start downloading them and in the meantime go ahead and proceed with next instructions.

Everyone:

• PHPStorm as preferred IDE: PHPStorm EAP
• Git for GitLab access: Git
• PHP (for Composer): PHP
• Composer for getting the framework code: Composer

Backend tools:

• Database tool: either Adminer or HeidiSQL
• (optional) Xdebug helper for Chrome: Xdebug helper

Frontend tools:

• Node + NPM: Node
• gulp: gulp

Setup Hosts¶

This step is optional, however sometimes it helps to keep the connection alive.

1. Open file C:\Windows\System32\drivers\etc\hosts in administrator mode

2. Add the following lines at the end (where CT_SERVER_NUMBER is you CT number)

   10.0.0.111 pinky.createit
   10.1.0.101 CT_SERVER_NUMBER.phinky.createit
   

3. The addresses may change, please ask your project manager for the actual addresses.

Setup Pinky (Poland) or PHinky (Philippines)¶

First, mount your server space as a local drive.

Basically, what you need to do is:

1. Go to My computer
2. Click Map network drive button
3. Select drive letter (we’ll use V in the examples)
4. Enter location: \\pinky.createit\www\CT_SERVER_NUMBER\ or CT_SERVER_NUMBER.phinky.createit\wwww\CT_SERVER_NUMBER (replace CT_SERVER_NUMBER with your information, eg. ct11)
5. Done. Check if you can browse your Pinky or PHinky.

More detailed instruction can be found here

WordPress Installation¶

Install PHP¶

1. Download the current stable PHP version at PHP Windows

2. Unzip contents to C:\php\

3. Rename file C:\php\php.ini-development to C:\php\php.ini

4. Open C:\php\php.ini and uncomment openssl extension, ie. change line

   ;extension=php_openssl.dll
   

   to

   extension=php_openssl.dll
   

5. That’s all

Install Composer¶

1. Just in case, install Visual C++ Redist
2. Download Composer
3. Run the installer with default options

Install Git¶

1. Download Git
2. Run the installer with default options

Setup PHPStorm¶

1. Download PHPStorm EAP . It is an EAP, so you will need to download new version and reinstall it every 30 days.

2. Run the installer

3. Check to install: JRE by JetBrains

4. Install

5. Run and open File -> Settings -> Version Control -> Git and enter path to installed git.exe

6. Open File -> Settings -> Build & Execution & Deployment -> Deployment and enter settings as follows changing ct11 to your CT Server Number

   

7. Make sure you have set pinky as default deployment (in servers list, right click on your pinky and check set as default)

8. You can add Wordpress support yo your PHPStorm by adding path to folder with fresh Wordpress Installation.

   

9. Your PHPStorm is configured

Setup new project¶

You can wath a video covering this chapter

When you have your project assigned, follow these steps.

1. Create a new folder, eg. c:\work\projectname (replace projectname with the actual project name)

2. Copy contents of c:\work\boilerplate to c:\work\projectname

3. Optionally, delete contents of c:\work\projectname\wp-content\themes and c:\work\projectname\wp-content\plugins

4. In PHPStorm choose File -> Open and select c:\work\projectname

5. Once opened, checkout your project files from Git (most likely, they will be empty)

   1. Checkout project theme to c:\work\projectname\wp-content\themes ( so in result you have c:\work\projectname\wp-content\themes\projectname\ ),
   2. Checkout project plugin to c:\work\projectname\wp-content\plugins ( so in result you have c:\work\projectname\wp-content\plugins\projectname-plugin\ )
   3. Checkout project demo plugin to c:\work\projectname\wp-content\plugins ( so in result you have c:\work\projectname\wp-content\plugins\projectname-demo-plugin\ )

6. Once checked out, in file explorer, copy boilerplate files to your project folders

   1. Copy theme-boilerplate contents to c:\work\projectname\wp-content\themes\projectname\theme (create directory theme), so in result you have c:\work\projectname\wp-content\themes\projectname\theme\style.css
   2. Copy theme-plugin-boilerplate contents to c:\work\projectname\wp-content\plugins\projectname-plugin
   3. Copy theme-demo-plugin-boilerplate contents to c:\work\projectname\wp-content\plugins\projectname-demo-plugin

Additional backend settings¶

# set this for easy plugin installation
define("FS_METHOD",'direct');

# set error show
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]

# add a trailing slash to /wp-admin
RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]

RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
RewriteRule ^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]
RewriteRule ^([_0-9a-zA-Z-]+/)?(.*\.php)$ $2 [L]
RewriteRule . index.php [L]

# general errors
php_flag display_startup_errors on
php_flag display_errors on
php_flag log_errors on
php_value error_log  /var/www/YOUR-PATH/logs/PHP_errors.log
php_value error_reporting -1
php_value short_open_tag false

# xdebug dump
php_value xdebug.var_display_max_depth 20
php_value xdebug.var_display_max_children 256
php_value xdebug.var_display_max_data -1
php_value xdebug.max_nesting_level 5000
php_value xdebug.show_local_vars 1
php_value xdebug.collect_params 1
# php_value xdebug.collect_assignments 1
# php_value xdebug.collect_includes 1
# php_value xdebug.collect_return 1

# xdebug debugger
php_value xdebug.remote_connect_back 1

# xdebug profiler
php_value xdebug.profiler_enable 0
php_value xdebug.profiler_enable_trigger 1
php_value xdebug.profiler_enable_trigger_value PHPSTORM
php_value xdebug.profiler_output_dir /var/www/YOUR-PATH/logs/profiler
php_value xdebug.profiler_output_name callgrind.%H%R.callgrind

# xdebug trace
php_value xdebug.auto_trace 0
php_value xdebug.trace_enable_trigger 1
php_value xdebug.trace_enable_trigger_value PHPSTORM
php_value xdebug.trace_output_dir /var/www/YOUR-PATH/logs/trace
php_value xdebug.trace_output_name trace_%H%R
php_value xdebug.trace_format 0

Structure¶

plugins/
│--themename-plugin/
  │--theme-name.php             # load bumblebee
  │--vendor/
  │  │--bumblebee/
  │    │--bumblebee/            # bumblebee core
  │    │--unyson/               # unyson core
  │--extensions/
    │--example-extension-name/
    │  │--includes/             # additional extension files
    │  │--views/                # view files
    │  │  │--view.php
    │  │--class-fw-extension-example-extension-name.php   # ( optional ) shortcode class to handle extension logic
    │  │--manifest.php          # Extension details: title, description, version, dependencies, etc.
    │  │--hooks.php             # Extension specific hooks ( add_filter, add_action )
    │  │--helpers.php           # Extension functions accessible globally
    │  │--static.php            # Add script and styles
    │  │-─posts.php             # Register post types, taxonomies etc.
    │  │-─shortcodes/
    │    │--example-shortcode-name/
    │    │  │--includes/        # additional shortcode files
    │    │  │--class-fw-shortcode-example-shortcode-name.php   # ( optional ) shortcode class to handle shortcode logic
    │    │  │--config.php       # simple options: title, tab, icon, description, custom markup
    │    │  │--options.php      # shortcode options array
    │    │  │--views/
    │    │  │--view.php
    │    │--...
    │--...

Plugin description¶

Sample project data do fill in the theme plugin would be (for an example My Theme theme):

/**
 * Plugin Name: My Plugin
 * Plugin URI: http://createit.pl/
 * Version: 1.0
 * Description: Plugin containing essential functionality required by My Theme.
 * Author: createIT
 * Author URI: http://createit.pl
 */

Vendor directory¶

When you clone Theme Plugin from repository, there will be composer.json and composer.lock files there. In order to get vendor files, you will need to have composer installed and run in the main plugin dir:

composer install

ie.:

C:\dimy\disrupt\wp-content\plugins\disrupt-plugin>composer install

This will pull both Bumblebee and Unyson from repositories. Unyson is the framework core with basic functionality. Bumblebee adds additional features to the core.

Structure¶

themes/
├-projectname/
  ├-theme/
  │  │--vendor/                     # Commerial plugins zip files (if required by the theme)
  │  │--page-templates/
  │  │--languages/                  # Leave empty for autogenerated .pot file (create a .gitkeep file if needed)
  │  │--demo-content/               # Demo contents manifests and screenshots. The content itself should be autogenerated.
  │  │  │--example-multipager/
  │  │  │  │--manifest.php          # Demo content name, image, preview link
  │  │  │  │--screenshot.png
  │  │  │--example-onepager/
  │  │  │--...
  │  │--assets/                     # Static assets
  │  │  │--css/
  │  │  │  │--style.css
  │  │  │--sass/
  │  │  │  │--style.scss
  │  │  │  │--..
  │  │  │--javascripts/
  │  │  │--images/
  │  │  │--.../
  │  │--inc/
  │  │  │--includes/
  │  │  │  │--bee-plugins-check/    # Library to check if required plugins are active and render install instructions
  │  │  │  │--mocks/                # Functions mocking required plugins (such as Unyson) when not active
  │  │  │  │--tgmpa/                # Plugin dependencies library & settings
  │  │  │  │--sub-includes.php      # Includes files in this directory
  │  │  │--vendor/                  # Autoincluded settings for external vendors
  │  │  │  │--megamenu.php
  │  │  │  │--...
  │  │  │--helpers.php              # Theme functions
  │  │  │--hooks.php                # Theme related hooks
  │  │  │--init.php                 # Includes everything else
  │  │  │--menus.php                # Menus related settings
  │  │  │--posts.php                # Default post types & taxonomies options
  │  │  │--static.php               # Enqueue scripts and styles
  │  │--framework-customizations/
  │    │--extensions/
  │    │  │-─extension-name/
  │    │  │-─...
  │    │--theme/
  │      ├-manifest.php             # Theme id, supported extensions etc.
  │      ├-config.php               # Theme specific configuration
  │      └─options/
  │        ├─settings.php           # Theme settings panel
  │        ├─{settings_tab}.php     # Theme settings example tab
  │        ├─customizer.php         # Customizer options
  │        ├─...
  │--child-theme/
     │--framework-customizations/
       │--... # same as in then parent theme, but here you can overwrite specific files from the parent theme

Structure overview¶

theme/languages/

In this directory, there should be .pot translation files for the theme. These are autogenerated in the package build process. See Build for more information.

theme/demo-content

In this directory, there should be demo contents for each theme flavor or version (ie. onepager, multipager). They are autogenerated in the package build process. See Build for more information.

theme/vendor

If theme requires any plugins which are not free to download from WordPress.org repository, they should be available in the theme vendor directory as zip files so that once theme is activated customer can quickly install them via WP Admin. Note this is relevant to external plugins only (ex. Visual Composer or Revolution Slider). The Theme Plugin will be pulled and packed automatically in the package build process. See Build for more information.

theme/inc

This directory contains main theme functionality which is available to users without the Theme Plugin being active. When developing a theme, put all the basic functionality in here.

Here are sample information to be put in the main theme stylesheet

/*
Theme Name: Mytheme
Theme URI: https://createit.pl
Author: Create IT
Author URI: Create IT
Description: My Theme
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: My
Domain Path: /languages
*/

Structure¶

plugins/
│--theme-name-demo-plugin/
  │--class-fw-demo-plugin.php     # Demo functionality hooks
  │--class-fw-demo-content.php    # Demo content import/export related functionality
  │--class-fw-settings-form.php   # Demo plugin settings form settings in wp-admin
  │--wp-cli-functions.php         # Functions accessible to WP CLI
  │--...
  │--extensions
    │--ct-demo
      │--class-fw-extension-ct-demo.php
      │--hooks.php
      │--manifest.php
      │--shortcodes
        │--ct_shortcode_markup
          │--config.php
          │--options.php
          │--views
            │--view.php

Project names¶

• The Project name should be one word and not contain any special characters such as -, _ etc. Examples of project names are: disrupt, estato.
• The Theme name should be projectnametheme and not contain any special characters such as -, _ etc. Examples of theme names and theme folder names are disrupttheme, estatotheme.
• The Theme Plugin folder should be projectname-plugin, examples: disrupt-plugin, estato-plugin. Plugin class name should be FW_CT_Bee_Projectname_Plugin, examples: FW_CT_Bee_Disrupt_Plugin, FW_CT_Bee_Estato_Plugin.
• The Theme Demo Plugin folder should be projectname-demo-plugin, examples: disrupt-demo-plugin, estato-demo-plugin. Demo Plugin class name should be FW_CT_Bee_Projectname_Demo_Plugin, examples: FW_CT_Bee_Disrupt_Demo_Plugin, FW_CT_Bee_Estato_Demo_Plugin.

Text domains¶

In every theme, the text domain to use is ct_theme which at later point is automatically changed to theme name.

$label = __( 'This text is translatable', 'ct_theme' );

Prefixes¶

In both theme and plugin everything is prefixed to prevent naming conflicts and to give a meaning to functions, classes and methods names. See the guidelines below.

Introduction¶

Visual Composer & Unyson¶

While Visual Composer has its own way of defining shortcode parameters (see vc_map), thanks to Bumblebee package we can take leverage of Unyson elegant approach to shortcode options and define our shortcodes Unyson way (read more about Unyson options).

Sample Shortcode¶

Here is a simple shortcode created Unyson way which will be automatically mapped to and available in Visual Composer. This shortcode displays an icon.

plugins/
│--theme-plugin/
  │--extensions/
    │--shortcodes/
        │--shortcodes/
          │--ct-icon/
            ├───config.php      # shortcode config
            ├───options.php     # shortcode options
            └───views
                └───view.php    # shortcode view

<?php if ( ! defined( 'FW' ) ) {
    die( 'Forbidden' );
}

$options = array(

    'icon' => array(
            'label' => __( 'Icon:', 'ct_theme' ),
            'value' => 'fa-users',  // default value
            'type'  => 'icon',      // unyson option type 'icon' (will translate to VC 'iconpicker' param type)
            'tab'   => __( 'Icon', 'ct_theme' ),
    ),

    'title' => array(
            'label'   => __( 'Icon title:', 'ct_theme' ),
            'type'    => 'text',    // unyson option type 'text' (will trasnalte to VC 'textfield' param type)
            'tab'     => __( 'Icon', 'ct_theme' ),
    ),

    'description' => array(
            'label'   => __( 'Icon description:', 'ct_theme' ),
            'type'    => 'text',    // unyson option type 'text' (will trasnalte to VC 'textfield' param type)
            'tab'     => __( 'Icon', 'ct_theme' ),
    ),

);

<?php if ( ! defined( 'FW' ) ) {
    die( 'Forbidden' );
}

/** @var $atts array The shortcode attributes */

?>

<div class="ct-iconBox ct-iconBox--type1 ct-iconBox--white">
    <div class="ct-iconBox-icon"><i class="<?php echo esc_attr( $atts['icon'] ) ?>"></i></div>
    <h6 class="ct-iconBox-title"><?php echo esc_html( $atts['title'] ) ?></h6>
    <p class="ct-iconBox-description"><?php echo esc_html( $atts['description'] ) ?></p>
</div>

<?php if ( ! defined( 'FW' ) ) {
    die( 'Forbidden' );
}

$cfg = array(
    'page_builder' => array(
            'title'            => __( 'Icon', 'ct_theme' ),
            'description'      => __( 'Displays icon', 'ct_theme' ),
            'tab'              => __( 'Disrupt', 'ct_theme' ),      // usually the theme name
            'icon'             => 'fa fa-caret-square-o-up fa-2x',
    )
);

Final effect: shortcode in VC backend editor¶

Final effect: shortcode rendered¶

Think About Your User¶

Think About Your Visitor¶

As well as thinking about your user, you need to think about the content that your website’s visitor will see on the front-end of the website. The Content Types that you create are going to be output, either through your theme or using Pods’s built-in shortcodes. Ask yourself some questions:

What information does the visitor need?

What information is most important?

How will the visitor navigate the content?

How will the visitor search the content?

Plan Your Content¶

With that advice in mind, start planning out your content. You’re going to need to decide the following things:

What Custom Post Types do you need on your website? Each of these will be an individual item of content. For example, on an Ecommerce website, the Custom Post Type needed would be Products. How should the content be organized? You may decide that you want to create more than one Taxonomy for a Post Type. This will create a website in which the content can be queried in multiple ways. For example, for an Ecommerce website you might wish to have the non-hierarchical taxonomy Brand and the hierarchical taxonomy Product Type. What additional data will enrich your content? You can create Custom Fields which are meta data attached to your Content. Examples for an Ecommerce website might be price, release date, and colour. Remember that while Taxonomies are ways to group Post Types together, Custom Fields are a mechanism for attaching individual data to your content.

Here are some examples of basic Content Types you might create for different types of websites.

An Ecommerce website:

A book review website:

An events website:

Posts Settings Locations¶

Post related options should be set in the following locations:

• for custom post types defined in extensions: plugin extension directory (see posts.php in Plugin structure)
• for basic post types (post, page) and post formats: theme/inc/posts.php (see Theme structure)

It is necessary to register basic post types settings in the theme because they need to work without the theme plugin activated.

Custom Post Type Example¶

To analyse example extension ct-portfolio with custom post type and taxonomy, there is a file theme-plugin/extensions/ct-portfolio/posts.php with the following example content:

<?php if ( ! defined( 'FW' ) ) {
        die( 'Forbidden' );
    }

/** Register post type & taxonomy for extension */

$ct_post = fw()->extensions->get( 'ct-portfolio' );

register_post_type( $ct_post->get_post_type(), array(
        'labels'              => array(
                'name'               => __( 'Portfolio items', 'ct_theme' ),
                'singular_name'      => __( 'Portfolio Item', 'ct_theme' ),
                'menu_name'          => __( 'Portfolio items', 'ct_theme' ),
                'add_new'            => __( 'Add New', 'portfolio', 'ct_theme' ),
                'add_new_item'       => __( 'Add New Portfolio Item', 'ct_theme' ),
                'new_item'           => __( 'New Portfolio Item', 'ct_theme' ),
                'edit_item'          => __( 'Edit Portfolio Item', 'ct_theme' ),
                'view_item'          => __( 'View Portfolio Item', 'ct_theme' ),
                'all_items'          => __( 'Our projects', 'ct_theme' ),
                'search_items'       => __( 'Search Portfolio Items', 'ct_theme' ),
                'parent_item_colon'  => '',
                'not_found'          => __( 'No portfolio item found', 'ct_theme' ),
                'not_found_in_trash' => __( 'No portfolio items found in Trash', 'ct_theme' ),
        ),
        'singular_label'      => __( 'portfolio', 'ct_theme' ),
        'public'              => true,
        'publicly_queryable'  => true,
        'exclude_from_search' => false,
        'show_ui'             => true,
        'show_in_menu'        => true,
        'menu_position'       => 4,
        'menu_icon'           => 'dashicons-images-alt',
        'capability_type'     => 'post',
        'hierarchical'        => false,
        'supports'            => array( 'title', 'editor', 'excerpt', 'thumbnail', 'comments', 'page-attributes' ),
        'has_archive'         => false,
        'rewrite'             => array( 'slug' => $ct_post->get_portfolio_slug() ),
        'query_var'           => false,
        'can_export'          => true,
        'show_in_nav_menus'   => true,
        'taxonomies'          => array( 'post_tag' )
) );

/**
* Creates taxonomies
*/


//Register taxonomy
$category_names = array(
        'singular' => __( 'Portfolio Category', 'fw' ),
        'plural'   => __( 'Portfolio Categories', 'fw' )
);

$labels = array(
        'name'              => sprintf( _x( '%s', 'taxonomy general name', 'fw' ), $category_names['plural'] ),
        'singular_name'     => sprintf( _x( '%s', 'taxonomy singular name', 'fw' ), $category_names['singular'] ),
        'search_items'      => __( 'Search categories', 'fw' ),
        'all_items'         => sprintf( __( 'All %s', 'fw' ), $category_names['plural'] ),
        'parent_item'       => sprintf( __( 'Parent %s', 'fw' ), $category_names['singular'] ),
        'parent_item_colon' => sprintf( __( 'Parent %s:', 'fw' ), $category_names['singular'] ),
        'edit_item'         => sprintf( __( 'Edit %s', 'fw' ), $category_names['singular'] ),
        'update_item'       => sprintf( __( 'Update %s', 'fw' ), $category_names['singular'] ),
        'add_new_item'      => __( 'Add New category', 'fw' ),
    'new_item_name'     => sprintf( __( 'New %s Name', 'fw' ), $category_names['singular'] ),
    'menu_name'         => sprintf( __( '%s', 'fw' ), $category_names['plural'] )
);

$args = array(
    'labels'            => $labels,
    'public'            => true,
    'hierarchical'      => true,
    'show_ui'           => true,
    'show_admin_column' => true,
    'query_var'         => true,
    'show_in_nav_menus' => true,
    'show_tagcloud'     => false,
    'rewrite'           => array(
            'slug' => $ct_post->get_taxonomy_slug()
    ),
);

register_taxonomy( $ct_post->get_taxonomy_type(), esc_attr( $ct_post->get_post_type() ), $args );

This file is automatically included as long as the extension is activated.

Result:

Create New Post Type Extension¶

Before you create a new extension, it is a good idea to browse already written extensions at Samples Gitlab repository

In order to create a new post type extension, please copy the example ct-team extension from boilerplate at theme-plugin-boilerplate/extensions/ct-team and change settings in class-fw-extension-ct-team.php and posts.php file according to new extension needs. More information about extensions can be found in Extensions documentation

Post Settings Example¶

If you need to add custom metaboxes to post formats, you can do so in theme/inc/posts.php file, as in the snippet below:

<?php if ( ! defined( 'ABSPATH' ) ) {
        die( 'Direct access forbidden.' );
}

/**
* Post settings
*/

/** Register metaboxes */
add_action( 'admin_print_scripts', 'fw_ct_bee_display_metaboxes', 1000 );
function fw_ct_bee_display_metaboxes() {
        add_meta_box( "post-video-meta", esc_html__( "Video format settings", 'ct_theme' ), "fw_bee_post_video_meta", "post", "normal", "high" );
        add_meta_box( "post-audio-meta", esc_html__( "Audio format settings", 'ct_theme' ), "fw_bee_post_audio_meta", "post", "normal", "high" );
}

/** Register custom post save action */
add_action( 'save_post', '_fw_ct_bee_post_save_details' );

/** meta render callback */
function fw_bee_post_audio_meta() {
    // TODO implement callback
}

/** meta render callback */
function fw_bee_post_video_meta() {
    // TODO implement callback
}

/** post save callbacks */
function _fw_ct_bee_post_save_details() {
    // TODO implement callback
}

...

Shortcodes¶

Test your knowledge of shortcodes by creating the following shortcodes in your project. Unyson way.

1. Simple Button¶

Create a simple button shortcode which allows you to:

• Enter a title,
• Enter a link,
• Select button size ( small or large ),
• Select button style ( white or dark ),
• Enter additional css classes.

The shortcode should look like this in the backend Visual Composer editor:

And should render an HTML like below, depending on options chosen:

<!-- Example one -->

<a href="http://link_example.com" class="btn btn-large bth-white example_custom_class">title_example</a>

<!-- Example two. -->

<a href="#" class="btn btn-small btn-dark example_custom_class_2">title_example_2</a>

<!-- Example three. No link entered in options. No custom class entered. -->

<a class="btn btn-small btn-dark">title_example_2</a>

Helpful reading:

• Unyson options
• Unyson options: text
• Unyson options: select

2. Button With Related Shortcode¶

Extend the previous button with following options:

• Checkbox to enable / disable the button ( render nothing when disabled ),
• Select simple or separated button,
• If grouped, allow to choose an icon ( as related shortcode ct_icon from the example ),
• If simple, hide icon select.

The shortcode should look like this in the backend Visual Composer editor:

Simple button options view:

Separated button options view:

And should render an HTML like below, depending on options chosen:

<!-- Example one. Simple button. -->

<a href="http://link_example.com" class="btn btn-large bth-white example_custom_class">title_example</a>

<!-- Example two. Separated button with icon. -->

<a href="http://button_link.com" class="btn-group btn-group--separated">
    <span class="btn btn-dark btn-separated btn-small ">button_title</span>
    <span class="btn btn-dark btn-separated btn-small ">
        <div class="ct-iconBox ct-iconBox--type1 ct-iconBox--white">
            <div class="ct-iconBox-icon"><i class="fa fa-instagram"></i></div>
            <h6 class="ct-iconBox-title">icon_title</h6>
            <p class="ct-iconBox-description">icon_desc</p>
        </div>
    </span>
</a>

<!-- Example three. Button disabled. Nothing to render. -->

Make sure you created ct_icon shortcode ( as in example ) beforehand in your project so you use it and not double functionality in button shortcode.

Helpful reading:

• Option type: ‘shortcode’
• Dependency: Shortcodes Visual Composer Integration

Customizer¶

Documentation¶

All the docs regarding both Bumblebee and Unyson can be found here: Bumblebee

1. Introduction to Awesome WordPress¶

Let’s start from the basics ie. what is WordPress and why it’s so cool. Below you will find step by step tutorials which should explain the basics.

• Watch the tutorial: WordPress Beginners Guide
• Understanding and Working with Data in WordPress
• Understanding WordPress Multisite

2. WordPress Themes and Plugins¶

So you now what WordPress is. Now it’s time to find our what makes WordPress awesome and universal platform. Below you will find tutorials about two most powerful WordPress elements: Themes and Plugins

• Watch the tutorial: WordPress Themes
• Child Theme
• Creating Child Themes
• Overriding Parent Theme Functions in Your Child Theme
• How to Install WordPress Plugin
• Plugin Territory

3. Post Types, Shortcodes, Widgets, Customizer¶

4. Visual Composer and Common Plugins¶

Plugins enhance the capabilities of WordPress.There are over 45 055 free plugins in WordPress.org repository

• Getting Started with Visual Composer
• Beginner’s Guide to Using WooCommerce
• Slider Revolution Beginner Video Guides
• Mini Guide to Contact Form 7
• The Beginner’s Guide to WordPress SEO by Yoast

5. Tips & Tricks¶

• Tips for Aspiring WordPress Developers
• 5 “Saintly” Practices that All WordPress Developers Should Strive For
• Common WordPress Development Mistakes and How to Fix Them
• How to Include JavaScript and CSS in Your WordPress Themes and Plugins
• Using Page Templates in Your WordPress Theme

6. Theme Testing¶

Each WordPress project before upload needs to be tested. By testing we mean checking every single theme element, shortcode and option. It will save your time when you do first tests while creating each element.

Theme Plugin¶

How to update framework files?¶

Run composer update in theme plugin directory terminal. Just like in this example:

Visual Composer¶

General¶

ssh -T git@gitlab.createit.pl

// parse all text in widget text as shortcodes
add_filter( 'widget_text', 'do_shortcode' );

Head area¶

First part of header.php file is head area. Be shure that things listed below are included corectly:

• Proper DOCTYPE
• Opened <html> tah with language_attributes()
• The <meta> charset element should be placed as first
• Use bloginfo() to set the <meta> charset and description elements
• Use wp_title() to seth the <title> element
• Use Automatic Feed Links to add feed links
• Add call tp wp_head() before you close </head> tag.

Remember - do not link the theme stylesheets in the Header template. Use the wp_enqueue_script and wp_enqueue_style action hooks in inc/static.php file.

Example of correctly-formatted HTML head area:

<!DOCTYPE html>
    <html <?php language_attributes(); ?>>
        <head>
            <meta charset="<?php bloginfo( 'charset' ); ?>" />
            <title><?php wp_title(); ?></title>
            <link rel="profile" href="http://gmpg.org/xfn/11" />
            <link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>" />
            <?php if ( is_singular() && get_option( 'thread_comments' ) ) wp_enqueue_script( 'comment-reply' ); ?>
            <?php wp_head(); ?>
        </head>

Body Section¶

Do not put cutom classes on body element. To pust custom classes on body use function in function.php file (fw_ct_bee_filter_add_body_classes()).

Site Header¶

Usually we should place here a logo and link to the main page but there is very important to protect theme to display page titile when header image is not attached. To use header image you must register function in fuction.php file, to see how you can do it visit Codex

Example of correct-placed logo and page title section.

<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home" class="navbar-brand">
    <?php if ( has_header_image() ) : ?>
        <img src="<?php header_image(); ?>" width="<?php echo get_custom_header()->width; ?>" height="<?php echo get_custom_header()->height; ?>" alt="<?php echo esc_attr( get_bloginfo( 'name' ) ); ?>">
            <?php else: ?> <h1> <?php echo esc_attr( get_bloginfo( 'name' ) ); ?></h1> <?php endif; ?>
</a>

Navigation menu¶

Header is file where we usually place the site main navigation. To do that in wordpress we use function wp_nav_manu(). If you want to use the default bootstrap classes in wp navigation you can use this function . Sumbenu items should display correctly, you should supprt drop-down menu for submenu items. Dropdown menus is good practice, them allowing showing menu depth instead of just showing the top level.

Note

Remember when you use mega menu be sure to use default plugin style method. DO NOT HARDCODE MEGA-MENU PLUGIN STYLE IN OUR CSS FILE.

Another thing you should remember when you use mega-menu plugin is that you mustd style default wordpress menu too.

Widgets and custom areas¶

Note

As you now the theme should be widgetized as fully as its possible it means that in header should be registered at least one widget area.

Every additional things (like buttons, links, phone numbers and other that are not a widgets) should be placed in customizer in header/navigation section. Think about put every options for header/navigation (eg. type of navigation - big/small or text in aditional button) to section header/navigation in customizer.

For more info abiut developing customizer options see Customizer section in this documentation.

Before you start¶

First thing you should do before you start developing blog and pages in wp theme (of course only if you didin`t done this before) is download and import to your wp installation Wordpress Theme Unit Test Data it helps you to develope your wp theme. Second thing you should have and which helps you in developing blog is WP Monster Widget .

Page structure¶

Your first step should be index.php file. This one is responsible for displaying post on page. It depends form the project but usually your this page should be displayed in three variants:

• Page with no sidebar
• Page with sidebar on left side
• Page with sidebar on right side

This one like any other blog setting should be set in blog section in Customizer options.

Remember to proper style all worpdress lists pages:

• Archive archive.php
• Author author.php
• Category category.php
• Tag tag.php
• Search search.php

Next thing you should do is develop every type of wp post. Wordpress by default have this type of posts:

• Standard single.php
• Aside content-aside.php
• Image content-image.php
• Video content-video.php
• Audio content-audio.php
• Quote content-quote.php
• Link content-link.php
• Gallery content-gallery.php
• Page content-page.php

Sidebar¶

Blog sidebar is container with registered widget area. You can register blog sidebar in inc/sidebar.php.

Use register function like this:

register_sidebar( array(
    'name'          => esc_html__( 'Blog sidebar', 'ct_theme' ),
    'id'            => 'blog-sidebar',
    'description'   => esc_html__( 'Sidebar placed in blog page', 'ct_theme' ),
    'before_widget' => '<div id="%1$s" class="widget %2$s ct-sidebar-widget ct-u-margin-bottom-30">',
    'after_widget'  => '</div>',
    'before_title'  => '<h4 class="widget-title ct-sidebar-widget-title">',
    'after_title'   => '</h4>',
) );

Next insert sidebar into pages and remember to put them into functions is_active_sidebar() :

<?php if ( is_active_sidebar( 'blog-sidebar' ) ):
        dynamic_sidebar( 'blog-sidebar' );
endif; ?>

For sidebar development put monster widget into your blog sidebar.

Custom post Types¶

When you finished with default blog and sidebar look your next step should be coding Custom Post Types if project need them templates. For more information see Custom Post Types.

Pages¶

The last thing you should do after you finished developing all posts types, lists pages and default widget is work on all custom pages in your project. Every project has unique pages wich you should code and register as a page template - eg. error 404 page - 404.php .

After you finished develping Header, Footer and Blog you should go on Codex Theme Testing Process and check all the points.

Shortcode testing¶

You may test your shortcode (or any markup) with Shortcode markup test shortcode in Bumblebee tab which is available when you activate Theme Demo Plugin.

It will display the markup inside different sections and columns scenarios as in the example:

Developers Tools for testing¶

Query Monitor - check if any PHP errors, warnings are displayed and fix them,

Developers Tools for testing¶

• Monster Widget - test all default WordPress widgets in all types of sidebars,
• WooCoomerce Monster Widget - if your theme support WooCoommerce

Developers Tools for testing¶

• WPtest.io

Frequent reasons¶

Below, there are gathered frequent theme reject reasons. Please make sure none of theme are present in your theme.

1. You should avoid and not to hardcode custom body_class(). Main reason for this is being able to remove the class when needed i.e. child themes.

   What you can do - https://gist.github.com/kailoon/d4d22c9204909dff21eb ref: http://themeshaper.com/2014/11/20/mastering-the-post_class-function/ https://codex.wordpress.org/Function_Reference/body_class#Add_Classes_By_Filters

2. Custom widget areas must use the safety condition “is_active_sidebar” to ensure no naming conflict with other plugins.

3. (Only for themes with WPML support) The file wpml-config.xml is missing.

   http://wpml.org/documentation/support/achieving-wpml-compatibility-for-your-themes-and-plugins/

4. Third party scripts/ styles don’t need to be prefixed to avoid double loading.

   ref: https://github.com/WordPress/twentysixteen/blob/master/functions.php#L250

5. It’s a very poor practice to deregister WordPress’ built-in jQuery and load another specific version.

   Please use the WordPress default javascript library. Use the jQuery noConflict mode to avoid issues — http://codex.wordpress.org/Function_Reference/wp_enqueue_script#jQuery_noConflict_wrappers

6. Please use ‘-‘ instead of ‘_’ or ‘.’ for handlers and remove the extension.

   For examples and there are more: http://envato.d.pr/PHo1V/2aQmS9y4

7. Please use a unique prefix for all function names, custom images sizes, classes, CONSTANTS, hooks,

   public/global variables, and database entries to avoid conflict issues with plugins and other themes. For example, themename_ OR frameworkname_ - Read more at http://themereview.co/prefix-all-the-things/ - You can have frameworkname_ if you are using a framework while using themename_ for your themes.

8. No page title by default, no top margin on content, http://envato.d.pr/8DeKF/2QTcjLug - Left margin is an issue too on some pages, http://envato.d.pr/bB6rr/3lx7HZPK
9. Comments / Trackbacks / pingbacks are not displaying: http://envato.d.pr/WZ9fB/5hnvD0Ar
10. Remove the static hard coded styles (style=) and move to classes/IDs and reference via CSS. http://envato.d.pr/N0hG8/4JGuX2Ri
11. http://envato.d.pr/bRfrC/1EIuWXbN is not needed unless you indicate support for these in your item attributes on ThemeForest
12. Missing site title upon intial installation: http://envato.d.pr/MI3VT
13. Please use get_template_directory when including/requiring files: http://envato.d.pr/E5IGl

14. All dynamic data must be correctly escaped for the context where it is rendered. Please perform a global search

    for “echo $” and you will see several issues. Ref: https://vip.wordpress.com/documentation/vip/best-practices/security/validating-sanitizing-escaping/ Example(s): http://envato.d.pr/fLPzH

15. Please disable force_activation: http://envato.d.pr/jmGZq

16. Please enqueue Google fonts the correct way.

    Here’s an example: https://gist.github.com/richtabor/b85d317518b6273b4a88448a11ed20d3 and here’s a good read: http://themeshaper.com/2014/08/13/how-to-add-google-fonts-to-wordpress-themes/ http://envato.d.pr/7XyrR

17. Directory path should be get_template_directory() and not dirname( FILE ). Use an appropriate path when

    including theme files: • get_template_directory(): Returns the absolute template directory path. • get_template_directory_uri(): Returns the template directory URI. • get_stylesheet_directory(): Returns the absolute stylesheet directory path. • get_stylesheet_directory_uri(): Returns the stylesheet directory URI. Don’t use: dirname(FILE), basename( FILE ) or anything else not listed above. http://envato.d.pr/wNcgO

18. Some of your files contain validation errors that will need to be fixed. Please be sure that all files validate

    before resubmitting. You can validate HTML at http://validator.w3.org

19. Themes should work out of the box without relying on plugins for basic functionality -

    http://envato.d.pr/XBHs/4dQIjsRZ

20. All theme text strings are to be translatable and properly escaped.

    https://gist.github.com/kailoon/01fa8e95d2e910e666c6 example(s) from your code and there are more: http://envato.d.pr/NQsK/1GGgLoRq

21. Scripts and styles should not be hardcoded anywhere in your theme or added any other way but with wp_enqueue_*

    hook and to be added from the functions file. This includes custom JS/CSS. For inline styles use: https://developer.wordpress.org/reference/functions/wp_add_inline_style/ and for scripts https://developer.wordpress.org/reference/functions/wp_add_inline_script/

22. Do not hardcode title. Title tag support now required.

    See https://make.wordpress.org/themes/2015/08/25/title-tag-support-now-required/

23. Data Validation issues have been found in your theme. All dynamic data must be correctly escaped for the context

    where it is rendered. - All dynamic data must be escaped with esc_attr() before rendered in an html attribute. - Whenever you are rendering a url to the screen its value must be passed through esc_url() first. - If dynamic data is rendered inside an attribute that triggers a JavaScript event, it must be escaped with esc_js(). Please make sure you read these articles: https://make.wordpress.org/themes/tags/writing-secure-themes/ http://codex.wordpress.org/Data_Validation http://developer.wordpress.com/themes/escaping/ http://code.tutsplus.com/articles/data-sanitization-and-validation-with-wordpress–wp-25536 https://vip.wordpress.com/documentation/best-practices/security/validating-sanitizing-escaping/

24. Please use wp_enqueue to load any external scripts/stylesheet - wp_enqueue_script / wp_enqueue_style -

    http://codex.wordpress.org/Function_Reference/wp_enqueue_script#Functions For examples and there are more: http://envato.d.pr/GRzd/3JT5PgZJ

25. Please install WordPress plugins from the WordPress repo http://envato.d.pr/p6Ms/448azTjT

26. http://envato.d.pr/bNkq/1jmnraYb

    Always use esc_url when sanitizing URLs, including WordPress related, also, all home_url() must include a trailing slash such as home_url(‘/‘) See: https://codex.wordpress.org/Function_Reference/esc_url

27. Some of your files contain validation errors that will need to be fixed. Please be sure that all files validate before resubmitting.

    You can validate HTML at http://validator.w3.org Example(s): https://validator.w3.org/nu/?doc=http%3A%2F%2Festato.wp.themeforest.createit.pl%2Fblog%2F

28. Make sure to display the page title: http://envato.d.pr/XbNR0/1jR02zSx
29. wp_footer should be placed immediately before body closing tag.
30. Provide unminified versions of JS files: http://envato.d.pr/Y4sW7d/2q0zcXbp

31. Don’t include libraries that are already pre-packaged with WordPress. Reference: https://developer.wordpress.org/reference/functions/wp_enqueue_script/#defaults

    Example(s): http://envato.d.pr/ccWXeZ/4JjyUEc2

32. WooCommerce inner pages need attention.Example(s): https://envato.d.pr/86R3j3/nzsQqAq4MB https://envato.d.pr/wV1TYx/r1PzCSO3MWetc.
33. Post title displaying twice: https://envato.d.pr/mNsB9F/QljldgLXpb
34. Outdated woocommerce templates
35. Ensure all bundled plugins are the latest versions. Example, Visual Composer: http://envato.d.pr/VC77dO
36. Found a translation function that is missing a text-domain. Function esc_html__, with the arguments ‘kidstheme’
37. wp_head should be placed immediately before head closing tag.
38. Don’t combine libraries. This prevents deregistering and can cause double loading issues. Enqueue separately with proper handler instead.
39. Make sure all the WP default widgets display properly in all widgetized areas. You can check with monster widgets plugin. e.g. https://envato.d.pr/Psx477
40. The performance is poor https://envato.d.pr/ltMgUW

41. Some of your files contain validation errors that will need to be fixed. Please be sure that all files validate before resubmitting.

    You can validate HTML at http://validator.w3.org

42. $_SERVER[‘REQUEST_URI’] or $_SERVER[‘SERVER_NAME’] is not safe or server reliable.

Other reasons¶

Below, you can find some of less frequent, project specific reject reasons. Look around to see what to expect from reviewers.

1. Keyword stuffing titles is not permitted, you can use tags for that.

   More info - https://help.market.envato.com/hc/en-us/articles/203039204-Tips-for-Excellent-Titles-Descriptions-and-Tags

2. Would it be possible to get more out-of-the-box look here?

   • http://envato.d.pr/39SvM/49ylx2vv
   • http://envato.d.pr/0dZso/1Lpdw2Ky

3. This is bit crowded:

   http://envato.d.pr/E0RzM/5Ayy0PjA

4. A search UI should be improved, it’s bit confusing:

   http://envato.d.pr/bE8rm/Oj75BSAK

5. A green button is more important here, therefore it should be first and read more second, it just makes better

   sense: http://envato.d.pr/upME9/3oMiY76P

6. Middle page feels a bit crowded:

   http://envato.d.pr/tkNUX/ZPZfbScZ

7. Not sure why the logo is in this area?

   http://envato.d.pr/teLrj/2yfVxJIK

8. Add more padding please:

   http://envato.d.pr/a0T1J/1VG33sJ9

9. Align the content vertically:

   http://envato.d.pr/vruDb/4SZvzVjA

10. Color contrast should be improved:

    http://envato.d.pr/lzebG/G7VqBSOw

11. Not enough of space:

    http://envato.d.pr/gNZIZ/5y8k0D5a

12. Align all items equally:

    http://envato.d.pr/CMV0R/4lNeRb2a

13. Pages like this feel bland:

    http://envato.d.pr/OdZPY/RgphEvdE

14. Test how your theme design breakpoints across desktop, mobile, and tablet: http://design.google.com/resizer
15. By default your theme doesn’t look presentable, this is what I get: http://envato.d.pr/6Cd0K/5R3qYGXw
16. No comments, http://envato.d.pr/oivXh/8GlEDwBw
17. Fatal error on category and author archive, http://envato.d.pr/q4IhV/FWOBkfRU
18. Tables require proper styling: http://envato.d.pr/Ouilr
19. Open mobile menu requires proper styling: http://envato.d.pr/bTTig

20. I found validation errors with the Theme Check plugin. Don’t forget to run Theme Check as well

    https://wordpress.org/plugins/theme-check/ http://envato.d.pr/9MSTp

21. ‘ct’ is not an appropriate prefix. Please use a unique prefix for all function names, custom images sizes,

    classes, constants, hooks, public/global variables, and database entries to avoid conflict issues with plugins and other themes. Two characters is not enough. Ref: http://themereview.co/prefix-all-the-things/ Example(s): http://envato.d.pr/Oqvxj

22. Mobile styling needs attention/improvement in some areas. Please check/test your pages carefully and resolve all

    issues. example: http://envato.d.pr/yhAR/2y1PckFF and more.

23. Your theme is pretty broken upon activation, even after plugins are installed - http://envato.d.pr/6BpU/4NJWxhFz

24. How to test the blog/posts layout/functionality - Import the Theme Unit Test

    [http://codex.wordpress.org/Theme_Unit_Test] file and make sure that: - Posts display correctly, with no apparent visual problems or errors. - Posts display in correct order. - Page navigation displays and works correctly. - As “sticky posts” are a core feature, the theme should style and display them appropriately. - Lack of body text should not adversely impact the layout. - Theme must incorporate both the “Tag” and the “Category” taxonomies in some manner. - Floats are cleared properly for floated element (thumbnail image) at the end of the post content. Reference link: https://wpthemetestdata.wordpress.com/

25. Make sure all the WP default widgets display properly in all widgetized areas. You can check with monster

    widgets plugin.

26. Please use a unique prefix (preferably the theme name or framework name) for all function names, custom images

    sizes, classes, hooks, public/global variables, and database entries to avoid conflict issues with plugins and other themes. For example, themename_ OR frameworkname_. - Read more at http://themereview.co/prefix-all-the-things/ - You can still be using frameworkname_ if you are using a framework while using themename_ for your themes. example(s) from your code and there are more: http://envato.d.pr/a9JH/1eupoJS0

27. This http://envato.d.pr/1dm83/3rnqpcgj lead to this http://envato.d.pr/CBsQ/zqoO93Vq and

    http://envato.d.pr/YFtf/1qaLZPxW

28. This page http://envato.d.pr/cPAF/WQDh9NRI is not necessary as you can easily write it down in the documentation.
29. Theme should work out of the box http://envato.d.pr/2vYK/1PyYwZGI

30. You should avoid and not to hardcode custom body_class(). Main reason for this is being able to remove the class

    when needed i.e. child themes. What you can do - https://gist.github.com/kailoon/d4d22c9204909dff21eb ref: http://themeshaper.com/2014/11/20/mastering-the-post_class-function/ https://codex.wordpress.org/Function_Reference/body_class#Add_Classes_By_Filters

31. The localization file should be in English and delivered as .POT file. .POT will contain all translation strings.

    .POT file name should match the themes-slug. Theme can include an actual translation files, but it should not add the en_US.mo or en_US.po because English already implies.

32. Directory path should be get_template_directory() and not dirname( FILE ).
33. Don’t leave unused code fragments as comments in the code. Please check all your files.

34. Please use a unique prefix for all function names, custom images sizes, classes, CONSTANTS, hooks,

    public/global variables, and database entries to avoid conflict issues with plugins and other themes. For example, themename_ OR frameworkname_ - Read more at http://themereview.co/prefix-all-the-things/ - You can have frameworkname_ if you are using a framework while using themename_ for your themes.

35. It’s a very poor practice to deregister WordPress’ built-in jQuery and load another specific version.

    Please use the WordPress default javascript library. Use the jQuery noConflict mode to avoid issues — http://codex.wordpress.org/Function_Reference/wp_enqueue_script#jQuery_noConflict_wrappers

36. Broken logo:

    http://envato.d.pr/cMmf/4aLb22ne

37. Input placeholders will increase the UX:

    http://www.w3schools.com/tags/att_input_placeholder.asp http://envato.d.pr/UQzi/3F4koerk

38. Icons are a bit crowded and not prominent enough:

    http://envato.d.pr/zXGP/5wC5axRf

39. Increase the spacing:

    • http://envato.d.pr/zAxb/5dWZDVJy
    • http://envato.d.pr/m5tF/qjNpHhTw

40. Rename to “Latest” Blog:

    http://envato.d.pr/BwyP/1pcOP3gr

41. Not sure what the arrow was for and line-height needs to be increased:

    http://envato.d.pr/XwDI/3LXhcFAu

42. Make the space in between more consistent:

    http://envato.d.pr/bysL/1D2a9Oo3

43. The typographic scale needs balancing http://spencermortensen.com/articles/typographic-scale/

    http://envato.d.pr/bysL/1D2a9Oo3

44. It doesn’t align vertically:

    http://envato.d.pr/FiOM/3ZjyZuyB

45. Post titles display twice:

    http://envato.d.pr/N6ip/DYpuIavZ

46. Looks incomplete:

    http://envato.d.pr/Zi6r/2uLZn1jx

47. A demo (Presentation) needs to be complete.
48. Test how your theme design breakpoints across desktop, mobile, and tablet: http://design.google.com/resizer/
49. Can’t close the side menu: http://envato.d.pr/lBo1Ap/5v6pw1sP
50. Comments area design could be improved: http://envato.d.pr/LrYeMO/ZGH7ZQgr
51. Avoid all-caps: https://envato.d.pr/ajh467/llLuYkeLwW
52. This section looks really odd https://envato.d.pr/qFtszT
53. There are a few inconsistent spacing/padding as well as alignment issues throughout the design. I’d like you to go over it with a fine toothed comb and weed out these basic design issues. For examples and there are more: https://envato.d.pr/1wiqaq

Theme¶

In theme development, a unique and more than 2 letters prefix is required by ThemeForest reviewers, therefore the prefix to use in a theme is fw_ct_bee_ for variables, functions, classes, and fw-ct-bee- for styles, image sizes, db options etc.

• Functions and classes should be prefixed with:

  • fw_ct_bee_ for functions
  • FW_Ct_Bee for classes

  function fw_ct_bee_head() {
      // ...
  }
  
  class FW_Ct_Bee_Pagination
  {
      // ...
  }
  

• Private functions and classes should be prefixed the same way due to ThemeForest standards

• Functions used for hooks should be prefixed with:

  • fw_ct_bee_action_ for add_action()
  • fw_ct_bee_filter_ for add_filter()

  /**
   * @internal
   */
  function fw_ct_bee_filter_the_content($content) {
      // ...
  
      return $content;
  }
  add_filter('the_content', 'fw_ct_bee_filter_the_content');
  
  /**
   * @internal
   */
  function fw_ct_bee_action_init() {
      // ...
  }
  add_action('init', 'fw_ct_bee_action_init');
  

• Filters and actions should be prefixed with fw_ct_bee_.

  $data = apply_filters('fw_ct_bee_whatever', $data);
  
  do_action('fw_ct_bee_whatever');
  

Extensions¶

• Public functions and classes should be prefixed with:

  • fw_ext_<extension-name>_ for functions
  • FW_Ext_<extension-name>_ for classes

• Private functions and classes should be prefixed the same way due to ThemeForest standards

• Functions used for hooks should be prefixed with:

  • fw_ext_<extension-name>_action_ for add_action()
  • fw_ext_<extension-name>_filter_ for add_filter()

  For e.g. if extension name is demo:

  /**
   * @internal
   */
  function fw_ext_demo_filter_the_content($content) {
      // ...
  
      return $content;
  }
  add_filter('the_content', 'fw_ext_demo_filter_the_content');
  
  /**
   * @internal
   */
  function fw_ext_demo_action_init() {
      // ...
  }
  add_action('init', 'fw_ext_demo_action_init');
  

• Filters and actions should be prefixed with 'fw_ext_<extension-name>_'.

  For e.g. if extension name is demo:

  $data = apply_filters('fw_ext_demo_whatever', $data);
  
  do_action('fw_ext_demo_whatever');
  

Unyson Core¶

• Public functions and classes should be prefixed with:

  • fw_ for functions
  • FW_ for classes

  function fw_useful_function() {
      // ...
  }
  
  class FW_Useful_Class {
      // ...
  }
  

  Note

  A Public function is meant to be used by anyone. Usually it’s a helper function that does something useful.

• Private functions and classes should be prefixed with:

  • _fw_ for functions
  • _FW_ for classes

  /**
   * @internal
   */
  function _fw_private_function() {
      // ...
  }
  
  /**
   * @internal
   */
  class _FW_Private_Class
  {
      // ...
  }
  

  Note

  A private function is used somewhere internally. Don’t forget to use the @internal tag in your PhpDoc in order to make it clear to other developers that this is a private function. It will also remove the function from your documentation (if you are using an automatic documentation generator)

• Functions and methods used for hooks should be prefixed with:

  • _action_ for add_action()
  • _filter_ for add_filter()

  /**
   * @internal
   */
  function _action_init_something() {
      // ...
  }
  add_action('init', '_action_init_something');
  

  Important

  Be sure the function name is unique enough in order to minimize the chances to be defined by someone else. Do not use too simple function names like _action_init.

  class FW_Example
  {
      public function __construct()
      {
          add_filter('the_content', array($this, '_filter_the_content'));
      }
  
      /**
       * @internal
       */
      public function _filter_the_content($content) {
          // ...
  
          return $content;
      }
  }
  

• Filters and actions should be prefixed with 'fw_'.

  $data = apply_filters('fw_whatever', $data);
  
  do_action('fw_whatever');
  

Escaping and translation functions¶

• wp_kses
• esc_html
• esc_html__
• esc_html_e
• esc_js
• esc_attr
• esc_attr__
• esc_attr_e
• esc_sql
• esc_textarea
• esc_url
• esc_url_raw
• sanitize_email

What needs to be escaped¶

• All php variables following echo should be escaped

  echo $var;                                      // wrong
  echo esc_html( $var );                          // ok
  

• All php functions following echo should be escaped

  echo home_url( '/' );                           // wrong
  echo esc_url( home_url( '/' ) );                // ok
  

• All translations should be escaped

  echo __( 'Hello', 'ct_theme' );                 // wrong
  echo esc_html__( 'Hello', 'ct_theme' );         // ok
  
  _e( 'Hello', 'ct_theme' );                      // wrong
  esc_html_e( 'Hello', 'ct_theme' );              // ok
  

• All attributes should be escaped

  <li id="accordion-section-<?php echo $this->id; ?>" class="<?php echo $classes ?>">                             // wrong
  <li id="accordion-section-<?php echo esc_attr( $this->id ); ?>" class="<?php echo esc_attr( $classes ); ?>">    // ok
  

• Variables should not and can not be translated

  echo esc_html__( $var );                        // wrong, generates a notice
  echo esc_html__( $var, 'ct_theme' );            // wrong
  echo esc_html( $var );                          // ok
  

Variables containing HTML¶

When outputting a variable which contains HTML you can do one of the following:

• Use wp_kses or wp_kses_post function to define allowed HTML tags

$var = 'Hello <b>world</b>';

echo $var;                                              // wrong
echo esc_html( $var );                                  // ok, but <b> tag is lost
echo wp_kses( $var, array( 'b' );                       // ok

Double check¶

Make sure you have everything escaped before publishing a theme. In order to double check, search the project for:

• echo $
• __( or better a regex: \W__\(
• _e(
• href=
• src=
• home_url(
• permalink(

Introduction¶

Options are intended for creating form fields representing different kind of data e.g. rich and plain text, icons, media content, fonts and more. With options you can easily create tabs, boxes and form inputs for the admin pages. You just build an array and it will be transformed to html. On form submit, values will be saved into the database, and you will be able to access them anywhere you want using fw_get_db_..._option() helper functions.

For advanced users, this is an easy way to create form inputs and use them for various purposes. The simplest options array looks something like this:

$options = array(
    'option_id' => array(
        'type' => 'text'
    )
);

This will generate a text input. The array key is used as option id, it should be unique. Values in the database will be stored as array('option_id' => 'value').

All options have some base parameters:

• label (string) Label
• desc (string) Description
• value (mixed) Default value
• attr (array) HTML attributes (some options will place these attributes in input, other in wrapper div)
• help (string|array) Additional info about option. This will generate an next to option that will show the text in a tip popup.

Some options can have additional (optional) parameters. A better customized option will look like this:

$options = array(
    'option_id' => array(
        'type'  => 'text',
        'value' => 'Default value',
        'label' => __('Option Label', '{domain}'),
        'desc'  => __('Option Description', '{domain}'),
        'attr'  => array('class' => 'custom-class', 'data-foo' => 'bar'),
        'help'  => __('Some html that will appear in tip popup', '{domain}'),
    )
);

You can test the above array by creating any of the below options file and placing the array in it.

Options files¶

These are the main places where options are used:

• Theme Settings Page: Loads the options from {theme}/framework-customizations/theme/options/settings.php
• Customizer Page: Loads the options from {theme}/framework-customizations/theme/options/customizer.php
• Post Add/Edit Page: Loads the options from {theme}/framework-customizations/theme/options/posts/{$post_type}.php
• Taxonomy Term Edit Page: Loads the options from {theme}/framework-customizations/theme/options/taxonomies/{$taxonomy}.php

Containers¶

Options that have no value and contain other options in the options parameter are containers. If an option has the options parameter, it is considered a container.

The simplest container option array looks as in the below example and will generate an empty metabox without title:

$options = array(
    array(
        'type'    => 'box',
        'options' => array()
    )
);

There are 4 built-in container types:

• box - WordPress metabox

  'box_id' => array(
      'type' => 'box',
      'options' => array(
          'option_id'  => array( 'type' => 'text' ),
      ),
      'title' => __('Box Title', '{domain}'),
      'attr' => array('class' => 'custom-class', 'data-foo' => 'bar'),
  
      /**
       * When used in Post Options on the first array level
       * the ``box`` container accepts additional parameters
       */
      //'context' => 'normal|advanced|side',
      //'priority' => 'default|high|core|low',
  ),
  

• tab - One tab (Tabs from the same array level will be collected and rendered as multiple tabs)

  'tab_id' => array(
      'type' => 'tab',
      'options' => array(
          'option_id'  => array( 'type' => 'text' ),
      ),
      'title' => __('Tab Title', '{domain}'),
      'attr' => array('class' => 'custom-class', 'data-foo' => 'bar'),
  ),
  'tab_id_2' => array(
      'type' => 'tab',
      'options' => array(
          'option_id_2'  => array( 'type' => 'text' ),
      ),
      'title' => __('Tab Title #2', '{domain}'),
      'attr' => array('class' => 'custom-class', 'data-foo' => 'bar'),
  ),
  

• group - Group options into a wrapper div. Has no design. Usually used to show/hide a group of options from javascript

  'group_id' => array(
      'type' => 'group',
      'options' => array(
          'option_id'  => array( 'type' => 'text' ),
      ),
      'attr' => array('class' => 'custom-class', 'data-foo' => 'bar'),
  ),
  

• popup - A button, when clicked it will open a modal with options

  'popup_id' => array(
      'type' => 'popup',
      'options' => array(
          'option_id'  => array( 'type' => 'text' ),
      ),
      'title' => __('Button and Popup Title', '{domain}'),
      'attr' => array('class' => 'custom-class', 'data-foo' => 'bar'),
      'modal-size' => 'small', // small, medium, large
      'desc' => __('Button Description', '{domain}'),
  ),
  

Restrictions¶

Here are some restrictions to keep in mind:

• attr parameter from Post Options first level box containers, is not used. Because boxes are added with add_meta_box() which has no parameter for specifying attributes.

Customizer Options¶

1. Create {theme}/framework-customizations/theme/options/customizer.php with the following contents:

<?php if (!defined( 'FW' )) die('Forbidden');

$options = array(
    'body-color' => array(
        'type' => 'color-picker',
        'label' => __('Body Color', '{domain}'),
        'value' => '#ADFF2F',
    ),
);

2. Add in {theme}/functions.php

function _action_theme_wp_print_styles() {
    if (!defined('FW')) return; // prevent fatal error when the framework is not active

    $option_value = fw_get_db_customizer_option('body-color');

    echo '<style type="text/css">'
         . 'body { '
         . 'border: 30px solid '. esc_html($option_value) .'; '
         . '}'
         . '</style>';
}
add_action('wp_print_styles', '_action_theme_wp_print_styles');

3. Go to menu Appearance > Customize, find the Body Color option and change it.

Settings Options¶

1. Create {theme}/framework-customizations/theme/options/settings.php with the following contents:

<?php if (!defined( 'FW' )) die('Forbidden');

$options = array(
    'body-color' => array(
        'type' => 'color-picker',
        'label' => __('Body Color', '{domain}'),
        'value' => '#ADFF2F',
    ),
);

2. Add in {theme}/functions.php

function _action_theme_wp_print_styles() {
    if (!defined('FW')) return; // prevent fatal error when the framework is not active

    $option_value = fw_get_db_settings_option('body-color');

    echo '<style type="text/css">'
         . 'body { '
         . 'border: 30px solid '. esc_html($option_value) .'; '
         . '}'
         . '</style>';
}
add_action('wp_print_styles', '_action_theme_wp_print_styles');

3. Go to menu Appearance > Theme Settings, find the Body Color option, change it and press Save.
4. Go to frontend and see the changes.

Post Options¶

1. Create {theme}/framework-customizations/theme/options/posts/post.php with the following contents:

<?php if (!defined( 'FW' )) die('Forbidden');

$options = array(
    'main' => array(
        'type' => 'box',
        'title' => __('Testing Options', '{domain}'),
        'options' => array(
            'body-color' => array(
                'type' => 'color-picker',
                'label' => __('Body Color', '{domain}'),
                'value' => '#ADFF2F',
            ),
        ),
    ),
);

2. Add in {theme}/functions.php

function _action_theme_wp_print_styles() {
    if (!defined('FW')) return; // prevent fatal error when the framework is not active

    global $post;

    if (!$post || $post->post_type != 'post') {
        return;
    }

    $option_value = fw_get_db_post_option($post->ID, 'body-color');

    echo '<style type="text/css">'
         . 'body { '
         . 'border: 30px solid '. esc_html($option_value) .'; '
         . '}'
         . '</style>';
}
add_action('wp_print_styles', '_action_theme_wp_print_styles');

3. Create a new Post, find Body Color option, change it and save the post.
4. Open the post in frontend and see the changes.

Introduction¶

Customizer Options {theme}/framework-customizations/theme/options/customizer.php are turned into Customizer elements (panels, sections and controls).

The customizer elements have a strict structure which also applies to options array structure:

• Containers can be nested only 2 levels

  • container > option is turned into section > control
  • container > container > option is turned into panel > section > control
  • container > container > container > option will not work panel > section > ERROR

• Containers must contain only options or only containers, because a panel can’t contain both sections and controls.

Examples¶

Try the below arrays in {theme}/framework-customizations/theme/options/customizer.php.

• Create a Section

  $options = array(
      'section_1' => array(
          'title' => __('Unyson Section', '{domain}'),
          'options' => array(
  
              'option_1' => array(
                  'type' => 'text',
                  'value' => 'Default Value',
                  'label' => __('Unyson Option', '{domain}'),
                  'desc' => __('Option Description', '{domain}'),
              ),
  
          ),
      ),
  );
  

• Create a Panel with Sections

  $options = array(
      'panel_1' => array(
          'title' => __('Unyson Panel', '{domain}'),
          'options' => array(
  
              'section_1' => array(
                  'title' => __('Unyson Section #1', '{domain}'),
                  'options' => array(
  
                      'option_1' => array(
                          'type' => 'text',
                          'value' => 'Default Value',
                          'label' => __('Unyson Option #1', '{domain}'),
                          'desc' => __('Option Description', '{domain}'),
                      ),
  
                  ),
              ),
  
              'section_2' => array(
                  'title' => __('Unyson Section #2', '{domain}'),
                  'options' => array(
  
                      'option_2' => array(
                          'type' => 'text',
                          'value' => 'Default Value',
                          'label' => __('Unyson Option #2', '{domain}'),
                          'desc' => __('Option Description', '{domain}'),
                      ),
                      'option_3' => array(
                          'type' => 'text',
                          'value' => 'Default Value',
                          'label' => __('Unyson Option #3', '{domain}'),
                          'desc' => __('Option Description', '{domain}'),
                      ),
  
                  ),
              ),
  
          ),
      ),
  );
  

• Get option database/saved value in template

  $value = fw_get_db_customizer_option('option_1');
  

Additional Arguments¶

• Control arguments can be set in wp-customizer-args option parameter.

  $options = array(
      'section_1' => array(
          'title' => __('Unyson Section', '{domain}'),
          'options' => array(
  
              'option_1' => array(
                  'type' => 'text',
                  'value' => 'Default Value',
                  'label' => __('Unyson Option', '{domain}'),
                  'desc' => __('Option Description', '{domain}'),
  
                  'wp-customizer-args' => array(
                      'priority' => 3,
                  ),
              ),
  
          ),
      ),
  );
  

• Setting arguments can be set in wp-customizer-setting-args option parameter.

  $options = array(
      'section_1' => array(
          'title' => __('Unyson Section', '{domain}'),
          'options' => array(
  
              'option_1' => array(
                  'type' => 'text',
                  'value' => 'Default Value',
                  'label' => __('Unyson Option', '{domain}'),
                  'desc' => __('Option Description', '{domain}'),
  
                  'wp-customizer-setting-args' => array(
                      'capability' => 'edit_posts',
                  ),
              ),
  
          ),
      ),
  );
  

Live Preview¶

In background, customizer options are converted into customizer elements, so they follow default WordPress behavior and implementing a live preview can be done using the default WordPress solution.

1. Change the setting transport and enqueue the javascript

   // file: {theme}/inc/hooks.php
   
   if (defined('FW')):
       /**
        * @param WP_Customize_Manager $wp_customize
        * @internal
        */
       function _action_customizer_live_fw_options($wp_customize) {
           if ($wp_customize->get_setting('fw_options[OPTION_ID]')) {
               $wp_customize->get_setting('fw_options[OPTION_ID]')->transport = 'postMessage';
   
               add_action( 'customize_preview_init', '_action_customizer_live_fw_options_preview' );
           }
       }
       add_action('customize_register', '_action_customizer_live_fw_options');
   
       /**
        * @internal
        */
       function _action_customizer_live_fw_options_preview() {
           wp_enqueue_script(
               'mytheme-customizer',
               get_template_directory_uri() .'/assets/js/theme-customizer.js',
               array( 'jquery','customize-preview' ),
               fw()->theme->manifest->get_version(),
               true
           );
       }
   endif;
   

2. Handle the change in javascript

   // file: {theme}/assets/js/theme-customizer.js
   
   ( function( $ ) {
       wp.customize( 'fw_options[OPTION_ID]', function( value ) {
           value.bind( function( newval ) {
               /**
                * An array of collected html inputs
                * [{'name':'input[name]','value':'input value'}]
                * or
                * [{'name':'input[name]','value':'input value'},{'name':'input[name]','value':'input value'},...]
                */
               newval = JSON.parse(newval);
   
               $( 'h1' ).text( newval[0].value );
           } );
       } );
   } )( jQuery );
   

   Note

   The value comes in [{'name':'input[name]','value':'input value'}] format, because the customizer form is not submitted as a regular form. A control can store its value only inside a single input which has some special attributes (instead of name="...") and it is monitored for changes by the Customizer script to trigger the preview update. Because of that, the framework options collect all their inputs values and store them in that special input (here is an advanced explanation).

HTML¶

All option types must have .fw-option-type-{type} class on main/wrapper html element.

CSS¶

If the option type has css, all rules must be prefixed with .fw-option-type-{type} class:

/* correct */
.fw-option-type-demo .some-class {
    color: blue;
}

/* wrong */
.some-class {
    color: blue;
}

Javascript¶

All javascript must stick to .fw-option-type-{type} class and work only within the main/wrapper element (no events attached to the body). If the option type has custom javascript events, those events must be triggered on the main element.

$someInnerElement.closest('.fw-option-type-demo')
    .trigger('fw:option-type:demo:custom-event', {some: 'data'});

If it’s specified in the documentation that an option type has custom events, it means that you can attach event listeners on the elements with .fw-option-type-{type} class (not on body or fwEvents).