Customization
Local Nav comes with a range of block templates to cover most uses and to help get you started for further uses and theme specific adaptations.
Block Templates
Each block template comprises:
view.php - sets up a marker and some reference data that Local Nav JavaScript uses to build the in-page navigation list.
view.css - classes and styles specific to that template.
Local Nav shares the same JavaScript between all block templates. This takes navigation design data structures from the block template, scans the page for headings, builds the navigation list, and handles subsequent navigation events.
The HTML built for the navigation lists is compatible with the core Autonav HTML, but because the HTML is built in-browser using JavaScript the details of how template designs are declared is necessarily different.
$nav_design
Every template view.php must provide an array $nav_design specifying HTML fragments to open and close navigation elements used at each level.
Below we have a sample $nav_design data structure.
$nav_design = [
0 => [
'nav_list_container' => [
'open' => '<ul class="nav flex-column">',
'close' => '</ul>'
],
'nav_list_item' => [
'open' => '<li class="nav-item">',
'close' => '</li>'
],
'nav_list_link' => [
'open' => '<a class="nav-link">',
'close' => '</a>'
],
//'active_class' => 'active' // defaults to 'active', so no need here
],
1 => [
'nav_list_container' => [
'open' => '<ul>',
'close' => '</ul>'
],
'nav_list_item' => [
'open' => '<li class="nav-item">',
'close' => '</li>'
],
'nav_list_link' => [
'open' => '<a class="nav-link">',
'close' => '</a>'
],
],
];
The $nav_design data structure must supply at least level 0. Levels 1..5 are optional. Any levels undefined will use the same structures as the previous level. Above we have specified levels 0 and 1. If the block edit dialogue is used to configure further levels 2, 3, 4 etc., they will use the $nav_design for level 1.
The section active_class is optional - inside Local Nav this defaults to 'active'.
If you have a look through the templates supplied with the block, you will see small variations in the classes declared, particularly for the Modena Sidebar template where the underlying grid framework is not Bootstrap.
You will also see some templates that insert Font Awesome icons into the HTML.
Extreme Templates
Callbacks
The above mechanisms are rigid, the same HTML snippets are filled for each item at each level. For a little more flexibility, and especially for adding some item specific HTML into the navigation, a template may optionally provide callback methods.
A callback method can be specified for any open or close fragment and can then be used to modify the HTML fragment. You need to specify the name of the JavaScript callbacks in the view.php and then provide the actual functions in your own JavaScript, such as in a view.js for the custom template.
view.php - add the name of your callback functions to the $nav_design data.
view.js - provide the actual callback functions.
We suggest you keep all your callbacks within your own object to protect them from polluting the global namespace, but its all up to you.
For a simple example of using callbacks, please look at the block template Example with Callbacks.
What code you put in your callbacks is entirely up to you and is not covered by marketplace support for this addon.
Overriding local_nav.js
All the bundled templates use the common JavaScript local_nav.js. For extreme customization of Local Nav, for example, where the HTML structures are not variations of container / item / link at each level, perhaps you would like to create your own version of local_nav.js.
Our suggested starting point is to copy the supplied local_nav.js into your custom template view.js or theme provided JavaScript. Then in the Local Nav block edit dialogue, check the option to Provide Own JavaScript in the Advanced tab of the block edit dialogue.
The Local Nav block controller will then skip loading of local_nav.js and the rest is up to you. What code you write is entirely up to you and is not covered by marketplace support for this addon.
Remember that local_nav.js also handles navigation events after the in-page navigation index is built.
Events
The local_nav.js JavaScript triggers JavaScript events:
local_nav_ready - triggered on the Local Nav block element jl_local_nav_block when the in-page index is ready. Also triggered when the in-page index is updated (such as after navigated content changes dynamically).
local_nav_navigate - triggered on the link clicked to navigate.
Developer Debug mode
To help developers we also have a debug option in the Advanced tab of the block edit. When enabled Local Nav will pull in debug.css to outline elements used and generated by Local Nav. The local_nav.js will then dump copious trace information to the browser developer console
Excluding from Local Nav
You may find that Local Nav is grabbing hold of headings you do not want it to index. Your first step here should be to tie down the Outer Scope selectors or/and extend the Exclude selectors in the Navigation tab of the block edit dialogue.
Sometimes a theme page template or block just doesn't provide a convenient .class or #id to select on. You can use block or area design to add the class local_nav_exclude or local-nav-exclude to exclude an element and any child elements from indexing by Local Nav.
Local Nav also has built in exclusion for the content of Omni Gallery blocks. This is specified in the configuration key jl_local_nav.navigation.always_exclude and you are free to extend that selector for further blocks you want to exclude from indexing by Local Nav.
