Skip to content

Commit

Permalink
Merge pull request #143 from timber/2.x-autoload-site-class
Browse files Browse the repository at this point in the history
  • Loading branch information
gchtr authored Nov 29, 2023
2 parents 3280b43 + e4fc2dd commit f0d6acf
Show file tree
Hide file tree
Showing 3 changed files with 165 additions and 134 deletions.
31 changes: 17 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

123 changes: 3 additions & 120 deletions functions.php
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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' );
}

/** 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();
145 changes: 145 additions & 0 deletions src/StarterSite.php
Original file line number Diff line number Diff line change
@@ -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;
}
}

0 comments on commit f0d6acf

Please sign in to comment.