Download the PHP package everlutionsk/navigation-bundle without Composer

Navigation Bundle

EverlutionNavigationBundle is Symfony Bundle for rendering multiple navigation instances registered dynamically by tagged services.

If you are looking just for Navigation library check out everlutionsk/navigation

Contents

• Installation
  • Download the bundle
  • Enable the bundle
• Configuration
• Usage
  • Create navigation items
  • Create container and register items
  • Register item to multiple containers from anywhere
  • Rendering the navigation
  • Adding route with parameters to navigation item
  • Adding dynamic parameters to item route
  • Highlight the current item in navigation
  • Filtering the navigation items
  • Sorting the navigation items
  • Adding nested items
  • Rendering breadcrumbs
  • Translating the item labels
  • Rendering single navigation item
• Troubleshooting
• TO DO's

Installation

Download the bundle

Enable the bundle

Configuration

You can specify custom router service. Router service must implement Symfony\Component\Routing\RouterInterface.

Usage

Create navigation items

You can create navigation item simply by implementing Everlution\Navigation\Item\ItemInterface. Interface contains getLabel(): string method for providing label which will be shown and translated in template and isHidden(): bool method. We have provided 3 traits so you can by default show (Everlution\Navigation\Item\ShownItemTrait) or hide (Everlution\Navigation\Item\HiddenItemTrait) the item. The third trait (Everlution\Navigation\Item\TogglableTrait) can be used with Everlution\Navigation\Item\TogglableInterface which provides show/hide interface.

There are several other interfaces provided within namespace Everlution\Navigation\Item. By implementing these interfaces you add behaviours to the navigation items.

Please inspect interfaces within this namespace. We will describe some of them further in following sections.

Example:

Create container and register items

The simplest way to implement navigation items container is to extend Everlution\Navigation\MutableContainer which provides predefined methods used internally within the bundle you need just to add the navigation items to the container.

Example:

By registering and tagging your navigation within service container the navigation will be automatically added to navigation registry.

As you can see we tagged the service with everlution.navigation name and we also provided an alias which will help us reference the navigation in templates later.

Register item to multiple containers from anywhere

There are times when you want to register your item to multiple navigation instances at once or you just want to register your items automatically to some navigation by for instance loading different Symfony bundles. To do this only thing you need to do is for your navigation item to implement Everlution\Navigation\Item\RegistrableItemInterface. By implementing this interface you are providing list of navigation aliases/FQCNs where you want the item to appear.

The registration process then is as simple as defining the item as service and tagging it with everlution.navigation_item. The bundle then registers the item via dependency injection while the service container is being build.

Rendering the navigation

Once you have the navigation registered within navigation registry you can call render_navigation() function in Twig templates. The first argument is either navigation alias which you have set whilst defining the service eg. sample_navigation or fully quantified class name of the navigation eg. \SampleNavigation.

Example:

We have provided default template which will render navigation with Bootstrap 4 styling you can examine the markup at @EverlutionNavigation/bootstrap_navigation.html.twig. If you need to change the markup you can provide path to your custom template as second argument eg. render_navigation('sample_navigation', '@Path/To/custom_template.html.twig').

Adding route with parameters to navigation item

Rendering the navigation without generating actual URLs would be useless. For simple usage with Symfony's Router you only need to implement Everlution\NavigationBundle\Bridge\Item\RoutableInterface and provide route name and route parameters. Most of the time you don't need any route parameters so you can use Everlution\NavigationBundle\Bridge\Item\EmptyRouteParametersTrait.

Example:

The bundle will generate URL for you automatically at the rendering time of the navigation.

Adding dynamic parameters to item route

There are times when you want to generate the same navigation for instance for multiple users and you just want to be able to change few parameters for the route. Since the navigation items are just plain PHP objects you can inject via constructor anything you wish, create the service within the service container and register the item with navigation within the service container.

Example:

Now register the navigation item with our SampleNavigation:

Sometimes when you just want to reuse some parameters from the current request. For that scenario we have prepared Everlution\NavigationBundle\Bridge\Item\RequestAttributesTrait. It automatically injects Everlution\NavigationBundle\Bridge\Item\RequestAttributesContainer via constructor which can fetch attributes from current master request.

Example:

We have prepared another useful helper method within Everlution\NavigationBundle\Bridge\Item\RequestAttributesTrait which allows you to copy arguments from the request with the same names.

Example:

Highlight the current item in navigation

When you want to highlight the current item within the navigation you need to implement Everlution\Navigation\Item\MatchableInterface and provide array of matches by getMatches(): Everlution\Navigation\Match\MatchInterface[].

We have prepared 3 types of match:

• Everlution\Navigation\Match\Voter\ExactMatch which tries to find exact match
• Everlution\Navigation\Match\Voter\PrefixMatch which tries find the match by provided prefix
• Everlution\Navigation\Match\Voter\RegexMatch which tries to find the match by provided regular expression

The bundle will try to find any match within current URL or route. After finding the first match the process of finding the match ends so you should provide the most generic patterns first and the most specific ones at last. You can provide multiple or none instances of each match type.

Example:

Above example will highlight the navigation item every time when the route or URL of current request is exactly edit_matched_route or it starts with /matched or it ends with .php while .php is case insensitive eg. it will for instance match also .PhP.

Filtering the navigation items

There are cases when you want to filter the navigation items by some rules for instance when user with different role is logged in. We have provided functionality for adding filters to the navigation. Everything you need to do is implement Everlution\Navigation\FilteredContainerInterface within your navigation. By implementing getFilters(): Everlution\Navigation\Filter\NavigationFilterInterface[] you can provide array of any filters you wish.

We provide the Everlution\Navigation\Filter\FilterByRole which will filter out the items which supports the roles provided by role provider. You can use Everlution\Navigation\Filter\RoleProvider or you can create custom provider by implementing Everlution\Navigation\Filter\RolesProviderInterface. In order to filter items by role you need to implement Everlution\Navigation\Item\HasSupportedRolesInterface in each of the navigation items within the navigation.

Example:

The above item will render within the navigation only when user is logged out from the application. The navigation object will look similar to the following one:

In this scenario eg. when your FilteredNavigation returns FilterByRole within array of filters all of navigation items added to the navigation must implement Everlution\Navigation\Item\HasSupportedRolesInterface. To avoid an exception you can chain your filters by preceding the filters by Everlution\Navigation\Filter\RemoveNotSupportedRoleFilter which will remove all items which don't implement the Everlution\Navigation\Item\HasSupportedRolesInterface interface before running FilterByRole filter. No exception will be thrown because the filters are executed sequentially so at the time the FilterByRole filter is running which expect all items to implement Everlution\Navigation\Item\HasSupportedRolesInterface all other items has been already filtered out.

We have also provided non strict filter Everlution\Navigation\Filter\FilterByRoleNonStrictly which will ignore items non implementing Everlution\Navigation\Item\HasSupportedRolesInterface causing showing these items within the final navigation no matter what role is provided.

Sorting the navigation items

At the time of rendering the navigation the navigation container has being to transformed to Everlution\Navigation\OrderedContainer. In this container all items which implements Everlution\Navigation\Item\SortableInterface are being sorted by simple comparison function in ascending order and all other items are appended to the end of the sorted items in its original order. Generally the items are ordered by the order in which they were added to the container.

By implementing the Everlution\Navigation\OrderedContainer you are defining the number (negative or positive) which specifies the place within the ordered container - order is specified by ordering these numbers from the smallest to the largest.

Adding nested items

When you need to render navigation with nested items you need to implement Everlution\Navigation\Item\NestableInterface. In your item then just provide fully quantified class name of parent class. The root navigation items which have no parent shouldn't implement Everlution\Navigation\Item\NestableInterface.

By default we provided template which will render only two level navigation with Bootstrap 4 styling. You can however create your own template and provide it as argument to render_navigation() function in Twig templates.

Example:

Within your navigation container you don't need to create any nested structure. Just add your items as usual. The nested structure is created for you within Twig functions.

Rendering breadcrumbs

When you combined within your navigation items all the perks which EverlutionNavigationBundle offers you can render breadcrumbs. We have prepared render_breadcrumbs() function which can be used within Twig templates. As a first argument you need to provide the navigation name. As second argument you can provide path to your custom template if you don't like look of Bootstrap 4 breadcrubms.

The breadcrumbs will check for current navigation item and renders all of its predecessors. For the breadcrumbs to function you need implement Everlution\Navigation\Item\MatchableInterface, Everlution\Navigation\Item\NestableInterface and Everlution\NavigationBundle\Bridge\Item\RoutableInterface alongside with Everlution\Navigation\Item\ItemInterface.

You should create as descriptive structure as possible eg. the hierarchy of your items should be really exhaustive.

Translating the item labels

By default all labels are translated whilst rendering of the navigation or breadcrumb. You can use helper method within your custom templates which is provided by injected helper variable, just call helper.getLabel(item) and your label will be translated.

There are times when you want to provide some additional parameters with your translation string. In that case your label needs to implement Everlution\NavigationBundle\Bridge\Item\TranslatableItemLabelInterface. Then you can provide array with parameters which will be injected to the translation. You can also set translation domain and locale as second and third parameter of helper.getLabel() method in Twig templates.

Example:

Rendering single navigation item

If you want to render single navigation item in Twig template only thing you need to do is register your item which implements Everlution\Navigation\Item\ItemInterface as service and tag it with everlution.navigation_item with appropriate alias like you can see in example below.

You can then call pre-defined Twig function when you will provide the alias of the registered item. Optionally you can define Twig template which is provided for you by default.

Troubleshooting

Alias is not registered when you registered it

Sometimes when you use Symfony's auto-wire functionality for easier registering of services exception depicted above may occur. In this case we have registered the main_navigation in external file navigaiton.yml which is being imported to main services.yml. Navigation items and navigation instances are implemented within AppBundle\Navigation namespace as you can see in following snippets.

The problem here is that the tagged services from navigation.yml are being overwriteen by main autowire config without the tags before the bundle can collect the tagged services. The solution here is to exclude AppBundle\Navigation from default autowiring.

To Do's

• dynamic generation of navigation (eg. implement items provider)