---
url: /docs/8.x/guide/link-to.md
---
# 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`

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

* For `LinkToEntityList`, `LinkToSingleShowPage` and `LinkToSingleForm`: `::make($entityKey)`
* For `LinkToForm` and `LinkToShowPage`: `::make($entityKey, $instanceId)`

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

```php
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('player', $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:

```php
LinkToForm::make('player', 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:

```php
LinkToShowPage::make('player', 1)
    ->withBreadcrumb(function (BreadcrumbBuilder $builder) {
        return $builder
            ->appendEntityList('team')
            ->appendShowPage('team', 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(string $text)`

Render the link as a `<a>` tag.

### `renderAsUrl()`

Render the link as an URL (string).

### `setTooltip(string $toltip)`

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

### `setSearch(string $searchText)`

`LinkToEntityList` only

Set a search text.

### `addFilter(string $filterFullClassNameOrKey, string $value)`

`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(string $attribute, string $dir = 'asc')`

`LinkToEntityList` only

Set a default sort.

### `setFullQuerystring(array $querystring)`

`LinkToEntityList` only

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

### `throughShowPage(boolean $throughShowPage = true)`

`LinkToForm` only

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

### `withBreadcrumb(Closure $closure)`

`LinkToForm` and `LinkToShowPage` only

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