Skip to content

Wordpress

Dependencies

Directory structure

  • Wordpress theme, mu-plugins and other internal or non-free plugins reside in wordpress/ subfolder of the repository or as a git submodule
  • Theme HTML/CSS/JS development is done in the ui/ folder where you also run gulp [build|serve|wp-copy|...] to work on the project and to copy all JS, CSS, and image files to wordpress/wp-content/themes/THEME-NAME folder this is true for some projects and needs to be revised

Project setup

  1. checkout the repository and install the Wordpress core files into /wordpress folder (wp core download PATH/TO/wordpress)
  2. set up wp-config.php
  3. import the database (wp db import DB_FILE_NAME.sql)
  4. manualy add a new user (wp user create test [email protected] --role=administrator --user_pass=test)

  5. serve missing media files from production (the js and css files are excluded in our example)

    • .htaccess 

      <IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteCond %{REQUEST_FILENAME} !-f [NC]
  RewriteRule ^(.*\.(png|jpe?g|gif|ico)) https://www.domain.tld/$1 [NC,P,L]
</IfModule>

    • nginx 

      # Directives to send expires headers and turn off 404 error logging.
location ~* \.(png|jpe?g|gif|ico)$ {
  expires 24h;
  log_not_found off;
  try_files $uri $uri/ @production;
}
location @production {
  resolver 8.8.8.8;
  proxy_pass http://www.domain.tld/$uri;
}

    • use a plugin to copy them localy uploads-by-proxy

Development wp-config.php

Remember there should be no PHP notices and this will help you achieve this

  1. Disable Search Bot indexing in wordpress and hide the website behind a Basic Auth ACL
  2. wp-config.php variables 
    define('FS_METHOD', 'direct');
define('WP_DEBUG_DISPLAY', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG', true); // always use true on local, dev and false on production
TODO - Minify needs to be available
define('MINIFY_RESOURCES', false); // use minified versions of css/js or not

Plugins and Themes

  • we try to develop the themes using only ACF Pro and custom code (TODO some project are using our internal framework for creating fields and admin interface and that will be covered in a separate documentation)
  • when we need to extend the functionality of ACF Pro we can use plugins if they are small and do a specific job
  • if the plugin is available in the Wordpress Market we add it to wp-cli.yml like:
    plugins:
  ninja-forms --version=3.1.6
  • if a plugin is available on github you can add it as a submodule and update the README.md to include this in the Project setup chapter
  • if a more complex solution needs to be developed you should discus this with us
  • child theme repos should contain only the theme and files that need to be changed

Common theme / plugin init code

  • Load CSS styles 

    function THEME_child_enqueue_styles() {
    $parent_style = 'base-style';
    wp_dequeue_style( 'base-theme-fix' );

    wp_enqueue_style( $parent_style, get_template_directory_uri() . '/style.css' );
    wp_enqueue_style( 'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( $parent_style ),
        wp_get_theme()->get('Version')
    );

    /**
     * This is used to add styles that are generated by PHP from settings in the theme
     * if you need it uncoment it
     * Example: https://gitlab.com/qloud/cmt/collegium-si/blob/master/wordpress/wp-content/themes/collegium-si/inc/css.php
     */
    //wp_enqueue_style(
  	//	'base-theme-fix',
  	//	get_template_directory_uri() . '/theme-fix.css',
  	//	array('child-style')
  	//);
}
add_action( 'wp_enqueue_scripts', 'THEME_child_enqueue_styles', 999 );

  • Save and load ACF Fields from json files (parent and child theme merged) 

    add_filter('acf/settings/load_json', function($paths) {
  $paths = array();

  if(is_child_theme())
  {
    $paths[] = get_stylesheet_directory() . '/acf-json';
  }
  $paths[] = get_template_directory() . '/acf-json';

  return $paths;
});

  • Set up WP-like updates using WPPUS child theme You should use /lib dir from examples in the WPPUS plugin 

    // Use get_template_directory() for parent theme
$theme_dir = get_stylesheet_directory();
require_once $theme_dir . '/lib/wp-package-updater/class-wp-package-updater.php';

$THEME_updater = new WP_Package_Updater(
  'https://wp.kupi.si',
  wp_normalize_path( __FILE__ ),
  $theme_dir,
  false
);

  • TODO Plugin and theme dependecies should be set up using TGMPA

    • plugins from WP Plugins can simply be included
    • 3rd party plugins / themes should be included using a zip file contained in the theme / plugin that needs dependecies. This includes our plugins and parent themes and this needs to be set up so that those zip's are automaticaly added when qloud-dist/THEME-PLUGIN is generated
    • dependecies should always be generated from latest tag or master branch where the plugin is located in our GitLab repo

Database

  1. Initial setup Default Wordpress generated database

  2. Adding custom tables

  3. use add_action("after_switch_theme", "your_set_tables_function"); example to add new tables

  4. then follow the guidelines for Creating Tables with Plugins

  5. Latest development database TODO
    If you need the latest LIVE version of the database contact us

UI setup & develoment

These commands should be run in the ui/ directory:

  • npm install to install all node dependencies
  • bower install to install all bower dependencies
  • gulp serve to start working on HTML/CSS/JS changes, it will also copy the concatenated files to wordpress/ on each change
  • Site is available at localhost:9000
  • ui/dev/scripts folder contains the JS files you need to change
  • THIS NEEDS TO BE VERIFIED AND UPDATED dev version reads the dummy json files (/ui/dev/scripts/dummyJSONPaths.js overrides the paths to json files, they are located in same /ui/dev/scripts/ folder)
  • gulp build to build the latest version (dist) and gulp wp-copy if the first command does not copy resources to wordpress/.. sub dirs

Site migration local / dev / staging / live

For ease of migrating the content and user created files not contained in the repo we are using UpdraftPlus plugin.

  • Use Migrate / Copy to another site (receive key from us)
  • Contact us to restore the backup on the dev or any other site where you were supposed to send the backup

Common guidelines

  • For any text that needs to be outputed to the client use __('STRING','theme-PART');