{
...
"projects": {
...
"default": {
...
},
...
}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
The following guide provides an explanation of the structure of frontend extensions using the default extension, that comes with SuiteCRM since version 8.3.0, as an example / guideline.
Starting with version 8.3.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 default extension is structured and how to use it.
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 default extension as an example, thus the folder is extensions/default.
Under the extension the folder, in this case extensions/default, 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/default
The above follows a similar structure as the one used in SuiteCRM core:
configs
core/app
core/backend
core/modules
The default 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/default/app/src folder.
To give developers an example on how to structure their apps, the default 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.
The ExtensionModule located in extensions/default/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.
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.
The config folder is where you should place your extensions / overrides to the configuration.
The angular.json file already contains the configuration needed to build the default extension. You can find the configurations under:
{
...
"projects": {
...
"default": {
...
},
...
}The package.json contains 2 build commands that you can use:
The following line in the package.json defines the dev build command
"build-dev:default": "ng build default --configuration dev",This command will build the default extension in a non-production mode.
Plus it will generate the files directly to the public/extensions/default folder, which allows to also use the --watch option.
Thus when developing, it is best to run:
yarn run build-dev:default --watchThe 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
The following line in the package.json defines the production build command
"build:default": "ng build default --configuration production",This command will build the default extension in a production mode.
It will also generate the extension to the "final" location within the package: extensions/default/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/default/public will be copied to public/extensions/default.
The reason to have two places for the code is:
extensions/default/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/default folder
It also makes it easier to remove / disable an extension
public/extensions/default
Is a web accessible folder
Since extensions/default/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/default/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:defaultContent is available under GNU Free Documentation License 1.3 or later unless otherwise noted.