تطوير مواضيع الخطاب ومكونات الموضوع

[Discourse]

Discourse Themes and Theme Components can be used to customize the look, feel and functionality of Discourse’s frontend. This section of the developer guides aims to provide all the reference materials you need to develop simple themes for a single site, right up to complex open-source theme components.

This introduction aims to provide a map of all the tools and APIs for theme development. If you prefer a step-by-step tutorial for theme development, jump straight to:

Theme Developer Tutorial: 1. Introduction

This tutorial will teach you how to create a Discourse Theme or Theme Component from the ground up. While this topic assumes no previous experience working on Discourse themes, it does assume some prior experience using HTML, CSS and JavaScript. It’ll also help if you know your way around GitHub. What are Discourse themes? A theme or theme component is a set of files packaged together designed to either modify Discourse visually or to add new features. Themes In general, themes are not suppo…

Themes vs. Theme Components

Discourse Themes can be used to customize the frontend user experience using CSS and JavaScript. Each theme has its own git repository, and community admins can generally install and manage them via the Discourse admin panel, even on shared hosting platforms.

Theme Components are themes which are intended for use alongside other Theme Components, as part of an overall Theme. From a development point of view, Theme Components and Themes are almost identical. In these guides, the phrase “Theme” and “Theme Component” are used interchangeably.

Prerequisites

Firstly, make sure you understand how to use existing themes and theme components in Discourse. Using ready-made themes is the quickest and safest way to customize your community. If you need more, then it’s time to consider writing your own theme.

As part of Discourse’s overall architecture, Discourse Themes are built using standard HTML, CSS, JavaScript technologies, and make use of Ember concepts for more advanced UIs. These reference guides assume a base-level understanding of these technologies, and link out to external references where possible.

Discourse is a fast-moving project, and as such any custom theme will require maintenance over time. Make sure you consider this as part of your planning & development processes.

Getting Started

• Theme CLI
• Theme Creator
• File structure of theme

Frontend Customization

• Color Schemes
• JavaScript API
• Outlets
• Transformers
• modifyClass

More!

Check out the rest of the Developer Guides !

---

This document is version controlled - suggest changes on github.

[rsigg]

الكثير من الروابط والمراجع القديمة و/أو غير الصالحة في قسم The PluginApi - modifyClass() section…

@Discourse

https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/controllers/composer.js#L578

لقد تغير هذا الملف كثيرًا لدرجة أن checkReplyLength لم يعد موجودًا حتى…

وفي وقت لاحق في نفس القسم:

@Discourse

https://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/app/components/discovery-categories.js

هذا الرابط يؤدي ببساطة إلى خطأ “404 - Page not found”…

لقد استسلمت عن استخدام هذه الوثائق بعد ذلك…

[Overgrow]

@Discourse

إذا كنت تريد تشغيل البرامج النصية عند تحميل مكون، يمكنك استخدام شيء مثل هذا

تبدو المستندات قديمة بعض الشيء في هذا الجزء.. (أيضًا api.modifyClass يشتكي من فقدان pluginId). كيف يمكنني تشغيل نص برمجي عند تحميل about-page؟ هذا لا يبدو أنه يعمل (لا توجد أخطاء على الرغم من ذلك). كانت لدي نتائج مختلطة مع بعض المكونات الأخرى. شكرًا.

<script type="text/discourse-plugin" version="0.11.1">

api.modifyClass("component:about-page", {
  pluginId: 'discourse-about-theme',

  didInsertElement() {
    this._super(...arguments);
    console.log("Welcome to the about page!");
  }

});

</script>

[Don]

مرحباً about-page أصبح الآن بصيغة .gjs مما يعني أيضاً أنه لم يعد قابلاً للتعديل بهذه الطريقة. إذا كنت ترغب في إجراء تغييرات، يجب عليك استخدام أحد الموصلات المتاحة في تلك الصفحة.

يمكنك التحقق من هذه بسهولة باستخدام Plugin outlet locations theme component أو التحقق في الملف \u003cPluginOutlet\u003e.

[Overgrow]

شكرا جزيلا. منطقي. لقد استخدمت موصلاً بدلاً من ذلك، وهو يعمل بشكل جيد.

[ddsgad (DDSGadget)]

هل هذا الدليل دقيق بعد الآن؟ قرأت الدليل بأكمله لمحاولة إنشاء مكون سمة، ثم نظرت إلى مكونات السمات النموذجية ولم يستخدم أي منها التعليمات التي يفترض بها أن تستخدمها. على سبيل المثال، بالنظر إلى مكون سمة discourse-brand-header، يبدو أنه تمت إعادة هيكلته من استخدام أشياء مثل api.createwidget في header.html إلى استخدام رمز مختلف تمامًا مع initializers و Components وما إلى ذلك. رمز معقد للغاية. يتحدث الدليل عن استخدام واجهة برمجة تطبيقات API مع الأدوات (widgets)، ولكن هذا ليس ما تستخدمه أي من المكونات على الإطلاق. هل هناك دليل محدث أو شيء لاستخدامه بدلاً من ذلك؟

تعديل: يُفترض أن واجهة برمجة تطبيقات الأدوات (widgets API) ستختفي، ولكن هل هناك أي أدلة حول ما يجب استخدامه بدلاً من ذلك؟ يبدو أن الدليل بأكمله هنا يعتمد على رمز تم إيقافه؟

[NateDhaliwal]

هذا صحيح. يجب تحديث الدليل. ومع ذلك، لا تزال بعض الأجزاء ذات صلة كبيرة، مثل بنية الملفات، وما إلى ذلك.

[ddsgad (DDSGadget)]

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

[ddsgad (DDSGadget)]

إذًا، صادفت هذا المنشور على سبيل المثال، للتو: Upcoming Header Changes - Preparing Themes and Plugins - فهل أعادوا هيكلة كل شيء من عناصر واجهة المستخدم القديمة إلى مكونات Glimmer؟ ولكن، هذا الدليل كله عناصر واجهة مستخدم قديمة. ما هي مكونات Glimmer بالضبط وهل هناك أي أدلة؟ أشعر أنني محظوظ لأنني اكتشفت هذا مبكرًا، قبل أن أبدأ في التطوير باستخدام عناصر واجهة المستخدم القديمة. ربما تضيف ملاحظة في هذا الدليل بأن عناصر واجهة المستخدم قديمة ولا ينبغي استخدامها بعد الآن؟

[ddsgad (DDSGadget)]

حسنًا، أرى أن Glimmer هي مكونات Ember جديدة. لكنني ألقيت نظرة على كود Discourse TOC ويا إلهي… ما كان يتكون سابقًا من 10 أسطر من التعليمات البرمجية أصبح الآن يتكون من مئات الأسطر عبر العديد من الملفات بفئات معقدة ومزخرفات وما إلى ذلك. أتوقع أن Ember مرت بلحظة React وقررت أن تجعل الأمور معقدة حقًا مرة أخرى. يبدو أن مكونات السمات لم تعد سهلة الآن، مع واجهة برمجة تطبيقات بسيطة للأدوات المصغرة، بل تتطلب ترميزًا مكثفًا…

[david (David Taylor)]

@ddsgad نعم أنت على حق، معظم هذا الدليل قديم جدًا. لقد كنت أعمل على تحسينات عامة للوثائق مؤخرًا، وآمل أن يتم تحديث هذا الدليل/استبداله في الأسابيع القليلة القادمة.

كما ذكرت، يمكن أن تكون الأمثلة الواقعية مثل DiscoTOC مرجعًا جيدًا. وهنا بعض الأدلة المحددة الأكثر حداثة:

• Install the Discourse Theme CLI console app to help you build themes

• Using Plugin Outlet Connectors from a Theme or Plugin

• Customizing the topic list

• Introducing Discourse developer toolbar

للحصول على معلومات عامة حول Ember ومكوناتها، أوصي بالاطلاع على أدلة Ember.

[ddsgad (DDSGadget)]

شكراً على تلك الروابط. مفيدة جداً. حالياً، نقوم بشكل أساسي بتخصيص الأشياء في موضوع نقاش (المنشور الأول) لإنشاء بعض التصاميم الأفضل، لذلك تمكنا من فعل كل شيء تقريباً باستخدام جافاسكريبت العادية (querySelectorAll وما إلى ذلك) و SCSS، لذلك أعتقد أننا سنلتزم بذلك في الوقت الحالي.

[david (David Taylor)]

تم الآن استبدال البرنامج التعليمي الطويل والقديم في المنشور الأصلي بمعلومات تمهيدية/إرشادية عامة أكثر، بما في ذلك رابط إلى برنامج تعليمي جديد من 7 خطوات يتبع أنماط تطوير سمات أكثر حداثة.

[Arkshine]

لقد قرأت كل شيء، استمتعت به! شرح جيد جدًا، ومقدمة ممتازة!

[NateDhaliwal]

أنا أحب هذه الأدلة! لقد تمكنت أخيرًا من فك رموز api.decorateCookedElement، شكرًا على الوثائق المفيدة مرة أخرى!