Tips For Setting up Sage 9

A month ago, I switched my theme development to Sage (version 9). I’ve been using an ancient build slowly upgraded over the years, and wasn’t the epitome of proper development. It even had a LESS compiler in php.

Since switching, I’ve been documenting a few things I learned in my upgrade process.

Home Template will use the FrontPage container

In Sage, it is proper to keep logic and layout (template files) as separate as possible. Sage achieves this using SoberWP. I build themes with a Home Template and then make a page and set that as the Front Page.

Normally, for any custom template, you’ll need/want to create a custom controller for it. However, this is not the case for whatever page you set as the front page of your site. By design, Sage will only look at 2 controllers per template: the App controller, and then whatever you have specified.

This rule means that the FrontPage controller will fulfill before TemplateHome controller.

Sage blades do not cache well with WP Engine

WPE doesn’t cache well with Sage. If you do development locally then upload the theme to wordpress, you’ll get put_file_content errors instead of blade files rendering.

So far, the only way around this that I’ve found is the change the caching location in the theme.

in sage > config > view.php

'compiled' => wp_upload_dir()['basedir'].'/cache', //DEV
'compiled' => '/tmp/sage-cache', //Change to this for WPE

You can read more about the whole discussion here:

https://discourse.roots.io/t/sage-9-on-wpengine/9090/32

 

Using a Theme Image in a Controller

Sage has a lot of handy functions built in thanks to Blade. One of those is using  @assets(‘my_image.jpg’) to place an image in your themes blade/template files. But sometimes you need to get an image while in the controller.

For One project i made a staff profile repeater. People would input the name, title, email, a bio and pic. I wanted to have a backup default picture though if someone didn’t have an image. Here’s what I did in my Controller:

namespace App\Controllers;

use Sober\Controller\Controller;

class TemplateStaff extends Controller
{
  public function StaffList(){

    // Get Repeater
    $pressRepeater = get_field('staff_repeater');

   return array_map(function ($item) {

        return [
            'name'         => $item['name']  ?? null,
            'description'  => $item['description']  ?? null,
            'image'        => $item['image']['url']  ?? \App\asset_path('images/profile-placeholder.jpg'),
            'email'        => $item['email'] ?? null,
            'title'        => $item['title']  ?? null,
        ];
    }, $pressRepeater ?? [] );
  }
}

Sage has a function. “\App\asset_path():” that can be used for grabbing assets. Normally you would call it like any other function, but with Sage, you have to use name-spacing to call it properly. This is the same function used to create the @asset() directive in the blade.

 

$Loop is amazing