Перейти к содержанию

API для работы с выгружаемым содержимым полей карточек

В системе существует API, который позволяет выгружать требуемые поля экспортируемых карточек в виде отдельных файлов. В самих файлах карточек значение таких полей заменяется на относительный путь до выгруженного контента.

Данный API удобно использовать, когда поля карточки содержат данные, с которыми может потребоваться работа как с отдельным файлом. Таковыми могут быть данные строкового типа, например, SQL и C# скрипты, html-содержимое, обычный текст и т.п., а также любые данные бинарного формата.

Файлы с выгружаемым контентом будут расположены в подпапке с таким же именем, что и у файла самой карточки, но без расширения .jcard.

Настройка полей выгружаемого контента для типов карточек

Для того, чтобы настроить, какие поля карточек должны быть выгружены при экспорте в отдельные файлы, необходимо создать хэндлер, реализующий интерфейс IStorageMappingHandler, который предоставляет параметры сериализации для выгрузки контента карточек во внешние файлы, а также зарегистрировать этот хэндлер в системе.

Note

Для некоторых типов карточек реализованы и зарегистрированы стандартные хэндлеры, которые, в случае необходимости, можно переопределить.

IStorageMappingHandler требует реализации метода GetContentMappings, возвращающего список параметров сериализации для выгрузки контента карточек во внешние файлы в виде IStorageContentMapping.

Note

Для интерфейса IStorageContentMapping существует стандартная реализация StorageContentMapping.

Свойства интерфейса IStorageContentMapping

  • StoragePath - тип string. Путь, по которому расположен контент/ссылка на контент внутри storage объекта. См. подробнее об API для работы со storage-объектами, а также об используемом синтаксисе в разделе Формат пути в storage-объекте.

    Например, если необходимо выгружать html-содержимое карточек справки, путь может выглядеть следующим образом: Sections.HelpSections.Fields.RichText.Text.

  • FileName - тип string. Имя внешнего ресурса с контентом.

  • IDKeys - тип IList<string>?. Список путей с расположением значений, которые представляют собой уникальные идентификаторы для значений. Требуется в случаях, когда путь в свойстве StoragePath содержит один или несколько wildcard’ов типа []. В других случаях, может не указываться или указываться как null.

    При разрешении путей они формируются из пути StoragePath без учёта последнего элемента и из путей, указанных в данном свойстве. Это позволяет использовать подстановочный символ перехода к родительскому элементу (“^”) в начале IDKeys.

    Например, в StoragePath задан путь Sections.KrStages.Rows[].Settings.AliasMetadata, а IDKeys содержит один элемент - ^.RowID. Тогда значение будет извлекаться по пути Sections.KrStages.Rows[].RowID.

  • ContentConverter - тип string?. Имя конвертера для выгружаемого контента, не указывается или может указываться как null, если конвертирование содержимого не требуется. Подробнее см. в разделе Конвертеры содержимого.

    Например, для выгрузки html-содержимого карточек справки, в отдельные файлы с применением форматирования содержимого, метод GetContentMappings хэндлера может выглядеть следующим образом:

/// <summary>
/// Параметры сериализации для выгрузки контента карточек во внешние файлы.
/// </summary>
public class HelpSectionsStorageMappingHandler : IStorageMappingHandler
{
    /// <inheritdoc />
    public IList<IStorageContentMapping> GetContentMappings(Card card) => new List<IStorageContentMapping>
    {
        // Здесь cвойство "IDKeys" указывать не требуется, т.к. это маппинг для строковой секции
        // и путь указывает на единственное значение.
        new StorageContentMapping(
            // storage-путь до выгружаемого содержимого
            "Sections.HelpSections.Fields.RichText.Text,
            // имя файла
            "HelpSection.html",
            // наименование конвертера, который произведёт форматирование перед выгрузкой
            contentConverter: nameof(RichTextStorageContentConverter))
    };
}

В результате экспорта, в целевой папке будет сохранен сам файл карточки, создана подпапка с аналогичным наименованием, а внутри данной подпапки будут созданы файлы с содержимым, согласно параметрам сериализации, заданным в хэндлере.

Note

К именам файлов выгружаемого контента будет добавлено хэш-значение, чтобы исключить вероятность файлов с одинаковым именем.

Содержимое целевой папки:

Файлы в подпапке:

В базе знаний см. подробные примеры реализации для хэндлеров, а также пример их регистрации в системе.

Конвертеры содержимого полей карточек

Существует возможность изменять содержимое выгружаемых полей перед выгрузкой. Это может быть полезно, например, для фоматирования содержимого и т.п. Для этого необходимо создать конвертер, реализующий интерфейс IStorageContentConverter, а также зарегистрировать его в системе по имени, затем в настройках маппинга в свойстве ContentConverter необходимо указать имя требуемого конвертера.

Note

Для некоторых типов содержимого уже реализованы стандартные конвертеры.

Для конвертирования IStorageContentConverter предоставляет метод ValueTask<object?> ConvertValueAsync(object? value, CancellationToken cancellationToken = default), где value - значение, которое требуется конвертировать.

В базе знаний см. пример реализации для конвертера, а также пример регистрации конвертера в системе.

Back to top