Jekyll One

Fulltext Search

When it comes to the usability of a website, the focus of your visitors is on one important component: the Navigation System of the site. The Navigation System used by J1 Theme, the Navigator module, is a multi-purpose navigation builder based on the Bootstrap Framework.

10-60 Minutes to read

Getting started

The J1 Navigator module improves the Bootstrap Framework in regard to ease-of-use and offers a powerful, simplified navigation. This is achieved by providing a Navigation Bar that features a Main Menu, an area for Quicklinks, and — as a collapsible component — the TopSearch element.

No doubt, a well-structured navigation system leads to an excellent browsing experience for your visitors by offering easy access, fast orientation, and quick overviews.

Navigator Architecture

The Navigator Module is quite a complex feature of J1. The module implements three sub-modules: the Main Menu (1) and the Quicklinks (2), and via the Quicklinks (the magnifying glass icon: ) an additional navigational component is available: the TopSearch (3).

Navigation Bar (Navigator)
Navigation Bar (Navigator)

Overall, the Navigator consists of the 3 fully configurable sub-modules:

  1. Menu Bar

  2. Quicklinks

  3. TopSearch

Menu Bar and Quicklinks Bar
Menu Bar and Quicklinks Bar
TopSearch
TopSearch

Navigator Configuration

The configuration of the Navigator Module covers the general behaviour of the Navigation System — for example colors and icons — and the placement and behaviour of all the other navigation components.

In order to configure the Navigator Module, two YAML configuration files are used. All sub-modules of the Navigator get configured in ~/data/modules/navigator.yml, whereas in ~/_data/modules/navigator_menu.yml only the content of the _Main Menu gets configured. As dropdown menus typically grow over time, they might become very large in data. This is why a separate file is used for their configuration.

Module configuration tree ~/_data for the Navigator
  ├──── _data
  │    │
    ..
  │    │
  │    └─── modules
  │         ├──  ..
  │         ├──  navigator.yml
  │         ├──  navigator_menu.yml
  │         └─── ..

Resource Settings

The Navigator is loaded by J1’s resource management on every page. The resource entry below registers the module adapter and its initializer function. The Navigator is a required module of the template — you do not need to change this entry.

Module resources ~/_data/resources.yml for the Navigator Module
# ----------------------------------------------------------------------------
# Navigator, JS API to create the navigation for J1 Theme
# based on the JS implementation of Bootsnav.
#
- name:                               J1 Navigator
  resource:
    enabled:                          true
    id:                               navigator
    comment:                          Module Navigator
    region:                           head
    layout:                           [ all ]
    required:                         always
    script_load:
    dependencies:                     false
    pass_init_data:                   false
    data:
      css:                            []
      files:                          [ adapter/js/navigator.js ]
      js:                             []
      init_function:                  [ j1.adapter.navigator.init ]

Navigation Bar properties

The Navigation Bar (the Navigator) is configurable in many ways. Fixation, overlay style, color settings, position and many other parameters can be adjusted to one’s personal taste. The table below provides a list of all possible configuration parameters, their default values and descriptions.

Table 1. Navigation Bar properties
Parameter Type Default Description

background_color_full

string

rgba(255, 255, 255, 0.8)

Color used for the NavBar if the main menu is not collapsed (desktop navigation).

background_color_scrolled

string

var(--md-blue)

Color used for the NavBar if the page is scrolled down.

bottom_line_color

string

var(--md-gray-300)

Color used for the bottom line of the NavBar — a thin line that separates the bar from the page content.

bottom_line_height

integer

1

Height of the bottom line of the NavBar (px).

brand_position

string

right

Position of the brand (logo) in the NavBar, one of left | right.

brand_type

string

image

Type of the brand shown in the (full) NavBar, one of image | text.

brand_type_collapsed

string

text

Type of the brand shown in the collapsed NavBar (mobile navigation), one of image | text.

color

string

light

Sets the color scheme for the top level menu items (including the Quicklink icons), one of light | dark.

fixed

boolean

true

Enables | Disables a fixed position of the top navigation bar. If a page is being scrolled down, the navigation bar remains fixed at the most top position of the page.

media_breakpoint

string

lg

Media breakpoint at which the NavBar switches between the desktop and the mobile navigation, one of sm | md | lg.

position

string

left

Position of the menu bar, one of left | right | centered.

style

string

overlay

Specifies how the NavBar is integrated with the page header, one of overlay | embedded.

translation

string

notranslate

Enables | Disables the (Google) translation of the menu texts, one of translate | notranslate. Menu items are usually not translated.

Main Menu properties

The Main Menu is the part of the NavBar where the website’s navigational menus themselves appear. The following excerpt from ~/_data/navigator_menu.yml config file is an example of how to create a main menu item. It shows a single top level item plus a dropdown list of more topics. One of which eventually has a dropdown list that includes another submenu.

The table below shows all possible configuration parameters for the Main Menu. Note that sublevel and dropdown are special configurational parameters (keywords) that mark the creation of the next level of submenus.

Table 2. Main Menu properties
Parameter Value Default Description

item

string

no default

The top level item (base menu level) in the Main Menu.

sublevel

keyword

no default

The keyword sublevel is used to build a dropdown menu that contains menu items (second menu level) or nested dropdown menus of a third or fourth menu level.

dropdown

keyword

no default

The keyword dropdown is used to build nested dropdown menus of a third or fourth level of the menu.

title

string

no default

The title string of a menu entry.

icon

string

no default

The icon used for a menu entry. The icon is given by its (MDI) icon name — no family name prefix is needed.

href

string

no default

The (string) URL is used to reference a page to be opened from the menu.

target

string

no default

The property target is used to instruct the browser to open the page referenced in a new window/tab. The only supported value for target is: _blank.

QuickLinks properties

The QuickLink area of the Navigator hosts links to common social media websites and provides access to the TopSearch (as will be described later). The following table holds all the config parameters for the Quicklink area of the Navigator.

Table 3. Quicklinks properties
Parameter Type Default Description

enabled

boolean

false

Enables | Disables the use of the Quicklinks bar.

icon_family

string

mdib

Icon font used for all icons of the Quicklinks bar.

icon_color

string

var(--md-gray-900)

Color used for the icons of the Quicklinks bar.

icon_color_hover

string

var(--md-gray-500)

Color used for the icons of the Quicklinks bar on mouse hover.

icon_size

string

mdib-2x

Size used for the icons of the Quicklinks bar.

<name>_icon

string

see defaults file

Icon of a link or action button — for example home_icon, github_icon, or site_search_icon. The icon is given by its (MDI) icon name — no family name prefix is needed. The buttons are placed within the Quicklinks bar in the order configured, from left to right.

<name>_url

string

none

Weblink (URL) of a link button — for example home_url or github_url. A link button is only displayed if a URL is configured; the value none disables the button.

<name>_action

string

see defaults file

Action of an action button — for example site_search, cookie-consent, or themeToggler. An action button opens the dialog of the related J1 module; the button is only displayed if the related module is enabled.

<name>_label

string

see defaults file

Label (tooltip) of a button — for example home_label or site_search_label. The label is shown as the title of the button and is used by screen readers.

TopSearch properties

The TopSearch element provides a collapsible search input on top of every page performing a Lunr full-text search. If enabled, a magnifier icon is displayed within the Quicklinks area at the most top position of the Navigator. Following is a table with all the possible settings for the TopSearch element.

The TopSearch is enabled with the Navigator; the search itself — the search engine, the search dialog, and all of its texts — is provided and configured by the J1 site search module (based on Lunr). The magnifier icon in the Quicklinks bar is only displayed if the site search module is enabled.

Table 4. TopSearch properties
Parameter Type Default Description

enabled

boolean

true

Enables | Disables the use of the TopSearch. If enabled (and the site search module is active), a magnifier icon is displayed in the Quicklinks bar that opens the search dialog on top of the current page.

J1 Integration

The Navigator is fully integrated in the J1 Template and is a required module of the theme — every page of a J1 site uses the Navigator to build the navigation bar at the top of the page. The template loads the module on every page, generates the HTML portions of the Main Menu and the Quicklinks from your YAML configuration at build time, and connects all menus, dropdowns, and quicklink buttons at runtime.

The content of the Main Menu is fully under your control: all menu items, submenus, and dropdowns are defined by simple YAML data — no HTML or JavaScript coding is needed. All other settings are optional and come with useful default values.

Module sources

The sources for the Navigator are stored within the asset path of the J1 Template. You’ll find the core module under /assets/theme/j1/modules/navigator:

Structure of the J1 Navigator application tree (base components)
  ├───assets
  │   ├───data
  │   │   ├───menu
  │   │   │       menu.html
  │   │   └───quicklinks
  │   │           quicklinks.html
  │   └───theme
  │       └───j1
  │           ├───adapter
  │           │   └───js
  │           │           navigator.js
  │           └───modules
  │               └───navigator
  │                   └───js
  │                           navigator.js
  └───_data
      └───modules
          │   navigator.yml
          │   navigator_menu.yml
          └───defaults
                  navigator.yml

The parts of the module have the following jobs:

navigator.js (module)

The core of the module — a JavaScript API based on the (jQuery) plugin Bootsnav. The core builds the desktop dropdown menus, switches between the desktop and the mobile navigation at a configurable breakpoint, manages sticky and transparent navigation bars on scroll, and connects the action buttons of the Quicklinks with the matching J1 modules.

navigator.js (adapter)

The J1 adapter for the Navigator. It reads the YAML settings, loads the generated HTML portions of the Main Menu and the Quicklinks into the page (via AJAX), initializes the core module, and applies all configured colors and styles to the navigation bar.

menu.html

The HTML data file of the Main Menu (desktop). The file is generated at build time from your menu configuration navigator_menu.yml and is loaded dynamically into the navigation bar by the adapter.

quicklinks.html

The HTML data file of the Quicklinks bar. The file is generated at build time from the nav_quicklinks settings and is loaded dynamically into the navigation bar by the adapter. A quicklink icon is only generated if the related module (for example the site search or the theme toggler) is enabled.

navigator.yml (two files)

The YAML configuration of the module. The file under _data/modules/defaults contains the default settings, the file under _data/modules contains your user settings. All sub-modules except the Main Menu are configured here.

navigator_menu.yml

The YAML configuration of the Main Menu. All menu items, submenus, and dropdowns of the desktop and the mobile navigation are defined in this file.

The core module and the adapter use the same filename navigator.js. When working on the sources, always check the path of a file to be sure which of the two files you are editing.

Configuration

The Navigator is configured by three YAML files. The default settings live in _data/modules/defaults/navigator.yml — this file documents all available options and should not be changed. Your personal user settings live in _data/modules/navigator.yml. At build time, both files are merged: every option you set in the user file overwrites the default value. The third file, _data/modules/navigator_menu.yml, contains the content of the Main Menu.

By default, the Navigator and all of its sub-modules are disabled in the defaults file. To activate the module, set the option enabled to true for the module itself and for every sub-module you want to use in your user configuration:

settings:
  enabled: true
  nav_bar:
    enabled: true
  nav_menu:
    enabled: true
  nav_quicklinks:
    enabled: true
  nav_topsearch:
    enabled: true
  nav_mmenu:
    enabled: true

Initialization

The Navigator is initialized automatically on every page load by the J1 adapter — you do not need to add any code to your pages. The adapter runs the following steps:

  1. Read the merged YAML configuration (defaults plus user settings) of all sub-modules.

  2. Load the generated HTML portions of the Quicklinks and the Main Menu (the data files quicklinks.html and menu.html) into the navigation bar via AJAX.

  3. Wait until all HTML portions are loaded, then initialize the Navigator core. The core builds the dropdown menus, decides between the desktop and the mobile navigation based on the configured media breakpoint, and connects all quicklink action buttons with their modules.

  4. Apply the configured colors and styles (for example the background colors of the navigation bar) as CSS to the page.

  5. Register a resize handler: if the size of the browser window changes, the Navigator switches between the desktop and the mobile navigation automatically.

Default settings

The general (default) settings of the Navigator define the icon font used by all navigation components and the primary color of the navigation system. The icons of the J1 Template are taken from the Material Design Icons (MDI) font; colors are given as CSS variables of the Material Design color palette.

Default settings
# ------------------------------------------------------------------------------
# Default settings
#
enabled:                              true
icon_family:                          mdib
icon_style:                           mdib
icon_color:                           mdib-grey
icon_size:                            mdib-sm
nav_primary_color:                    var(--md-blue)

MainMenu settings

The content of the Main Menu is defined in the configuration file _data/modules/navigator_menu.yml as a simple YAML list. A menu is built of top level items (keyword item); each top level item opens a dropdown list of menu entries (keyword sublevel). A menu entry either links to a page (property href) or opens a nested dropdown menu of a third or fourth menu level (keyword dropdown).

The following excerpt shows a single top level item Learn with a dropdown list of entries. One of the entries (Tutorials) opens a nested dropdown that includes another submenu:

Main Menu settings (excerpt)
# ------------------------------------------------------------------------------
# Menu LEARN
#
- item:                                 Learn
  sublevel:
    - title:                            Where to go
      href:                             /pages/public/learn/where_to_go/
      icon:                             foot-print
    # --------------------------------------------------------------------------
    # Tutorials
    #
    - title:                            Tutorials
      icon:                             wizard-hat
      dropdown:
        - title:                        Rocketstart
          href:                         /pages/public/learn/rocketstart/
          icon:                         rocket-launch
        - title:                        Jekyll In A Day
          icon:                         alpha-j-box
          dropdown:
            - title:                    Meet & Greet
              href:                     /pages/public/learn/kickstart/web_in_a_day/meet_and_greet/
              icon:                     human-queue
            - title:                    Development System
              href:                     /pages/public/learn/kickstart/web_in_a_day/dev_system/
              icon:                     hammer-wrench
            - title:                    Creating content
              href:                     /pages/public/learn/kickstart/web_in_a_day/create_content/
              icon:                     file-document-edit

NavigationBar settings

The Navigation Bar is the frame of the whole navigation system: the bar at the top of every page that hosts the brand (logo), the Main Menu, and the Quicklinks. The settings of the nav_bar section define the general look and feel of the bar: the position of the brand and the menu, the media breakpoint at which the bar switches to the mobile navigation, and the colors of the bar in its different states (full, collapsed, and scrolled).

The nav_menu section configures the desktop version of the Main Menu — mainly the dropdown menus: their style, colors, animation, and the delay used to open a dropdown on hover. The nav_mmenu section configures the mobile version of the Main Menu (the drawer menus), which is managed by the separate MMenu module.

Navigation Bar settings
# ------------------------------------------------------------------------------
# NavBar
#
nav_bar:
  enabled:                            false
  translation:                        notranslate
  container_id:                       navigator_nav_navbar
  media_breakpoint:                   lg
  brand_position:                     right
  brand_type:                         image
  brand_type_collapsed:               text
  fixed:                              true
  style:                              overlay
  color:                              light
  position:                           left
  bottom_line_height:                 1
  bottom_line_color:                  var(--md-gray-300)
  background_color_full:              rgba(255, 255, 255, 0.8)
  background_color_scrolled:          var(--md-blue)
# ------------------------------------------------------------------------------
# NavMenu (Mobile)
#
nav_mmenu:
  enabled:                            false
  nav_main_menu:                      navigator_nav_menu
  nav_quicklinks:                     quicklinks
  mmenu_plugin:
    node:                             "null"
    mediaQuery:                       all
    max_width:                        100000
  mmenu_navigator:
    selected:                         Selected
    slidingSubmenus:                  true
    title:                            Navigation
    theme:                            dark
  mmenu_drawer:
    position:                         right
# ------------------------------------------------------------------------------
# NavMenu (Desktop)
#
nav_menu:
  enabled:                            false
  xhr_container_id:                   navigator_nav_menu
  xhr_data_element:                   desktop_menu
  xhr_data_path:                      /assets/data/menu/index.html
  raised_level:                       5
  delay_menu_open:                    200                                     # milli seconds
  max_height:                         600                                     # px
  menu_font_size:                     larger
  megamenu_font_size:                 small
  icon_family:                        mdib
  icon_style:                         mdib
  icon_color:                         var(--md-gray-500)
  icon_size:                          mdib-sm
  menu_item_color:                    var(--md-gray-900)
  menu_item_color_hover:              var(--md-gray-300)
  dropdown_style:                     raised
  dropdown_color:                     var(--md-blue)
  dropdown_left:                      12                                      # px
  dropdown_item_style:                flat
  dropdown_animate:                   false
  dropdown_animate_in:                slideInDown
  dropdown_animate_out:               fadeOutDown
  dropdown_animate_duration:          .75                                     # seconds
  dropdown_item_min_width:            15                                      # rem
  dropdown_menu_max_height:           35                                      # rem
  dropdown_font_size:                 small
  dropdown_padding_x:                 18                                      # rem
  dropdown_padding_y:                 10                                      # px
  dropdown_item_color:                var(--md-gray-900)
  dropdown_border_color:              var(--md-blue)
  dropdown_border_top:                0                                       # px
  dropdown_border_radius:             2                                       # px
  dropdown_background_color_hover:    var(--md-gray-300)
  dropdown_background_color_active:   var(--md-gray-500)

Quicklink settings

The Quicklinks bar hosts two types of buttons. Link buttons open external websites — for example your GitHub project or a social media site. A link button is configured by an icon, a URL, and a label; the button is only displayed if a URL is configured (the value none disables a button). Action buttons open a dialog of another J1 module — for example the site search, the Cookie Consent dialog, or the Theme Toggler. An action button is displayed automatically if the related module is enabled.

Quicklinks settings (excerpt)
# ------------------------------------------------------------------------------
# NavQuicklinks
#
nav_quicklinks:
  enabled:                            false
  xhr_container_id:                   navigator_nav_quicklinks
  xhr_data_element:                   quicklinks
  xhr_data_path:                      /assets/data/quicklinks/index.html
  icon_family:                        mdib
  icon_color:                         var(--md-gray-900)
  icon_color_hover:                   var(--md-gray-500)
  icon_size:                          mdib-2x
  # Link buttons
  # --------------------------------------------------------------------------
  home_icon:                          home-variant
  home_url:                           /                                       # URL|none
  home_label:                         Home
  github_icon:                        github-circle
  github_url:                         none
  github_label:                       Github
  # Action buttons
  # --------------------------------------------------------------------------
  site_search_icon:                   magnify
  site_search_action:                 site_search
  site_search_label:                  Fulltext Search
  cookies_icon:                       cookie
  cookies_action:                     cookie-consent
  cookies_label:                      Cookie Consent
  theme_toggler_icon:                 lightbulb-outline
  theme_toggler_action:               themeToggler
  theme_toggler_label:                Theme Toggler

TopSearch settings

The TopSearch element offers a full-text search over all pages of your site. The search itself is powered by the J1 site search (based on the search engine Lunr); the Navigator provides the access to the search: if the site search is enabled, a magnifier icon () is displayed in the Quicklinks bar that opens the search dialog on top of the current page.

In the Navigator configuration, the TopSearch only needs to be enabled. All settings of the search itself — for example the placeholder text of the input field or the headings of the result window — are configured with the site search module:

TopSearch settings
# ------------------------------------------------------------------------------
# NavTopsearch
#
nav_topsearch:
  enabled:                            true

Programming Interface

The Navigator core is implemented as a J1 API module registered as j1.api.navigator. The implementation is based on the (jQuery) plugin Bootsnav, a multi-purpose navigation builder for the Bootstrap Framework. In the J1 Template, you normally do not call the core module yourself — the J1 adapter (j1.adapter.navigator) does all the work for you: it loads the generated HTML portions of the menus, passes the merged YAML configuration to the core, and initializes the module on every page load. The sections below describe the core interface for users who want to understand the integration in detail.

The core module offers the following features:

Responsive navigation

The Navigator switches automatically between the desktop navigation (the Main Menu with dropdowns) and the mobile navigation (the drawer menus of the MMenu module) at a configurable media breakpoint. The navigation is re-evaluated whenever the size of the browser window changes.

Multi-level dropdown menus

Dropdown menus of the desktop navigation open on hover with a configurable delay — this prevents menus from flickering open while the mouse only passes by. Nested dropdowns of a third and fourth menu level are supported; very long dropdowns are made scrollable automatically.

Sticky and transparent navigation bars

The navigation bar can stay fixed at the top of the page while scrolling. A transparent bar (style overlay) changes its background color as soon as the page is scrolled down, so the menu stays readable on any content.

Quicklink actions

The core connects the action buttons of the Quicklinks bar with their J1 modules: the site search dialog, the Cookie Consent dialog, the Translator dialog, and the Speak2Me dialog are opened by a simple click on the matching icon.

In-page smooth scrolling

Click events on badge elements (for example the tag badges of blog posts) are bound to a smooth scroll animation that moves the page to the linked section instead of jumping there.

Initialization

In the J1 Template, all JavaScript files of the Navigator are loaded by the resource management of the template — no manual script tags are needed. The adapter function j1.adapter.navigator.init is registered as the initializer in the resource configuration (see section Resource Settings) and runs automatically on every page load.

The adapter loads the HTML portions of the Quicklinks and the Main Menu first. As soon as all portions are available in the page, the adapter initializes the core module by passing the merged YAML configuration:

// Initialize the Navigator core (called by the adapter)
j1.api.navigator.init(navDefaults, navMenuOptions);

The parameters have the following meaning:

navDefaults

The complete (merged) configuration of the Navigator — all sub-module sections of the configuration files, defaults overloaded by the user settings.

navMenuOptions

The (merged) configuration of the desktop Main Menu — the nav_menu section of the configuration files.

Methods

All methods of the core module are called on the API object j1.api.navigator. The methods are used by the J1 adapter — for your own code, they are useful if the layout of a page is changed dynamically and the navigation needs to be re-evaluated.

init

Initializes the Navigator core. The method creates a wrapper element for the navigation system, builds the dropdown menus for the current window size (method manageDropdownMenu), activates sticky navigation bars (method navbarSticky), and registers all event handlers of the navigation (method eventHandler). When finished, the core reports the state core_initialized to the adapter.

j1.api.navigator.init(navDefaults, navMenuOptions);

eventHandler

Registers all event handlers of the navigation system: the click handlers of the quicklink action buttons (site search, Cookie Consent, Translator, and Speak2Me), the smooth scroll handlers for badge elements, and the scroll handlers that change the background of transparent and sticky navigation bars. The method is called once by init — calling it a second time would register all handlers twice.

j1.api.navigator.eventHandler(navDefaults);

manageDropdownMenu

Builds the menus of the navigation bar for the current window size. Based on the configured media breakpoint (option nav_bar.media_breakpoint, one of sm|md|lg), the method decides between the two navigation modes:

Mobile

If the window is smaller than the breakpoint, the desktop menu is collapsed and the Quicklinks bar is shown. The mobile menu itself (the drawers) is managed by the separate MMenu module.

Desktop

If the window is larger than the breakpoint, the desktop menu is shown and all dropdown menus are activated: the dropdowns open on hover, delayed by the configured time (option nav_menu.delay_menu_open), and very long dropdown lists are made scrollable.

The J1 adapter calls this method on every resize of the browser window to switch between the two modes:

j1.api.navigator.manageDropdownMenu(navDefaults, navMenuOptions);

navbarSticky

Activates the sticky mode of the navigation bar. If the bar is configured fixed, the method measures the height of the bar, reserves the needed space in the page, and registers a scroll handler that keeps the bar at the most top position of the window while the page is scrolled down.

j1.api.navigator.navbarSticky();

updateSidebar

Updates the user data displayed in the sidebar drawer (see the boxes of type site_info and user_info in the nav_mmenu configuration). The method resolves all macro placeholders (the values starting with ??, for example ??theme-name) to their current values.

j1.api.navigator.updateSidebar(user_data);

Messages

The Navigator uses the J1 message system for the communication between the core module and the adapter. When the core initialization is finished, the core sends a state message to the adapter:

message.type    = 'state';
message.action  = 'core_initialized';
message.text    = 'navigator core initialized';
j1.sendMessage('j1.navigator.core', 'j1.adapter.navigator', message);

The adapter waits for this message before it applies the configured colors and styles and finishes the module initialization.

Callbacks

No public callbacks or events available.

The Navigator registers a number of internal event handlers (for example on window resize and page scroll) to keep the navigation in sync with the browser window. These handlers are used by the module only and are not a public callback interface.

Examples

Re-evaluate the navigation after a dynamic layout change (for example if the size of the content area was changed by your own code):

// Rebuild the menus for the current window size
j1.api.navigator.manageDropdownMenu(
  j1.adapter.navigator.navDefaults,
  j1.adapter.navigator.navMenuOptions
);
// Re-activate sticky navigation bars
j1.api.navigator.navbarSticky();