Custom main menu subitems - czcorpus/kontext GitHub Wiki

KonText recognizes the following sub-menu items:

These are controlled by KonText core application and cannot be changed via a plug-in. There are two sub-types:

1. items with an action and args - where action specifies KonText's controller action (e.g. first_form, view) and args are respective URL arguments. These items are transformed into common HTML links (i.e. user clicks an item and browser navigates him to a new page within KonText)
2. items with a message and args - where message specifies a Flux message to be dispatched once the item is clicked and args are its respective arguments.

These are configured by an administrator of a concrete KonText installation. These custom items are always appended behind core items, i.e. it is not possible to add a custom item to a specified position within a menu item box (e.g. for 'Corpora', something like 'Available corpora', 'My custom item', 'My subcorpora', etc. cannot be done). There are two sub-types:

1. static items are just URLs with localized text label
2. dynamic items are server defined "anchors" with a respective client-side code which binds custom labels and event handlers.

The functionality is in general handled by the menu_items plug-in. The following text describes use of its default implementation default_menu_items.

First of all, a proper entry must be defined within conf/config.xml along with a JSON file containing custom menu items definition (at least a file containing an empty JSON object {} must be defined.

<kontext>
...
  <plugins>
    ...
      <menu_items>
        <module>default_menu_items</module>
        <data_path extension-by="default">/path/to/kontext/install/dir/conf/main-menu.json</data_path>
      </menu_items>
    ...
  </plugins>
...
</kontext>

# Custom static items

Static items are useful for adding external links (e.g. an organization homepage, discussion/support forum etc.).

E.g. to add a custom item with two translations (English and Czech) to the "help" section:

{
  "menu-help": [
    {
      "type": "static",
      "data": {
        "en_US": {
          "url": "https://wiki.korpus.cz/doku.php/manualy:kontext:index",
          "label": "User manual (in Czech)",
          "openInBlank": true
        },
        "cs_CZ": {
          "url": "https://wiki.korpus.cz/doku.php/manualy:kontext:index",
          "label": "Uživatelská příručka",
          "openInBlank": true
        }
      }
    }
  ]
}

# Custom dynamic items

Dynamic items are suitable for cases when the item's functionality is based on current UI Flux stores state (i.e. it cannot be predefined as a bunch of constant arguments) and/or requires more complex behavior.

To define such an item, an "anchor" server item must be defined first. It is similar to the static items above, but there is just an ident and no URL, label, or arguments. This ident is then used by client-side code to refer to the item.

Please note that while core sub-menu items are identified by both menu section identifier (e.g. "menu-new-query", "menu-concordance") and sub-menu item identifier (e.g. "new-query", "shuffle"), custom dynamic items are expected to have an unique sub-menu item identifier (i.e. there is no menu section specification; see below).

{
  "menu-corpora": [
    {
      "type": "dynamic",
      "ident": "ucnk-get-a-similar-corpus"
    }
  ]
}

class SomePlugin {
 
  private pluginApi:Kontext.PluginApi;

  // constructor omitted
  
  init():void {
    this.pluginApi.getStores().mainMenuStore.bindDynamicItem(
      'ucnk-get-a-similar-corpus',
      this.pluginApi.translate('some_plugin__find_a_similar_corpus_last_srch'),
      () => {
         // do stuff here, typically something like
           this.pluginApi.dispatcher().dispatch({
             actionType: 'MY_CUSTOM_FLUX_ACTION',
             props: { /* ... (dynamic) action properties ... */ }
           });
      }
    );
  }
}