Is there a theming 'map'? (An easy way to find plugin-outlets etc)

I’ve gone through the brilliant plugin and theme component guides, however I’m still a bit stuck on where to quickly find the template/components/widgets/plugin-outlets I need.

I thought I’d start with 3 simple edits - if anyone can point me in the right direction that would be a great help :blush:

Which template, component or plugin-outlet do I need to make changes to these?

  1. The <title> tags in the <head> of the html of the show Topic page (so when viewing a Topic). I need the change to show to bots as well as humans.
  2. The markup of the category boxes when anywhere they are shown. (These: AdminCP > settings > category style.)
  3. About page (where to change content in Admin and Moderator blocks)

When theming on other forum software you would usually have a parent which would contain references to everything that makes up that page, making it easy to quickly find the templates you need to edit. For instance, there would be a forumdisplay (view Category in Discourse) file/template which would contain the main html then reference all the other templates. Another for the showthread page (so the show/view Topic page on Discourse), another for member profile page, etc. These would act like a list or map of where to find what you need. So if you wanted to edit, say, the underlying posts markup, you would go to the showthread (I.e view Topic) file or template and then look through it and you’d spot that you need to edit or look in the postbit template.

Do we have anything like that? If not would the team please consider adding something similar? It would be a huge help :slight_smile:

6 Likes
7 Likes

I’ve seen that (sorry should have mentioned it!) and it’s very helpful for visible plugin-outlets, but what about for templates/components/widgets etc? How are you quickly and easily finding them Robert? Any idea where the ones mentioned in the first post are?

1 Like

My advice is always to start simple. Work on a simple requirement first and work out how to do it. Then move on to the next.

As far as Theme-ing goes, I would say that most of that will be modifications to CSS. Use the usual resources. Where it’s not you will need to consider modifying templates with jQuery, or at a push overriding templates. Build your own components or widgets for novel use cases and attach them.

The source code is always your friend, look through the GitHub directory structure for discourse/discourse and you will find the different bits of the app laid out. The templates are the easier side to understand I think. If you are not familiar with the Ember directory structure, now is the time to get familiar.

5 Likes

Yes, definitely. I’ve been building themes for almost as long as Discourse has existed, and I’m constantly referencing the source in a separate window.

Generally for templates you want to be looking here discourse/app/assets/javascripts/discourse/templates at master · discourse/discourse · GitHub

and for widgets here discourse/app/assets/javascripts/discourse/widgets at master · discourse/discourse · GitHub.

Sometimes it’s not immediately clear where a template is, because maybe it’s a component that gets nested within another template… if I can’t remember what I’ll end up doing is searching the source for a specific piece of markup…

So for example if I’m looking to add something to the about page… I can see that the body of the about page has a unique class about-page, so I’ll start searching for about and body-page (which is another class on the page).

To answer some of your questions:

I think this requires a plugin, which is outside of my expertise… maybe someone else can be more helpful

There are different templates for the different page layouts, but assuming you’re talking about one of the “Boxes with…” layouts

discourse/categories-boxes.hbs at master · discourse/discourse · GitHub

discourse/about.hbs at master · discourse/discourse · GitHub

11 Likes

Thanks for the replies both :slight_smile:

That’s what I thought I was doing (I don’t think you can get much simpler than editing the title tags). On other forum software I would just open the file/template for the ‘showthread’ page and edit it, it would literally take less than a minute and I would love Discourse theming to be this easy (however it is possible that my not being familiar with Discourse theming right now is why I’m feeling lost).

That’s what I think I need for all of the items in the first post because they need to modify existing content (rather than append or prepend in a specific place which the plugin-outlets seem to be geared towards).

I think that is quite possibly the issue here. I don’t know Ember and maybe that is what’s making this feel somewhat alien. I would love for something like Plugin outlet locations theme component but for templates and everything else that can be customised - that would be a huge help.

How do you find what you need though Kris?

Ah thanks, that’s really good advice!

Are you sure Kris? I thought plugins (or plugin-outlets) only let you add something in the place of that particular outlet. Whereas to change the title tag format I would probably need to open the exiting template (or component or widget) and copy/edit that. At least that’s my understanding after having read the two guides on plugins and theming.

Thank you! That looks like the one I need :smiley:

Thanks again, haha! Both of those look relatively straightforward to find now given their naming and you pointing them out. I think being stumped on changing the title tags may have been a factor :relaxed:

At the moment it feels like I am missing something, and as @merefield pointed out it may be my unfamiliarity with Ember. Does anyone know of any YouTube vids that quickly walk you through it? Perhaps your or @merefield could do one? :blush:

1 Like

Ember is really worth learning. It’s very powerful, extensible and fast.

Reading this will help make the source code make more sense:

Read up on Templates, Computed Properties, Router and Components.

Discourse isn’t exactly like a vanilla Ember app but the guides really help in any case.

One more BIG tip: identify an existing (good) plugin that achieves something similar to what you want to achieve. Look at the code and copy the approach.

7 Likes

Thanks Robert! It’s saying that version of the guides is old - is Discourse using that version or should I read the latest, 3.15 guides?

1 Like

Read 3.10 for now. It’s what Discourse currently uses. If you open the javascript console you will see the version of Ember and jQuery an instance is running.

Also be aware there are various ‘styles’ of code decoration. So things in the source code can sometimes vary slightly.

7 Likes

Unfortunately that’s not it :–(

Also tried these:

I created a theme component and added the following to it:

<script type="text/x-handlebars" data-template-name="components/categories-boxes">
 test
</script>

But changing the data-template-name with all those has no effect. (When I change it for components/topic-list it works.)

Any ideas where this template is?

This is what I want to edit (but when the box format is shown, from; AdminCP > settings > category style):

Any help greatly appreciated.

1 Like

So it looks like this is not possible with theme components as there doesn’t seem to be any templates/components for this :sob:

Appears this Ruby module is injecting inline styles: https://github.com/discourse/discourse/blob/888e68a1637ca784a7bf51a6bbb524dcf7413b13/lib/category_badge.rb

Was this meant to be a temporary measure? If not, do you think it would be possible to allow us to specify custom styles please @sam?

It code be tied to the existing none option, where we could have two fields in the admin settings panel where we could paste our styles for each (if no styles are pasted it just acts like the none option acts now):

<span class="badge-category-bg" style="background-color: #25AAE2;"></span>

and

<span style="color: #FFFFFF;" data-drop-close="true" class="badge-category clear-badge restricted" title="A category exclusive to members with trust level 3 and higher."><svg class="fa d-icon d-icon-lock svg-icon svg-string" xmlns="http://www.w3.org/2000/svg"><use xlink:href="#lock"></use></svg><span class="category-name">Lounge</span></span>

From this snippet:

We would just need access to the background colour and text colour variables from the usual category-edit page.

Or is there any other way we can edit this Sam? I just want to remove the background colour and give it a border that is the same colour as the text (as specific in the usual category-edit page).

Any help would be greatly appreciated.

Edit: appears that it’s not that Ruby file after all (I edited it on my dev install but nothing changed)… further digging and it seems like it’s this one: https://github.com/discourse/discourse/blob/b25d9e96c1414bf78b44221da4d385675843991e/app/assets/javascripts/discourse/helpers/category-link.js.es6 is there any way to create a plugin to modify it?

2 Likes

Probably multiple ways to do this.

Try this:

  • override the template that invokes that helper
  • substitute it for a helper of your own

Template in question: discourse/topic-list-item.raw.hbs at c6e255f4e00400b8a6f82a799b7fa082b17adb1c · discourse/discourse · GitHub

Overriding a template so low in the hierarchy is relatively low risk.

Another way might be to use jQuery within an override of the topic-list-item Component to perform the modifications you need.

5 Likes