Javascript API

API concepts

Since 3.16.0:

1. new API designed to be modular around the new qTranx entry point with a qTranx.hooks sub-module for multi-lingual hooks.
2. new event handler based on WordPress action framework via wp.hooks. See wordpress/hooks.

Yes that's two "hooks" interfaces but they serve different purposes, one for qTranslate multi-lingual content and the other is for integration of events in WordPress.

Attention! The legacy QTX API is supported with many functions deprecated in 3.16.0. They will be removed in 4.0.0. See also Javascript-Migration-guide

qTranx module

Technically it's bundled as ES module but it's simply a Javascript global object when used externally. We want this entry point to be unique and hold all of the API. The sources are located in js/core and bundled in the dist folder with webpack.

For more advanced usage see Troubleshooting#debugging-javascript. It is possible to produce your own bundle locally with custom logging after changing JS code or even a developer build with a file watcher and breakpoints in plain source. You don't need to know webpack or npm, it is very easy to use once you are familiar with the setup and how to run the commands via package.json.

qTranx.config

No one should use qTranslateConfig directly, it's produced from the PHP server and it's only meant for internal usage.
The new config object is self-documented to provide a stable API independently of PHP. See js/core/config/index.js. Auto-generated doc might follow.

qTranx.hooks

This module contains the functions to manipulate multi-lingual (such as content & display hooks) and LSB (Language Switching Buttons).
This replaces the QTX object but its API is unchanged here except deprecations.
[TODO] Complete documentation for hooks. For now see js/core/hooks/handler.js. Main functions:

• addContentHook
• addDisplayHook
• getActiveLanguage
• ...

qTranx.ml

New module for multi-language functions to parse ML tokens

• splitLangs
• splitTokens
• parseTokens

WP hooks

This replaces the qtxLoadAdmin:<page> events triggered with jQuery and the complicated switch callbacks that were handled in QTX.

New WP actions triggered by qTranx.hooks:

• qtranx.load: when qTranx.hooks is ready to use for multi-language content
• qtranx.languageSwitch (langTo, langFrom): after a language switch
• qtranx.languageSwitchPre (langTo, langFrom): before a language switch

Subscribers should register their action callbacks to wp.hooks. See wordpress/hooks.

Note: the WP actions are string IDs intentionally lower-case as qtranx.action where qtranx is a pseudo-namespace for the WP hooks, unlike the qTranx ES module named with a JS camelCase convention. This also makes it easier to find the two different usages in the code.

Example for a single usage (*)

wp.hooks.addAction('qtranx.load', '<my-org/my-plugin/my-function>', function () {
    qTranx.hooks.addContentHook( ... );
});

The second argument called "namespace" in WP hooks is just a string identifier so anonymous functions can also be removed. Therefore it should be unique to every function and made specific to your plugin to avoid collisions.

(*) You don't need to check the active page if your script is associated to a single page. Only if the script is shared for multiple page i18n entries you may want to create the hook conditionally. In that case the function qTranx.config.isPageActive('pageId') can be used if multiple pages are loaded in the same script.

if (qTranx.config.isPageActive('post'))
   wp.hooks.addAction('qtranx.load', <my-org/my-plugin/my-function-post>, function() { // my-loader-for-post...
if (qTranx.config.isPageActive('another-post-type'))
   wp.hooks.addAction('qtranx.load', <my-namespace-another-post-type>, function() { // my-loader-for-another-post-type>

Example: js/core/pages

Full user example

A complete example with WP actions and qTranx API usage can be found in the internal ACF module js/acf. See loader.js and switch.js.