Extension Structure

The following documentation is for SuiteCRM Version 8+; to see documentation for Version 7, click here.

The following documentation assumes that you have a good understanding of the angular framework

1. Intro

The following guide provides an explanation of the structure of frontend extensions using the defaultExt extension, that comes with SuiteCRM since version 8.4.0, as an example / guideline.

Starting with version 8.4.0, SuiteCRM comes with a pre-configured frontend extension that is ready to be used for customizations.

Apart from being a starting point to start coding, it provides a base structure for you to use on your customisations.

The following sections will try to provide some info on how the defaultExt extension is structured and how to use it.

2. Extension Contents

An extension can include both backend and frontend customizations.

Each extension is a separate folder within the extensions folder.

All the contents of the extension are located under its folder. Thus, it is possible to remove an extension just by deleting the folder.

As mentioned earlier we will be using the defaultExt extension as an example, thus the folder is extensions/defaultExt.

3. Extension Structure

Under the extension the folder, in this case extensions/defaultExt, you can have 5 folder:

app
- Contains the frontend code
backend
- Contains the backend code
modules
- Contains the module specific backend code and configuration
config
- Contains the SuiteCRM 8 side configuration (not the SuiteCRM 7 side configuration)
public
- Automatically generated by the frontend build command
- Contains the built version of the frontend extension
- When the cache is cleared, its contents are automatically copied to public/extensions/defaultExt

The above follows a similar structure as the one used in SuiteCRM core:

configs
core/app
core/backend
core/modules

The defaultExt extension comes with a pre-setup structure for frontend extensions. In essence, the app folder is a micro angular app with a special webpack config that uses the ModuleFederation plugin.

Your custom code should go under the extensions/defaultExt/app/src folder.

3.1.1 Structure

To give developers an example on how to structure their apps, the defaultExt extension already includes the following folder as placeholders:

components
containers
fields
services
views

The above are the main building blocks of the frontend code. When adding a new item within these you should try to keep the same structure that core uses. This will provide a pattern that makes it easier to navigate through the code.

Please note that this structure is not mandatory, it is a guideline and recommended.

3.1.2 Extension Module

The ExtensionModule located in extensions/defaultExt/app/src/extension.module.ts is the entrypoint for all front end extension code. In order for your custom code to be picked up it needs to be registered in the ExtensionModule, or some other file that is then used in the ExtensionModule

On some of the frontend extension example guides you can find examples of how to register your code for those extensions, so that it gets picked up.

3.2 Backend and Modules Folders

The backend and modules folders are meant to contain backend code. They are autowired in Symfony, so they will automatically be picked up and classes can be used through dependency injection.

Ideally the files and folders added to backend should follow the same structure used on the core/backend.

The modules folder should have a folder for each module you want to extend. Within the module folder you can follow the same structure used in core/backend.

3.3 Config Folder

The config folder is where you should place your extensions / overrides to the configuration.

4 Angular Setup

4.1 angular.json

The angular.json file already contains the configuration needed to build the defaultExt extension. You can find the configurations under:

{
  ...

  "projects": {
    ...
    "defaultExt": {
      ...
    },

  ...
}

4.2 package.json

The package.json contains 2 build commands that you can use:

4.2.1 Development build

The following line in the package.json defines the dev build command

    "build-dev:defaultExt": "ng build defaultExt --configuration dev",

This command will build the defaultExt extension in a non-production mode.

Plus it will generate the files directly to the public/extensions/defaultExt folder, which allows to also use the --watch option.

Thus when developing, it is best to run:

yarn run build-dev:defaultExt --watch

The command will stay on "watch" for changes to the files in the extension:

It will automatically re-rebuild
The re-build process is significantly faster than a full new build.
After the auto re-build you just need to refresh your browser to get the changes
- Please use the `Empty Cache and Hard Reload" Option (or similar) from your browser to reload the page, to make sure you don’t get any cached code

4.2.2 Production Build

The following line in the package.json defines the production build command

    "build:defaultExt": "ng build defaultExt --configuration production",

This command will build the defaultExt extension in a production mode.

It will also generate the extension to the "final" location within the package: extensions/defaultExt/public. This is the location for the production extension code.

When the cache is cleared, using a php bin/console cache:clear or by deleting the cache, the code from extensions/defaultExt/public will be copied to public/extensions/defaultExt.

The reason to have two places for the code is:

extensions/defaultExt/public
- Is the place to keep the built front end code.
- When the extension is installed in a new instance all the code comes with it, just by copying the extensions/defaultExt folder
- It also makes it easier to remove / disable an extension
public/extensions/defaultExt
- Is a web accessible folder
- Since extensions/defaultExt/public is not a publicly accessible folder, the front end code needs to be copied over to a location that is web accessible.
- It is not the main source for the code, on every cache clear it will be deleted and the contents from extensions/defaultExt/public will be copied again

Therefore, after you’ve written and tested your extension using the dev command, you should run the following to build a "package-ready" and production version of your extension:

yarn run build:defaultExt