Як застосувати логіку користувача до нез'єднаних областей

У деяких ситуаціях повне видалення нез’єднаних областей з документа під час Mail Merge небажано або призводить до того, що документ виглядає неповним. Це може статися, коли користувачеві замість повного видалення області слід відобразити відсутність вхідних даних у вигляді повідомлення.

Бувають також випадки, коли видалення невикористаного регіону самого по собі недостатньо, наприклад, якщо регіону передує заголовок або Регіон міститься в таблиці. Якщо ця область не використовується, то заголовок і таблиця все одно залишаться після видалення області, що буде виглядати недоречно в документі.

У цій статті пропонується рішення, яке дозволяє вручну визначити, як обробляються невикористані області в документі. Базовий код для цієї функції надається і може бути легко використаний повторно в іншому проекті.

Логіка, застосована до кожної області, визначається всередині класу, що реалізує інтерфейс IFieldMergingCallback. Подібним чином можна налаштувати обробник Mail Merge для управління об’єднанням кожного поля, цей обробник можна налаштувати для виконання дій з кожним полем у невикористаній області або з регіоном загалом. У цьому обробнику ви можете задати код для зміни тексту області, видалення вузлів або порожніх рядків і осередків і т. д.

У цьому прикладі ми будемо використовувати документ, показаний нижче. Він містить вкладені області та область, що міститься в таблиці.

Для короткої демонстрації ми можемо запустити зразок бази даних у зразку документа з увімкненим прапором MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS. Ця властивість автоматично видалить нез’єднані області з документа протягом mail merge.

Джерело даних містить два записи для області StoreDetails, але навмисно містить будь-які дані для дочірніх областей ContactDetails для одного із записів. Крім того, в області Suppliers також немає рядків даних. Це призведе до того, що в документі залишаться невикористовувані області. Результат після об’єднання документа з цим джерелом даних наведено нижче.

Як показано на малюнку, ви можете бачити, що Область ContactDetails для другого запису та області Suppliers були автоматично видалені обробником Mail Merge, оскільки в них немає даних. Однак є кілька проблем, через які цей вихідний документ виглядає неповним:

• В області ContactDetails як і раніше залишається абзац з текстом “контактні дані”.
• У цьому ж випадку немає жодних ознак відсутності телефонних номерів, лише пробіл, який може призвести до плутанини.
• Таблиця та заголовок, що стосуються області Suppliers, також залишаються після видалення області всередині таблиці.

Методика, представлена в цій статті, демонструє, як застосувати логіку користувача до кожної нез’єднаної області, щоб уникнути цих проблем.

Рішення

Щоб вручну застосувати логіку до кожної невикористаної області документа, ми використовуємо можливості, вже доступні в Aspose.Words.

Механізм Mail Merge надає властивість видаляти невикористані області за допомогою прапора MailMergeCleanupOptions.RemoveUnusedRegions. Це можна відключити, щоб такі області залишалися недоторканими протягом mail merge. Це дозволяє нам залишати не об’єднані області в документі і обробляти їх вручну самостійно.

Потім ми можемо скористатися властивістю MailMerge.FieldMergingCallback як засобом застосування власної логіки користувача до цих не пов’язаних областей під час Mail Merge за допомогою класу обробника, що реалізує інтерфейс IFieldMergingCallback.

Цей код у класі handler-єдиний клас, який вам потрібно буде змінити, щоб керувати логікою, застосованою до нез’єднаних областей. Інший код у цьому прикладі можна повторно використовувати без змін у будь-якому проекті.

Цей зразковий проект демонструє цю техніку. Він включає наступні кроки:

1. Виконайте Mail Merge у документі, використовуючи джерело даних. Прапор MailMergeCleanupOptions.RemoveUnusedRegions вимкнено, поки ми хочемо, щоб області залишалися, щоб ми могли обробляти їх вручну. Будь-які області без даних не відображатимуться в документі.
2. Викличте метод ExecuteCustomLogicOnEmptyRegions. Цей метод представлений у цьому прикладі. Він виконує дії, які дозволяють викликати вказаний обробник для кожної виділеної області. Цей метод можна використовувати повторно і без змін скопіювати в будь-який проект, який його вимагає (разом з будь-якими залежними методами).Цей метод виконує наступні дії:
   1. Присвоює властивості MailMerge.FieldMergingCallback обробника, зазначеного користувачем.
   2. Викликає метод CreateDataSourceFromDocumentRegions, який приймає власні імена областей, що містять Document та ArrayList. Цей метод створить фіктивне джерело даних, що містить таблиці для кожної виділеної області в документі.
   3. Виконує Mail Merge для документа, використовуючи фіктивне джерело даних. Коли Mail Merge виконується з цим джерелом даних, це дозволяє викликати вказаний Користувачем обробник для кожної області розділення та застосовувати логіку користувача

Код

Нижче наведено реалізацію методу ExecuteCustomLogicOnEmptyRegions. Цей метод приймає кілька параметрів:

1. Об’єкт Document, що містить непоєднані області, які повинні бути оброблені переданим обробником.
2. Клас обробника, який визначає логіку, що застосовується до нез’єднаних областей. Цей обробник повинен реалізовувати IFieldMergingCallback інтерфейс.
3. Використовуючи відповідну перевантаження, метод може також приймати третій параметр-список назв регіонів у вигляді рядків. Якщо це вказано, то вручну будуть оброблятися тільки назви регіонів, що залишаються в документі, зазначеному в списку. Інші виявлені області не будуть викликані обробником і будуть видалені автоматично. Якщо задана перевантаження тільки з двома параметрами, кожна залишилася область в документі включається за допомогою методу, який буде оброблятися вручну.

Приклад

Показує, як виконати логіку користувача в невикористаних областях за допомогою вказаного обробника.

Якщо ви розглядаєте можливість послідовного запуску методу ExecuteCustomLogicOnEmptyRegions з різними обробниками (наприклад, кожен обробник застосовує логіку до певних полів), то вам потрібно буде відключити видалення невикористаних областей, щоб такі області не видалялися між цими викликами.

Приклад

Визначає метод, який використовується для ручної обробки нез’єднаних областей.

Цей метод передбачає пошук усіх нез’єднаних областей у документі. Для цього використовується метод MailMerge.GetFieldNames. Цей метод повертає всі об’єднуючі поля в документі, включаючи маркери початку та кінця області (представлені об’єднаними полями з префіксом TableStart або TableEnd).

При виявленні поля злиття TableStart воно додається як нове DataTable до DataSet. Оскільки область може відображатися більше одного разу (наприклад, через те, що це вкладена область, де батьківська область була об’єднана з кількома записами), таблиця створюється та додається лише в тому випадку, якщо вона ще не існує в DataSet.

Коли відповідний початок регіону знайдено та додано до бази даних, до DataTable додається наступне поле (що відповідає першому полю в регіоні). Для кожного поля в регіоні, яке потрібно об’єднати та передати обробнику, потрібно додати лише перше поле.

Ми також встановили значення першого поля “FirstField”, щоб полегшити застосування логіки до першого або інших полів у регіоні. Увімкнення цього параметра означає, що немає необхідності жорстко кодувати ім’я першого поля або реалізовувати додатковий код, щоб перевірити, чи поточне поле є першим у коді обробника.

Наведений нижче код демонструє, як працює ця система. Документ, показаний на початку цієї статті, повторно об’єднаний з тим самим джерелом даних, але цього разу невикористані області обробляються кодом користувача.

Приклад

Показує, як обробляти нез’єднані області після Mail Merge за допомогою користувацького коду.

Код виконує різні операції на основі назви області, отриманої за допомогою властивості FieldMergingArgs.TableName. Зверніть увагу, що залежно від вашого документа та регіонів ви можете запрограмувати обробник для запуску логіки, яка залежить від кожного регіону, або коду, який застосовується до кожної виділеної області в документі, або їх комбінації.

Логіка для області ContactDetails полягає у зміні тексту кожного поля в області ContactDetails з відповідним повідомленням про відсутність даних. Імена кожного поля відображаються в обробнику за допомогою властивості FieldMergingArgs.FieldName.

Подібний процес застосовується до області Suppliers з додаванням додаткового коду для обробки таблиці, що містить цю область. Код перевірить, чи міститься область у таблиці (оскільки вона, можливо, вже була видалена). Якщо це так, то з документа буде видалена вся таблиця цілком, а також попередній їй абзац, якщо він відформатований в стилі заголовка, наприклад “Heading 1”.

Приклад

Показує, як визначити логіку користувача в обробнику, що реалізує IFieldMergingCallback, який виконується для незв’язаних областей у документі.

Результат виконання наведеного вище коду показаний нижче. Не об’єднані поля в першій області замінені інформативним текстом, а видалення таблиці та заголовка дозволяє документу виглядати завершеним.

Код, який видаляє батьківську таблицю, також може бути змушений виконуватися в кожному невикористаному регіоні, а не лише в певному регіоні, видаляючи перевірку імені таблиці. У цьому випадку, якщо будь-який регіон всередині таблиці не був об’єднаний з будь-якими даними, як Регіон, так і таблиця контейнерів також будуть автоматично видалені.

Ми можемо вставити інший код в обробник, щоб керувати обробкою розділених областей. Використання наведеного нижче коду в обробнику замість цього змінить текст у першому абзаці області на корисне повідомлення, тоді як усі наступні абзаци в області будуть видалені. Ці інші абзаци видаляються, оскільки вони залишаться в регіоні після об’єднання нашого повідомлення.

Замінний текст вводиться в перше поле шляхом установки зазначеного тексту у властивості FieldMergingArgs.Text. Текст з цієї властивості вводиться в поле за допомогою механізму Mail Merge.

Код застосовує це лише до першого поля в регіоні, перевіряючи властивість FieldMergingArgs.FieldValue. Значення першого поля в регіоні позначається як " FirstField". Це полегшує реалізацію цього типу логіки у багатьох регіонах, оскільки не потрібен додатковий код.

Приклад

Показує, як замінити невикористану область повідомленням і видалити зайві абзаци.

Отриманий документ після виконання наведеного вище коду показаний нижче. Невикористана область замінюється повідомленням про те, що в ній немає записів для відображення.

Як інший приклад, ми можемо вставити наведений нижче код замість коду, який спочатку обробляв SuppliersRegion. Це призведе до відображення повідомлення всередині таблиці та об’єднання комірок замість видалення таблиці з документа. Оскільки область знаходиться в таблиці з декількома комірками, краще об’єднати комірки таблиці разом і розташувати повідомлення по центру.

Приклад

Показує, як об’єднати всі батьківські комірки невикористаної області та відобразити повідомлення в таблиці.

Отриманий документ після виконання наведеного вище коду показаний нижче.

Нарешті, ми можемо викликати метод ExecuteCustomLogicOnEmptyRegions і вказати імена таблиць, які повинні оброблятися в нашому методі-обробнику, вказавши при цьому інші, які будуть автоматично видалені.

Приклад

Показує, як вказати лише Область ContactDetails, яка буде оброблятися за допомогою класу handler.

При виклику цього перевантаження із зазначеним значенням ArrayList буде створено джерело даних, що містить лише рядки даних для зазначених областей. Області, відмінні від області ContactDetails, не будуть оброблятися і замість цього будуть автоматично видалені механізмом Mail Merge. Результат виклику вище за допомогою коду з нашого оригінального обробника показаний нижче.