"Maquetas"

Intro

"Maquetas" refers to npm packages that are used to build the front-end of the application. The last few XalokNext projects were developed using this approach.

In this case, the recommended approach for the XalokNext project is to consume the frontend assets (CSS/JS) from the maqueta package directly, instead of copying them to the project. This ensures that future changes to the maqueta package are automatically reflected in the project.

Installation

Add the maqueta npm package as a dependency of the XalokNext project, by adding it in the root package.json of the XalokNext project

Example: In __XALOKNEXT_PROJECT__/package.json

{
  ...,
  "dependencies": {
    ...,
    "project-maqueta": "git+ssh://git@git.xalok.com/HML/project-maqueta.git#main",
    ...
  },
  ...,
}

The line above is only an example, you have to adapt it according to the maqueta package:

• project-maqueta use the name field in the package.json of the maqueta package.
• git+ssh://git@git.xalok.com/HML/project-maqueta.git put the git.xalok.com address of the maqueta package
• main is the name of the branch of the maqueta package that you'd like to use

After adding this line, run npm install in the root of the XalokNext project to install the maqueta package. Commit the resulting changes to the package.json and package-lock.json files.

Usage

To use assets from the maqueta package, refer to them using the project-maqueta prefix.

Importing CSS files

Example: Assuming the maqueta package has a dist/prod/assets/css/style.css file, you can include it in the screen.scss of the XalokNext project like this:

@import "project-maqueta/dist/prod/assets/css/style";

Importing compiled JS files

Example: Assuming the maqueta package has a dist/prod/assets/js/global.js file, you can include it in one of the JS files of the XalokNext project like this:

define([
    'project-maqueta/dist/prod/assets/js/global',
], function() {
})

Importing source JS files

In case the maqueta package doesn't compile all the JS files into one and puts them in the dist folder, like in the example above, it's very likely that it needs the jquery package to be installed in the XalokNext project. If that's the case, install the jquery package in the XalokNext project, by adding it in the same package.json where the maqueta dependency was added. Then, assuming the maqueta package has a file src/assets/js/main.js file that requires jQuery, use the imports loader:

define([
    "imports-loader?imports=default|jquery|$!project-maqueta/src/assets/js/main"
], function () {});

This will use the default export in XalokNext's project jquery dependency and pass it to the main.js file of the maqueta package as the $ variable. You might need to adapt these depending on the package required, what it exports and what the maqueta JS file expects.

Developing

Intro

If you need to make changes to the maqueta files, you can do so by cloning the maqueta package and working with it locally.

Check the scripts section of the maqueta package.json to see the available commands. It's very likely that the development of the maqueta is made in .scss files and there's an available npm command required to compile these to .css files. Without running the process that compiles these files, the changes wouldn't be available in the browser when viewing the maqueta HTMLs and also won't be available in the XalokNext project.

Example:

npm run start

Packaging

Just like the npm run start command described above, the maqueta package might have an npm script to compile the CSS files for production:

Example:

npm run package

If that's the case, you should run this command before committing your changes to the maqueta package.

Versioning

Besides running the package command, it's a good habbit to update the version of the maqueta package before committing your changes. In package.json, update the version field to a new version number. This will help you more easily check what version of the maqueta package you have installed in the XalokNext project.

After bumping the version number, run npm install and commit the resulting changes to the package.json and package-lock.json files, together with the .scss changes and the resulting .css files.

Updating the XalokNext project

After committing and pushing the changes to the maqueta project, in the XalokNext project run

npm update project-maqueta

to bring the changes to the XalokNext project. Commit the resulting changes to the package-lock.json file.

Linking

The above steps are good for checking the new developments using the static HTML files that maqueta comes with. But there can be cases where the changes are intertwined with changes that need to be made in the XalokNext project. For example: having an admin script (XalokNext) dispatch an event that's listened by the maqueta scripts. In these cases, testing the changes to the maqueta files can be very tedious, as after every change in the maqueta files you'd have to package, version, commit and push the changes, as described in the steps above.

An alternative is to link the two projects together.

In the maqueta project, run:

sudo npm link

After this, in the XalokNext project, run:

npm link project-maqueta

Now, every change made to the maqueta directory should be available in the XalokNext project immediately.

Note: You'd still need to run npm run start (or similar) in the maqueta project to compile the .scss files to .css files.

Note: You'd still need to package, version, commit and push the changes to the maqueta project (see the steps above), to make them available for everyone else running the XalokNext project.