Relation

• Introduction
• Preview
  • Display Pivot Data
• Sortable
• Filter
• Forms
  • Create A New Relationship Model
  • Pivot Fields
• Inline Fields
• Eager Loading & Appending Accessors
• Allow Direct Unlink
• Delete Unlinked Model
• Tags
• oneRelation And manyRelation
• Methods

Introduction

A relation picker. Relation pickers can be created for any relation of your model.

The relation field requires the name of the relation that should be edited. The type of the relation is automatically recognized and displayed accordingly.

The relations Field can only be used for Crud Models and not in Forms or Blocks. For Forms or Blocks the oneRelation or manyRelation field can be used.

$form->relation('articles')
    ->title('Articles')
     ->preview(function ($table) {
        // Build the preview table in here.
        $table->col('title'); // In this case we are showing the article title.
    });;

In the Model:

public function articles()
{
    return $this->hasMany('App/Models/Article');
}

Preview

The table preview is configured in preview.

$form->relation('articles')
    ->title('Articles')
    ->preview(function ($table) {
        // Build the preview table in here.
        $table->col('title'); // In this case we are showing the article title.
    });

However you don't need to define a new preview table every time you create a new relation field. You can simply display the index table of the related Model by setting settings its Crud config class in the use method list this:

use Lit\Config\Crud\ArticleConfig;

$form->relation('articles')
    ->title('Articles')
    ->use(ArticleConfig::class);

Display Pivot Data

You may load and display data from the pivot table of a many to many relation.

In the following example we want to display when a subscrition of a user expires:

First load the pivot data by specifing the desired columns in the withPivot method:

$index->query(function($query) {
    $query->withPivot('expires_at');
});

Now we can display the expires_at attribute like this:

$field->preview(function ($table) {
    $table->col('subscriptions.pivot.expires_at');
});

Sortable

If the relation should be sortable, the related query in your Model must be sorted by an orderColumn.

public function articles()
{
    return $this->hasMany('App/Models/Article')->orderBy('order_column');
}

Now the sortable attribute can be added:

$form->relation('articles')
    ->title('Articles')
    ->sortable()
    ->preview(function ($table) {
        $table->col('Title')->value('{title}');
    });

Filter

With a filter you can specify which models can be selected for a relation.

$form->relation('articles')
    ->title('Articles')
    ->filter(function($query) {
        $query->where('created_by', lit_user()->id);
    });

Forms

You can edit the related attributes in a modal by configuring fields in the form method:

$form->relation('articles')
    ->form(function($form) {
        $form->wysiwyg('text')->title('text');
    });

Create A New Relationship Model

You may also add a create form so the user can create new relationship models directly:

$form->relation('articles')
    ->create(function($form) {
        $form->wysiwyg('text')->title('text');
    });

Pivot Fields

Sometimes you may want to edit pivot data such as the expired_at date of a subscription. Therefore the pivot method must be prepended to the field.

$field->form(function($form) {
    $form->pivot()->datetime('expires_at')->title('Expires At');
});

Inline Fields

You may even add inline fields to your relationship table. The following example show's how to add an relationship to opening hours that can be created and edited directly:

$form->relation('openingHours')
    ->title('Opening Hours')
    ->showTableHead()
    ->deleteUnlinked()
    ->hideRelationLink()
    ->names([
        'singular' => 'Opening Hour',
        'plural'   => 'Opening Hours',
    ])
    ->preview(function ($preview) {
        $preview->col('Week Day')->value('{week_day}');

        $preview->field('Opening Time')
            ->datetime('opening_time')
            ->onlyTime()
            ->minuteInterval(15);

        $preview->field('Closing Time')
            ->datetime('closing_time')
            ->onlyTime()
            ->minuteInterval(15);
    })
    ->create(function ($form) {
        $form->select('week_day')
            ->title('Wochentag')
            ->options([
                'monday' => 'Monday',
                'tuesday' => 'Tuesday',
                'wednesday' => 'Wednesday',
                'thursday' => 'Thursday',
                'friday' => 'Friday',
                'saturday' => 'Saturday',
                'sunday' => 'Sunday',
            ]);
        $form->datetime('opening_time')
            ->onlyTime()
            ->minuteInterval(15)
            ->width(1 / 2);

        $form->datetime('closing_time')
            ->onlyTime()
            ->minuteInterval(15)
            ->width(1 / 2);
    });

Eager Loading & Appending Accessors

With query, relationships & accessors that should be displayed can be eager loaded or appended.

$form->relation('articles')
    ->title('Articles')
    ->query(function($query) {
        $query->with('author')->append('comments_count');
    })
    ->preview(function ($table) {
        $table->col('Author')->value('{author.first_name} {author.last_name}');
        $table->col('Comments')->value('{comments_count} comments');
    });

Allow Direct Unlink

To switch off the modal in which unlinking a relation is confirmed, confirm must be set to false.

$form->relation('articles')
    ->confirm(false);

Delete Unlinked Model

You may wish to delete a relation when it has been unlinked:

$form->relation('articles')
    ->deleteUnlinked();

Tags

For many relations a tag preview can be generated by passing tags to the type method. Therefore the attribute that should be displayed in the tag must be specified using tagValue. Furthermore the variant can be specified with tagVariant.

$form->relation('tags')
    ->title('Tags')
    ->type('tags')
    ->tagValue('{value}');

oneRelation And manyRelation

Every Laravel relation needs its corresponding database setup. For example the belongsTo relation needs an extra column that stores the id of the related Model. However you migth want to create relations without going through the process of creating a new migration to add the required columns/tables. For this there is the oneRelation and manyRelation. They can simply be added to your Models or Forms.

The following example shows the simplep setup of a the relation field that works for both:

use App\Models\Article;

$form->manyRelation('articles')
    ->title('Articles')
    ->model(Article::class)
    ->preview(function($preview) {
        //...
    });

In the Model:

public function articles()
{
    return $this->manyRelation('App/Models/Article', 'articles');
}

Methods