Packages file content basics
The package file content comprises files (*.js, *.css, images, etc.) added to custom Creatio packages. Since the file content is static, the webserver does not process it. This helps to improve Creatio performance.
The types of file content:
- Client content generated in real time.
- Pre-generated client content.
Special aspects of client content generated in real time:
- The pre-generation of client content is not needed.
- The calculation of package and schema hierarchy, as well as the generation of content, put a load on the CPU.
- The retrieval of package and schema hierarchy, as well as the generation of content, put a load on the database.
- The caching of client content takes up memory.
Special aspects of pre-generated client content:
- The load on the CPU is minimal.
- The pre-generation of client content is required.
- The database queries are not needed.
- The IIS tools cache the client content.
Storage structure of package file content
File content is an integral part of the package. You can pre-generate the file content in the dedicated ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\<PackageName>\Files
Creatio directory to improve Creatio performance and reduce the load on the database. If the IIS server receives a request, it will search for requested content in this directory and send the content to Creatio immediately. You can add any files to the package, however, Creatio will use only the files required for its client part.
We recommend structuring the Files
directory as below.
-PackageName
...
-Files
-src
-js
bootstrap.js
[other *.js files]
-css
[*.css files]
-less
[*.less files]
-img
[image files]
-res
[resource files]
descriptor.json
...
descriptor.json
js
– the directory with JavaScript *.js source code files
css
– the directory with *.css style files
less
– the directory with *.less style files
Img
– the directory with images
res
– the directory with resource files
descriptor.json
– the file content descriptor that stores the information about package bootstrap files
View the descriptor.json
file structure below.
- descriptor.json file structure
- descriptor.json file example
{
"bootstraps": [
... // The string array that contains relative paths to bootstrap files.
]
}
{
"bootstraps": [
"src/js/bootstrap.js",
"src/js/anotherBootstrap.js"
]
}
To add file content to a package, place the file in the corresponding subdirectory of the Files
package directory.
Package bootstrap files
Package bootstrap files are *.js files that handle the loading of client configuration logic. The file structure may vary.
- bootstrap.js file structure
- bootstrap.js file example
(function() {
require.config({
paths: {
"Module name": "Link to the file content",
...
}
});
})();
(function() {
require.config({
paths: {
"MyPackage1-ContactSectionV2": Terrasoft.getFileContentUrl("MyPackage1", "src/js/ContactSectionV2.js"),
"MyPackage1-Utilities": Terrasoft.getFileContentUrl("MyPackage1", "src/js/Utilities.js")
}
});
})();
Creatio loads bootstrap files asynchronously after loading the core, but before loading the configuration. Creatio generates _FileContentBootstraps.js
auxiliary file in the static content directory to ensure the bootstrap files are loaded correctly. The auxiliary file contains information about bootstrap files of all packages.
var Terrasoft = Terrasoft || {};
Terrasoft.configuration = Terrasoft.configuration || {};
Terrasoft.configuration.FileContentBootstraps = {
MyPackage1: ["src/js/bootstrap.js"],
};
File content versioning
Creatio generates _FileContentDescriptors.js
auxiliary file in the static file content directory to ensure the file content versioning works correctly. The auxiliary file contains information about files in the file content of all packages, displayed as a “key-value” collection. Each key (filename) corresponds to a unique hash code. This ensures the browser will receive the up-to-date file version.
var Terrasoft = Terrasoft || {};
Terrasoft.configuration = Terrasoft.configuration || {};
Terrasoft.configuration.FileContentDescriptors = {
"MyPackage1/descriptor.json": {
Hash: "5d4e779e7ff24396a132a0e39cca25cc",
},
"MyPackage1/Files/src/js/Utilities.js": {
Hash: "6d5e776e7ff24596a135a0e39cc525gc",
},
};
Auxiliary file generation
To generate auxiliary files (_FileContentBootstraps.js
and FileContentDescriptors.js
), execute the BuildConfiguration
operation using the WorkspaceConsole utility.
View the BuildConfiguration
operation parameters in the table below.
Parameter | Description |
---|---|
-operation | The name of the operation. Set the value to |
-useStaticFileContent | Enables the static content. Set the value to |
-usePackageFileContent | Enables the package file content. Set the value to |
Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -destinationPath=Terrasoft.WebApp\ -configurationPath=Terrasoft.WebApp\Terrasoft.Configuration\ -useStaticFileContent=false -usePackageFileContent=true -autoExit=true
As a result, Creatio will generate _FileContentBootstraps.js
and _FileContentDescriptors.js
auxiliary files in the ...\Terrasoft.WebApp\conf\content
static content directory.
Learn more about the parameters of the utility: WorkspaceConsole parameters.
Static file content pre-generation
Creatio generates the file content in the .\Terrasoft.WebApp\conf
special directory. The directory contains *.js files with schema source code, *.css style files, *.js resource files of all Creatio cultures, as well as images.
The user of the IIS pool that runs Creatio must have modification permissions for static content generation in the .\Terrasoft.WebApp\conf
directory to work properly. Set up permissions in the Handler Mappings section on the server level. Learn more: Set up Creatio application server on IIS (user documentation).
Set the name of the IIS pool user in the Identity property. Click Advanced Settings on the Application Pools tab of the IIS manager to open this property.
The following events trigger static file content generation or re-generation:
-
Saving a schema in the Client Schema Designer and Client Objects Designer.
-
Saving in the Section Wizard and Detail Wizard.
-
Installing and deleting applications via Marketplace and *.zip archive.
-
Applying translations.
-
Running Compile and Compile all actions in the Configuration section.
Run these actions after you delete schemas or packages from the Configuration section.
Run the Compile all action after you install or update a package from SVN version control system.
The Compile all action fully re-generates the static file content. Other Creatio actions re-generate only the modified schemas.
File content generation
To generate the file content, execute the BuildConfiguration
operation using the WorkspaceConsole utility.
View the BuildConfiguration
operation parameters in the table below.
Parameter | Description |
---|---|
-workspaceName | The workspace name. Set to |
-destinationPath | The directory to which to generate the static content. |
-webApplicationPath | Path to the web application from which to read the information about the connection to the database. Optional. If you do not specify a value, Creatio will establish a connection to the database specified in the connection string of the |
-force | Optional. Set to |
- Generate the file content (option 1)
- Generate the file content (option 2)
Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -destinationPath="C:\WebApplication\Creatio\Terrasoft.WebApp" -force=true -logPath=C:\wc\log
Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -webApplicationPath="C:\WebApplication\Creatio" -destinationPath="C:\WebApplication\Creatio\Terrasoft.WebApp" -force=true -logPath=C:\wc\log
Client content generation when adding a new culture
After you add new cultures in the Creatio UI, run the Compile all action in the Configuration section.
If you cannot log in to Creatio after adding a new culture, open the Configuration section via the http://[Creatio path]/0/dev
URL.
Retrieve the image URL
The browser requests images in the client part of Creatio with the URL specified in the src
attribute of the img
HTML element. Creatio generates this URL using the Terrasoft.ImagesUrlBuilder (imagurlbuilder.js)
module with the getUrl(config)
public method for retrieving the image URL. This method expects the config
JavaScript configuration object that contains the parameters object in the params
property. Creatio generates the image URL to add to the page based on this property.
config: {
params: {
schemaName: "",
resourceItemName: "",
hash: "",
resourceItemExtension: ""
}
}
schemaName
– the schema name (string)
resourceItemName
– the image name in Creatio (string)
Hash
– the image hash (string)
resourceItemExtension
– the image file extension. For example, “.png.”
View the example that generates the parameters configuration object needed to retrieve the static image URL below.
var localizableImages = {
AddButtonImage: {
source: 3,
params: {
schemaName: "ActivityMiniPage",
resourceItemName: "AddButtonImage",
hash: "c15d635407f524f3bbe4f1810b82d315",
resourceItemExtension: ".png",
},
},
};
Compatibility with the file system development mode
It is not possible to retrieve client content from pre-generated files in the file system development mode. To ensure the correct operation of the file system development mode, disable the retrieval of static client content from the file system. To disable this feature, set the UseStaticFileContent
flag in the Web.config
file to false
.
<fileDesignMode enabled="true" />
...
<add key="UseStaticFileContent" value="false" />
Transfer changes between environments
File content is an integral part of the package. The content is stored in the version control system repository along with other package content. You can transfer the file content to another environment:
- We recommend using the SVN version control system to transfer changes to the development environment.
- We recommend using the export and import mechanism in Creatio IDE to transfer changes to pre-production and production environments.
Creatio will add the Files
directory when installing packages only if there are files to place in it. If there is no such directory, create it manually to begin development.
See also
Set up Creatio application server on IIS (user documentation)