diff --git a/README.md b/README.md index 7ff82ec4e..0a32885c0 100644 --- a/README.md +++ b/README.md @@ -3,27 +3,31 @@ [![Build Status](https://travis-ci.com/timber/starter-theme.svg?branch=master)](https://travis-ci.com/github/timber/starter-theme) [![Packagist Version](https://img.shields.io/packagist/v/upstatement/timber-starter-theme?include_prereleases)](https://packagist.org/packages/upstatement/timber-starter-theme) -The "_s" for Timber: a dead-simple theme that you can build from. The primary purpose of this theme is to provide a file structure rather than a framework for markup or styles. Configure your Sass, scripts, and task runners however you would like! +The "_s" for Timber: a dead-simple theme that you can build from. The primary purpose of this theme is to provide a file structure rather than a framework for markup or styles. Configure your SASS files, scripts, and task runners however you would like! -## Installing the Theme +## Installing the theme -Install this theme as you would any other, and be sure the Timber plugin is activated. But hey, let's break it down into some bullets: +Follow the guide on [how to Install Timber using the Starter Theme](https://timber.github.io/docs/v2/installation/installation/#use-the-starter-theme). -1. Make sure you have installed the plugin for the [Timber Library](https://wordpress.org/plugins/timber-library/) (and Advanced Custom Fields - they [play quite nicely](https://timber.github.io/docs/guides/acf-cookbook/#nav) together). -2. Download the zip for this theme (or clone it) and move it to `wp-content/themes` in your WordPress installation. -3. Rename the folder to something that makes sense for your website (generally no spaces and all lowercase). You could keep the name `timber-starter-theme` but the point of a starter theme is to make it your own! -4. Activate the theme in Appearance > Themes. -5. Do your thing! And read [the docs](https://timber.github.io/docs/). +Then, -## What's here? +1. Rename the theme folder to something that makes sense for your website. You could keep the name `timber-starter-theme` but the point of a starter theme is to make it your own! +2. Activate the theme in the WordPress Dashboard under **Appearance → Themes**. +3. Do your thing! And read [the docs](https://timber.github.io/docs/). -`static/` is where you can keep your static front-end scripts, styles, or images. In other words, your Sass files, JS files, fonts, and SVGs would live here. +## The `StarterSite` class -`theme/` contains all of the PHP and other files needed by WordPress. When using the Timber Starter Theme as a parent theme, you need to include the theme directory in your child theme’s `style.css` docblock like so: `Template: timber-starter-theme/theme` +In **functions.php**, we call `new StarterSite();`. The `StarterSite` class sits in the **src** folder. You can update this class to add functionality to your theme. This approach is just one example for how you could do it. -`views/` contains all of your Twig templates. These pretty much correspond 1 to 1 with the PHP files that respond to the WordPress template hierarchy. At the end of each PHP template, you’ll notice a `Timber::render()` function whose first parameter is the Twig file where that data (or `$context`) will be used. Just an FYI. +The **src** folder would be the right place to put your classes that [extend Timber’s functionality](https://timber.github.io/docs/v2/guides/extending-timber/). -`tests/` ... basically don't worry about (or remove) this unless you know what it is and want to. +Small tip: You can make use of Composer’s [autoloading functionality](https://getcomposer.org/doc/04-schema.md#psr-4) to automatically load your PHP classes when they are requested instead of requiring one by one in **functions.php**. + +## What else is there? + +- `static/` is where you can keep your static front-end scripts, styles, or images. In other words, your Sass files, JS files, fonts, and SVGs would live here. +- `views/` contains all of your Twig templates. These pretty much correspond 1 to 1 with the PHP files that respond to the WordPress template hierarchy. At the end of each PHP template, you’ll notice a `Timber::render()` function whose first parameter is the Twig file where that data (or `$context`) will be used. Just an FYI. +- `tests/` ... basically don’t worry about (or remove) this unless you know what it is and want to. ## Other Resources @@ -32,4 +36,3 @@ Install this theme as you would any other, and be sure the Timber plugin is acti * [Timber and Twig Reignited My Love for WordPress](https://css-tricks.com/timber-and-twig-reignited-my-love-for-wordpress/) on CSS-Tricks * [A real live Timber theme](https://github.com/laras126/yuling-theme). * [Timber Video Tutorials](http://timber.github.io/timber/#video-tutorials) and [an incomplete set of screencasts](https://www.youtube.com/playlist?list=PLuIlodXmVQ6pkqWyR6mtQ5gQZ6BrnuFx-) for building a Timber theme from scratch. - diff --git a/functions.php b/functions.php index 10b9e837f..43cddcbec 100644 --- a/functions.php +++ b/functions.php @@ -7,128 +7,11 @@ // Load Composer dependencies. require_once __DIR__ . '/vendor/autoload.php'; +require_once __DIR__ . '/src/StarterSite.php'; + Timber\Timber::init(); -/** - * Sets the directories (inside your theme) to find .twig files - */ +// Sets the directories (inside your theme) to find .twig files. Timber::$dirname = [ 'templates', 'views' ]; -/** - * By default, Timber does NOT autoescape values. Want to enable Twig's autoescape? - * No prob! Just set this value to true - */ -Timber::$autoescape = false; - -/** - * We're going to configure our theme inside of a subclass of Timber\Site - * You can move this to its own file and include here via php's include("MySite.php") - */ -class StarterSite extends Timber\Site { - /** Add timber support. */ - public function __construct() { - add_action( 'after_setup_theme', array( $this, 'theme_supports' ) ); - add_filter( 'timber/context', array( $this, 'add_to_context' ) ); - add_filter( 'timber/twig', array( $this, 'add_to_twig' ) ); - add_action( 'init', array( $this, 'register_post_types' ) ); - add_action( 'init', array( $this, 'register_taxonomies' ) ); - parent::__construct(); - } - /** This is where you can register custom post types. */ - public function register_post_types() { - - } - /** This is where you can register custom taxonomies. */ - public function register_taxonomies() { - - } - - /** This is where you add some context - * - * @param string $context context['this'] Being the Twig's {{ this }}. - */ - public function add_to_context( $context ) { - $context['foo'] = 'bar'; - $context['stuff'] = 'I am a value set in your functions.php file'; - $context['notes'] = 'These values are available everytime you call Timber::context();'; - $context['menu'] = Timber::get_menu(); - $context['site'] = $this; - return $context; - } - - public function theme_supports() { - // Add default posts and comments RSS feed links to head. - add_theme_support( 'automatic-feed-links' ); - - /* - * Let WordPress manage the document title. - * By adding theme support, we declare that this theme does not use a - * hard-coded tag in the document head, and expect WordPress to - * provide it for us. - */ - add_theme_support( 'title-tag' ); - - /* - * Enable support for Post Thumbnails on posts and pages. - * - * @link https://developer.wordpress.org/themes/functionality/featured-images-post-thumbnails/ - */ - add_theme_support( 'post-thumbnails' ); - - /* - * Switch default core markup for search form, comment form, and comments - * to output valid HTML5. - */ - add_theme_support( - 'html5', - array( - 'comment-form', - 'comment-list', - 'gallery', - 'caption', - ) - ); - - /* - * Enable support for Post Formats. - * - * See: https://codex.wordpress.org/Post_Formats - */ - add_theme_support( - 'post-formats', - array( - 'aside', - 'image', - 'video', - 'quote', - 'link', - 'gallery', - 'audio', - ) - ); - - add_theme_support( 'menus' ); - } - - /** This Would return 'foo bar!'. - * - * @param string $text being 'foo', then returned 'foo bar!'. - */ - public function myfoo( $text ) { - $text .= ' bar!'; - return $text; - } - - /** This is where you can add your own functions to twig. - * - * @param string $twig get extension. - */ - public function add_to_twig( $twig ) { - $twig->addExtension( new Twig\Extension\StringLoaderExtension() ); - $twig->addFilter( new Twig\TwigFilter( 'myfoo', array( $this, 'myfoo' ) ) ); - return $twig; - } - -} - new StarterSite(); diff --git a/src/StarterSite.php b/src/StarterSite.php new file mode 100644 index 000000000..7f6c3ac86 --- /dev/null +++ b/src/StarterSite.php @@ -0,0 +1,145 @@ +<?php + +use Timber\Site; + +/** + * Class StarterSite + */ +class StarterSite extends Site { + public function __construct() { + add_action( 'after_setup_theme', array( $this, 'theme_supports' ) ); + add_action( 'init', array( $this, 'register_post_types' ) ); + add_action( 'init', array( $this, 'register_taxonomies' ) ); + + add_filter( 'timber/context', array( $this, 'add_to_context' ) ); + add_filter( 'timber/twig', array( $this, 'add_to_twig' ) ); + add_filter( 'timber/twig/environment/options', [ $this, 'update_twig_environment_options' ] ); + + parent::__construct(); + } + + /** + * This is where you can register custom post types. + */ + public function register_post_types() { + + } + + /** + * This is where you can register custom taxonomies. + */ + public function register_taxonomies() { + + } + + /** + * This is where you add some context + * + * @param string $context context['this'] Being the Twig's {{ this }}. + */ + public function add_to_context( $context ) { + $context['foo'] = 'bar'; + $context['stuff'] = 'I am a value set in your functions.php file'; + $context['notes'] = 'These values are available everytime you call Timber::context();'; + $context['menu'] = Timber::get_menu(); + $context['site'] = $this; + + return $context; + } + + public function theme_supports() { + // Add default posts and comments RSS feed links to head. + add_theme_support( 'automatic-feed-links' ); + + /* + * Let WordPress manage the document title. + * By adding theme support, we declare that this theme does not use a + * hard-coded <title> tag in the document head, and expect WordPress to + * provide it for us. + */ + add_theme_support( 'title-tag' ); + + /* + * Enable support for Post Thumbnails on posts and pages. + * + * @link https://developer.wordpress.org/themes/functionality/featured-images-post-thumbnails/ + */ + add_theme_support( 'post-thumbnails' ); + + /* + * Switch default core markup for search form, comment form, and comments + * to output valid HTML5. + */ + add_theme_support( + 'html5', + array( + 'comment-form', + 'comment-list', + 'gallery', + 'caption', + ) + ); + + /* + * Enable support for Post Formats. + * + * See: https://codex.wordpress.org/Post_Formats + */ + add_theme_support( + 'post-formats', + array( + 'aside', + 'image', + 'video', + 'quote', + 'link', + 'gallery', + 'audio', + ) + ); + + add_theme_support( 'menus' ); + } + + /** + * his would return 'foo bar!'. + * + * @param string $text being 'foo', then returned 'foo bar!'. + */ + public function myfoo( $text ) { + $text .= ' bar!'; + return $text; + } + + /** + * This is where you can add your own functions to twig. + * + * @param Twig\Environment $twig get extension. + */ + public function add_to_twig( $twig ) { + /** + * Required when you want to use Twig’s template_from_string. + * @link https://twig.symfony.com/doc/3.x/functions/template_from_string.html + */ + // $twig->addExtension( new Twig\Extension\StringLoaderExtension() ); + + $twig->addFilter( new Twig\TwigFilter( 'myfoo', [ $this, 'myfoo' ] ) ); + + return $twig; + } + + /** + * Updates Twig environment options. + * + * @link https://twig.symfony.com/doc/2.x/api.html#environment-options + * + * \@param array $options An array of environment options. + * + * @return array + */ + function update_twig_environment_options( $options ) { + // $options['autoescape'] = true; + + return $options; + } +}