主题修饰符：简要介绍

[Discourse]

随着主题变得越来越宏大，我们一直在寻找允许它们操纵核心 服务器端 行为的方法。虽然它们永远不会获得与插件相同的控制级别，但我们可以为主题提供一些预定义的钩子来进行操纵。

隆重推出：主题修改器

它们在主题的 about.json 文件中使用 modifiers 键指定。

有关修改器的 100% 最新列表，请查看 theme_modifier_set.rb 末尾的数据库架构，但以下是我们目前所拥有的快速摘要：

• serialize_topic_excerpts 布尔值 (默认为 false) - 在序列化主题列表时始终包含摘录

• csp_extensions 字符串数组 - 向 CSP 添加指令。其工作方式与旧的 “extend_content_security_policy” 主题设置方法相同。但请记住，简单的 \u003cscript src=\"\"\u003e 标签会自动允许。

• svg_icons 字符串数组 - 应包含在图标子集中的图标列表

• topic thumbnails 尺寸数组 - 请求主题缩略图集中的附加分辨率。请注意，它们是异步生成的，因此如果请求的大小不可用，您必须回退到原始图像。更多信息请参阅 提交信息

• serialize_post_user_badges 字符串数组 - 与帖子数据一起序列化的徽章名称列表（与 badges 表中的条目匹配）。配置后，系统会在每个帖子中包含指定的用户名徽章，以供客户端渲染。

一个大量使用这些新钩子的主题是 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 设置时，修改器值将自动更新以匹配。这为站点管理员通过管理界面自定义主题行为提供了灵活性。

---

此文档已版本控制 - 在 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!