Create links to an entity

You may need to create a link to an EntityList, a Show Page or a Form.

Classes

Depending on your target, you'll want to use either:

• Code16\Sharp\Utils\Links\LinkToEntityList
• Code16\Sharp\Utils\Links\LinkToForm
• Code16\Sharp\Utils\Links\LinkToShowPage
• Code16\Sharp\Utils\Links\LinkToSingleShowPage
• Code16\Sharp\Utils\Links\LinkToSingleForm
• Code16\Sharp\Utils\Links\LinkToDashboard

To create an instance, use the static make method, which may take one or two arguments:

• For LinkToEntityList, LinkToSingleShowPage, LinkToSingleForm and LinkToDashboard: ::make($entityClassOrKey)
• For LinkToForm and LinkToShowPage: ::make($entityClassOrKey, $instanceId)

TIP

Prefer using the full class name of the entity instead of an entity key, as it will be more robust to potential renaming. This means you should use LinkToForm::make(PlayerEntity::class, $id) instead of LinkToForm::make('players', $id).

Link use case

Each link class has a renderAsText method, which will render the link as a <a> tag.

Let’s see an example, in which we want to list the players of a team in an Entity List column and directly link each one to its form. We leverage a custom transformer to do so:

class TeamsList extends \Code16\Sharp\EntityList\SharpEntityList 
{
   // ...
   
   function getListData(EntityListQueryParams $params)
   {
      return $this
          ->setCustomTransformer('players', function($value, $yeam) {
              return $yeam->players
                  ->map(fn ($player) => LinkToForm::make(PlayerEntity::class, $player->id)
                      ->renderAsText($pilot->name); // This will render a full <a...> tag
                  )
                  ->implode('<br>');
          })
          ->transform(Team::orderBy('name')->get());
   }
}

URL use case

If you only need the URL and not the <a> tag, use $link-⁠>renderAsUrl().

Handle the breadcrumb

In Form or Show Page cases, you may want to handle the breadcrumb. The most common case is to insert a Show Page between an Entity List and a Form. To do so, you can use the throughShowPage method:

LinkToForm::make(PlayerEntity::class, 3)->throughShowPage()->renderAsUrl();

This will generate the URL corresponding to the breadcrumb

• Entity List (player)
• Show Page (player #3)
• Form (player #3)

Full control of the breadcrumb

In more complex cases you can also handle the full breadcrumb, by using the withBreadcrumb() method:

LinkToShowPage::make(PlayerEntity::class, 1)
    ->withBreadcrumb(fn (BreadcrumbBuilder $builder) => $builder
        ->appendEntityList(TeamEntity::class)
        ->appendShowPage(TeamEntity::class, 6)
    )
    ->renderAsUrl(),

This will generate the URL corresponding to the breadcrumb

• Entity List (team)
• Show Page (team #6)
• Show Page (player #1)

WARNING

There is no technical limit to the number of breadcrumb items, but you should keep in mind that Sharp will NOT check the functional validity of the breadcrumb you build (apart for basic checks, like piling up Entity Lists).

All available methods

renderAsText

Render the link as a <a> tag.

renderAsUrl

Render the link as an URL (string).

setTooltip

Set a link tooltip (only when rendered as link).

setSearch

LinkToEntityList only

Set a search text.

addFilter

LinkToEntityList only

Set a filter and its value; for the filter, you can either pass its custom key or (more conveniently) its full class name.

setSort

LinkToEntityList only

Set a default sort.

setFullQuerystring

LinkToEntityList only

To manually build the querystring (which you should avoid).

throughShowPage

LinkToForm only

To generate a list > show > form breadcrumb, instead of (by default) just a list > form.

withBreadcrumb

LinkToForm and LinkToShowPage only

To take full control of the breadcrumb, by passing a closure that will receive a BreadcrumbBuilder instance.