Custom Javascript

The configuration key js-exec provides an opportunity to customize the Javascript functionalities on admin pages. Scripts defined via js-exec run after the qTranslate-XT script. See below for conditional triggering with events.

Custom scripts can also be enqueued without using js-exec. In that case, it is advised to add a dependency to the qtranslate-admin-js handle.

An object instance of class qTranslateX (qTranslateConfig.js.qtx) holds and maintain all Language Switching Buttons (LSB) and all multilingual fields hooked. When an LSB is pressed, the current content of the multilingual fields is stashed away into an internal storage, and the values for new language are fetched from internal storage and applied. You may supply a code to execute before and/or after the language switch is executed on each LSB click.

API

Disclaimer: this description is possibly obsolete, to be updated. Check the functions in the JS code documented as "Designed as interface for other plugin integration."

Below is the list of provided java interface functions:

• getLanguages() – returns an array keyed by two-letter language code. Example of usage:

  var langs = getLanguages();
  for(var lang_code in langs) {
  var lang_conf = langs[lang_code];
  // variables available:
  //lang_conf.name
  //lang_conf.flag
  //lang_conf.locale
  // and may be more properties later
  }
  

• isLanguageEnabled(lang) – return true if two-letter code ‘lang’ defines an enabled language.

• getFlagLocation() – returns URL to folder with flag images.

• addLanguageSwitchBeforeListener(func) – the function passed will be called when user presses one of the Language Switching Buttons before the content of all fields hooked is replaced with an appropriate language. Two arguments are supplied:

  • two-letter language code of currently active language from which the edit language is being switched.
  • the language code to which the edit language is being switched.

  The value of “this” is set to the only global instance of qTranslateX object.

• addLanguageSwitchAfterListener(func) – the function passed will be called when user presses one of the Language Switching Buttons after the content of all fields hooked is replaced with an appropriate language. Two arguments are supplied:

  • two-letter language code of active language to which the edit language is already switched.
  • the language code from which the edit language is being switched.

  The value of “this” is set to the only global instance of qTranslateX object.

• enableLanguageSwitchingButtons(on)  – show/hide all the Language Switching Buttons on the page.

All functions are defined in qTranslateConfig.qtx object and can be called like:

qTranslateConfig.qtx.addLanguageSwitchBeforeListener(function(lang_from, lang_to){ your code here;});

Conditional triggering

JS code usually runs in pair with an integration setup defined in admin-config.json. The JS code can be synched for the execution on a specific page.

Events named 'qtxLoadAdmin:[page-key]' are triggered from the core module on document when the page is loaded. The main qtx object is passed as parameter.

Example of handler:

$(document).on('qtxLoadAdmin:post', function( event, qtx ) {
  /* run integration code (with qtx) */
});

This allows to regroup several page handlers in the same script, avoiding a too small granularity and benefit from the browser cache. The page keys come from the admin-config entry in the i18n-config.json. Only the active keys for the page currently visited are passed, they could be several keys corresponding to different page selectors.

There must be some pages or post_type selector making the current page specific for the event to be fired. Entries without specific selector are irrelevant since they would apply to all pages.

Note: though the custom scripts are executed after the main qTranslate script does not mean the qtx object is initialized yet. This happens before TinyMCE init or on page load, depending on the content of the page (type of editors) and the state of the Visual mode. Adding an event handler when the script is run should solve many issues of synchronization.

More detailed examples:

post

// i18n-config.json
"admin-config": {
    "post": {   // <--- page key
      "pages": {
        "post.php": "",
        "post-new.php": ""
      },

// JS handler for exec (ES5)
$(document).on('qtxLoadAdmin:post', function(event, qtx) {
   // do exec for this entry...
});

nav-menus

// i18n-config.json
"admin-config": {
    "nav-menus": { // <--- page key
      "pages": {
        "nav-menus.php": "action=edit|menu=\\d+|^$"
      },

// JS handler for exec (with ES6 arrow function)
$(document).on('qtxLoadAdmin:nav-menus', (event, qtx) => {
   // do exec for this entry...
});