XalokNext Documentation

Appearance

Webpack ​

Intro ​

Webpack is used to bundle javascript files together. It's being used for the admin client JavaScript, for the SSR JavaScript and for the public-facing JavaScript.

Admin JavaScript ​

Intro ​

In the root of the project there's a config.js file that exports an adminConfig. In this object you can add an webpack entry that contains the webpack's configuration. XalokNext will merge this configuration into the default one it uses.

Making changes ​

Please note that the config.js file is not being watched by make dev. If you make changes to this file, you need to stop the make dev process and start it again.

Adding new entry points (apps) ​

Entry points are the result of compiling a JavaScript application to use it directly in the browser

Example: Define a new entry point called entry_name

javascript
// in config.js

adminConfig.webpack = adminConfig.webpack || {};

adminConfig.webpack.entry = adminConfig.webpack.entry || {};
adminConfig.webpack.entry.entry_name = 'admin/app/entry.js'

This can be then used in the twig file:

html
{{ wf_webpack_js('entry_name') }}

The common entry point ​

The common entry point is a special entry point that is used to include functionality required by webpack to work. If you're creating a new admin page and want to include a custom entry point, you need to make sure that the common entry point is also included above your custom entry point.

By default, the admin layout file defined in WfCmsBaseBundle already includes it. If you cannot extend this layout file, include the common entry point just like any others:

html
{{ wf_webpack_js('common') }}
{{ wf_webpack_js('entry_name') }}

require vs define ​

Note that most of the JavaScript code defines dependencies using the define function. But entry points must use the require function instead:

javascript
// in admin/app/entry.js
require(["jquery", "wfca/form/plugin"], function () {
    const $myForm = $('.my-form');
    $myForm.wfForm();
});

Aliases ​

Overwriting dependencies ​

Throughout the JavaScript code in XalokNext you'll see dependencies injected like:

javascript
define(["wfca/view/page_edit_form"], function(PageEditForm) {
});

You can overwrite every piece of functionality by overwriting the dependency identifier in webpack's aliases:

javascript
// in config.js

adminConfig.webpack = adminConfig.webpack || {};
adminConfig.webpack.resolve = adminConfig.webpack.resolve || {};
adminConfig.webpack.resolve.alias = adminConfig.webpack.resolve.alias || {};
Object.assign(adminConfig.webpack.resolve.alias, {
    // other aliases overwrites
    "wfca/view/page_edit_form": "admin/view/form/page_edit_form",
});

Now, you need to create src/App/Bundle/CmsAdminBundle/Resources/public/javascripts/view/form/page_edit_form.js and implement the functionality you want to overwrite.

javascript
// in src/App/Bundle/CmsAdminBundle/Resources/public/javascripts/view/form/page_edit_form.js
define(["jquery", "_wfca/view/page_edit_form"], function (
    $,
    Base
) {
    return Base.extend({});
});

Note: The above example shows extending a Backbone view. Check this wiki page to see how other types of JavaScript code can be extended.

Note: See that the JavaScript file in the project injects the _wfca/view/page_edit_form dependency. Note that this is the same identifier that we've overwritten in the config.js file, but prefixed with an underscore. This is to avoid circular dependencies, as the identifier without the underscore prefix (wfca/view/page_edit_form) points to itself.

Special aliases ​

Note that throughout the examples, both when adding custom entries and when ovewritting aliases, we've used the admin alias. This is a special alias that points to the src/App/Bundle/CmsAdminBundle/Resources/public/javascripts directory.

wflib ​

Intro ​

wflib is a special entry point that exposes some internal XalokNext JavaScript libraries directly in the window object, to be used where one doesn't want or cannot use webpack to add custom entry points. One example of this functionality is the settings manager app, that is written using VueJS (and other libraries) directly from a CDN, without bundling the code.

Using it ​

To use it, you must first include it in a twig:

html
{{ wf_webpack_js('wflib') }}

Note: the common entry point is required to appear above wflib in the twig file.

Then, in the JavaScript code, you can access the exposed libraries using the window.wfLib object.

Available functionality ​

cnf ​

This is the configuration object that is exposed from Symfony to share parameters between PHP and JavaScript

i18n ​

Example:

javascript
window.wfLib.i18n.get('translation.key');

routing ​

Exposes the wfed/util/routing module, used to generate links. Example documentation: content-router