Discourse-webpack: قالب لتطوير مكونات Discourse المعتمدة على JS

[labofoz (Oz Ramos)]

تعديل من @david: نظام تنسيقات Discourse يدعم الآن مدمجًا ملفات JS متعددة. لم تعد طريقة webpack هذه مطلوبة.

---

مرحبًا! بينما كنت أعمل على تطوير مكوني handsfree-discourse، واجهتُ بعض المشكلات المتعلقة بإدارة الملفات. كانت مشكلتي الرئيسية هي حاجتي إلى وسيلة لتقسيم شريحتي عبر ملفات متعددة. والمشكلة الأخرى كانت حاجتي إلى تضمين مكتبات طرف ثالث دون الحاجة إلى طلب من المشرفين لتمكين CORS أو إثارة طلبات HTTP إضافية.

ولحل هذه المشكلات، أنشأتُ discourse-webpack، وهو قالب مبدئي لتسريع إنشاء مكونات غنية بـ JS! تشمل الميزات:

• خادم تطوير محلي مع إعادة تحميل فورية
• يتضمن سكريبت commit للحفاظ على كود المصدر والكود المُجمَّع في فروع منفصلة!

يشرح باقي هذا الموضوع كيفية استخدامه ولماذا يعمل. لقد انتهيت للتو من اختباره لبعض المكونات الأخرى التي أعمل عليها، لذا أخبرني إذا واجهتَ أي مشاكل أو لديك أي طلبات محددة!

---

Discourse Webpack

قم بسرعة بإنشاء مكونات غنية بـ JavaScript لمجتمع Discourse الخاص بك، مع سكريبت commit للحفاظ على كود المصدر وكود البناء في فروع منفصلة لمساعدتك على الاستمرار في النشر بسرعة!

---

التثبيت

أولاً، تأكد من تثبيت NodeJS >= 8 و git محليًا على جهازك. ثم، اكتب كل سطر من الأسطر التالية:

# تحميل هذا المستودع
git clone https://github.com/browsehandsfree/discourse-webpack

# الانتقال إلى الدليل
cd discourse-webpack

# تثبيت التبعيات
npm install

ثم ستحتاج إلى تعديل ما يلي في package.json، باستبدال جميع روابطنا بروابطك. تحديدًا:

{
  name: 'your-project',
  repository: {
    url: 'git+https://github.com/username/repo'
  },
  author: '',
  bugs: {
    url: 'https://github.com/username/repo/issues'
  },
  homepage: 'https://example.com'
}

الأهم من ذلك كله، تأكد من صحة repository.url وأنها تسبقها git+. عند تشغيل npm run discourse، سيقوم بتثبيت الدفع إلى ذلك المستودع.

أيضًا، لا تنسَ إعداد ملف about.json الخاص بـ Discourse، والذي يقع في /src/discourse/about.json

---

التطوير

بعد npm install، ستحصل على هيكل الدليل التالي:

discourse-webpack
|- node_modules/        # التبعيات
|- src/                 # ملفات المصدر الرئيسية
|--|- discourse/        # ملفات سمة Discourse
|--|--|- common/
|--|--|- desktop/
|--|--|- mobile/
|--|- main.css          # ملف التنسيق الرئيسي
|--|- main.js           # نقطة الدخول الرئيسية لـ JavaScript
|--|- sandbox.html      # بيئة تجريبية للتطوير المحلي
|- .gitignore
|- discourse-push.js    # سكريبت commit خاص
|- README.md
|- webpack.config.js    # إعدادات Webpack
|- yarn.lock

سكريبتات سطر الأوامر

بالإضافة إلى ذلك، لديك الوصول إلى الأوامر التالية من جذر المشروع:

# تشغيل خادم تطوير على localhost:8080
# - يدعم إعادة التحميل الفورية
# - يستخدم `/src/sandbox.html` لمساعدتك على التصحيح محليًا
npm run dev

# تجميع مكونك إلى `/dist`
npm run build

# تجميع مكونك إلى `/dist`
# - ثم يقوم بتثبيت `/dist` في فرع `discourse`
npm run discourse

كيف يعمل

بمجرد تحميلك للمستودع وتثبيت التبعيات، حان الوقت للبدء في التطوير! استخدم npm run dev لبدء خادم إعادة التحميل الفوري على localhost:8080.

سيؤدي زيارة هذا العنوان إلى تحميل ملف HTML الموجود في /src/sandbox.html. هذا الملف لا يُستخدم فعليًا داخل Discourse، وهو موجود هنا فقط لمساعدتك على تطوير سكريبتاتك محليًا (خارج سياق Discourse).

نقطة الدخول الرئيسية لـ webpack هي /src/main.js. من هناك، يمكنك import سكريبتات أخرى، وسيقوم webpack بتجميع كل شيء معًا وحقنه في الملفات التالية:

• /src/sandbox.html
• /src/discourse/common/body_tag.html

يتم تجميع main.js وحقنه تلقائيًا في sandbox.html، لكنه يتم حقنه يدويًا داخل body_tag.html بسبب الكود التالي:

<script>
  <%= compilation.assets['main.js'].source() %>
</script>

إذا كنت ترغب في حقن سكريبتك في قالب آخر، مثل after_header.html، فما عليك سوى نسخ وسم script هذا إلى ذلك القالب بدلاً من ذلك. هذا يسمح لك بالحفاظ على فصل HTML و JavaScript لذلك القالب أثناء التطوير… لكن دمجهما عند النشر!

---

التجميع

عند التجميع باستخدام npm run build، فإن ما يحدث هو:

• أولاً، يتم تجميع /src/main.js والتبعيات
• ثم، يتم نسخ جميع الملفات الموجودة في /src/discourse/ إلى /dist/
• في الوقت نفسه، يتم حقن main.js ضمنيًا في أي ملف قالب يحتوي على:

<script>
  <%= compilation.assets['main.js'].source() %>
</script>

---

النشر

عند تشغيل npm run discourse، يتم استدعاء سكريبت /discourse-push.js ويقوم بما يلي:

• أولاً، سيقوم بالتجميع، كما لو كان باستخدام npm run build
• ثم، سيقوم بتهيئة مستودع git جديد داخل /dist
• ثم يقوم بتثبيت /dist في فرع discourse الخاص بمشروعك (سيقوم بإنشاء الفرع إذا لم يكن موجودًا)

---

استخدام فرع discourse

كل من /relative/urls/ التالية نسبيًا إلى عنوان URL الأساسي لمنتداك، على سبيل المثال، https://example.com/relative/urls/

تثبيت المكون

قم بتثبيت مكونك بزيارة /admin/customize/themes واختيار “استيراد من الويب” من مستودع مشروعك، على سبيل المثال: https://github.com/my-awesome/discourse-component.

ثم قم بتعيين الفرع إلى discourse. لن يعمل إذا تركته على master، لأن Discourse سيحاول تحميل الملفات غير المجمعَة (إذا كان يعمل على الإطلاق).

---

تصحيح ملفات السمة المحددة على مضيفك الخاص

• قم بتثبيت Discourse Theme CLI
• سجل الدخول إلى https://theme-creator.discourse.org
• انتقل إلى هذا الدليل، ثم شغّل discourse_theme watch .
• استخدم https://theme-creator.discourse.org كعنوان URL الأساسي
  • استخدم مفتاح API الخاص بك من theme-creator

إذا كنت جديدًا على Discourse وتود عمل نسخة fork لهذا المشروع، فقد تكون القراءات التالية مفيدة.

• دليل المبتدئين لتثبيت Discourse على Windows 10
• دليل المبتدئين لاستخدام سمات Discourse
• دليل المطورين لسمات Discourse

[david (David Taylor)]

Discourse now has native support for “JS heavy” theme components

Split up theme Javascript into multiple files

Complex theme javascript can be split into multiple files, to keep things nicely organised. To use this functionality, simply add files to the /javascripts folder in your theme directory. Currently, these files can not be edited from the Discourse UI, so you must use the Theme CLI or source the theme from git. Javascript files are treated exactly the same as they are in core/plugins, so you should follow the same file/folder structure. Theme files are loaded after core/plugins, so if the filen…

@labofoz I would be interested to know whether you think this is enough to avoid the need for discourse-webpack?