Custom Pages

Plugins can provide custom pages to be added to the ntopng menu bar. They are fully customizable pages, which can define they own style and functionalities.

The custom pages are defined into the ./web_gui subdirectory of the plugin. Let’s analyze the example plugin as an example.

Custom Pages Definition

The file menu.lua is used to define the custom menu entry:

return {
  label = "example.custom_menu_entry",
  script = "example_page.lua",
  sort_order = -1,
  menu_entry = {key = "example_plugin", i18n_title = "Example Page", section = "system_stats"},
  is_shown = function()
    return(true)
  end,
}

The Lua script returns a table with the following structure:

  • label: A localized message for the label of the menu entry. The localization strings can be supplied by the plugin as explained in the Localization section.
  • script: the unique file name of the script to be visited when the user selects the menu entry. The script must be located into the same directory of menu.lua.
  • sort_order: The sort order in the menu. Entries with higher sort_order are shown before entries with lower sort order.
  • menu_entry: Contains information about the menu entry. In particular, the following elements are required: key defines a unique key for this menu entry, i18n_title contains a localized title for the page, section indicates to which menu section the entry should be attached (for now only “system_stats” is supported). Check out menu_entries in page_utils.lua for more details.
  • is_shown: can be used to programmatically hide a menu entry. If defined, it must be a Lua function which returns true when the entry should be shown, false otherwise.

The actual page is implemented in the Lua script referenced in the script parameter above.

Page Skeleton

As explained above, any Lua script can be linked to the ntopng menu. In order to provide a consistent look, custom pages can use the following template:

-- Set up the modules path
local dirs = ntop.getDirs()
package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path

-- Load some essential modules
require "lua_utils"
local page_utils = require("page_utils")

-- Setup up the page header. The "example_plugin" key below is taken
-- from the menu_entry "key" as defined in menu.lua.
sendHTTPContentTypeHeader('text/html')
page_utils.set_active_menu_entry(page_utils.menu_entries.example_plugin)
dofile(dirs.installdir .. "/scripts/lua/inc/menu.lua")

local subpage = _GET["page"] or "overview"
local title = i18n("example.custom_page_title")
local base_url = plugins_utils.getUrl("example_page.lua") .. "?ifid=" .. getInterfaceId(ifname)

-- Populate the navbar with subpages
page_utils.print_navbar(title, base_url, {
   {
      active = (subpage == "overview"),
      page_name = "overview",
      label = "<i class=\"fas fa-lg fa-home\"></i>",
   },
})

-- Subpages logic here
if(subpage == "overview") then
  -- "overview" subpage logic here
end

dofile(dirs.installdir .. "/scripts/lua/inc/footer.lua")

Once the plugin is loaded, ntopng will make the above page available through its web server. The URL for a given custom page can be obtained by using the plugins_utils.getUrl(script) Lua function.