مكتبة روبي مفتوحة المصدر لتوليد ملفات Word DOCX
واجهة برمجة تطبيقات Ruby مجانية قوية تمكّن مطوري البرمجيات من إنشاء مستندات Word DOCX بسهولة. تسمح بتصميم المستند's Layout, Apply Styles, and Use Mail Merge Fields as Placeholders for Dynamic Content.
ما هي مكتبة Sablon؟
في عالم تطوير البرمجيات، توليد مستندات ديناميكية مثل التقارير، الفواتير، أو الرسائل هو مطلب شائع. بينما يمكن للعديد من المكتبات إنشاء المستندات من الصفر، غالبًا ما تتطلب منحنى تعلم حادًا وتشفيرًا شاقًا للحصول على التنسيق الصحيح. هنا يأتي دور Sablon، مكتبة روبي مفتوحة المصدر قوية، التي تُعيد تعريف عملية توليد المستندات من خلال الاستفادة من معرفة Microsoft Word وقوة Ruby، مما يتيح لك إنشاء مستندات معقدة ومنسقة بشكل جميل بجهد قليل. تدعم ميزات مثل إنشاء Word Docx، إدراج المحتوى عبر حقول MailMerge، دعم تنسيق متقدم، إضافة تعليقات في القوالب، تحويل HTML & CSS قابل للتكوين، والعديد غيرها.
في جوهرها، Sablon هي معالج قوالب مستندات للملفات .docx. تستفيد من وظيفة دمج البريد المدمجة في Word، مما يتيح لك إنشاء القوالب في بيئة مألوفة. يمكنك تصميم تخطيط المستند، وتطبيق الأنماط، واستخدام حقول دمج البريد كعناصر نائب للمحتوى الديناميكي. ثم يأخذ Sablon هذا القالب وسياق البيانات (hash روبي) لإنتاج مستند Word نهائي مملوء بالبيانات. هذا النهج يفصل طبقة العرض (قالب Word) عن طبقة البيانات (كود Ruby الخاص بك)، مما يجعل عملية توليد المستند نظيفة وقابلة للصيانة. صيغته بديهية لأي شخص مألوف بـ Ruby ولغات القوالب. إنه صديق للمصمم، حيث يتم فصل المحتوى عن التصميم تمامًا. يمكن للمصممين العمل مباشرة في Word دون الحاجة إلى لمس الكود.
البدء مع Sablon
الطريقة الموصى بها لتثبيت Sablon هي باستخدام RubyGems. يرجى استخدام الأمر التالي لتثبيت سلس.
إدراج المحتوى باستخدام حقول Word عبر Ruby
الوظيفة الأساسية هي إدراج محتوى ديناميكي. تستخدم مكتبة Ruby المفتوحة المصدر Sablon بنية الحقول المدمجة في Word لتحديد عناصر النائب. في قالب Word الخاص بك، تُدخل رمز حقل حيث تريد المحتوى الديناميكي. سيستبدل Sablon هذا الحقل بقيمتك. المثال التالي يوضح كيف يمكن للمطورين إدراج محتوى تحية للمستخدم بشكل ديناميكي.
كيفية إدراج محتوى نصي ديناميكي في ملفات Word عبر Ruby؟
require 'sablon'
template = Sablon.template(File.expand_path('~/template.docx'))
context = {
name: "Sarah Connor"
}
template.render_to_file(File.expand_path('~/output.docx'), context)
Template:
Hello, «name»! Welcome to our platform.
Output:
Hello, Sarah Connor! Welcome to our platform.
تحويل HTML إلى WordML
إحدى الميزات البارزة في Sablon هي قدرته على تحويل HTML إلى WordProcessingML (تنسيق XML المستخدم في ملفات .docx). هذا مفيد جدًا عندما تحتاج إلى إدراج محتوى نص غني، مثل فقرات منسقة، قوائم، أو جداول، من قاعدة بيانات أو محرر نص غني. سيحول Sablon سلسلة HTML إلى قسم منسق بشكل صحيح في مستند Word، مع الحفاظ على العناوين، النص العريض والمائل، وتنسيق القوائم. إليكم مثالًا بسيطًا يوضح كيفية تحميل قالب موجود وتحويل محتوى HTML إلى ملف Word Docx داخل تطبيقات Ruby.
كيفية تحويل محتوى HTML إلى ملف Word Docx عبر مكتبة Ruby؟
require "sablon"
template = Sablon.template(File.expand_path("template.docx"))
html_content = "هذا عنوان فرعي
هذه فقرة تحتوي على نص عريض ونص مائل.
- العنصر الأول
- العنصر الثاني
"
context = {
article_content: Sablon.content(:html, html_content)
}
template.render_to_file(File.expand_path("output.docx"), context)
Conditional Rendering
إدراج صورة ديناميكية عبر Ruby
تتضمن مكتبة Sablon المفتوحة المصدر ميزة مفيدة لإدراج صور ديناميكيًا داخل مستندات Word Docx باستخدام مكتبة Ruby. مع بضع أسطر من الكود فقط يمكن للمطورين إدراج صور ديناميكيًا في المستندات. يمكنك تحديد ملف صورة، وستدمج Sablon الصورة في المستند. المثال التالي يوضح كيفية تحقيق إدراج صورة ديناميكي داخل مستندات Word.
كيفية إدراج صورة ديناميكيًا في Word Docx عبر مكتبة Ruby؟
// You would have a placeholder image in your template with a special filename like «=company_logo».
context = {
company_logo: Sablon.content(:image, "path/to/your/logo.png")
}
العرض الشرطي عبر Ruby
تدعم مكتبة Sablon كتلًا شرطية، مما يتيح للمستخدمين إظهار أو إخفاء أجزاء من مستند Word بناءً على وجود أو قيمة متغير. هذا مثالي لتخصيص المستندات وفقًا لشروط محددة. على سبيل المثال، يوضح المثال التالي كيف يمكن للمستخدمين تعيين أوامر لإخفاء أو إظهار معلومات معينة داخل مستند Word. إذا كان المتغير show_extra_info صحيحًا، سيُضمّن المحتوى بين وسمي if و endIf في المستند النهائي. إذا كان خاطئًا أو nil، سيتم إزالة المحتوى.
كيفية عرض أو إخفاء أجزاء من مستندات Word Docx باستخدام Ruby؟
context = {
show_extra_info: true # or false
}
