Sage

https://roots.io/sage/docs
Admin
Sage is a WordPress starter theme that integrates modern development tools like Laravel Blade for...
Tokens:9,350
Snippets:104
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Bootstrap and Popper.js using npm

Source: https://roots.io/sage/docs/bootstrap

Installs Bootstrap and Popper.js as project dependencies using npm. These are essential for Bootstrap's JavaScript components and Popper.js's positioning capabilities.

```bash
$ npm install --save bootstrap @popperjs/core

```

--------------------------------

### Use Heroicons in Blade views

Source: https://roots.io/sage/docs/use-blade-icons

Shows how to use icons from the installed `blade-heroicons` package. It demonstrates usage with the Blade component and the `@svg()` directive, including an example with a closing parenthesis.

```html
<x-heroicon-s-menu />

@svg('heroicon-s-menu')

{{ svg('heroicon-s-menu) }}

```

--------------------------------

### Implement Blade Component Structure

Source: https://roots.io/sage/docs/components

Example of a Blade component implementation, including the template markup and the corresponding PHP class for logic and data handling.

```blade
<div {{ $attributes }}>
    <h3>{!! $title !!}</h3>
    @if($imageElement)
        <figure>{!! $imageElement !!}</figure>
    @endif
</div>
```

```php
namespace App\View\Components;

use Roots\Acorn\View\Component;

class ExampleComponent extends Component
{
    public $title;
    public $imageElement;

    protected $imageId;

    public function __construct($title, $imageId = null) {
        $this->title = $title;
        $this->imageId = $imageId;
        $this->imageElement = $this->getImage();
    }

    protected function getImage()
    {
        if (!is_numeric($this->imageId)) {
            return false;
        }
        
        return wp_get_attachment_image($this->imageId, 'medium_large');
    }
}
```

--------------------------------

### Publish blade-icons configuration

Source: https://roots.io/sage/docs/use-blade-icons

Publishes the configuration file for blade-icons, allowing customization of its behavior. This command is typically run after installing the package.

```bash
$ wp acorn vendor:publish --tag=blade-icons

```

--------------------------------

### Install blade-icons using Composer

Source: https://roots.io/sage/docs/use-blade-icons

Installs the blade-icons package as a Composer dependency. This is the first step to enable SVG icon management in your project.

```bash
$ composer require blade-ui-kit/blade-icons

```

--------------------------------

### Getting Asset Content in PHP

Source: https://roots.io/sage/docs/compiling-assets

Explains how to retrieve the raw content of a compiled asset in PHP using the `Vite::content` method. This can be useful for inline SVG or other scenarios where the asset's content is needed directly.

```php
use Illuminate\Support\Facades\Vite;

$asset = Vite::content('resources/images/example.svg');
```

--------------------------------

### Install a third-party icon set (Heroicons)

Source: https://roots.io/sage/docs/use-blade-icons

Adds a community-provided icon set, such as `blade-heroicons`, as a Composer dependency. This allows you to use icons from that set in your Blade views.

```bash
$ composer require blade-ui-kit/blade-heroicons

```

--------------------------------

### Getting Asset URL in PHP

Source: https://roots.io/sage/docs/compiling-assets

Illustrates how to obtain the URL of a compiled asset in PHP using the `Vite::asset` method from the `IlluminateSupportFacadesVite` facade. This is useful for dynamically setting asset sources in backend logic.

```php
use Illuminate\Support\Facades\Vite;

$asset = Vite::asset('resources/images/example.svg');
```

--------------------------------

### Blade Template Rendering with Composer Data

Source: https://roots.io/sage/docs/composers

These Blade templates illustrate how data passed from a Composer is rendered. The first example shows an error when trying to access a variable not defined in the current scope, while the subsequent examples show successful rendering of the `$roots` variable in `example.blade.php` and its inheritance in `example2.blade.php`.

```blade
<!-- resources/views/content.blade.php -->
{{ $roots }} 
<!-- Throws an error because the variable is not defined -->

@include('partials.example')

```

```blade
<!-- resources/views/partials/example.blade.php -->
<h1>{{ $roots }}</h1>
<!-- <h1>Tools for modern WordPress development</h1> -->

@include('partials.example2')

```

```blade
<!-- resources/views/partials/example2.blade.php -->
<div>{{ $roots }}</div>
<!-- <div>Tools for modern WordPress development</div> -->
<!-- Variable is defined in this context because it inherits 
    it from example.blade.php -->

```

--------------------------------

### Configure Sass in Sage

Source: https://roots.io/sage/docs/sass

Commands and configuration updates required to switch from Tailwind CSS to Sass. This includes installing the sass package and updating Vite, Blade, and PHP settings to point to the new .scss files.

```bash
npm uninstall -D @tailwindcss/vite tailwindcss
npm install -D sass
```

```javascript
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import { wordpressPlugin, wordpressThemeJson } from '@roots/vite-plugin';

export default defineConfig({
  base: '/app/themes/sage/public/build/',
  plugins: [
    laravel({
      input: [
        'resources/css/app.scss',
        'resources/js/app.js',
        'resources/css/editor.scss',
        'resources/js/editor.js',
      ],
    }),
    wordpressThemeJson({
      disableTailwindColors: true,
      disableTailwindFonts: true,
      disableTailwindFontSizes: true,
    }),
  ],
})
```

```php
@vite(['resources/css/app.scss', 'resources/js/app.js'])

add_filter('block_editor_settings_all', function ($settings) {
    $style = Vite::asset('resources/css/editor.scss');

    $settings['styles'][] = [
        'css' => "@import url('{$style}')",
    ];

    return $settings;
});
```

--------------------------------

### Configuring Tailwind CSS Font Theme in Sage

Source: https://roots.io/sage/docs/fonts-setup

This example shows how to add your custom font family to the Tailwind CSS theme configuration within `app.css`. This allows you to use the 'Public Sans' font in your project using Tailwind's utility classes.

```css
@theme {
  --font-sans: "Public Sans", sans-serif;
}

```

--------------------------------

### Composer Accessing Inherited Data in PHP

Source: https://roots.io/sage/docs/composers

This PHP code snippet shows how a Composer can access and manipulate data that has been passed to or inherited by the view. It uses the `$this->data->get('variable_name')` method to retrieve existing data and modifies it before returning it as a new variable.

```php
class Example2 extends Composer 
{
    ...
    public function with()
    {
        return [
            'better_roots' => str_replace(
                'modern',
                '*awesome*',
                $this->data->get('roots')
            ),
        ];
    }
}

```

--------------------------------

### Passing Data to Components

Source: https://roots.io/sage/docs/components

Demonstrates how to pass string literals versus evaluated PHP expressions to components using attribute syntax.

```blade
<x-example-component :title="$variable"/>
<x-example-component :title="get_my_title()"/>
<x-example-component :title="TITLE_CONSTANT"/>
```

--------------------------------

### Optimize Sage Theme with Acorn

Source: https://roots.io/sage/docs/deployment

This command optimizes the Sage theme by caching configuration and views. It should be run as part of the deployment process. No specific inputs or outputs are detailed, but it's a server-side operation.

```bash
$ wp acorn optimize
```

--------------------------------

### Using with() to Pass Data to Views (PHP)

Source: https://roots.io/sage/docs/composers

Shows how to use the `with()` method within a Composer class to pass data to a view. This data is merged with existing view data.

```php
class Example extends Composer
{
    public function with()
    {
        return [
            'roots' => "An amazing stack!",
        ];
    }
}
```

--------------------------------

### Generate Language Files for Sage Theme

Source: https://roots.io/sage/docs/localization

Use the `yarn translate:pot` command to generate the initial language POT file from your theme's templates. This file serves as a template for creating translations. After generating, open the POT file with Poedit to create and save `.mo` and `.po` files in the `resources/lang` directory with the correct locale naming convention (e.g., `fr_FR.po`).

```bash
yarn translate:pot
```

--------------------------------

### Generate Sage Component via WP-CLI

Source: https://roots.io/sage/docs/components

Use the WP-CLI acorn command to scaffold a new traditional Blade component in the Sage project structure.

```bash
$ wp acorn make:component ExampleComponent
```

--------------------------------

### Blade Layouts and Content Sections

Source: https://roots.io/sage/docs/blade-templates

Illustrates the use of Blade's layout system with `@extends`, `@section`, `@show`, and `@yield`. Layouts define a base structure, while child views extend them and inject content into specific sections.

```html
<!-- resources/views/layouts/app.blade.php -->
<html>
  <body>
    <header>
    @section('header')
      @include('partials.nav.primary')
    @show
    </header>
    <main>
      @yield('content')
    </main>
  </body>
</html>
```

```blade
<!-- resources/views/page.blade.php -->
@extends('layouts.app')
@section('header')
  @parent
  @include('partials.nav.page')
@endsection

@section('content')
  <h1>{{ $title }}</h1>
  <div>{!! $content !!}}</div>
@endsection
```

--------------------------------

### Load Language Files in Sage Theme

Source: https://roots.io/sage/docs/localization

To load the translated language files for the Sage theme, add the provided PHP code snippet to your `app/setup.php` file. This action hooks into the `after_setup_theme` action and uses `load_textdomain` to load the appropriate `.mo` file based on the determined locale from the `resources/lang` directory.

```php
add_action('after_setup_theme', function () {
    load_textdomain( 'sage', get_template_directory() . '/resources/lang/' . determine_locale() . '.mo' );
});
```

--------------------------------

### Directory Structure for Fonts in Sage

Source: https://roots.io/sage/docs/fonts-setup

This shows the expected file structure for adding custom fonts to your Sage theme. The `resources/fonts/` directory is where you should place your font files, and `css/fonts.css` is where you'll define the font's CSS.

```text
resources
├── css
│   ├── app.css
│   ├── fonts.css    # Create this file
│   └── editor.css
├── fonts
│   └── public-sans-v14-latin-regular.woff2
├── images
├── js
└── views

```

--------------------------------

### Referencing Assets in Blade Templates

Source: https://roots.io/sage/docs/compiling-assets

Demonstrates how to reference compiled assets, such as images, within Blade template files using the `Vite::asset` method. This ensures correct paths are generated for assets processed by Vite.

```html
<img src="{{ Vite::asset('resources/images/example.svg') }}">
```

--------------------------------

### Blade Template Output with with() (PHP)

Source: https://roots.io/sage/docs/composers

Illustrates the output of a Blade template when data is passed using the `with()` method. The `with()` method merges data without replacing existing variables.

```html
<!-- /resources/views/partials/example.blade.php -->
<h1>{{ $roots }}</h1>
<!-- <h1>Resources for modern WordPress development</h1> -->
<!-- The same output! -->
```

--------------------------------

### Handling Component Attributes

Source: https://roots.io/sage/docs/components

Shows how to pass arbitrary HTML attributes to a component, which are collected in the $attributes bag for use in the template.

```blade
<x-example-component title="Styled Component" 
    class="bg-color-red text-color-white"/>
```

--------------------------------

### WP-CLI Command to Cache Blade Templates

Source: https://roots.io/sage/docs/blade-templates

This command compiles all Blade templates into view caches using WP-CLI. It's useful for optimizing performance by pre-compiling templates.

```bash
$ wp acorn view:cache
```

--------------------------------

### Composer with Data Binding in PHP

Source: https://roots.io/sage/docs/composers

This PHP code demonstrates a Composer that binds data to a specific view partial. It defines which view (`partials.example`) the data should be available in and returns an associative array where keys are variable names and values are the data to be passed.

```php
class ExampleComposer extends Composer
{
    /**
     * This tells the Composer that it should bind data to the 'example'
     * partial.
     */
    protected static $views = [
        'partials.example',
    ];
    
    /**
     * This will make the variable `$roots` available in the 'example' partial
     * with the value described here.
     */
    public function with()
    {
        return [
            'roots' => "Tools for modern WordPress development",
        ];
    }
}

```

--------------------------------

### Apache Configuration to Secure Blade Templates

Source: https://roots.io/sage/docs/deployment

This Apache configuration snippet, compatible with both Apache 2.4 and 2.2, denies direct access to Blade template files. It should be placed in the virtual host configuration or the .htaccess file. This is a server-side security measure.

```apache
<FilesMatch ".+\.(blade\.php)$">
    # Apache 2.4
    <IfModule mod_authz_core.c>
        Require all denied
    </IfModule>

    # Apache 2.2
    <IfModule !mod_authz_core.c>
        Order deny,allow
        Deny from all
    </IfModule>
</FilesMatch>
```

--------------------------------

### Referencing Assets in CSS

Source: https://roots.io/sage/docs/compiling-assets

Shows how to reference images within CSS files using the Vite alias `@images`. This allows for easy management of image paths in stylesheets that are processed by Vite.

```css
.background {
  background-image: url("@images/example.svg");
}
```

--------------------------------

### Importing Fonts CSS in Sage

Source: https://roots.io/sage/docs/fonts-setup

This demonstrates how to import your custom font styles into the main CSS files of your Sage theme. By importing `css/fonts.css`, you ensure your custom font definitions are included during the build process.

```css
@import './fonts.css';

```

--------------------------------

### Cache Blade UI Icons in production

Source: https://roots.io/sage/docs/use-blade-icons

Enables icon caching for production environments to improve performance. This command should be run during the deployment process.

```bash
wp acorn icons:cache

```

--------------------------------

### Blade Template Inclusion with Data

Source: https://roots.io/sage/docs/composers

Demonstrates how to include a Blade partial and pass data to it. The included partial then displays the passed data.

```html
<!-- /resources/views/page.blade.php -->
@include('partials.example', ['roots' => "Resources for modern WordPress development"])

<!-- /resources/views/partials/example.blade.php -->
<h1>{{ $roots }}</h1>
<!-- <h1>Resources for modern WordPress development</h1> -->
```

--------------------------------

### Include Blade Partials with Data

Source: https://roots.io/sage/docs/blade-templates

Demonstrates how to include a Blade partial and pass data to it. The `@include` directive allows for reusable template components. Data is passed as a keyed array, where keys become variable names in the partial.

```blade
@include('partials.example-partial', ['variableName' => 'Variable Value'])
```

```html
<!-- /resources/views/partials/example-partial.blade.php -->

<h1>{{ $variableName }}</h1>
<!-- <h1>Variable Value</h1> -->
```

--------------------------------

### Nginx Configuration to Secure Blade Templates

Source: https://roots.io/sage/docs/deployment

This Nginx configuration snippet prevents direct access to Blade template files by denying all requests for files ending in .blade.php. It should be added to the site's Nginx configuration before the final location directive. This is a server-side security measure.

```nginx
location ~* \.(blade\.php)$ {
    deny all;
}
```

--------------------------------

### Using override() to Replace View Data (PHP)

Source: https://roots.io/sage/docs/composers

Demonstrates how to use the `override()` method within a Composer class to replace existing data passed to or inherited by a view. This method provides a more aggressive data replacement.

```php
class Example extends Composer
{
    public function override()
    {
        return [
            'roots' => "An amazing stack!",
        ];
    }
}
```

--------------------------------

### Create Composer using WP-CLI

Source: https://roots.io/sage/docs/composers

This command uses WP-CLI to generate a new Composer file within the Sage WordPress Theme. It follows PSR-4 autoloading standards and places the new file in the `app/View/Composers/` directory.

```bash
wp acorn make:composer ExampleComposer
```

--------------------------------

### Import Bootstrap Sass into app.scss

Source: https://roots.io/sage/docs/bootstrap

Imports Bootstrap's Sass files into the Sage theme's main Sass file (`resources/css/app.scss`). This makes Bootstrap's styles available for customization and use within the theme.

```scss
@import "bootstrap/scss/bootstrap";

```

--------------------------------

### Use icons in Blade views

Source: https://roots.io/sage/docs/use-blade-icons

Demonstrates two methods for rendering icons in Blade views: using the dedicated Blade component `<x-icon-name />` and the `@svg()` directive. Both methods assume the icon is available in the configured path.

```html
<x-icon-example-icon />

@svg('example-icon')

```

--------------------------------

### Defining @font-face in Sage

Source: https://roots.io/sage/docs/fonts-setup

This CSS snippet shows how to define a custom font using the `@font-face` rule within your `css/fonts.css` file. It specifies the font family name, display behavior, and the path to the font file.

```css
@font-face {
  font-display: swap;
  font-family: 'Public Sans';
  font-style: normal;
  font-weight: 400;
  src: url('@fonts/public-sans-v18-latin-regular.woff2') format('woff2');
}

```

--------------------------------

### Update Language Files in Sage Theme

Source: https://roots.io/sage/docs/localization

When you make changes to translatable strings within your Sage theme's templates, run `yarn translate:update`. This command updates the existing POT file. Subsequently, use Poedit's 'Catalog > Update from a POT file' option to merge these changes into your existing `.po` translation files.

```bash
yarn translate:update
```

--------------------------------

### Integrate Polylang with Sage Theme Strings

Source: https://roots.io/sage/docs/localization

For themes using the Polylang plugin, replace all instances of the standard WordPress translation function `__()` with `pll__()` in your templates. This ensures that strings are correctly recognized and translated by Polylang. For translating strings within the `app/` folder, refer to the `Sage_Polylang_Theme_Translation` documentation.

```php
// Replace __("Some string") with pll__("Some string")
```

--------------------------------

### Cache Blade UI Icons in Trellis deployment

Source: https://roots.io/sage/docs/use-blade-icons

Integrates the `wp acorn icons:cache` command into the Trellis deployment workflow. This ensures icons are cached on each new release.

```yaml
- name: Cache Blade UI Icons
  command: wp acorn icons:cache
  args:
    chdir: "{{ deploy_helper.new_release_path }}"

```

--------------------------------

### Basic Composer Structure in PHP

Source: https://roots.io/sage/docs/composers

This is the most basic structure for a Composer in Sage. It extends the `Composer` class from RootsAcorn and requires adherence to PSR-4 naming conventions for autoloading.

```php
// app/View/Composers/ExampleComposer.php

namespace App\View\Composers;

use Roots\Acorn\View\Composer;

class ExampleComposer extends Composer
{}

```

--------------------------------

### Configure default icon set path

Source: https://roots.io/sage/docs/use-blade-icons

Sets the default icon set within the `config/blade-icons.php` file. This configuration points to the directory where your custom SVG icons are stored, relative to the theme.

```php
<?php

return [
    'sets' => [
        'default' => [
            'path' => 'web/app/themes/sage/resources/images/icons', 
            'prefix' => 'icon',
        ],
    ],
];

```

--------------------------------

### WP-CLI Command to Clear Blade Template Cache

Source: https://roots.io/sage/docs/blade-templates

This command clears the compiled Blade view caches using WP-CLI. It's useful when template changes are not reflecting or to ensure a clean state.

```bash
$ wp acorn view:clear
```

--------------------------------

### Blade Template Rendering Inherited Data

Source: https://roots.io/sage/docs/composers

This Blade template demonstrates the output of the `better_roots` variable, which was modified in the Composer using inherited data. The output shows the replaced string, confirming the data manipulation.

```blade
<!-- resources/views/partials/example2.blade.php -->
<div>{{ $better_roots }}</div>
<!-- <div>Resources for *awesome* WordPress development</div> -->

```

--------------------------------

### Sage Theme Directory Structure

Source: https://roots.io/sage/docs/structure

A visual representation of the Sage theme file system. This structure organizes theme logic, assets, and dependencies, following PSR-4 standards for PHP autoloading.

```text
themes/your-theme-name/   # → Root of your Sage based theme
├── app/                  # → Theme PHP
│   ├── Providers/        # → Service providers
│   ├── View/             # → View models
│   ├── filters.php       # → Theme filters
│   └── setup.php         # → Theme setup
├── public/               # → Built theme assets (never edit)
├── resources/            # → Theme assets and templates
│   ├── css/              # → Theme stylesheets
│   ├── fonts/            # → Theme fonts
│   ├── images/           # → Theme images
│   ├── js/               # → Theme JavaScript
│   └── views/            # → Theme templates
│       ├── components/   # → Component templates
│       ├── forms/        # → Form templates
│       ├── layouts/      # → Base templates
│       └── partials/     # → Partial templates
├── vendor/               # → Composer packages (never edit)
├── composer.json         # → Autoloading for `app/` files
├── functions.php         # → Theme bootloader
├── index.php             # → Theme template wrapper
├── node_modules/         # → Node packages (never edit)
├── package.json          # → Node dependencies and scripts
├── screenshot.png        # → Theme screenshot for WP admin
├── style.css             # → Theme meta information
└── vite.config.js        # → Vite configuration
```

--------------------------------

### Blade Template Output with override() (PHP)

Source: https://roots.io/sage/docs/composers

Shows the output of a Blade template when data is passed using the `override()` method. This method replaces any existing data with the new values.

```html
<!-- /resources/views/partials/example.blade.php -->
<h1>{{ $roots }}</h1>
<!-- <h1>An amazing stack!</h1> -->
```
Tokens:
Raw