# WordPress Theme Boilerplate

## Authors
+ Christopher Rumpler <christopher.rumpler@koerbler.com\>
+ Florian Flock <florian.flock@koerbler.com\>
+ Michael Serajnik <michael.serajnik@koerbler.com\>

## Abstract
This is a basic boilerplate theme for WordPress development. It features many of our commonly used functions and should be used whenever you are developing a custom theme (in order to have a consistent base for developing themes). It is NOT a guide for how to write/structure HTML/CSS/JS – please ask one of the senior developers if you have questions about that. Christopher and Michael (see authors) can provide you with an up-to-date LESS/SASS structure that works well with this boilerplate, if needed.

Please ask (see authors) if you have questions or are unsure about how to do something specific in WordPress – there are many development shortcuts (that do not compromise code quality) that might not be obvious to new WordPress developers and are hard to find when googling.

## Features
+ A good basic structure for any custom theme
+ An example for splitting up theme files in the correct way (header – template – footer)
+ An example for extending the TinyMCE editor with custom formats
+ An example for a custom Visual Composer element
+ Various "nice to haves" (SVG support for uploads, a custom helper function for excerpts, lightbox markup for media links/galleries etc.)

## Prerequisites
- [WordPress](https://wordpress.org/) (always get the latest version, we make sure this boilerplate is up to date)

## Installation
1. Copy the folder *theme-boilerplate* into *wp\_content/themes/* of your WordPress installation
2. Change the theme metadata in *theme-boilerplate/style.css*
3. Change the function name prefixes from *boilerplate* to a fitting prefix for your theme in all the files in *theme-boilerplate/functions* – double check to make sure you are not changing a prefix of a function and forget to change it in the hook
4. Adapt/extend as needed
5. Activate the theme in the WordPress admin backend

## Planned Features as of December 2016
+ A more elaborate Visual Composer example that includes all the different field types
+ A custom post type example

Furthermore, we would like to provide examples for the following points (and probably more) but don't want to include them here (in order to not clutter up the theme) – these will probably be forks (unless we find another way to present them in a ready-to-use fashion).

In the meantime, please ask if you have any questions about these topics.

+ An example for how to use the WordPress AJAX API
+ An example for how to add widget areas and create custom widgets
+ An example for a custom nav walker (needed for custom menus that deviate from the basic ul > li > a structure)
+ An example for adapting/extending WooCommerce

## Additional information about WordPress development

### Plugins
Here are some plugins you might consider using. Please always check if the plugin is compatible with your version of WordPress. You might need to check manually in a test environment since plugins might not always say that they are compatible with the latest version (even if they are). You can also find a user-voted compatibility overview in the bottom right of the plugin page in the plugin directory (but don't rely on that alone).

#### Recommended plugins for ANY WordPress installation

##### Free (there may be a paid version but the free one is adequate in most cases)
+ [Duplicate Page](https://wordpress.org/plugins/duplicate-page/) – for duplicating pages/posts/custom post types
+ [WP Migrate DB](https://wordpress.org/plugins/wp-migrate-db/) – for migrating sites to a different environment/server
+ [Yoast SEO](https://wordpress.org/plugins/wordpress-seo/) – for SEO (titles, descriptions, keywords etc.)

##### Paid (we have license keys for these, please ask Florian or Michael)
+ [Advanced Custom Fields Pro](http://www.advancedcustomfields.com/) – for adding custom fields to pages/posts/custom post types, great for sliders, additional content areas etc.
+ [Visual Composer](https://vc.wpbakery.com/) – for adding grid functionality to the TinyMCE editor (based on [Bootstrap](http://getbootstrap.com/)) and creating custom elements (it also comes with a ton of preconfigured elements that we disable in this boilerplate, but feel free to check them out)
+ [WP Rocket](https://wp-rocket.me/) – adds caching and other performance improvements (combining CSS/JS, minifying HTML etc.) to WordPress

#### Situational plugins

##### Free (there may be a paid version but the free one is adequate in most cases)
+ [All In One WP Security & Firewall](https://wordpress.org/plugins/all-in-one-wp-security-and-firewall/) – adds additional security features to WordPress, important for sites that handle money transactions (e.g., WooCommerce shops) – do not configure it without reading the documentation/asking
+ [Breadcrumb NavXT](https://wordpress.org/plugins/breadcrumb-navxt/) – adds breadcrumb support
+ [Contact Form 7](https://wordpress.org/plugins/contact-form-7/) – adds form management to the WordPress admin backend
+ [Nested Pages](https://wordpress.org/plugins/wp-nested-pages/) – changes the default page overview to a tree view and allows you to sync it with the menu – use with caution, known to break pages (temporarily) if configured/used incorrectly
+ [TinyMCE Advanced](https://de.wordpress.org/plugins/tinymce-advanced/) – extends the TinyMCE editor and adds lots of cool features that make life easier, might be overkill for small sites
+ [Query Monitor](https://wordpress.org/plugins/query-monitor/) – for debugging in case of (server-side) performance issues
+ [Quick Page/Post Redirect Plugin](https://wordpress.org/plugins/quick-pagepost-redirect-plugin/) – adds redirect support to posts/pages/custom post types/URLs in general
+ [WooCommerce](https://wordpress.org/plugins/woocommerce/) – the most commonly used shop plugin for WordPress
+ [WooCommerce Germanized](https://wordpress.org/plugins/woocommerce-germanized/) – extends WooCommerce to become legally compliant for German markets
+ [WP Main SMTP](https://wordpress.org/plugins/wp-mail-smtp/) – forces WordPress to send mails via SMTP (instead of using the PHP *mail()* function) – only use when necessary

##### Paid (we have license keys for these, please ask Florian or Michael)
+ [WPML](https://wpml.org/) – adds multilanguage support to WordPress, has different additional plugins (for static string translation, WooCommerce support etc.)

### Useful links
+ [WordPress Codex](https://codex.wordpress.org/) – the official WordPress documentation
+ [WordPress Developer Resources](https://developer.wordpress.org/) – useful information about WordPress development (especially plugins)
+ [Das eigene WordPress-Theme erstellen (German)](http://t3n.de/news/grosse-guide-wordpress-theme-555618/) – a detailed guide for WordPress theme development
+ [A Detailed Guide To WordPress Custom Page Templates](http://www.smashingmagazine.com/2015/06/19/wordpress-custom-page-templates/) – a detailed guide for custom templates
+ [Extending WordPress With Custom Content Types](http://www.smashingmagazine.com/2015/04/22/extending-wordpress-custom-content-types/) – a detailed guide for custom post types