Форматированный документ в 1С

Начиная с версии 8.2.11 в платформе появился новый объект – Форматированный документ. Так как не нашел на Инфостарте ни одного упоминания об этой функциональности, решил опубликовать небольшую статейку о том, что это за объект и какой функционал он добавляет.

Прошу учесть, что это моя первая публикация. Итак, начнем…
 

Предназначение

Форматированный документ предназначен для оформление текста. Его можно выделить жирным, подчеркнуть, увеличить/уменьшить шрифт, центрировать и т.д. Также можно добавить картинку. Т.е. в 1С теперь можно отформатировать текст, примерно, как в MS Word и др. подобным программам. Это может быть удобно при оформлении различных договоров или, например, при редактировании электронного письма. Таким образом, у нас есть возможность привести текстовый документ в тот вид, который мы пожелаем.

В синтакс-помощнике есть описание.
Объект ФорматированныйДокумент (FormattedDocument) имеет одноименный тип данных, который поддерживает функционирование данного объекта и имеет следующие методы:

Вставить (Insert)
Добавить (Add)
Записать (Write)
ПолучитьHTML (GetHTML)
ПолучитьЗакладкуКонца (GetEndBookmark)
ПолучитьЗакладкуНачала (GetBeginBookmark)
ПолучитьЗакладкуПоПозиции (GetPositionBookmark)
ПолучитьПозициюПоЗакладке (GetBookmarkPosition)
ПолучитьТекст (GetText)
Удалить (Delete)
УстановитьHTML (SetHTML)

Доступен во всех типах приложения: Тонкий клиент, веб-клиент, сервер, толстый клиент, внешнее соединение. Нельзя указать новый тип данных в качестве типа реквизита.

Есть одна важная особенность этого типа. Нельзя задавать тип «Форматированный документ» для реквизита объекта (справочника, документа и др.). Но есть возможность указывать его для реквизитов формы.

Возникает вопрос, как же нам сохранить те изменения при форматировании текста, которые сделал пользователь? Для этого применяется специальный объект «ХранилищеЗначения», который может содержать в себе любой тип данных, в том числе и «форматированный документ». Таким образом, в базе данных сам объект будет храниться как «Хранилище значения», далее при открытии формы необходимо будет извлечь объект из хранилища, отобразить его на форме используя тип «ФорматированныйДокумент». Если пользователь решит сохранить изменения, то при записи объекта нужно снова взять объект «форматированный документ» и записать его в хранилище.
 

Пример работы

Возьмем за основу каркасную конфигурацию, создадим в ней справочники «Контрагенты» и «Договоры». Установим справочник «Договоры» подчиненным справочнику «Контрагенты» и создадим реквизит «Текст» с типом ХранилищеЗначения.

Создадим форму элемента справочника «Договоры» и добавим на нее новый реквизит, который назовем «ТекстДоговора», укажем тип данных «ФорматированныйДокумент». Обратите внимание, что реквизит «Текст» с типом «ХранилищеЗначения» на форму поместить нельзя.
Создадим также командную панель (меню) содержащую необходимые кнопки для управления форматированным документом. Для этого надо добавить в форму «Группа – Командная панель» и указать в свойстве «Источник команд» реквизит формы «ТекстДоговора» с типом ФорматированныйДокумент.

Запускаем отладчик, проверяем, что у нас получилось…

Все бы хорошо, но есть некоторые проблемы:

Во-первых, если ввести текст и отформатировать его должным образом, то признак модифицированности для формы не возникает. Таким образом, случайно нажав на кнопку закрытия формы, система не задавая вопросов закрывает ее без всякого сохранения.
Для того чтобы подобные неприятности не случались, необходимо установить флаг у свойства «Сохраняемые данные» реквизита формы «ТекстДоговора». В результате, при любом изменении данных в реквизите «ТекстДоговора», будет устанавливаться признак модифицированности формы, а при ее закрытии система спросит: «Сохранить изменения?».

Во-вторых. Попытаемся закрыть форму и сохранить введенные данные. Заново открыв сохраненный договор, видим что текст введенный в форму договора отсутствует. Почему так происходит?

Все дело в том, что мы делаем изменения в реквизите формы, который у нас никак не связан с реквизитом объекта. Давайте настроим связь между реквизитом формы «Текст договора» с типом данных «ФорматированныйДокумент» и реквизитом объекта «Текст» с типом «ХранилищеЗначения».

Пропишем эту связь программно в модуле формы. Опишем алгоритм.

1. При открытии формы, необходимо будет обратиться к реквизиту объекта «Текст», чтобы прочитать из него данные и записать их в форматированный документ «Текст договора».
2. При записи объекта, берем содержимое форматированного документа и помещаем его в реквизит объекта «Текст» с типом «ХранилищеЗначения».

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

Нам понадобятся следующие обработчики событий:

 - событие ПриЧтенииНаСервере(ТекущийОбъект)

оно удобно тем, что при ошибочном внесении изменений в данные формы, можно нажать кнопку «Перечитать» и вернутся к исходным данным.

&НаСервере
Процедура ПриЧтенииНаСервере(ТекущийОбъект)
    ТекстДоговора = ТекущийОбъект.Текст.Получить();
КонецПроцедуры

 - событие ПередЗаписьюНаСервере(Отказ, ТекущийОбъект, ПараметрыЗаписи)

&НаСервере
Процедура ПередЗаписьюНаСервере(Отказ, ТекущийОбъект, ПараметрыЗаписи)
    ТекущийОбъект.Текст = Новый ХранилищеЗначения(ТекстДоговора);
КонецПроцедуры

Т.к. реквизит Текст у нас имеет тип «ХранилищеЗначений», надо учесть нюансы работы с ним… В случае чтения объекта используем метод Получить(), а в случае записи используем конструктор объекта Новый ХранилищеЗначения(, ).

На этом пока всё. В следующий раз попробую рассказать про использование шаблонов для вставки параметров в текст форматированного документа, например, вместо %Контрагент% вставлять наименование контрагента.

Благодарю за внимание!

upd

Полезные ссылки указаны товарищем Evg-Lylyk

http://www.1c-pro.ru/index.php?showtopic=21524&st=0&p=92729&#entry92729
http://v8.1c.ru/overview/Term_000000785.htm