Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/laravelista/ekko
Framework agnostic PHP package for marking navigation items active.
https://github.com/laravelista/ekko
active bootstrap helper laravel php
Last synced: about 9 hours ago
JSON representation
Framework agnostic PHP package for marking navigation items active.
- Host: GitHub
- URL: https://github.com/laravelista/ekko
- Owner: laravelista
- License: mit
- Created: 2015-05-22T11:31:28.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2021-03-25T11:31:15.000Z (over 3 years ago)
- Last Synced: 2024-05-18T17:45:03.294Z (6 months ago)
- Topics: active, bootstrap, helper, laravel, php
- Language: PHP
- Homepage:
- Size: 248 KB
- Stars: 279
- Watchers: 12
- Forks: 28
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Ekko
Framework agnostic PHP package for marking navigation items active.
[](https://www.patreon.com/laravelista)
## 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:
```bash
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](http://getbootstrap.com/components/#navbar), you need to add a `active` CSS class to the `
```html
```
You could do it manually with Laravel, but you will end up with a sausage:
```html
```
With Ekko your code could look like this:
```html
```
or like this:
```html
```
or this:
```html
```
### 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.
```html
```
You can alse set the **default output value** if you don't want to type it everytime:
```php
$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
'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:
```html
@if(Ekko::isActive('/about', true))
Something that is only visible on the `about` page.
@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`.
```
```
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
```bash
# 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](https://github.com/judgej) for route wildcards.
- [@Jono20201](https://github.com/Jono20201) for helper functions.
- [@JasonMillward](https://github.com/JasonMillward) for improving wildcards in nested route names.
- [@it-can](https://github.com/it-can) for Laravel 5.5+ auto-discovery.
- [@foo99](https://github.com/foo99) for snake_case function names.
- [@Turboveja](https://github.com/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](https://mariobasic.com/backers).
## Contributing
Thank you for considering contributing to Ekko! The contribution guide can be found [Here](https://mariobasic.com/contributing).
## 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](https://mariobasic.com/code-of-conduct).
## License
Ekko is open-source software licensed under the [MIT license](https://opensource.org/licenses/MIT).