مُعدِّلات الثيم: مقدمة موجزة

[Discourse]

مع تزايد طموح الثيمات، كنا نبحث عن طرق للسماح لها بالتلاعب بالسلوك الأساسي الخاص بالخادم. على الرغم من أنها لن تحصل أبدًا على نفس مستوى التحكم مثل الإضافات (plugins)، يمكننا توفير بعض نقاط الربط (hooks) المحددة مسبقًا لكي تتلاعب بها الثيمات.

نقدم لكم: مُعدِّلات الثيمات

يتم تحديدها باستخدام المفتاح modifiers في ملف about.json الخاص بالثيم الخاص بك.

للحصول على قائمة محدثة بنسبة 100% بالمُعدِّلات، تحقق من مخطط قاعدة البيانات في نهاية theme_modifier_set.rb، ولكن إليك ملخص سريع لما لدينا حتى الآن:

• serialize_topic_excerpts قيمة منطقية (boolean) (الافتراضي خطأ) - قم دائمًا بتضمين المقتطفات عند تسلسل قوائم المواضيع.

• csp_extensions مصفوفة سلاسل نصية (string array) - أضف توجيهات إلى سياسة أمان المحتوى (CSP). يعمل بنفس طريقة طريقة extend_content_security_policy القديمة لإعدادات الثيم. ولكن تذكر، يُسمح تلقائيًا بوسوم <script src=""> البسيطة.

• svg_icons مصفوفة سلاسل نصية (string array) - قائمة بالأيقونات التي يجب تضمينها في مجموعة الأيقونات الفرعية.

• topic thumbnails مصفوفة أبعاد (array of dimensions) - اطلب دقة إضافية في مجموعة صور مصغرات المواضيع. لاحظ أنها تُنشأ بشكل غير متزامن، لذا يجب عليك الرجوع إلى الصورة الأصلية إذا لم يتم توفير الحجم الذي طلبته. مزيد من المعلومات متاحة في رسالة الالتزام (commit message).

• serialize_post_user_badges مصفوفة سلاسل نصية (string array) - قائمة بأسماء الشارات (تطابق الإدخالات في جدول الشارات) لتسلسلها جنبًا إلى جنب مع بيانات المنشور. عند التكوين، يشتمل النظام على شارات المستخدم المحددة مع كل منشور للعرض من جانب العميل.

أحد الثيمات التي تستخدم هذه النقاط الجديدة بكثافة هو Topic List Thumbnails - تحقق من الشيفرة لترى كيف يعمل.

المُعدِّلات المعتمدة على الإعدادات

يمكن أيضًا تكوين مُعدِّلات الثيم لسحب قيمتها من إعداد ثيم، مما يسمح لمشغلي الموقع بتجاوز سلوك المُعدِّل دون تعديل شيفرة الثيم. لجعل مُعدِّل يعتمد على إعداد، استخدم هذا التركيب في ملف about.json الخاص بك:

{
  "modifiers": {
    "modifier_name": {
      "type": "setting",
      "value": "setting_name"
    }
  }
}

على سبيل المثال، إذا كان لديك إعداد ثيم يسمى show_excerpts وتريد أن يتحكم في المُعدِّل serialize_topic_excerpts:

في settings.yml:

show_excerpts:
  default: false

في about.json:

{
  "modifiers": {
    "serialize_topic_excerpts": {
      "type": "setting",
      "value": "show_excerpts"
    }
  }
}

عند تغيير إعداد show_excerpts، سيتم تحديث قيمة المُعدِّل تلقائيًا لتطابقه. يوفر هذا مرونة لمشغلي الموقع لتخصيص سلوك الثيم من خلال واجهة المشرف (admin UI).

---

يتم التحكم في إصدار هذه الوثيقة - اقترح التغييرات على github.

[merefield (Robert)]

David, probably a bit lazy of me to ask but is there any way to access this in a plugin:

Themes can request additional thumbnail sizes by using a modifier in their about.json file:

I will be attempting to migrate the TLP plugin to this new schema and it would be good to have the same access to features from a plugin, at least in the meantime.

[david (David Taylor)]

There isn’t at the moment, but I’ll look into it

[merefield (Robert)]

David, what’s the right approach for BULK recreation of thumbnails?

I’ve just tried utilising on one of my sites and it seems to have processed about 10% of the Topics … then given up (or turned its nose up at the rest). Why I think it’s the former is that the Topics for whom Thumbnails were produced were the latest 10%.

Rebaking posts doesn’t seem to cut it. In fact, I did run a bulk rebake and wonder if that upset it …

I notice that image_url can be populated, but there are no thumbnails.

Any advice, appreciated!

[david (David Taylor)]

@merefield

image_url can be populated

That column doesn’t do anything, and will be dropped very soon. image_upload_id is the one you want.

@merefield

BULK recreation of thumbnails?

There should be no need for this. I deliberately designed it so that people can install new themes without having to mess around on the console. Thumbnails are generated asynchronously when needed. For example:

• you add a new theme, which requests new resolutions
• a user requests a topic, we serve the thumbnails that exist. If any sizes don’t exist, we schedule a sidekiq job.
• next time someone requests the topic, the correct thumbnails will exist

If the requested thumbnail size is larger than the original, we won’t bother generate the thumbnail.

So the critical thing to bear in mind for this to work is:

@david

you must fall-back to the original image if your requested size is not provided.

There’s an example of this fallback logic in the thumbnail theme component I made - feel free to steal logic from there.

[merefield (Robert)]

The fallback is serialised as thumbnailsl[0]? Yes, I’m already handling that. (nice implementation btw, very easy to handle)

Is it possible some images are ‘not making the grade’ or fitting the criteria?

The behaviour we have in the TLP plugin will pick up one-box thumbnails. That’s not happening in every case here I think.

For example, if you get time, take a look at these examples:

The Original MiRiDER ONE Folding eBike - UK built 2 year warranty

Forget the Car. E-Scooters Could Save The City

How to wash your hands NHS song | NHS

I don’t think these thumbnails make the cut. The thumbnails are serialized as null

[david (David Taylor)]

@merefield

I don’t think these thumbnails make the cut

Yes that’s deliberate - we had a number of requests to remove small onebox thumbnails. For example, people were ending up with their github avatar as a topic thumbnail - which is rarely intended

https://github.com/discourse/discourse/commit/956d15d13fd8056cbf60ca64ebbd1edca00d0125

Note that for oneboxes where the image is the actual content (such as instagram/twitter/etc photos), they will be selected.

As for the youtube video, I fixed that yesterday.

https://github.com/discourse/discourse/commit/0c6f30d92a4090aa7447e2e579a17a180e49ce17

[merefield (Robert)]

Ah great, thanks for confirmation.

@david

As for the youtube video, I fixed that yesterday.

That’s odd, build was more recent, but some still seem to be being overlooked.

@david

Yes that’s deliberate - we had a number of requests to remove small onebox thumbnails. For example, people were ending up with their github avatar as a topic thumbnail - which is rarely intended

Yeah, that’s partly why I ended up implementing a thumbnail picker for the situations where the automated choice wasn’t optimal. I may still want to modify that behaviour, but I will try to do so in the plugin.

Thanks for your time David!

[merefield (Robert)]

OK, I’ve worked it out. After a somewhat fruitless byebug session I could not work out why older YT posts were not getting thumbnails.

Then is dawned on me. It’s because of this:

So I suggest that actually it might be necessary to rebake after setting this to a rather larger number (365?).

I think I’m right in saying that if something is not uploaded locally, it won’t have a thumbnail created? …

[david (David Taylor)]

@merefield

I think I’m right in saying that if something is not uploaded locally, it won’t have a thumbnail created?

correct, this only works for local uploads… we may need to rethink that “max days old” setting

[david (David Taylor)]

@merefield

would be great to have a plugin only option here

I have a plan, will try and get it implemented this week. One question - do you need the values to be dynamic?

i.e. Will the resolutions be defined at boot? Or at runtime (e.g. via site settings)?

The former is easier… but the latter might be possible as well

[merefield (Robert)]

Thanks for taking a look.

I just need a fixed way, exactly like the theme component.

A site setting would be nice though.

I will add for full disclosure: id like to migrate away from the plugin so parity with theme component solution would be more than enough.

[david (David Taylor)]

@merefield here you go:

DEV: Allow plugins to request topic thumbnail sizes (#9828)

Hopefully the commit message explains how it works, but let me know if you have any questions

[merefield (Robert)]

Excellent. Just added it to TLP and looks like it’s working! Thanks for your help!

[petepan23 (Peter)]

Can we make it work for images from remote server as well? For example, images from Blogger, Picasa, or Amazon S3?

Because Discourse supports hosting on Amazon S3 for big and large image site, now if everything needs to be hosted on the local server directly then this design methodology seems to be a drawback.

With this update, it’s not an easy fix for my site since we’re using other server to host the images. Now it’s too difficult to move to an affiliated server with many posts, while it’s too big for hosting on local sever.

[david (David Taylor)]

This is only designed to work on Discourse ‘uploads’. Those can be on S3, or some other service, if you use

Configure an S3 compatible object storage provider for uploads

This topic covers how to configure some common S3 compatible Object Storage providers (S3 clones). See Set up file and image uploads to S3 for more details about Amazon AWS S3 configuration, which is officially supported and used internally by Discourse for our hosting services. Provider Service Name Works with Discourse? Amazon AWS S3 Yes Digital Ocean Spaces Yes Linode Object Storage Yes Google Cloud Storage Yes Scaleway Object Storage Yes Vultr Obj…

We recommend using the download_remote_images site setting to automatically download images which are hotlinked from other sites.

[merefield (Robert)]

@david

svg_icons string array - a list of icons which should be included in the icon subset

Hi David, anything special one needs to do to ensure Pro icons can be used in a TC?

[david (David Taylor)]

Nothing special, no. It should work just the same as using pro icons elsewhere in Discourse. I guess you are using this plugin to enable pro icons?

If it doesn’t work let me know and I’ll take a look

[merefield (Robert)]

Yep we are. We’ll have another dig. Thanks for response late your eve!