This document is for CakePHP's development version, which can be significantly different from previous releases.
You may want to read current stable release documentation instead.

Page Contents

Breadcrumbs

class Cake\View\Helper\BreadcrumbsHelper(View $view, array $config = [])

BreadcrumbsHelper vous offre la possibilité de gérer la création et le rendu de vos breadcrumbs (fil d’Ariane) pour vos applications.

Créer un fil d’Ariane

Vous pouvez ajouter un élément à la liste en utilisant la méthode add(). Elle accepte trois arguments:

  • title La chaîne affichée comme titre de l’élément.

  • url Une chaîne ou un tableau de paramètres qui sera passé au Url

  • options Un tableau d’attribut pour les templates item et itemWithoutLink. Référez-vous à la section sur la définition d’attributs pour un élément pour plus d’informations.

En plus de pouvoir ajouter un élément à la fin de la liste, vous pouvez effectuer diverses opérations:

// Ajoute à la fin de la liste
$this->Breadcrumbs->add(
    'Produits',
    ['controller' => 'products', 'action' => 'index']
);

// Ajoute plusieurs éléments à la fin de la liste
$this->Breadcrumbs->add([
    ['title' => 'Produits', 'url' => ['controller' => 'products', 'action' => 'index']],
    ['title' => 'Nom du produit', 'url' => ['controller' => 'products', 'action' => 'view', 1234]]
]);

// Ajoute l'élément en premier dans la liste
$this->Breadcrumbs->prepend(
    'Produits',
    ['controller' => 'products', 'action' => 'index']
);

// Ajoute plusieurs éléments en premier dans la liste
$this->Breadcrumbs->prepend([
    ['title' => 'Produits', 'url' => ['controller' => 'products', 'action' => 'index']],
    ['title' => 'Nom du produit', 'url' => ['controller' => 'products', 'action' => 'view', 1234]]
]);

// Insert l'élément à un index spécifique. Si l'index n'existe pas
// une exception sera levée.
$this->Breadcrumbs->insertAt(
    2,
    'Produits',
    ['controller' => 'products', 'action' => 'index']
);

// Insert l'élément avant un autre, basé sur le titre.
// Si l'élément ne peut pas être trouvé, une exception sera levée
$this->Breadcrumbs->insertBefore(
    'Un nom de produit', // le titre de l'élément devant lequel on veut faire l'insertion
    'Produits',
    ['controller' => 'products', 'action' => 'index']
);

// Insert l'élément après un autre, basé sur le titre.
// Si l'élément ne peut pas être trouvé, une exception sera levée
$this->Breadcrumbs->insertAfter(
    'Un nom de produit', // le titre de l'élément derrière lequel on veut faire l'insertion
    'Produits',
    ['controller' => 'products', 'action' => 'index']
);

Utilisez ces méthodes vous donne la possibilité de contourner la façon dont CakePHP rend les vues. Puisque les templates et les layouts sont rendu de l’intérieur vers l’extérieur (entendez par là que les éléments inclus sont rendus avant les éléments qui les inclusent), cela vous permet de définir précisemment où vous voulez ajouter un élément.

Afficher le fil d’Ariane

Affichage simple

Après avoir ajouté un élément à la liste, vous pouvez facilement l’afficher avec la méthode render(). Cette méthode accepte deux tableaux comme arguments:

  • $attributes : Un tableau d’attributs qui seront appliqués au template wrapper. Cela vous donne lapossibilité d’ajouter des attributs au tag HTML utilisé. Il accepte également la clé templateVars ce qui vous permet d’insérer des variables de template personnalisées dans le template.

  • $separator : Un tableau d’attributs pour le template separator. Voici les propriétés disponibles:

    • separator La chaîne qui sera utilisée comme séparateur

    • innerAttrs Pour fournir des attributs dans le cas où votre séparateur est en deux éléments

    • templateVars Vous permet de définir des variables de templates personnalisées dans le template

    Toutes les autres propriétés seront converties en attributs HTML et remplaceront la clé attrs dans le template. Si vous fournissez un tableau vide (le défaut) pour cet argument, aucun séparateur ne sera affiché.

Voici un exemple d’affichage d’un fil d’Ariane:

echo $this->Breadcrumbs->render(
    ['class' => 'breadcrumbs-trail'],
    ['separator' => '<i class="fa fa-angle-right"></i>']
);

Personnaliser l’affichage

Personnaliser les templates

Le BreadcrumbsHelper utiliser le trait StringTemplateTrait en interne, ce qui vous permet de facilement personnaliser le rendu des différentes chaînes HTML qui composent votre fil d’Ariane. Quatre templates sont inclus. Voici leur déclaration par défaut:

[
    'wrapper' => '<ul{{attrs}}>{{content}}</ul>',
    'item' => '<li{{attrs}}><a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{{separator}}',
    'itemWithoutLink' => '<li{{attrs}}><span{{innerAttrs}}>{{title}}</span></li>{{separator}}',
    'separator' => '<li{{attrs}}><span{{innerAttrs}}>{{separator}}</span></li>'
]

Vous pouvez facilement personnaliser ces templates via la méthode setTemplates() du StringTemplateTrait:

$this->Breadcrumbs->setTemplates([
    'wrapper' => '<nav class="breadcrumbs"><ul{{attrs}}>{{content}}</ul></nav>',
]);

Puisque les templates supportent l’option templateVars, vous pouvez ajouter vos propres variables de templates:

$this->Breadcrumbs->setTemplates([
    'item' => '<li{{attrs}}>{{icon}}<a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{{separator}}'
]);

Et pour définir le paramètre {{icon}}, vous n’avez qu’à la spécifier lorsque vous ajouter l’élément à la liste:

$this->Breadcrumbs->add(
    'Produits',
    ['controller' => 'products', 'action' => 'index'],
    [
        'templateVars' => [
            'icon' => '<i class="fa fa-money"></i>'
        ]
    ]
);

Defining Attributes for the Item

Si vous voulez déclarez des attributs HTML à l’élément et ses sous-éléments, vous pouvez utiliser la clé innerAttrs supportée par l’argument $options. Toutes les clés exceptées innerAttrs et templateVars seront affichés comme attributs HTML:

$this->Breadcrumbs->add(
    'Produits',
    ['controller' => 'products', 'action' => 'index'],
    [
        'class' => 'products-crumb',
        'data-foo' => 'bar',
        'innerAttrs' => [
            'class' => 'inner-products-crumb',
            'id' => 'the-products-crumb'
        ]
    ]
);

// En se basant sur le template par défaut, la chaîne suivante sera affichée:
<li class="products-crumb" data-foo="bar">
    <a href="/products/index" class="inner-products-crumb" id="the-products-crumb">Produits</a>
</li>

Réinitialiser la Liste d’éléments

Vous pouvez réinitialiser la liste d’éléments à l’aide de la méthode reset(). Ceci est particulièrement utile quand vous souhaitez modifier les éléments et complètement réinitialiser la liste:

$crumbs = $this->Breadcrumbs->getCrumbs();
$crumbs = collection($crumbs)->map(function ($crumb) {
    $crumb['options']['class'] = 'breadcrumb-item';

    return $crumb;
})->toArray();

$this->Breadcrumbs->reset()->add($crumbs);