Allow use of home-assistant icons in template card secondary.

[thybag]

Description

This PR allows mushroom card's to use home-assistant icons in their secondary state area by defining these as :mdi:home-assistant: within the templates.

This allows template cards for example to be setup to show an icons for any device that is currently turned on, e.g.

This can also be used to allow for inline icons, for example next to displayed temperature values such as in the link ticket.

This has been implemented via adding a parseIcons function to the state-info.ts, which uses a rejex to swap out bracketed values, e.g. :mdi:icon-name: for <ha-icon icon="mdi:icon-name"></ha-icon>. I've wrapped this in a fragment in order to render the added HTML as part of the TemplateResult. I've additionally tweaked the css to ensure the icons are an appropriate size for the context.

I've never worked with TypeScript or Lit components before, so apologies if I've set them up wrong/butchered them a bit. Please let me know if there are cleaner ways of approaching this.

I'd be appreciative of any guidance as to whether this change would warrant a documentation update, assuming this functionality is something that is seen as desirable to have added.

Re: code style - I ran the prettier command to format my change. I wasn't able to easily locate any additional document on the code style choices, beyond attempting to be similar to what is already there.

Note:

• I've currently implemented icons as {mdi:sofa} as its nice and simple, although it'd be easy to swap the regex to look for { icon:'mdi:sofa' } instead.
• The change will technically allow raw html rendered in the secondary (as it bypasses the escaping in order to add the icons). Given this content is edited by the owner, I don't think* this should be a problem (this is also possible via the HA markdown cards) but is probably worth flagging in case this is a concern .

Related Issue

This PR fixes or closes issue: fixes #327

Motivation and Context

I currently use template cards for each room of my house, which then contain logic to show a Unicode icon for each device that's is turned on in the given room within the cards secondary area. Unicode is far more limited in the range of icons i can use, so I had a go at this in order to allow for much better identification of specific devices - ie. is it a lamp or main light that's on.

Other use cases include in-line use of icons next to figures displayed (power usage by a device, a temperature reading etc)

How Has This Been Tested

I've primarily tested this on my own home assistant instances by swapping out the build JS imported by hacs.
I've tested a variety of icons, although as far as I'm aware only the template card allows me to directly control what text (and thus icons) are output in the secondary area.

I could make the behaviour available to content on the chip templates or names, if that was a desirable extension to this.

Tested in

• Chrome 123.0.6312.86 (windows)
• Edge 124.0.2478.10 (windows)
• Firefox 124.0.1 (windows)

Types of changes

• 🐛 Bug fix (non-breaking change which fixes an issue)
• 🚀 New feature (non-breaking change which adds functionality)
• 🌎 Translation (addition or update a translation)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have tested the change locally.
• I followed the steps if I add a new language .

[piitaya]

Hello 👋
Thank you for the contribution.
If this is used for template card, the parsing must be located in template card because state-info component is used in every card. Also, we should check if the text contain emoji before the replacement to improve performance (there is no need to call document.createRange().createContextualFragment if there is no icon in the text)

Also, for the icon format with brackets, I'm not sure because bracket already have a role in jinja template. Github is using :emoji: format for emoji. I wonder if we can have something like :mdi:home:. What do you think?

[thybag]

Hi @piitaya

Thank you for the quick feedback!

I've reworked the logic as you suggested so that

• The parse icon functionality now lives in the template card itself rather than state-info
• The icon format is now :mdi:icon-name:
• I've added a check to avoid the createContextualFragment if the secondary doesn't contain any matched icons

I've also retested on my local and everything still appears to work happily for me.

Re: the icon format, I think the only thing that feels a bit off with :mdi:home: is that it ends up with 3 : - although I think that's unavoidable assuming support for non-mdi icons is wanted and isn't really an issue in normal use. I guess the other aspect worth considering re: the original tickets proposal is that if you went with something like { icon:'mdi:sofa' }, it'd be a straightforward evolution if you ever wanted to support color etc {icon:"mdi:sofa" color:"#fff"}.
That said, I do agree the { approaches risk it being confused for the jinja templates.

[TurnrDev]

If you added markdown support, we could use the ha-icon attribute
<ha-icon icon="mdi:temperature-celsius"></ha-icon>

[thybag]

Hmm, markdown support could be a more flexible approach.

I see similar suggestions ages back #767 and #1189 more recently.

[thybag]

Looking at my code change, i actually think a general html solution would be pretty trivial (my original change enables it as a side effect), so updating everything to the latest and wrapping everything in the createContextualFragment would likely be all that's needed. Markdown would prob need to import a parser (assuming we can't grab a top level one from HA), although main impact I imagine is overhead of running md parser over all the text in the template version.

In the older ticket I saw piitaya wasn't 100% sold on the idea of allowing markdown or html, given it'd no longer be possible to keep styling consistent for all the possible combinations. I guess on the flip side, most the people using html/markdown are likely the sort to have cardmod adding custom styling/design choices anyway so guess it'd be on them to make stuff look nice if they changed anything substantially.

Be happy to have a go at adding the feature if @piitaya is open to the idea.