Ekko
Framework agnostic PHP package for marking navigation items active.
Features
- Framework agnostic.
- Can be modified for any custom application and UI.
- Currently supported frameworks: Laravel (PRs are welcome!).
- Global helper functions disabled by default.
- Supports default output value.
- Backward compatible.
- Fully tested using table driven testing (data providers in PHPUnit).
Installation
From the command line:
composer require laravelista/ekko
By default Ekko is initialized with these sensible defaults:
- the default output value is
active. - it uses GenericUrlProvider (
$_SERVER['REQUEST_URI']). - global helper functions are disabled.
Laravel
The only dependency for this package is PHP ^8.0, meaning that you can possibly install it on any Laravel version that supports PHP 8 (I think that for now this is only Laravel 8). The service provider is always going to follow the latest Laravel release and try to be as backward compatible as possible.
Laravel 8 will use the auto-discovery function to register the ServiceProvider and the Facade.
If you are not using auto-discovery, you will need to include the service provider and facade in config/app.php:
'providers' => [
...,
Laravelista\Ekko\Frameworks\Laravel\ServiceProvider::class
];
And add a facade alias to the same file at the bottom:
'aliases' => [
...,
'Ekko' => Laravelista\Ekko\Frameworks\Laravel\Facade::class
];
Overview
To mark a menu item active in Bootstrap, you need to add a active CSS class to the <li> tag:
<ul class="nav navbar-nav">
<li class="active"><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
You could do it manually with Laravel, but you will end up with a sausage:
<ul class="nav navbar-nav">
<li class="@if(URL::current() == URL::to('/')) active @endif"><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
With Ekko your code could look like this:
<ul class="nav navbar-nav">
<li class="{{ Ekko::isActive('/') }}"><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
or like this:
<ul class="nav navbar-nav">
<li class="{{ Ekko::isActiveRoute('home') }}"><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
or this:
<ul class="nav navbar-nav">
<li class="{{ $ekko->isActive('/') }}"><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
Default output value
What if you are not using Bootstrap, but some other framework or a custom design? Instead of returning active CSS class, you can make Ekko return anything you want.
<ul class="nav navbar-nav">
<li class="{{ Ekko::isActive('/', 'highlight') }}"><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
You can alse set the default output value if you don't want to type it everytime:
$ekko = new Ekko;
$ekko->setDefaultValue('highlight');
return $ekko->isActive('/');
or in Laravel you can set the default output value in the config config/ekko.php file:
<?php
return [
'default_output' => 'highlight'
];
To publish the config for Ekko use this in Laravel:
php artisan vendor:publish --provider="Laravelista\Ekko\Frameworks\Laravel\ServiceProvider"
Using boolean true or false is convenient if you need to display some content depending on which page you are in your layout view:
@if(Ekko::isActive('/about', true))
<p>Something that is only visible on the `about` page.</p>
@endif
Global helper functions
Global helper functions are disabled by default. To enable them use Ekko::enableGlobalHelpers(); or $ekko->enableGlobalHelpers().
In Laravel add this code to your app/Providers/AppServiceProvider.php file in register method:
\Ekko::enableGlobalHelpers();
Usage
When used outside a framework, this package has only one main method of interest called isActive. The function accepts an input which can be a string or an array of strings, and an output which can be anything. The default output is active.
<li class="{{ $ekko->isActive('/') }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive(['/', '/home]) }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive(['/', '/home, '*home*']) }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive('/home*') }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive('/home*feature=slideshow*') }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive('/index.php?page=*') }}"><a href="/">Home</a></li>
It supports strings, arrays, wildcards and query parameters.
Laravel usage
Use the facade Ekko::, resolve(Ekko::class) or app(Ekko::class) to obtain the Laravel bootstraped instance.
Laravel comes with few special methods for named routes and other helper methods. Also, there is a lot of backward compatibility here for v1 of this package.
Methods
Ekko::isActive($input, $output = null) This calls the main Ekko method isActive. Described above.
Ekko::isActiveRoute($input, $output = null) For named routes. Supports arrays and wildcards.
Ekko::areActiveRoutes(array $input, $output = null) For arrays of named routes. Supports wildcards. Backward compatibility. Use isActiveRoute and pass it the same array.
Ekko::isActiveURL($input, $output = null) The same as Ekko::isActive. Backward compatibility. Use Ekko::isActive and pass it the same input.
Ekko::areActiveURLs(array $input, $output = null) The same as Ekko::isActiveURL, but accepts only the array of Urls. Backward compatibility. Use Ekko::isActive and pass it the same array.
Ekko::isActiveMatch($input, $output = null) The same as Ekko::isActive. This method encloses the input with wildcard *. Supports string, array and wildcards as input. Backward compatibility. Use Ekko::isActive and pass it the same input, but with wildcard * at the desired place.
Ekko::areActiveMatches(array $input, $output = null) The same as Ekko::isActiveMatch, but accepts only the array of strings. Backward compatibility. Use Ekko::isActive and pass it the same array.
Development
# Install dependencies
composer install
# Run tests
vendor/bin/phpunit
# Run Psalm
vendor/bin/psalm
# Format code (php-cs-fixer)
vendor/bin/php-cs-fixer
Credits
Many thanks to:
- @judgej for route wildcards.
- @Jono20201 for helper functions.
- @JasonMillward for improving wildcards in nested route names.
- @it-can for Laravel 5.5+ auto-discovery.
- @foo99 for snake_case function names.
- @Turboveja for are_active_matches function.
Sponsors & Backers
I would like to extend my thanks to the following sponsors & backers for funding my open-source journey. If you are interested in becoming a sponsor or backer, please visit the Backers page.
Contributing
Thank you for considering contributing to Ekko! The contribution guide can be found Here.
Code of Conduct
In order to ensure that the open-source community is welcoming to all, please review and abide by the Code of Conduct.
License
Ekko is open-source software licensed under the MIT license.
47 Nov 30, 2022
4 Sep 25, 2022
10 Nov 28, 2022
36 Oct 30, 2022
61 Dec 30, 2022
0 Jun 29, 2022
54 Sep 21, 2022
10 Nov 17, 2022
45 Dec 27, 2022
824 Jan 7, 2023
5 Oct 31, 2022
565 Dec 9, 2022
240 Nov 19, 2022
10 Dec 16, 2022
686 Dec 28, 2022
264 Dec 23, 2022
931 Dec 24, 2022
4 Dec 8, 2022