Packages file content

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.

{
    "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.

(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.

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 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.

File content generation 

To generate the file content, execute the BuildConfiguration operation using the WorkspaceConsole utility.

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.

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.