Bitrix Framework

Extension location

bitrix/js/<module>/<extension>
bitrix/modules/js/<module>/<extension>
local/js/<module>/<extension>

Structure

• myextension
  • src — original files
  • dist — bundles Bundle (set) is a combination of software data (files), unified by an attribute. In this case, bundles are processed and unified source files. for browser
  • bundle.config.js — configuration file for assembler
  • config.php — extension configuration file
  • lang — localizations
  • test — tests
  • @types — *.d.ts files

Required elements: src, dist, bundle.config.js, config.php.

Optional elements (directories): lang, test, @types.

If you have an installed @bitrix/cli, the extension structure can be created To create an extension:

1) Go to directory local/js/{module}

2) Execute command bitrix create

3) Reply to wizard questions

Learn more... , by executing the command bitrix create.

src

The directory src must have the source files in ES6 format. Files in this directory as well as the file with config and internal links data will be used for creating final bundle versions to connect in browser in ES5 format.

You can use import of other files from current directory or import other CoreJS extensions.

Use the following syntax below to import variables and classes from another file inside current directory:

• If the folder src has the file file.js and exported class SomeClass:

  import {SomeClass} from "./file";
  

• for import file.css:

  import './file.css';
  

• for import CoreJS 2.0:

  import {Loader} from 'main.loader';
  

• for import of library from CoreJS 1.0:

  import "main.date";
  

dist

The directory dist contains files, automatically created using the assembler for subsequent connecting in browser. Usually, these files are <extension>.bundle.js and <extension>.bundle.css.

bundle.config.js

Assembler configuration file.

• Basic configuration:

  module.exports = {
      input: './src/app.js', 
      output: './dist/app.bundle.js',
  };
  

  Please, be advised: this config file doesn't indicate CSS files, they must be imported via file input.

• All parameters:

  module.exports = {
  	// File to be assembled. 
  	// Usually, it's './src/<extension>.js
  	// You need to indicate a relative path 
  	input: string, 
  	
  	// Path to bundle to be created as an assembly result 
  	// Usually, it's ./dist/<extension>.bundle.js
  	// Indicate the relative path 
  	output: string,
  	
  	// Namespace to add all exports from the file, indicated in the input
  	// Example 'BX.Main.Filter'
  	namespace: string,
  	
  	// List of files for forced merging. 
  	// Files will be merged without code duplicate checks. 
  	// sourcemap's are merged automatically 
  	// Indicate relative paths
  	concat: {
  		js: Array<string>,
  		css: Array<string>,
  	},
  	
  	// Allow or deny assembler to edit config.php
  	// Default: true (allowed)
  	adjustConfigPhp: boolean,
  	
  	// Allows or denies assembler to delete unused code . 
  	// Default: true (allowed).
  	treeshake: boolean,
  	
  	// Allows or denies to rebuild bundles 
  	// when assembly is triggered outside of root of current extension 
  	// Default: `false` (allowed)
  	'protected': boolean,
  	
  	plugins: {
  		// Redefines Babel parameters.
  		// You can indicate your own Babel parameters
  		// https://babeljs.io/docs/en/options
  		// When set as false, code will be built without transpiling
  		babel: boolean | Object,
  		
  		// Additional Rollup plugins, 
  		// executed when assembling the bundles 
  		custom: Array<string | Function>,
  	},
  };
  

config.php

Extension config file defines, which files must be connected to page.

Using @bitrix/cli automatically creates and updates the file config.php when building as required. For example, when JS code has a dependency, not indicated in config.php, it will be automatically added to rel.

• Basic configuration:

  if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true)
  {
  	die();
  }
  
  return [
  	'css' => './dist/loader.bundle.css',
  	'js' => './dist/loader.bundle.js',
  	'rel' => [
  		'main.core'
  	]
  ];
  

• All parameters:

  ...
  
  return [
      // Path to `css` file or array with paths 
      // It's recommended to indicate a relative path 
  	'css' => String | Array<String>,
  	
  	// Path to `js` file or array with paths to `js` files 
      // It's recommended to indicate a relative path 
  	'js' => String | Array<String>,
  	
  	// List of dependencies
  	// Indicate names of extensions to be connected
  	// before connecting current extension
  	// Dependencies are connected recursively and with specified order 
  	'rel' => String | Array<String>,
  	
  	// Path to file with language phrases or array with paths 
  	// file `lang//config.php` is connected automatically, 
  	// you can skip it here
  	'lang' => String | Array<String>,
  	
  	// Denies connecting `main.core` automatically, as a dependency
  	// Default: `false` — connects `main.core`. 
  	// Parameter is set automatically when assembling the bundle
  	// if code has no direct dependency to `main.core` 
  	'skip_core' => Boolean,
  	
  	// Handler, called before connecting extension to the page
  	// passes array with extension configuration as the first parameter
  	// handler can modify this array and return it from function
  	// This can be useful when adding some data from server into language phrases 
  	'oninit' => Function,
  	
  	// Additional language phrases
  	// This can be useful for passing calculated values of language phrases
  	// Accepts the array. Indicate language phrases IDs as keys
  	'lang_additional' => Array<string, string>,
  
  	// Parameter is available from the main module version 20.5.100.
  	// Parameter allows to set the settings,
  	// which can be got in JS,
  	// using the method Extension.getSettings().
  	'settings' => Array
  ];
  

@types

Directory can contain files <name>.d.ts with description of public JS API extension, with TypeScript. It's recommended to use *.d.ts files for describing API libraries, written with ES5. No need to describe ES6 code.

Description example for extension main.loader:

declare module 'main.loader' 
{
    type loaderOptions = {
        target?: HTMLElement,
        size?: number,
        mode?: 'absolute' | 'inline' | 'custom',
        offset?: {
            top?: string,
            left?: string
        },
        color?: string
    };
    
    class Loader 
    {
        constructor(options?: loaderOptions);

        readonly layout: HTMLElement;
        readonly circle: HTMLElement;

        createLayout(): HTMLElement;
        show(target?: HTMLElement): Promise<any>;
        hide(): Promise<any>;
        isShown(): boolean;
        setOptions(options: loaderOptions): void;
        destroy(): void;
    }
}

test

Directory must contain nested directories and files for Mocha Mocha (Мока) — JavaScript test framework to be launched both at node.js, as in browser. It's convenient for asynchronous testing. Mocha tests are launched serially, allowing to create reports flexibly and with precisely.

Learn more... -tests. Each file must create an automatic directory with name of tested file and inserted file with tests in format <sourceName>.test.js.

For example, with such structure in `src`

• src
  • entity
    • column.js
    • row.js
  • app.js

directory test must have the following structure:

• test
  • entity
    • column
      • column.test.js
    • row
      • row.test.js
  • app
    • app.test.js

Extension use

• In PHP

  \Bitrix\Main\UI\Extension::load('main.loader');
  

  Method \Bitrix\Main\UI\Extension::load accepts extension name as parameter, or array with names.

• В JS

1. Importing extension exports:

   import {Loader} from 'main.loader';
   

   If you want to import an old extension (not supporting the ES6 import, for example, main.date), indicate the import without extension export:

   import "main.date";
   

   When you import an extension to JS, assembler automatically adds this extension as dependency in config.php.

2. Deferred connection:

   import {Runtime} from 'main.core';
   Runtime.loadExtension('main.loader').then((exports) => {
   	// Code that uses `main.loader`
       // `exports` will contain all exports from `main.loader`
   });
   

   Lazy loading can be useful when your feature is used at the page not immediately, but for example, when user opens a popup or executes some action.