webstractions/sage-xpress

Extends Sage ~9-beta with Blade directives, component providers, streamlined configurations, and more.

Sage Xpress

, _(*1)

A collection of extensions, providers, and Blade revisions for your Roots\Sage 9.x beta themes., _(*2)

• Blade Directives: @directives for loop, query, sidebar, FontAwesome, and more.
• Menu Provider: Register nav menu and markup via configuration file.
• Sidebar Provider: Register sidebar and widget markup via configuration file.
• Comment Form Provider: Register comment form markup via configuration file.
• Schema Provider Quickly add schema.org markup via @schema directive.
• Facade/Alias Support Provide a "static" interface to classes that are bound to the Sage container.
• Blade Fixes Fixes Blade @inject directive and 5.5's Blade::if() method.

Requirements

This package is specifically built for Roots\Sage 9.0.0-beta.4 and above. It goes without saying that your development server needs to have Php 7.0 or greater as well., _(*3)

Installation

You can install the package via composer:, _(*4)

composer require webstractions/sage-xpress

Sage Xpress Setup

Add to your after_theme_setup action in app/setup.php file. It is important that you make this addition after Sage's singleton for the BladeProvider:, _(*5)

add_action('after_setup_theme', function (){

  ...

  /**
    * Add Blade to Sage container
    */
  sage()->singleton('sage.blade', function (Container $app) {
      $cachePath = config('view.compiled');
      if (!file_exists($cachePath)) {
          wp_mkdir_p($cachePath);
      }
      (new BladeProvider($app))->register();
      return new Blade($app['view']);
  });

  // Copy this part into app\setup.php after_theme_setup action.
  // Make sure it follows the Sage singleton for the Blade Provider.
  (new \SageXpress\SageXpress(sage()))->bootstrap();

});

Important Since this package is introducing new Blade directives, you should clear your cached/compiled Blade files. Those files are located in wp-content\uploads\cache., _(*6)

Configuration Files

Currently, you have to copy and paste the sample config files into your theme config directory. You can find them in the vendor\webstractions\sage-xpress\config directory., _(*7)

The configuration files are a major component of SageXpress that drives the Providers (more below)., _(*8)

• app.php Registers theme environment, providers, composers, and aliases.
• blade-directives.php For your custom Blade directives.
• comments.php Comment form configuration. Other comments related tasks.
• menu.php Register nav menus and configurations.
• sidebar.php Register sidebars and configurations.

Overview

Outside of one line of code that you need to add to setup.php and the config files, there is nothing else you need to do. Config files are automatically registered with the Sage Container, no messing with functions.php., _(*9)

Additionally, your setup.php file should actually be leaner. No need for widgets_init, register_nav_menus, and funky wp_nav_menu callouts in your controllers or blade files. The providers automatically do the registration for you based on your configurations and there are Blade Directives to spew them out., _(*10)

Facades and Aliases

You can now register aliases via the config\app.php configuration file. Currently, there are standard Laravel Facades for Blade, Config, Event, File, and View. Facades for SageXpress providers are in a state of flux and currently supports Comments, Menu, and Sidebar., _(*11)

With Facades, you can reference bound providers with unruly instantiation and method calls like the following., _(*12)

Instead of, _(*13)

sage('blade')->compiler()->directive('name', function ($expression) {
        // Handle the directive.
    });

You can:, _(*14)

Blade::directive('name', function ($expression) {
        // Handle the directive.
    });

Facades have some advantages. Rather than list the pros and cons of Facades, and how they work, please reference the Laravel Facade Documentation., _(*15)

The SageXpress Provider

SageXpress providers are similar to Laravel Service Providers, but they contain additional methods for config() and render(). You can think of them as configurable components that can be rendered in a Blade view., _(*16)

Providers are autoloaded via the config\app.php congifuration file during the SageXpress boot process. The providers are then bound to the Sage Container where you can use or reference them from your theme classes and controllers., _(*17)

Providers handle WordPress-centric methods for registration, filters, etc. The render() method can be used for the creation of custom Blade directives., _(*18)

Blade Directives Provider

Provides some handy Blade directives targetted mostly for WordPress use, but other helpful functionality as well., _(*19)

There are a whole slew of directives, and requires its own Blade Directives Documentation., _(*20)

One example, the @loop directive does a nice job of cleaning up your templates., _(*21)

@loop

   {{-- Code inside of the loop --}}

@endloop

The directive will output this php., _(*22)

if (have_posts()) :
  while(have_posts()) :
    the_post();

    // Code inside of the loop

  endwhile;
endif;

Menu Provider

Configure your menus in config\menu.php. The MenuProvider will handle the registration with WordPress., _(*23)

 [
        'primary'    => __('Primary Navigation', 'sage'),
    ],

    'default' => [],

    'primary' => [
        'theme_location'    => 'primary',
        'container_class'   => 'collapse navbar-collapse',
        'container_id'      => 'primary-menu',
        'menu_class'        => 'navbar-nav ml-auto',
        'depth'             => 2,
        'fallback_cb'       => '\App\Lib\WP_Bootstrap_Navwalker::fallback',
        'walker'            => new \App\Lib\WP_Bootstrap_Navwalker(),
    ],
];
```
You can safely remove any configured menus from your `setup.php` file.
```php
// Delete this function. MenuProvider has it handled.
register_nav_menus([
    'primary' => __('Primary Navigation', 'sage'),
]);
```
Use `@menu` directive in your Blade files to render a menu.
```blade
@menu('primary')
```

Alternatively, you can create a static rendering function in `app\controllers\app.php`
```php
public static function renderMenu($name='')
{
    return sage('menu')->render($name);
}
```
Then call the function in your Blade files.
```blade
@php( \App::renderMenu('primary') )
```

### Sidebar Provider
Configure your sidebars in `config\sidebar.php`. The `SidebarProvider` will handle the registration with WordPress.

```php
 [
        'sidebar-primary',
    ],

    /**
     * Default config options for all sidebars
     */
    "default" => [
        'after_widget'  => "",
        'before_title'  => '
',
        'after_title'   => '
'
    ],

    /**
     * Sidebar configuration.
     */
    'sidebar-primary' => [
        'name'          => __('Primary', 'sage'),
        'id'            => 'sidebar-primary',
        'before_widget' => '
',
    ],
];
```

You can safely remove any configured sidebars from your `setup.php` file.
```php
// Delete this function. The SidebarProvider has it handled.
/**
 * Register sidebars
 */
add_action('widgets_init', function () {
    $config = [
        'before_widget' => '
',
        'after_widget'  => '
',
        'before_title'  => '
',
        'after_title'   => '
'
    ];
    register_sidebar([
        'name'          => __('Primary', 'sage'),
        'id'            => 'sidebar-primary'
    ] + $config);

});
```

Use `@sidebar` directive in your Blade files to render a menu.
```blade
@sidebar('sidebar-primary')
```

Alternatively, you can still use WordPress functions to display a sidebar.

```blade
@php( \dynamic_sidebar('sidebar-primary') )
```

### Comment Form Provider
Configure your comment form in `config\comments.php` and use the `@commentform` directive to display in your Blade templates.

The following shows an example configuration for Bootstrap 4 Beta markup.
```php
 [
        // Change the title of send button
        'label_submit' => __( 'Send', 'textdomain' ),
        // Change the title of the reply section
        'title_reply' => __( 'Write a Reply or Comment', 'textdomain' ),
        // Remove "Text or HTML to be displayed after the set of comment fields".
        'comment_notes_after' => '',
        'comment_field' => '
          

            ' . _x( 'Comment', 'sage' ) . '
            

            
          
',
        'fields' => [
          'author' => '
            

              ' . _x( 'Name', 'sage' ) . '
              

                
                

                    Please provide a valid name.
                
              
            
',
          'email' => '
            

              ' . _x( 'Email', 'sage' ) . '
              

                
              
              

                  Please provide a valid email.
              
            
',
          'url' => '
            

              ' . _x( 'Url', 'sage' ) . '
              

                
              
            
',
        ],
    ],
];
```

### Schema Provider
As with the Blade directives, there are numerous schema.org attributes and has its own documentaion. There are also two filters for each attribute, which can be used to extend them further. See [Schema Provider Documentation](https://github.com/webstractions/sage-xpress/tree/master/docs/schema.md) for complete details.

Using the `@schema` directive makes markup simple.

```blade
{{--  Author  --}}

  @php( the_author_posts_link() )

```
Will produce the following Php.
```php

    
</span>

Documentation

• Blade Directives
• Schema Attributes

Acknowledgements

• Roots/Sage Discourse thread Resources for Blade and Log1x's contributions for inspiring the Blade component.
• Appstract's Laravel Blade Directives for configuration and service provider logic.
• Justin Tadlock's hybrid_attr() functions from older versions of Hybrid Core.

License

The MIT License (MIT). Please see License File for more information., _(*24)