Resources

What are resources?

For each of the Eloquent models you wish to use with Runway, you’ll need to define a ‘resource’.

A resource basically tells Runway about the model and how you’d like it to be configured - which blueprint to use, whether or not it should be manageable in the CP, etc.

Defining resources

You can define resources inside of the configuration file published during installation. It’s located in config/runway.php.

 1<?php
 2 
 3return [
 4 
 5    /*
 6    |--------------------------------------------------------------------------
 7    | Resources
 8    |--------------------------------------------------------------------------
 9    |
10    | Configure the resources (models) you'd like to be available in Runway.
11    |
12    */
13 
14    'resources' => [
15        //
16    ],
17 
18];

To define a resource, add an item to the resources array like so:

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4    ],
5],

The key of the array item is the Eloquent model, and the array value contains the configuration for the resource.

The next thing you’ll want to do is create a blueprint for your model.

Resource Blueprints

Creating a new blueprint

Unfortunately, you can’t yet create/edit blueprints used for Runway in the Control Panel but it’s something we’re hoping comes in the future (it’s a Statamic Core change).

However, we can workaround it for now. Instead, create a new blueprint for one of your collections, taxonomies etc (it doesn’t matter).

When creating it, add in all the fields you need. Remember that the field handles need to match up with the column names, otherwise bad things will happen.

Once created via the CP, you’ll find the blueprint’s YAML file in a folder somewhere, probably something like resources/blueprints/collections/pages/my-special-blueprint.yaml.

You’ll want to move the file of the blueprint you just created into the root resources/blueprints folder.

Next, you’ll want to actually use the blueprint… (explained in the next point)

Configure which blueprint to use

To use the blueprint you just created (or use one you’ve already created), you can simply specify it’s ‘namespace’ as a blueprint key in your resource configuration.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4        'blueprint' => 'order',
5    ],
6],

If you’re blueprint is in the root resources/blueprints directory (which I’d recommend by the way), you just need to specify the blueprint’s handle.

If it’s inside a folder like resources/blueprints/foo/order.yaml, you can specify it like so: foo.order

Generating migrations from your blueprints

If you’ve already went and created a blueprint for your model(s) and still to do the database side of things, Runway can help! Runway can automatically generate migrations for your models, based on the fields defined in your blueprint, and their configurations.

To generate a migration for a specific blueprint:

1php please runway:generate-migrations resource-handle

You may also run this same command for all resources pending a migration.

1php please runway:generate-migrations

Generating blueprints from your database

If you've already got an Eloquent model setup, Runway can help you turn it into a blueprint!

Before you can generate, you'll need to install the doctrine/dbal package as it'll be used by Runway to analyse your database columns. You'll also need to have migrated your database already.

As well as having your model setup, you will also need to add the resource(s) to your config/runway.php config.

To generate a blueprint for a specific resource:

1php please runway:generate-blueprints resource-handle

You may also run this same command for all resources:

1php please runway:generate-blueprints

Configuring resources

There’s about a dozen configuration options available for resources, they are all documented below.

Hidden

By default, Runway provides a Control Panel interface for managing your models.

If you’d like to hide the CP Nav Item that’s registered for this model, just say so:

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4        'hidden' => true,
5    ],
6],

Bear in mind, this will just hide the Nav Item for the CP interface, it won’t actually get rid of the routes being registered. If someone knows where to look, they could still use the CP to manage your models (they could guess the URL).

CP Nav

Runway will automatically register a Control Panel Nav Item for any configured resources (unless they're marked as hidden). By default, it'll put them in the 'Content' section and give them a generic icon. However, you may configure various settings for the CP Nav Item if required:

Icon

You should set icon to the name of the icon you’d like to use instead.

Alternatively, if the icon you want isn’t included in Statamic, you can also pass an SVG inline.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4 
5        'nav' => [
6            'icon' => 'date',
7        ],
8    ],
9],

Section

You should set section to the name of the section you’d like to use instead.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4 
5        'nav' => [
6            'section' => 'Tools',
7        ],
8    ],
9],

Title

You should set title to whatever you want the name of the Nav Item to be.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4 
5        'nav' => [
6            'title' => 'Shop Orders',
7        ],
8    ],
9],

Route

If you want to take advantage of Runway’s front-end routing abilities, you can pass in a route to enable it.

Your route can include Antlers code - the variables available are driven by the resource’s blueprint.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4        'route' => '/my-orders/{{ id }}',
5    ],
6],

Templates & Layouts

You may also specify the template and layout you want to use when front-end routing.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4        'route' => '/my-orders/{{ id }}',
5        'template' => 'orders.show',
6        'layout' => 'default',
7    ],
8],

Read Only

You may also specify if you want a resource to be 'read only' - eg. users will not be able to create records and when editing, all fields will be marked as read only and no save button will be displayed.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4        'read_only' => true,
5    ],
6],

Ordering

Sometimes you may want to change the order that your models are returned in the Control Panel listing table. You can use the order_by and order_by_direction configuration options to tell Runway the order you wish models to be returned.

1'resources' => [
2    \App\Models\Order::class => [
3        'name' => 'Orders',
4 
5        // In this case, orders will the highest total will be displayed first.
6        'order_by' => 'total',
7        'order_by_direction' => 'DESC',
8    ],
9],

Actions

In much the same way with entries, you can create custom Actions which will be usable in the listing tables provided by Runway.

You can register them in the same way as you normally would.

The only thing that’s different is the fact that instead of filtering down to just Entry objects for example, you can filter by your model, like Order.

1use App\Models\Order;
2 
3public function visibleTo($item)
4{
5    return $item instanceof Order;
6}

List of Resources

If you're unsure about the handle of a resource, you may want to check it. You may do so with the php please runway:resources command which will display a list of Runway Resources.

Resource List command