Breadcrumbs can be the easiest solution to giving users the smooth web navigation experience they deserve.
Breadcrumbs provide a navigation system to help users know their current location in relation to other web pages on a website.
The name breadcrumbs is derived from the well-known fairy tale Hansel and Grettel because it does pretty much the same thing; leaves a trail behind to prevent users from getting lost hence promoting user experience.
Breadcrumbs on a website will also reduce the number of actions a user has to trigger to reach a page of choice.
Setting up breadcrumbs in Laravel is quite simple.
There is a package that takes care of most of the logic, and we will be looking at how to use this package and get the best features out of it.
Setting up the Laravel applicationThis entire tutorial is targeted at Laravel developers.
We will be pulling in the Laravel Breadcrumbs package via Composer and writing code to render breadcrumb navigation services dynamically, depending on what page the user is viewing.
The resulting code for this article is available here on GitHub.
For the sake of this article, we will be installing a fresh instance of a Laravel application.
laravel new breadcrumbsORcomposer create-project –prefer-dist laravel/laravel breadcrumbsNext, we pull in the Laravel Breadcrumbs package by typing the command below in the terminal.
composer require davejamesmiller/laravel-breadcrumbsCreating the HTTP routingLet’s create some HTTP routes ( and name them as well ) in theroutes/web.
php file — we will be referring to these routes by name in later parts of this article.
These are the routes needed for this example:routes/web.
phpRoute::get('/', ['as' => 'home', 'uses' => 'MainController@home']);Route::get('/continent/{name}', ['as' => 'continent', 'uses' => 'MainController@continent']);Route::get('/country/{name}', ['as' => 'country', 'uses' => 'MainController@country']);Route::get('/city/{name}', ['as' => 'city', 'uses' => 'MainController@city']);To demonstate the power of Laravel Breadcrumbs, we will build a small application where we register continent, country and citiy models.
We will also say that a continent hasMany countries and a country hasMany cities.
To create these models, we write these commands to the terminal:php artisan make:model Continentphp artisan make:model Countryphp artisan make:model CityLet’s also create the migration files for each of these models:php artisan make:migration continentsphp artisan make:migration countriesphp artisan make:migration citiesNext, let’s define the relationship methods in each one of the model classes:app/Continent.
phpnamespace App;use AppCountry;use IlluminateDatabaseEloquentModel;class Continent extends Model{ public function country(){ return $this->hasMany(Country::class); }}app/Country.
phpnamespace App;use AppCity;use AppContinent;use IlluminateDatabaseEloquentModel;class Country extends Model{ protected $guarded = []; public function city(){ return $this->hasMany(City::class); } public function continent(){ return $this->belongsTo(Continent::class); }}app/City.
phpnamespace App;use AppCountry;use IlluminateDatabaseEloquentModel;class City extends Model{ protected $guarded = []; public function country(){ return $this->belongsTo(Country::class); }}Notice that guarded is set to an empty array, this is because we intend to do some form of mass assignment when seeding the database.
Whenever you make a change like this to a model file, always remember to revert the change before the application gets to production stage.
Now let’s create a controller that will handle all the HTTP requests the application receives.
We will call the controller MainController and will declare different actions (methods) to compact instances of models with the returning view, each view will display its own breadcrumb(s).
To create this controller, we write this command to the terminal:php artisan make:controller MainControllerNow let’s write the actions (methods) that will return views after handling the HTTP requests.
app/Http/Controllers/MainControllers.
phpnamespace AppHttpControllers;use AppContinent;use AppCountry;use AppCity;use IlluminateHttpRequest;class MainController extends Controller{ public function home(){ return view('home'); } public function continent($name){ $continent = Continent::where('name', $name)->first(); return view('continent', compact('continent')); } public function country($name){ $country = Country::where('name', $name)->first(); return view('country', compact('country')); } public function city($name){ $city = City::where('name', $name)->first(); return view('city', compact('city')); }}We have included the relationships between models so we can explore the capabilities of the Laravel Breadcrumbs package when it comes to dynamic linking and relational properties.
Now let’s create some views to match the models we just created.
In the resources/views directory, we'll add four new files, we'll name them:home.
blade.
phpcontinent.
blade.
phpcountry.
blade.
phpcity.
blade.
phpTheir names are quite intuitive; the first will hold the frontend code for the homepage, the second will hold the frontend code for the continent page, the third will hold the frontend code for the country page and the last will hold the frontend code for the city page.
Great, now let’s put some code in these new views:resources/views/home.
blade.
php<!DOCTYPE html><html><head><link rel="stylesheet" href="https://maxcdn.
bootstrapcdn.
com/bootstrap/4.
0.
0-alpha.
6/css/bootstrap.
min.
css" integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" crossorigin="anonymous"> </head> <body>{{ Breadcrumbs::render('home') }}</body></html>resources/views/continent.
blade.
php<!DOCTYPE html><html><head><link rel="stylesheet" href="https://maxcdn.
bootstrapcdn.
com/bootstrap/4.
0.
0-alpha.
6/css/bootstrap.
min.
css" integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" crossorigin="anonymous"> </head> <body>{{ Breadcrumbs::render('continent', $continent) }}</body></html>resources/views/country.
blade.
php<!DOCTYPE html><html><head><link rel="stylesheet" href="https://maxcdn.
bootstrapcdn.
com/bootstrap/4.
0.
0-alpha.
6/css/bootstrap.
min.
css" integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" crossorigin="anonymous"> </head> <body>{{ Breadcrumbs::render('country', $country->continent, $country) }}</body></html>resources/views/city.
blade.
php<!DOCTYPE html><html><head><link rel="stylesheet" href="https://maxcdn.
bootstrapcdn.
com/bootstrap/4.
0.
0-alpha.
6/css/bootstrap.
min.
css" integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" crossorigin="anonymous"> </head> <body>{{ Breadcrumbs::render('city', $city->country->continent, $city->country, $city) }}</body></html>The Continent and Country models exhibit a One To Many relationship.
Many cities belong to one country and many countries belong to one continent.
A continent is the grandparent of a city while a country is the parent of a city.
We won't be diving into the logic that binds Laravel relationships in this article but if you wish to learn about it, you can find good knowledge here.
Lastly, Let’s modify the migration files a bit so they define the proper structure for the tables in the database.
database/migrations/2017_11_02_092826_continents.
phpuse IlluminateSupportFacadesSchema;use IlluminateDatabaseSchemaBlueprint;use IlluminateDatabaseMigrationsMigration;class Continents extends Migration{ /** * Run the migrations.
* * @return void */ public function up() { Schema::create('continents', function (Blueprint $table) { $table->increments('id'); $table->string('name'); $table->timestamps(); }); } /** * Reverse the migrations.
* * @return void */ public function down() { // }}database/migrations/2017_11_02_092835_countries.
phpuse IlluminateSupportFacadesSchema;use IlluminateDatabaseSchemaBlueprint;use IlluminateDatabaseMigrationsMigration;class Countries extends Migration{ /** * Run the migrations.
* * @return void */ public function up() { Schema::create('countries', function (Blueprint $table) { $table->increments('id'); $table->string('name'); $table->string('continent_id'); $table->timestamps(); }); } /** * Reverse the migrations.
* * @return void */ public function down() { // }}database/migrations/2017_11_02_092845_cities.
phpuse IlluminateSupportFacadesSchema;use IlluminateDatabaseSchemaBlueprint;use IlluminateDatabaseMigrationsMigration;class Cities extends Migration{ /** * Run the migrations.
* * @return void */ public function up() { Schema::create('cities', function (Blueprint $table) { $table->increments('id'); $table->string('name'); $table->string('country_id'); $table->timestamps(); }); } /** * Reverse the migrations.
* * @return void */ public function down() { // }}We can run the migrations with this command on the terminal:php artisan migrateLet’s insert some data into the database so we can test this application.
To do this, we’d create three factory files [ one for each model ] and update the run method of the [ already existing ] DatabaseSeeder.
php file in the database/seeds directory.
To create the factory files, we’d write these commands to the terminal:php artisan make:factory ContinentFactory –model=Continentphp artisan make:factory CountryFactory –model=Countryphp artisan make:factory CityFactory –model=CityThe commands above will create these files respectively:database/factories/ContinentFactory.
phpuse FakerGenerator as Faker;$factory->define(AppContinent::class, function (Faker $faker) { return [ // ];});database/factories/CountryFactory.
phpuse FakerGenerator as Faker;$factory->define(AppCountry::class, function (Faker $faker) { return [ // ];});database/factories/CityFactory.
phpuse FakerGenerator as Faker;$factory->define(AppCity::class, function (Faker $faker) { return [ // ];});Lastly, let’s update the DatabaseSeeder.
php file that ships with every fresh instance of a Laravel application.
We'll use this file to insert three rows into the database, we'll insert Africa [ of the continent model], South Africa [ of the country model ] and Johannesburg[ of the city model ], we'll also specify their relationships :use IlluminateDatabaseSeeder;class DatabaseSeeder extends Seeder{ /** * Run the database seeds.
* * @return void */ public function run() { factory(AppCity::class)->create([ 'name' => 'Johannesburg', 'country_id' => function(){ return factory(AppCountry::class)->create([ 'name' => 'South Africa', 'continent_id' => function(){ return factory(AppContinent::class)->create([ 'name' => 'Africa' ])->id; } ])->id; } ]); }}We can seed the database with this command to the terminal:php artisan db:seed –class=DatabaseSeederSetting up the breadcrumbs fileWe need to create a breadcrumbs.
php file in the routes directory.
This file will be referenced whenever a breadcrumb is rendered because it instructs Laravel on how to process the breadcrumb information.
Without this file, Laravel will squawk an error in our faces whenever it encounters a call to a breadcrumb function in the views.
The first breadcrumb function we will be defining in our newly created breadcrumbs.
php file is the one for our homepage.
The 'home' breadcrumb will be loaded whenever the route named 'home' is visited.
routes/breadcrumbs.
phpBreadcrumbs::register('home', function ($breadcrumbs) { $breadcrumbs->push('Home', route('home'));});Rendering a static breadcrumbIn the above code, we see that the Breadcrumbs class is used to call a static method.
The register method registers a new breadcrumb with the name home and calls a closure.
Then the closure takes a $breadcrumbs parameter and pushes a new breadcrumb instance alongside its URL.
$breadcrumbs->push('Home', route('home'));The ‘Home’ in the push method is hard-coded and what will appear when the breadcrumb is rendered on the home view or any other view that requires the Home breadcrumb to display a complete navigation chain.
The route('home') returns the URL of 'home' and will be the link Home leads to when it is rendered on any view.
Finally, in the home view code, this is how we render the breadcrumb.
resources/views/home.
blade.
php{{ Breadcrumbs::render('home') }}The render method receives the name of the breadcrumb to display on the home view.
In more complex navigation chains that include some form of database relationship, the render function will accept as many instances of Models as arguments, as are required to render the complete breadcrumb navigation chain.
We will talk more about this next.
Rendering a dynamic breadcrumbWhat happens when we have a web application where we do not know the exact attributes of the pages users will be visiting?.For example, we have a website that displays information about continents, countries, and cities.
We can’t always hard-code the name of any continent, country or city to the routes/breadcrumbs.
php file because we never know which one a user will be viewing.
To make it possible for dynamic breadcrumb rendering in real time, we can write the routes/breadcrumbs.
php file to efficiently work with the dynamic Models in our application and create the breadcrumb navigation chain as users explore deeper layers in our web application.
As we said before, the continent Model hasMany countries and the country Model hasMany cities.
Knowing this, we should be able to get a breadcrumb display that looks like this if we visit Johannesburg of South Africa where South Africa belongs to Africa.
To generate the chain of breadcrumb navigation using Model relationships as we see above, we start by writing the code for registering the continent breadcrumb:routes/breadcrumbs.
phpBreadcrumbs::register('continent', function ($breadcrumbs, $continent) { $breadcrumbs->parent('home'); $breadcrumbs->push($continent->name, route('continent', ['name' => $continent->name]));});We register a continent breadcrumb and pass a closure.
The closure accepts a new parameter, the $continent (which will be supplied by the calling view in real time).
Next, the home breadcrumb is assigned as the parent and lastly, the name and URL of the $continent breadcrumb is pushed.
To render the breadcrumb in the continent view code, we write this snippet:resources/views/continent.
blade.
php{{ Breadcrumbs::render('continent', $continent) }}The render method receives the name of the breadcrumb as the first argument.
It also receives a $continent argument that will help in resolving the instance of the continent Model to its basic properties such as name and URL.
On my local machine, visiting http://127.
0.
0.
1:8000/continent/africa will result in the Africa continent page with this breadcrumb display.
Rendering a complete navigation chainWe have looked at the code to render individual breadcrumbs, now let’s look at the code and logic to render a complete breadcrumb chain.
For the sake of this article, we will be rendering a city page that is related to a country page, then a continent page and lastly, a home page.
This is the final code [for this article, it can get way bigger depending of what you aim to achieve ] for the routes/breadcrumbs.
php file:routes/breadcrumbs.
phpBreadcrumbs::register('home', function ($breadcrumbs) { $breadcrumbs->push('Home', route('home'));});Breadcrumbs::register('continent', function ($breadcrumbs, $continent) { $breadcrumbs->parent('home'); $breadcrumbs->push($continent->name, route('continent', ['name' => $continent->name]));});Breadcrumbs::register('country', function ($breadcrumbs, $continent, $country) { $breadcrumbs->parent('continent', $continent); $breadcrumbs->push($country->name, route('country', ['name' => $country->name]));});Breadcrumbs::register('city', function ($breadcrumbs, $continent, $country, $city) { $breadcrumbs->parent('country', $continent, $country); $breadcrumbs->push($city->name, route('city', ['name' => $city->name]));});We have added two more breadcrumbs — country and city — We need these additional breadcrumbs so that all the breadcrumbs can effectively communicate with one another when a view calls for a navigation chain that involves more than one breadcrumb.
The methods for registering and pushing the country and city breadcrumbs are the same as the ones for the continent breadcrumb so we will not be looking at it in detail.
To render the breadcrumb in the view code for the city page, we simply insert this snippet of code in the desired location:resources/views/city.
blade.
php{{ Breadcrumbs::render('city', $city->country->continent, $city->country, $city) }}The render method here receives the name of the breadcrumb as the first argument.
Next, it receives a $city->country->continent argument which will evaluate to an instance of a continent Model, also it receives a $city->country argument which is the country the city belongsTo and lastly a $city instance.
That is it.
We have completely generated our fully functional and dynamic breadcrumb navigation in only a few lines of code.
ConclusionIn a world where the ‘users’ of internet services seek for the easiest to use products, it is only be right for developers to add breadcrumbs to websites.
This article has taught that, with just a few lines of code, we can create a fully functional navigation service.
There are lots more that can be done with the Laravel Breadcrumb package [ for example, we can affect the style and layout to our taste ], feel free to explore it to its fullest power.
Originally published at dev.
to.
.