Fieldtypes ​

Table of Contents

• Belongs To
• HasMany fieldtype
  • Re-ordering relationships
  • BelongsToMany
• Title Format
• Eager Loading

Runway provides two fieldtypes to let you manage Eloquent relationships within Statamic: Belongs To & Has Many.

You can not only use these fieldtypes to represent Eloquent relationships on your models but you can also use them to relate Eloquent models to entries/terms, it's almost like magic 🪄.

Belongs To

You can use the Belongs To fieldtype to relate to a single Eloquent model.

To configure the Belongs To fieldtype, you'll need to ensure you've created the belongsTo relationship on your model:

// app/Models/Post.php
 
public function author()
{
    return $this->belongsTo(Author::class);
}

You'll next need to add the field to your resource's blueprint:

# resources/blueprints/post.yaml
 
-
    handle: author_id
    field:
        max_items: 1
        mode: default
        resource: author
        create: true
        display: 'Author'
        type: 'belongs_to'

Make sure resource is set to the handle of the 'related resource' (in this case, the one for the Author model). You should also ensure the handle of the field is set to the name of the Belongs To column in the database, like author_id.

HasMany fieldtype

You can use the Has Many fieldtype to relate to multiple Eloquent models.

To configure the Has Many fieldtype, you'll need to ensure you've created a hasMany/morphedByMany relationship on your model:

// app/Models/Post.php
 
public function categories()
{
    return $this->hasMany(Category::class);
}

You'll next need to add the field to your resource's blueprint:

# resources/blueprints/post.yaml
 
-
    handle: categories
    field:
        type: has_many
        resource: category
        mode: default
        display: Categories

Make sure resource is set to the handle of the 'related resource' (in this case, the one for the Category model). You should also ensure the handle of the field is the same as the name of the Eloquent relationship.

Re-ordering relationships

If you'd like users to be able to re-orderable models in your Has Many field, you may set reorderable to true and specify the column you'd like to use to store the order.

If you're using a pivot table for the relationship, the order column must exist on the pivot table.

# resources/blueprints/post.yaml
 
-
    handle: categories
    field:
        type: has_many
        resource: category
        mode: default
        display: Categories
        orderable: true // [tl! add]
        order_column: sort_order  // [tl! add]

BelongsToMany

You can use the HasMany fieldtype to handle belongsToMany relationships. Simply add a HasMany fieldtype to both sides of the relationship and you'll be golden!

Title Format

The title_format configuration option allows you to specify a title format to be used when related models are displayed in the Control Panel.

You can even use Antlers when specifying a title_format.

# resources/blueprints/post.yaml
 
-
    handle: categories
    field:
        type: has_many
        resource: category
        mode: default
        display: Categories
        title_format: 'Category ID {{ id }}: {{ name }}' // [tl! add]

Eager Loading

If you wish, you can configure additional relationships to be eager loaded with the field:

# resources/blueprints/post.yaml
 
-
    handle: categories
    field:
        type: has_many
        resource: category
        mode: default
        display: Categories
        with:
            - 'parentCategory'