Blueprints

As explained in the Statamic Docs, Blueprints are a key component to the content modeling process. They let you define the fields that should be available in the Control Panel and the way your data is stored.

Creating & managing blueprints

Unfortunately, it's not yet possible to manage Runway blueprints in the Control Panel as there's no way for addons to "register" their own blueprints.

In the meantime, you can create a blueprint for a collection, then move the outputted YAML file to the resources/blueprints directory.

Note!

Remember that the field handles in your blueprint should match up exactly with the column names in the database, otherwise bad things will happen.

Now, to use the blueprint you just created, simply specify it's "namespace" (usually just its filename, minus the .yaml extension) as a blueprint key in your resources's config array:

'resources' => [
\App\Models\Order::class => [
'name' => 'Orders',
'blueprint' => 'order',
],
],

If you want to store your resource's blueprint inside a directory, like resources/blueprints/runway, you'll need to specify the blueprint as runway.blueprint_name.

Supported Fieldtypes

Runway supports pretty much ALL fieldtypes available in Statamic, including Bard. As long as you have the correct fieldtype and the correct column type, everything should "just work"!

For simplicity, here's a table matching Statamic's Core fieldtypes with the correct column types:

Fieldtype Column Type Notes
Array json
Assets string/json
Bard string/json If 'Display HTML' is true, then Bard will save as a string.
Button Group string
Checkboxes json
Code string
Collections string/json If 'Allow multiple' is 1, column type should be string. Otherwise, json is what you want.
Color string
Date string/range Format is specified field configuration options. Ranges are should be stored as json.
Entries string/json If 'Allow multiple' is 1, column type should be string. Otherwise, json is what you want.
Fieldset Depends on the fields being imported. The columns depend on the fields being imported by your fieldset. You may import a fieldset using import: fieldset_handle. (the automatic migration generator does not support fieldsets)
Float float
Grid json
Hidden string
HTML - UI only
Integer integer
Link json
List json
Markdown string
Radio string
Range string
Replicator json
Revealer - UI only
Section - UI only
Select string/integer/json
Structures json
Table json
Tags json
Template string
Terms string/json
Text string
Textarea string
Time string
Toggle boolean
Users string/integer/json
Video string
YAML string
Belongs To bigInteger Usually bigInteger or integer but depends on personal preference.

Nesting fields inside JSON columns

To avoid creating a migration for every new field you add to a blueprint, fields can be stored within a JSON column. To do so, use the -> symbol within the field handle:

fields:
-
handle: 'values->excerpt'
field:
type: text

Your table will need to have a suitable column:

$table->json('values')->nullable();

And the cast defined on the model:

protected $casts = [
'values' => 'array', // or 'json', AsArrayObject::class
];

Note!

Nested Fields aren't currently available in GraphQL.

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:

php please runway:generate-migrations resource-handle

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

php 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:

php please runway:generate-blueprints resource-handle

You may also run this same command for all resources:

php please runway:generate-blueprints

Computed Fields

Like Statamic Core, Runway supports the concept of Computed Fields. However, instead of the computed values being part of a callback in your AppServiceProvider, they're accessors on your Eloquent model.

For example, if you wanted to have a full_name field that's computed based on the user's first & last name, you'd do something like this in your User model:

use Illuminate\Database\Eloquent\Casts\Attribute;
 
public function fullName(): Attribute
{
return Attribute::make(
get: function () {
return "{$this->first_name} {$this->last_name}";
}
);
}

Then, in your user blueprint, you'd define visibility: computed in the field's config, like you would normally:

-
handle: full_name
field:
type: text
visibility: computed