Использование файлового контента в пакетах

Общие сведения

Начиная с версии 7.11.3 в системе появилась возможность добавлять файловый контент (*.js-, *.css-файлы, изображения и др.) в пользовательские пакеты.

Файловый контент пакетов — любые файлы, используемые приложением. Файловый контент не обрабатывается web-сервером и является статическим (см. "Статический клиентский контент в файловой системе"), что в свою очередь повышает скорость работы приложения.

Рекомендованная структура хранения файлового контента

Для использования файлового контента в структуру пакета (см. "Структура и состав пакетов") добавлен каталог Files. Рекомендуется соблюдать следующую структуру каталога Files:

-PackageName
    ...
    -Files
        -src
            -js
                bootstrap.js
                [другие *.js-файлы]
            -css
                [*.css-файлы]
            -less
                [*.less-файлы]
            -img
                [файлы изображений]
            -res
                [файлы ресурсов]
        descriptor.json
    ...
descriptor.json

Здесь

js — каталог с *.js-файлами исходных кодов на языке JavaScript.

css — каталог с *.css-файлами стилей.

less — каталог с *.less-файлами стилей.

img — каталог с изображениями.

res — каталог с файлами ресурсов.

descriptor.json — дескриптор файлового контента.

Как добавить файловый контент в пакет

Достаточно просто поместить файл в соответствующий подкаталог директории Files необходимого пакета. Каталог Files будет размещен по пути ...\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\<Название пакета>\Files.

Дескриптор файлового контента

В файле descriptor.json, размещенном в каталоге Files, хранится информация о bootstrap-файлах пакета. Файл имеет следующую структуру:

{
    "bootstraps": [
        ... // Массив строк, содержащих относительные пути к bootstrap-файлам.
    ]
}

Пример файла descriptor.json:

{
    "bootstraps": [
        "src/js/bootstrap.js",
        "src/js/anotherBootstrap.js"
    ]
}

Bootstrap-файлы пакета

Это *.js-файлы, которые позволяют управлять загрузкой клиентской конфигурационной логики. Файл не имеет четкой структуры.

(function() {
    require.config({
        paths: {
            "Название модуля": "Ссылка на файловый контент",
            ...
        }
    });
})();

Пример файла bootstrap.js:

(function() {
    require.config({
        paths: {
            "MyPackage1-ContactSectionV2": Terrasoft.getFileContentUrl("MyPackage1", "src/js/ContactSectionV2.js"),
            "MyPackage1-Utilities": Terrasoft.getFileContentUrl("MyPackage1", "src/js/Utilities.js")
        }
    });
})();

Загрузка bootstrap-файлов

Для корректной загрузки bootstrap-файлов в директории статического контента генерируется вспомогательный файл _FileContentBootstraps.js (см. "Генерация вспомогательных файлов" ниже). Это файл, в котором содержится информация о bootstrap-файлах всех пакетов.

Пример содержимого файла _FileContentBootstraps.js:

var Terrasoft = Terrasoft || {};
Terrasoft.configuration = Terrasoft.configuration || {};
Terrasoft.configuration.FileContentBootstraps = {
    "MyPackage1": [
        "src/js/bootstrap.js"
    ]
};

Версионирование файлового контента

Для корректной работы версионирования файлов файлового контента в директории статического контента генерируется вспомогательный файл _FileContentDescriptors.js (см. "Генерация вспомогательных файлов" ниже). Это файл, в котором в виде коллекции "ключ-значение" содержится информация о файлах в файловом контенте всех пакетов. Каждому ключу (названию файла) соответствует значение — уникальный хэш-код. Таким образом обеспечивается гарантированная загрузка в браузер актуальной версии файла.

Пример содержимого файла _FileContentDescriptors.js:

var Terrasoft = Terrasoft || {};
Terrasoft.configuration = Terrasoft.configuration || {};
Terrasoft.configuration.FileContentDescriptors = {
    "MyPackage1/descriptor.json": {
        "Hash": "5d4e779e7ff24396a132a0e39cca25cc"
    },
    "MyPackage1/Files/src/js/Utilities.js": {
        "Hash": "6d5e776e7ff24596a135a0e39cc525gc"
    }
};

Генерация вспомогательных файлов

Для генерации вспомогательных файлов (_FileContentBootstraps.js и FileContentDescriptors.js) необходимо с помощью утилиты WorkspaceConsole выполнить операцию BuildConfiguration:

Terrasoft.Tools.WorkspaceConsole.exe -operation=BuildConfiguration -workspaceName=Default -destinationPath=Terrasoft.WebApp\ -configurationPath=Terrasoft.WebApp\Terrasoft.Configuration\ -useStaticFileContent=false -usePackageFileContent=true -autoExit=true

Здесь:

• operation — название операции. BuildConfiguration — операция компиляции конфигурации.
• useStaticFileContent — признак использования статического контента. Должен иметь значение false.
• usePackageFileContent — признак использования файлового контента пакетов. Должен иметь значение true.

Остальные параметры WorkspaceConsole описаны в статье "Параметры утилиты WorkspaceConsole".

В результате выполнения операции в каталоге со статическим контентом ...\Terrasoft.WebApp\conf\content будут сгенерированы вспомогательные файлы _FileContentBootstraps.js и _FileContentDescriptors.js.

Перенос изменений между средами

Файловый контент является неотъемлемой частью пакета. Он фиксируется в хранилище системы контроля версий наравне с остальным содержимым пакета. В дальнейшем он может быть перенесен на другую среду разработки при помощи SVN (см. "Работа с системой контроля версий").