pwix:tabbed

What is it ?

A Blaze component which provides a consistent tabbed display.

The tabbed navs and panes are Bootstrap-based.

Here, 'consistent' means that all panes will have the same height (respectively the same width) regarding of their content.

Installation

This Meteor package is installable with the usual command:

    meteor add pwix:tabbed

Usage

In your .html template:

1    {{> Tabbed name="myInstance" }}

In your .js code:

1    Template.my_template.onRendered( function(){
2        const tabbed = new Tabbed.Instance( 'myName', {
3            ...
4        });
5    });

Provides

Tabbed

The exported Tabbed global object provides following items:

Classes

Tabbed.Instance()

A class to be instanciated for each displayed Tabbed component.

Each instance must be uniquely named, and will be used to define and interact with the corresponding Tabbed Blaze component.

Instanciation

The class can be instanciated as:

1    new Tabbed.Instance( this<BlazeInstance> [, parms<ReactiveVar> ] ) : Tabbed.Instance;

with:

• this: the current Blaze.TemplateInstance instance

• parms: a mandatory ReactiveVar which contains an options object with following keys:

  • name

    The name which uniquely identifies this Tabbed instance at runtime

    This name is mandatory, and let us uniquely associate the Tabbed.Instance instance with the Blaze component view. This is the mechanism which let instance methods interact with the UI. It is non-reactively read from the template data context at creation time.

  • dataContext

    An optional common data context to be passed to all templates.

  • activateLastTab

    Whether to keep the last active pane in local storage, defaulting to true.

  • navClasses

    Classes to be added to each ul.nav element.

  • navItemClasses

    Classes to be added to each li.nav-item element.

  • navLinkClasses

    Classes to be added to each button.nav-link element.

  • navPosition

    Defines where the navs are relatively to the panes.

    May be one the following values:

    • Tabbed.C.Position.TOP
    • Tabbed.C.Position.RIGHT
    • Tabbed.C.Position.BOTTOM
    • Tabbed.C.Position.LEFT

    Defaults to Tabbed.C.Position.TOP.

  • paneClasses

    Classes to be added to each tab-pane element.

  • paneSubTemplate

    The name of a Blaze template to be added to the bottom of the panes.

  • paneSubData

    A data context object to be passed to the above paneSubTemplate sub-template.

  • tabs

    An optional array with the initial list of tabs.

    Each tab is defined with an object with following keys:

    • name

      The optional name of the tab.

      Defaults to paneTemplate name.

      Though all randomly generated names can be later be got by the application, this may be rather cumbersome. We strongly suggest to attribute a name to all tabs you want explicitely manage.

    • enabled

      Whether this tab is enabled, defaulting to true.

    • navLabel

      The optional nav label, as a HTML string.

      Defaults to the tab name.

    • navAttributes

      An optional object which define attributes to be added to the nav-link element where each attribute is expected to be defined as { name: value }.

    • navTemplate

      The name of an optional template to be displayed as the nav content (besides of the label if one is specified).

    • navData

      An optional data context specific to be passed to the above navTemplate, defaulting to Tabbed data context.

    • navItemClasses

      Classes to be added to this li.nav-item element.

    • navLinkClasses

      Classes to be added to this button.nav-link element.

    • paneTemplate

      The name of the pane template name.

      Defaults to none.

    • paneData

      An optional data context to be passed to the above paneTemplate.

    Tabbed generates a unique random identifier for each tab, which is derived both in the nav and pane parts.

All above parameters can be specified either with the expected value, or with a function which returns such a value.

Tabbed.Instance.get( parm )

parm is a dotted-string with following structure:

• the parameter to be set, or tab to address a particular tab, or tabs to address all the tabs as a whole

• maybe the name of the tab

• maybe the parameter to be set for this tab.

Tabbed.Instance.set( parm, value )

Functions

Tabbed.configure()

See below.

A reactive data source.

Tabbed.i18n.namespace()

Returns the i18n namespace used by the package. Used to add translations at runtime.

Blaze components

Tabbed

A consistent tabbed Blaze component.

It accepts following parameters:

• name

  An optional name

  If the name actually addresses an already instanciated Tabbed.Instance, then all parameters are taken from the named instance, and other parameters passed in the component data context are just ignored.

If the name doesn't address any Tabbed.Instance, or the component is not named, then all parameters accepted at Tabbed.Instance class instanciation can be provided as the component data context.

Data context

This Tabbed component increases the data context passed to navTemplate's and paneTemplate's with datas:

• tabbedId: the identifier of the 'Tabbed' component
• tabbedTabId: the identifier of each tab, same whether we display a nav-link or a tab-pane

Events

The component handles following events:

• tabbed-do-activate, data={ tabbedId, index } ask to activate the tab by its index
• tabbed-do-activate, data={ tabbedId, label } ask to activate the tab by its current nav label
• tabbed-do-activate, data={ tabbedId, name } ask to activate the tab by its name
• tabbed-do-activate, data={ tabbedId, attribute } ask to activate the tab by the specified nav attribute
• tabbed-do-activate-same, data={ tabbedId } ask to re-send the activation event on the same tab
• tabbed-do-enable, data={ tabbedId, index, enabled } ask to enable/disable the tab by its index
• tabbed-do-enable, data={ tabbedId, label, enabled } ask to enable/disable the tab by its current nav label
• tabbed-do-enable, data={ tabbedId, name, enabled } ask to enable/disable the tab by its name
• tabbed-do-enable, data={ tabbedId, attribute, enabled } ask to enable/disable the tab by the specified nav attribute where 'tabbed' is expected to be the internal identifier of this tabbed template

The component triggers following events:

• on itself (and bubble up to the parents)

  • tabbed-rendered, data={ tabbedId, tabbedName, $tabbed } when the Tabbed component has been rendered

  • tabbed-changed, data={ tabbedId, tabbedName, $tabbed } when the tabs population has changed

• on every .tab-pane first child, which happens to be the topmost component of the pane template:

  • tabbed-pane-to-hide, data={ tabbedId, tabbedName, tab:<tab_object>, next:<tab_object> } when about to leave a tab

  • tabbed-pane-to-show, data={ tabbedId, tabbedName, tab:<tab_object>, prev:<tab_object> } when a new tab is about to be shown

  • tabbed-pane-hidden, data={ tabbedId, tabbedName, tab:<tab_object>, next:<tab_object> } when a tab has left

  • tabbed-pane-shown, data={ tabbedId, tabbedName, tab:<tab_object>, prev:<tab_object> } when a tab has been shown

Identifiers management

We dynamically allocate random identifiers for:

• the Tabbed parent component itself, advertized as 'data-tabbed-id' in the DOM, and as tabbedId in events and children data contexts

• each tab, advertized as 'data-tabbed-tab-id' in the DOM, and as tabbedTabId in children data contexts.

Dynamically removing tabs

When dynamically removing tabs, because you have provided less tabs in the Tabbed data context, you should be conscious that Blaze introduces somes asynchronicities, and that - as such - the to-be-removed tab helpers will still be re-run before the view be actually destroyed.

When using such a feature, you should take care of protecting your code by checking that the tabs are still alive.

See, for example, pwix:validity.

Configuration

The package's behavior can be configured through a call to the Tabbed.configure() method, with just a single javascript object argument, which itself should only contains the options you want override.

Known configuration options are:

• verbosity

  Define the expected verbosity level.

  The accepted value can be any or-ed combination of following:

  • Tabbed.C.Verbose.NONE

    Do not display any trace log to the console

  • Tabbed.C.Verbose.CONFIGURE

    Trace Tabbed.configure() calls and their result

  • Tabbed.C.Verbose.FUNCTIONS

    Trace all functions calls

  Defaults to Tabbed.C.Verbose.CONFIGURE.

Please note that Tabbed.configure() method should be called in the same terms both in client and server sides.

Remind too that Meteor packages are instanciated at application level. They are so only configurable once, or, in other words, only one instance has to be or can be configured. Additionnal calls to Tabbed.configure() will just override the previous one. You have been warned: only the application should configure a package.

Tabbed.configure() is a reactive data source.

NPM peer dependencies

Starting with v 0.1.0, and in accordance with advices from the Meteor Guide, we no more hardcode NPM dependencies in the Npm.depends clause of the package.js.

Instead we check npm versions of installed packages at runtime, on server startup, in development environment.

Dependencies as of v 1.3.0:

1    'lodash': '^4.17.0'

Each of these dependencies should be installed at application level:

    meteor npm install <package> --save

Translations

New and updated translations are willingly accepted, and more than welcome. Just be kind enough to submit a PR on the Github repository.

Cookies and comparable technologies

On named tabs, pwix:tabbed uses sessionStorage to record the last activated tab.

Because this is dynamically done on a per tabbed display unit basis, and only if this later is named, the package doesn't advertize of this use, relying on the caller own declaration.

Issues & help

In case of support or error, please report your issue request to our Issues tracker.

---

P. Wieser

• Last updated on 2024, Sep. 13th