Configuration (Web)

Now with alphaTab being part of your project it is time for customization. alphaTab has quite a list of settings, events and API methods to interact with.

Setup

On the installation guide you already saw that alphaTab initializes itself to a given div element.

Simply create a div container where you want alphaTab to be located on your page. alphaTab will dynamically resize to the available width of the div when using the page layout. If you prefer a fixed layout simply set a fixed width on the div via CSS and no resizes to alphaTab will happen either.

If jQuery is detected on the page you can use the jQuery plugin to interact with alphaTab. Otherwise alphaTab is initailized using a special API object. The main namespace alphaTab contains every class and enum exposed by the API. The main api is the alphaTab.AlphaTabApi class:

<div id="alphaTab"></div>

const element = document.getElementById('alphaTab');
const api = new alphaTab.AlphaTabApi(element);

Settings

There are 2 main ways to initialize alphaTab: either via a settings object or via data attributes. Depending on the technologies used in your project either the direct code initialization or the data attributes might be easier to use.

The data attributes might be more suitable for server side rendering technologies where settings are provided from a backend infrastructure during page rendering. When printing the main alphaTab div element to the DOM you can pass on any settings you might want to have.

When using client side frontend frameworks like Angular, React or even plain JavaScript it might be more suitable to initialize alphaTab via a settings object.

Both systems can be combined while the data attributes will overrule the JSON settings. The full list of settings can be found in the API Reference.

Settings Object

The settings object is passed to the constructor of the API object as second parameter:

const api = new alphaTab.AlphaTabApi(element, {
    // any settings go here    
});

jQuery

AlphaTab is initialized via the $.alphaTab() plugin. The first parameter is the settings object and the API object will be returned.

const api = $('#alphaTab').alphaTab();

Data Attributes

Data Attributes will only allow configuration, you still need to manually initailize alphaTab with one of the other variants. But the settings parameter can be simply left out.

<div id="alphaTab" data-layout-mode="horizontal"></div>

const api = new alphaTab.AlphaTabApi(element);

Events

Events of alphaTab can be either subscribed on the API object directly, or via the DOM element to which alphaTab is attached. Please refer to the API Reference to find a full list of events available.

API Object

Each event has an .on(handler) and .off(handler) function to subscribe or unsubscribe.

const api = new alphaTab.AlphaTabApi(element);
api.scoreLoaded.on( (score) => {
    console.log('Score was loaded!', score);
});

DOM events

DOM events are namespaced with a alphaTab. prefix and can be subscribed either via addEventListener(eventName, handler) or via jQuerys .on(eventName, handler). To access potential parameters that are passed along the event, you will need to access the event details.

For raw DOM events, the info object will be contained in the detail property of the DOM event.

element.addEventListener('alphaTab.scoreLoaded', (e) => {
    console.log('Score was loaded!', e.detail);
});

For jQuery events the object related to the event will be the second parameter:

$(element).on('alphaTab.scoreLoaded', (e, score) => {
    console.log('Score was loaded!', score);
});

API

The main interaction with alphaTab happens through the API object or via jQuery plugin. Simply use any available API to get/set details or trigger actions.

API Object

const api = new alphaTab.AlphaTabApi(element);
api.tex('\title "Hello AlphaTab" . 1.1*4')

jQuery API

$(element).alphaTab('tex', '\title "Hello AlphaTab" . 1.1*4')