Discourse Bars 🍻 🍸 (a sidebar framework)

[merefield (Robert)]

Overview

A Theme Component that allows you to lay out Components (“widgets*”) on top and side bars

• Specify a set of “widgets” distinctly for Route and Position.
• Supports setups for each of: discovery^[1], topic, tag^[2], category^[2:1], categories^[2:2] or the new custom homepage!^[3]
• “Bars” can be either: top, left, right OR alternative right location.
• Each bar can be collapsed or dismissed (refresh browser to reset dismiss).
• Handles the Official Sidebar, but if you intend you use a Bars Left Sidebar, the Dropdown mode of the official Sidebar is recommended (change setting navigation menu to “Dropdown”)
• It comes with existing example settings that show some big letters, partly as a demo and partly so you can see example settings. Delete these and replace with your own Component names.
• Ships with one Component: bars-custom-html (see pre-filled example settings) - but components from many existing Theme Components & Plugins are compatible.
• Mobile support is not yet implemented.

Quick Links

Get the code	https://github.com/merefield/discourse-tc-bars
See the code	GitHub - merefield/discourse-tc-bars: A Theme Component that allows you to lay out Components ("widgets") on top and side bars
Installation Guide	Install a theme or theme component

Enjoying this Theme Component? Please it on GitHub !

Gratuitous example:

Upon first load:

Some important things to note about this TC!

• This Theme Component is mainly intended for developers and administrators that have some technical understanding of Theme development. If you are not sufficiently technical and need help with implementing sidebars using Bars, you can hire me or a developer in marketplace

• This Theme Component is intended to provide a framework for supporting sidebars. It does not and is not intended to provide final visual polish which you will need to add in your Theme with additional CSS. However, it does a lot of work for you and gives you less things to think about and maybe even give you the ability to do things you didn’t have the ability to do before …

• Consider this a little experimental at this stage! Be prepared for potential volatility in function and styling selectors

Component considerations

• You must specify a Component name. The component name is in fact the same as the filename in the theme, tc or plugin component directory without the suffix.

  • the component name is not the name of the Theme Component (which could hold many Ember Glimmer Components), it’s the name of the actual Ember Component file , so e.g.:

  

  so layouts-tag-list

• They can be from an existing Theme Component or Plugin. Existing Components may work. Examples are:

  • 🏷️ Tag List Widget (Bars & RSB Theme Component)
  • Render a component within a Widget. (Using select-kit components within plugin code) - #31 by merefield
  • Discourse AI Topic Summary: 🤖 automated summaries and smart tagging … and possibly even:
  • The Leaderboard widget: discourse-gamification/assets/javascripts/discourse/components/minimal-gamification-leaderboard.js at main · discourse/discourse-gamification · GitHub (let me know if you try it down below!)

• It requires some expertise to build Components

  • But have a go at building your own Component in another Theme Component and make sure they are both active in the same Theme.

• Components must source their own data (they can’t use plugin outlet pass-through models unfortunately due to the specific plugin outlets required to be used to lay things out in this way)

  • Out of the box, you can only use existing json API data from e.g. Discourse core or ones provided by an existing Plugin. If you need bespoke data that you can’t source from current API’s, you can hire me or someone in marketplace to help you.

• You may need to style the sidebar and component boundaries to taste. (again if you need help, consider hiring a developer).

  • Strategic use of box shadows and borders can make things look really nice - be artistic!

Why

• With the update of Discourse core to Ember 5, the trick Pavilion’s plugin Layouts used to provide an excellent way to manipulate the Discourse layout ceased to work. There was now no easy way to show a sidebar on a Topic route via a relatively easy end-user interface.

• In addition, Ember introduced Glimmer Components that were much nicer to work with. (Layouts used the Widgets API which is deprecated in favour of Glimmer Components).

• Finally Discourse core team provided a new JSON editor for Theme Component settings which made deploying a more complex setting possible

• Rather than fix the Layouts plugin (TC’s didn’t exist back in Layouts day), it made sense to rebuild as a Theme Component, because we can achieve most things we need just in the front end.

• Enter “Bars” Cheers!!

Known Issues

• Top bar doesn’t stick (I may remove the corresponding setting if I can’t resolve).

Credits

• Spiritual successor to the now broken Layouts Plugin built by @angus (Cheers!) which served us well for many years.
• Uses the params system from Right Side Blocks (thanks @pmusaraj!)

---

1. the term ‘discovery’ (route) refers to the main Topic List pages (e.g. “Latest”, “New”) that allow you to browse available Topics before clicking and diving into a specific one. ↩︎

2. technically also a “discovery” route but we’re breaking these out to distinct names so you can treat them differently if you so choose. ↩︎ ↩︎ ↩︎

3. currently not yet available on stable, only tests-passed. See here for more details. So that this remains optional (not all installers of Bars will want a custom homepage) Bars does not add the required modifier in about.json so you must add this in the parent Theme or another TC to activate it. ↩︎

[Lilly]

woah, this is cool! Nice work Robert. Thanks for doing this and making it available!

forked!

[thoka (Thomas Kalka)]

I’m quite at the beginning of learning how to add custom widgets, but: I would love an option to add widgets in a non-scrolling footer in the mobile view.
Would this be possible with a future version of this component?

[merefield (Robert)]

No plans to add additional “bars” at this stage but maybe once things settle down and the TC is clearly stable …

… PR or sponsorship always welcome too

[denvergeeks]

This looks awesome - Thank You! Could you please provide an example for what the settings look like for including the Tag List Widget in one of the sidebars?

For example, from the instructions it seems this should work…

But the left sidebar still only shows the big-a…

[merefield (Robert)]

Two things:

First, here are similar settings from StarZen:

The component name is in fact the same as the file name in the Component (i’ll add that to the OP)

StarZen

Secondly, it’s really silly, but you have to press Save and hit the tick after hitting Save.

It’s a double Save!

That’s the nature of cores current theme setting, not bars. I might add a note about that in the OP.

[denvergeeks]

@merefield

Secondly, it’s really silly, but you have to press Save and hit the tick after hitting Save.

It’s a double Save!

Yes, I did the double Save

Still, I must be missing something because the result is the same. Is there something else I can provide to help?

[merefield (Robert)]

Share your settings json (button at bottom of TC).

[denvergeeks]

[
	{
		"setting": "bar_components",
		"value": "[{\"component_name\":\"layouts-tag-list-widget\",\"route\":\"discovery\",\"position\":\"left\"},{\"component_name\":\"big-b\",\"route\":\"discovery\",\"position\":\"left\"},{\"component_name\":\"big-c\",\"route\":\"discovery\",\"position\":\"right-alt\"},{\"component_name\":\"big-d\",\"route\":\"discovery\",\"position\":\"right-alt\"},{\"component_name\":\"big-e\",\"route\":\"discovery\",\"position\":\"top\"},{\"component_name\":\"big-f\",\"route\":\"discovery\",\"position\":\"top\"},{\"component_name\":\"big-c\",\"route\":\"topic\",\"position\":\"right\"},{\"component_name\":\"big-d\",\"route\":\"topic\",\"position\":\"right\"},{\"component_name\":\"big-e\",\"route\":\"topic\",\"position\":\"top\"},{\"component_name\":\"big-a\",\"route\":\"categories\",\"position\":\"left\"},{\"component_name\":\"big-c\",\"route\":\"category\",\"position\":\"left\"},{\"component_name\":\"big-b\",\"route\":\"tag\",\"position\":\"right\"}]"
	},
	{
		"setting": "left_sidebar_width",
		"value": 300
	},
	{
		"setting": "right_sidebar_width",
		"value": 300
	},
	{
		"setting": "sticky_sidebars",
		"value": true
	},
	{
		"setting": "sidebar_sticky_top_position",
		"value": 60
	},
	{
		"setting": "sidebar_height",
		"value": 800
	},
	{
		"setting": "scrolly_sidebars",
		"value": false
	},
	{
		"setting": "top_bar_height",
		"value": 150
	},
	{
		"setting": "top_bar_sticky_top_position",
		"value": 60
	},
	{
		"setting": "sidebar_gap",
		"value": 5
	},
	{
		"setting": "rightalt_sidebar_gap",
		"value": 5
	}
]

[merefield (Robert)]

Your component_name is still wrong, see my example and you might want to delete the rest.

[denvergeeks]

Hmm… OK I deleted all but the first one, and changed the name to match yours (even though the component name is coming from the TC GitHub - paviliondev/layouts-tag-list-widget: The Tag List Widget allows you to display tags from Discourse in a sidebar using Pavilion's Custom Layouts Plugin. - where would I find that the correct component name is layouts-tag-list?)

However, changing the component name in the modal doesn’t seem to change it in the settings json, or remove the rest of the items, even after double save…

[
	{
		"setting": "bar_components",
		"value": "[{\"component_name\":\"layouts-tag-list-widget\",\"route\":\"discovery\",\"position\":\"left\"},{\"component_name\":\"big-b\",\"route\":\"discovery\",\"position\":\"left\"},{\"component_name\":\"big-c\",\"route\":\"discovery\",\"position\":\"right-alt\"},{\"component_name\":\"big-d\",\"route\":\"discovery\",\"position\":\"right-alt\"},{\"component_name\":\"big-e\",\"route\":\"discovery\",\"position\":\"top\"},{\"component_name\":\"big-f\",\"route\":\"discovery\",\"position\":\"top\"},{\"component_name\":\"big-c\",\"route\":\"topic\",\"position\":\"right\"},{\"component_name\":\"big-d\",\"route\":\"topic\",\"position\":\"right\"},{\"component_name\":\"big-e\",\"route\":\"topic\",\"position\":\"top\"},{\"component_name\":\"big-a\",\"route\":\"categories\",\"position\":\"left\"},{\"component_name\":\"big-c\",\"route\":\"category\",\"position\":\"left\"},{\"component_name\":\"big-b\",\"route\":\"tag\",\"position\":\"right\"}]"
	},
	{
		"setting": "left_sidebar_width",
		"value": 300
	},
	{
		"setting": "right_sidebar_width",
		"value": 300
	},
	{
		"setting": "sticky_sidebars",
		"value": true
	},
	{
		"setting": "sidebar_sticky_top_position",
		"value": 60
	},
	{
		"setting": "sidebar_height",
		"value": 800
	},
	{
		"setting": "scrolly_sidebars",
		"value": false
	},
	{
		"setting": "top_bar_height",
		"value": 150
	},
	{
		"setting": "top_bar_sticky_top_position",
		"value": 60
	},
	{
		"setting": "sidebar_gap",
		"value": 5
	},
	{
		"setting": "rightalt_sidebar_gap",
		"value": 5
	}
]

[merefield (Robert)]

Like I explained above (and have now elaborated in the OP), the component name is not the name of the Theme Component (which could hold many Ember Glimmer Components), it’s the name of the actual Ember Component:

so layouts-tag-list

This is a useful misunderstanding, I’ll clarify further in the OP, using this example.

Not sure why your setting is being sticky

Try deleting the Theme Component and re-adding and going through the same process.

Or just refresh your browser?

[ckshen]

Thanks for the work @merefield !

Functionally how does Discourse Bars differ from Right Sidebar Blocks with custom html, besides the fact that the location doesn’t have to be only on the right ?

Right Sidebar Blocks

Summary Right Sidebar Blocks shows a sidebar to the right of topic lists with a configurable list of blocks. It’s a refactor of the sidebar blocks plugin. Repository Link https://github.com/discourse/discourse-right-sidebar-blocks New to Discourse Themes? Beginner’s guide to using Discourse Themes Install this theme component The component includes a few blocks you can display in the sidebar: popular-tags top-contributors recent…

[merefield (Robert)]

Bars is the spiritual successor of Pavilions Layouts which came before RSB.

But compared to RSB, mutli-route and multi-position support mainly (Bar’s target is to reproduce the usefulness and flexibility of Layouts), the critical addition being Topic route support. Plus I don’t presently support params … I’ve yet to hit a use case. I also don’t bundle any components aside from the demo big letters - this is deliberate and this is meant to be more of an Admin/Developers framework (much like Layouts was).

The roadmap might be more ambitious too - if I get funding I may add the mobile functionality that Layouts had - anyone is free to contact me to sponsor that work.

[denvergeeks]

OK I deleted and re-installed both the bars TC and the layouts-tag-list TC (I tried removing and re-adding them both individually and together) but the results are all the same. And I did refresh every time as I had before as well. I also cleared my browser cache.

[merefield (Robert)]

I cannot reproduce your issue of stuck settings. I just added and removed a left sidebar.

I’d be interested in other reports of the same.

[denvergeeks]

Thanks for your time spent trying – I’ll try it on some of my other Discourse instances later today and report in again.

[denvergeeks]

I have also now also removed all plugins, and rebuilt (and have no other TCs or themes installed), and it is a fresh install from last night.

In case it’s helpful, I did discover that, with the same settings as above, while the left sidebar is not appearing anywhere else, it is showing on the /latest route (albeit only the title “Tags”, without showing any tags.)

---

---

---

---

And here is the settings json…

[
	{
		"setting": "bar_components",
		"value": "[{\"component_name\":\"layouts-tag-list\",\"route\":\"discovery\",\"position\":\"left\"}]"
	},
	{
		"setting": "left_sidebar_width",
		"value": 300
	},
	{
		"setting": "right_sidebar_width",
		"value": 300
	},
	{
		"setting": "sticky_sidebars",
		"value": true
	},
	{
		"setting": "sidebar_sticky_top_position",
		"value": 60
	},
	{
		"setting": "sidebar_height",
		"value": 800
	},
	{
		"setting": "scrolly_sidebars",
		"value": false
	},
	{
		"setting": "top_bar_height",
		"value": 150
	},
	{
		"setting": "top_bar_sticky_top_position",
		"value": 60
	},
	{
		"setting": "sidebar_gap",
		"value": 5
	},
	{
		"setting": "rightalt_sidebar_gap",
		"value": 5
	}
]

[merefield (Robert)]

You are going to have to debug that for yourself - check your console, theme CSS etc.

Works for me:

Can’t recall if Layouts Tag List requires Tag Groups … might do!

[denvergeeks]

@merefield

Can’t recall if Layouts Tag List requires Tag Groups …

Yes enabling Tag Groups in the settings (and then creating some Tag Groups) did make the tags appear.

However, setting the route for the component item to discovery still only shows the left bar on /latest, /new and /top lists.

Could you be so kind as to point me toward a list of all available “routes” that can be used here?

Thank you again!