Как да приложим потребителска логика към необвързани региони

Има някои ситуации, при които пълното премахване на неергирани региони от документа по време на 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.

Този код в класа на манипулатора е единственият клас, който ще трябва да промените, за да контролирате логиката, приложена към неучастилите региони. Другият код в тази извадка може да се използва повторно без промяна във всеки проект.

Този примерен проект демонстрира тази техника. Тя включва следните стъпки:

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, която да бъде обработвана през класа манипулатор.

Извикването на това претоварване с посочения ArrayList ще създаде източник на данни, който съдържа само редове от данни за посочените региони. Региони, различни от ContactDetails региона, няма да бъдат обработени и ще бъдат премахнати автоматично от двигателя Mail Merge. Резултатът от горното повикване, използвайки кода в нашия оригинален манипулатор, е показан по-долу.