چگونه منطق سفارشی را به مناطق غیر ادغام شده اعمال کنیم
برخی شرایط وجود دارد که حذف کامل مناطق غیر ادغام شده از سند در طول 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 تنها کلاس است که شما باید برای کنترل منطق اعمال شده در مناطق غیر ادغام شده تغییر دهید. کد دیگر در این نمونه را می توان بدون تغییر در هر پروژه استفاده کرد.
این نمونه پروژه این تکنیک را نشان می دهد. این شامل مراحل زیر است:
- Mail Merge را با استفاده از منبع داده خود بر روی سند اجرا کنید. پرچم MailMergeCleanupOptions.RemoveUnusedRegions فعلا غیر فعال شده ما می خواهیم مناطق باقی بمانند تا بتوانیم آنها را به صورت دستی اداره کنیم. هر منطقه ای بدون داده در سند ادغام نخواهد شد.
- روش ExecuteCustomLogicOnEmptyRegions را فراخوانی کنید. این روش در این نمونه ارائه شده است. این اقدامات را انجام می دهد که اجازه می دهد تا کنترل کننده مشخص شده برای هر منطقه غیر ادغام شده فراخوانده شود. این روش قابل استفاده مجدد است و می تواند بدون تغییر در هر پروژه ای که نیاز به آن دارد (همراه با هر روش وابسته) کپی شود.این روش مراحل زیر را اجرا می کند:
- کنترل کننده مشخص شده توسط کاربر را به ویژگی MailMerge.FieldMergingCallback تنظیم می کند.
- روش CreateDataSourceFromDocumentRegions را فرا می خواند که نام های منطقه ای Document و ArrayList کاربر را می پذیرد. این روش یک منبع داده ساختگی ایجاد می کند که شامل جداول برای هر منطقه غیر ادغام شده در سند است.
- Mail Merge را بر روی سند با استفاده از منبع داده ساختگی اجرا می کند. هنگامی که Mail Merge با این منبع داده اجرا می شود، اجازه می دهد تا کنترل کننده مشخص شده توسط کاربر برای هر منطقه unmerge و منطق سفارشی اعمال شده فراخوانده شود
کد خبر
پیاده سازی برای روش ExecuteCustomLogicOnEmptyRegions در زیر یافت می شود. این روش چندین پارامتر را می پذیرد:
- شیء Document که شامل مناطق غیر ادغام شده است که باید توسط کنترل کننده عبور شده اداره شود.
- کلاس کنترل کننده که منطق را برای مناطق غیر ادغام شده تعریف می کند. این کنترل کننده باید IFieldMergingCallback رابط.
- از طریق استفاده از اضافه بار مناسب، این روش همچنین می تواند پارامتر سوم را بپذیرد – لیستی از نام های منطقه به عنوان رشته ها. اگر این مشخص شود، تنها نام های منطقه باقی مانده سند مشخص شده در لیست به صورت دستی اداره می شود. مناطق دیگری که با آنها مواجه می شوند توسط کنترل کننده فراخوانده نمی شوند و به طور خودکار حذف می شوند. هنگامی که اضافه بار با تنها دو پارامتر مشخص می شود، هر منطقه باقی مانده در سند توسط روش مورد استفاده دستی گنجانده می شود.
مثال
نشان می دهد که چگونه منطق سفارشی را در مناطق استفاده نشده با استفاده از کنترل کننده مشخص شده اجرا کنید.
مثال
روش مورد استفاده برای دستکاری مناطق غیر ادغام شده را تعریف می کند.
این روش شامل یافتن تمام مناطق ادغام نشده در سند است. این کار با استفاده از روش MailMerge.GetFieldNames انجام می شود. این روش تمام فیلدهای ادغام در سند را باز می گرداند، از جمله نشانگرهای شروع و پایان منطقه (با فیلدهای ادغام با پیشوند TableStart یا TableEnd نشان داده شده است).
وقتی یک فیلد ادغام TableStart مواجه می شود این به عنوان یک DataTable جدید به DataSet اضافه می شود. از آنجا که یک منطقه ممکن است بیش از یک بار ظاهر شود (به عنوان مثال به این دلیل که یک منطقه آشیانه ای است که در آن منطقه مادر با چندین رکورد ادغام شده است)، جدول فقط در صورتی ایجاد و اضافه می شود که قبلا در DataSet وجود نداشته باشد.
هنگامی که یک شروع منطقه مناسب پیدا شده و به پایگاه داده اضافه شده است، فیلد بعدی (که با فیلد اول در منطقه مطابقت دارد) به DataTable اضافه می شود. فقط فیلد اول برای هر فیلد در منطقه مورد نیاز است تا ادغام شود و به کنترل کننده منتقل شود.
ما همچنین مقدار فیلد فیلد اول را به “FirstField” تنظیم می کنیم تا استفاده از منطق برای فیلد اول یا سایر فیلد های منطقه آسان تر شود. با اضافه کردن این به این معنی است که لازم نیست نام فیلد اول را سخت کد کنید یا کد اضافی را برای بررسی اینکه آیا فیلد فعلی اولین فیلد در کد کنترل کننده است، پیاده سازی کنید.
کد زیر نشان می دهد که این سیستم چگونه کار می کند. سند نشان داده شده در ابتدای این مقاله با همان منبع داده ادغام شده است اما این بار، مناطق استفاده نشده توسط کد سفارشی اداره می شوند.
مثال
نشان می دهد که چگونه مناطق غیر ادغام شده را پس از Mail Merge با کد تعریف شده توسط کاربر مدیریت کنیم.
کد عملیات مختلفی را بر اساس نام منطقه با استفاده از ویژگی FieldMergingArgs.TableName انجام می دهد. توجه داشته باشید که بسته به سند و مناطق شما می توانید کنترل کننده را برای اجرای منطق بسته به هر منطقه یا کد که برای هر منطقه غیر ادغام شده در سند یا ترکیبی از هر دو اعمال می شود، کد کنید.
منطق برای منطقه ContactDetails شامل تغییر متن هر فیلد در منطقه ContactDetails با یک پیام مناسب است که بیان می کند هیچ داده ای وجود ندارد. نام هر فیلد با استفاده از ویژگی FieldMergingArgs.FieldName در کنترل کننده مطابقت دارد.
یک فرآیند مشابه به منطقه Suppliers با اضافه کردن کد اضافی برای رسیدگی به جدول که شامل منطقه است، اعمال می شود. کد بررسی خواهد کرد که آیا منطقه در یک جدول قرار دارد (زیرا ممکن است قبلا حذف شده باشد). اگر این طور باشد، کل جدول را از سند و همچنین پاراگراف پیش از آن حذف می کند تا زمانی که با یک سبک عنوان به عنوان مثال “Heading 1"فرمت شود.
مثال
نشان می دهد که چگونه منطق سفارشی را در یک کنترل کننده پیاده سازی IFieldMergingCallback که برای مناطق غیر ادغام شده در سند اجرا می شود تعریف کنید.
نتیجه کد بالا در زیر نشان داده شده است. زمینه های ادغام نشده در منطقه اول با متن آموزنده جایگزین می شوند و حذف جدول و عنوان اجازه می دهد تا سند کامل به نظر برسد.
کد که جدول اصلی را حذف می کند نیز می تواند در هر منطقه استفاده نشده به جای فقط یک منطقه خاص با حذف چک برای نام جدول اجرا شود. در این مورد، اگر هر منطقه ای در داخل یک جدول با هیچ داده ای ادغام نشده باشد، هر دو منطقه و جدول کانتینر به طور خودکار حذف می شوند.
ما می توانیم کد های مختلف را در کنترل کننده وارد کنیم تا کنترل کنیم که چگونه مناطق غیر ادغام شده اداره می شوند. استفاده از کد زیر در handler به جای آن متن در پاراگراف اول منطقه را به یک پیام مفید تغییر می دهد در حالی که هر پاراگراف بعدی در منطقه حذف می شود. این پاراگراف های دیگر حذف می شوند زیرا پس از ادغام پیام ما در منطقه باقی می مانند.
متن جایگزین با تنظیم متن مشخص شده در ویژگی FieldMergingArgs.Text در فیلد اول ادغام می شود. متن این خاصیت توسط موتور Mail Merge به میدان ادغام می شود.
کد این را فقط برای اولین فیلد در منطقه با چک کردن ویژگی FieldMergingArgs.FieldValue اعمال می کند. مقدار فیلد فیلد اول در منطقه با “FirstField” مشخص شده است. این امر اجرای این نوع منطق را در بسیاری از مناطق آسان تر می کند زیرا نیازی به کد اضافی نیست.
مثال
نشان می دهد که چگونه یک منطقه استفاده نشده را با یک پیام جایگزین کنیم و پاراگراف های اضافی را حذف کنیم.
سند حاصل پس از اجرای کد بالا در زیر نشان داده شده است. منطقه استفاده نشده با یک پیام جایگزین می شود که بیان می کند هیچ سوابق برای نمایش وجود ندارد.
به عنوان مثال دیگر، می توانیم کد زیر را به جای کد که در اصل SuppliersRegion را اداره می کند، وارد کنیم. این یک پیام را در جدول نمایش می دهد و سلول ها را به جای حذف جدول از سند ادغام می کند. از آنجا که این منطقه در یک جدول با سلول های متعدد قرار دارد، بهتر به نظر می رسد که سلول های جدول با هم ادغام شوند و پیام متمرکز شود.
مثال
نشان می دهد که چگونه تمام سلول های اصلی یک منطقه استفاده نشده را ادغام کنید و یک پیام را در جدول نمایش دهید.
سند حاصل پس از اجرای کد بالا در زیر نشان داده شده است.
در نهایت، ما می توانیم روش ExecuteCustomLogicOnEmptyRegions را فراخوانی کنیم و نام جدول را که باید در روش handler ما اداره شود، مشخص کنیم، در حالی که مشخص می کنیم که دیگران به طور خودکار حذف می شوند.
مثال
نشان می دهد که چگونه فقط منطقه ContactDetails را که از طریق کلاس handler اداره می شود مشخص کنید.
فراخوانی این اضافه بار با ArrayList مشخص شده منبع داده را ایجاد می کند که فقط شامل ردیف های داده برای مناطق مشخص شده است. مناطق غیر از منطقه ContactDetails اداره نمی شوند و به جای آن به طور خودکار توسط موتور Mail Merge حذف می شوند. نتیجه تماس فوق با استفاده از کد در کنترل کننده اصلی ما در زیر نشان داده شده است.
