Expand documentation

[alex3305]

Sadly I have no idea how to use this. It's not clear to me what any of these mean:

Basic usage

Add a -global-mod theme
Reload your themes

Could you please provide a minimal working example?

Originally posted by @ThomDietrich in #1 (comment)

[alex3305]

HI @ThomDietrich,

Is the example provided in the Home Assistant community more clear for you?

Maybe the documentation should be expanded to be more clear.

[ThomDietrich]

Hey! Thanks for the pointer. I've already played with many constellations and tried to understand what's going on in the background. So far no luck.

With the example in the community, I am seeing this error on the console:

Global mod loaded without any config...
👉 Add a 'mods' section to your theme default-global-mod-global-mod to enable modding.

[ThomDietrich]

Update: I just realized that the sidebar is now yellow in my HA smartphone app. The error seems to be limited to some devices/browsers. My PC browser is Firefox with deleted cache.

[ThomDietrich]

Hey Alex, I just realized what my issue was.
After adding the theme yaml as suggested in your examples, the theme "default-global-mod" is offered under profile settings. Why is it, that all mods work flawlessly, as long as that theme is NOT selected? Please keep in mind that I did never work with HA themes and seem to lack background understanding of how they work.

So in spirit of the title of this issue ticket: It would definitely be worthwhile to add detailed getting started instructions to the README of your project.

[alex3305]

Hi @ThomDietrich 👋,

Sorry for neglecting this issue. Life got in the way, which unfortunately happens sometimes 😉 .

I appreciatie the feedback and I will try to elaborate on the readme so it should be a little clearer. I just created this little project because I needed it myself and than decided to open source it for others to enjoy. Hence the reason why the documentation can be a bit sparse in places.

Why is it, that all mods work flawlessly, as long as that theme is NOT selected?

That's a similarly good question. I think I once created it like that so that global mod would not interfere with custom themes downloaded from elsewhere. However after testing it locally using the original theme name seems to work just as well. I think I'm going to implement that going forward to make global mod a little easier to setup.

If you have any suggestions or comments feel free to bring them up and I will try to answer them the best I can.

[ThomDietrich]

No worries, I totally get where you come from. I've been there. Your project is exactly what I was looking for and I'm sure many more users are interested in it. Which is why I think you could update the README ;)

In summary I think a combination of setup and basic example instructions is all that is needed. It gets complicated quickly right after :) I recon many users will be totally overwhelmed by the knowledge needed to build your own mod. It might be worthwhile to actively collect working mods, just as you've already started. Ideally this list of mods would always include a screenshot and a short explanation why the mod is useful.

I'm struggling with my own mod to remove one column from the device page. I'll come back with the solution after I found it. I wonder if there is anything major you could do by printing information to the console, that would be helpful to build ones mode, e.g. the selector for the last element clicked?

Cheers!