order the icons table

[Mariusthvdb]

HI all,

now this repo has only just started, and already the need for some extra ordering in the icons table seems required.
before this gets out of hand completely, Id love to hear your suggestions to keep that overview well organized.
@arallsopp pardon the tag, but what do you think?

cheers,
Marius

[arallsopp]

No problem, mate.

To keep mine in order (350+ custom icons, you can imagine the pain!) I've written a PHP script. It:

• reads all of the svg files in a folder, checks they have only one path
• adds the results into an array, then sorts it alphabetically.
• tries to find a matching tag in a json file that holds 'light', 'security', 'lamp', etc. If none found, creates a 'light' entry for it.
• outputs the names and icons over the table in readme.
• outputs the names, paths and tags over the icons section of the .js
• outputs the tags into a json file that I can tweak afterwards.

I tend to run the build process once, then go find the new tag section and add any aliases I need, then re-run to read those new tags back in.

[arallsopp]

The script and json file are in the build folder of my repo.

• index.php creates the output.
• meta.json holds all of the tags.

[Mariusthvdb]

o dear, that is way over my head just yet. Though I confess I've tried to see how this process could be automated...<anually editing those Markdown columns is a true pain.

thats on technique. Do you have any thoughts on content? should we distinguish types of icons? or maybe alphabetically sort them?

[arallsopp]

that is way over my head just yet

I feel your pain, mate. Hass-hue-icons was a massive learning curve for me. Its really repaid the time I've put in though, so am excited for the journey you have ahead.

editing those Markdown columns is a true pain

Oh, absolutely. Drove me right to the edge before I automated it. I was spending more time trying to battle syntax for the documentation than I was creating actual icons. There are free Markdown editors out there (https://dillinger.io/ is a good online one) but remember the images won't work until you've added them to your main branch. That's why I tend to push twice in my repo. Once for the images in svg format, then again after the build (or manual tweak of readme) to see the update.

should we distinguish types of icons

I think its good practice to start tagging as you go. I use "light", "infrastructure", "tv", "sync", "spot", "ceiling", "exterior", "room", etc, as well as aliases if they don't appear in the filename. eg: centura-round is the same as milliskin, so my tag for that entry includes this.

As the library expands, you may need to be able to group in the readme. I differentiate only between icons I've extracted and resized from the Hue developer pack, vs those I've created for community driven requests. For your repo, this could grow exponentially. At the moment, they're all devices or lights. Perhaps review when the icon count gets bigger?

maybe alphabetically sort them?

Alpha sort within a category will be good. If there's only one category, then the place for each icon is relatively simple to work out at time of addition. I use alpha sort just because it stops me from creating two with the same name, and helps to group similar things together. Even then, I probably mis-stepped with some of the groups, as I'm inconsistent between multi bulb appliances (eg hue:ceiling-buratto-three) and groups of the same fixture (hue:bulb-group-bollard-3). Similarly, if I later became aware of a variant I hadn't expected, eg: hue:adore vs. hue:ceiling-adore-alt-flush.

You won't please all people, but search is pretty good so if someone is scanning your readme for a particular device (say, iPhone), they'll find it, whether its under mdi-legacy, or devices, or whatever.

Because I use that json file, I could add code to generate my readme by tag. I don't think it'd be any easier to read, mind. :)

[arallsopp]

Ps. Sorry, I've just realised you had alphabetised the readme, and I made a PR that added the new ones to the bottom.

[arallsopp]

@Mariusthvdb: Ok. I've had a thought. Its not a brilliant thought, and its a little lonely, but it could lead to something that really helps you... Stand by for updates :)

[arallsopp]

And here it is: https://youtu.be/Hl64GA1TvkI

A single html file that you can open in a browser on your machine, that will take a paste of a json file (in this example:

{
 "icons": [
   { "name": "apple-homepod", "author": "arallsopp"},
   { "name": "laptop-mac",	"author": "arallsopp"},
   { "name": "delete-alert", "author": "[@idevo89](https://github.com/idevo89)"}
  ]
}

and which will build you an alpha sorted markdown table that you can copy straight back out. There's no error handling or tolerance in there, so you just need to know:

• the icons list has to be present.
• every item in the icons list needs a name.
• every item in the icons list needs an author.
• the image is assumed to be whatever the name is, with a .svg on the end

You can use markdown within the author tag to create an author as an hyperlink.

What do you reckon? Worth playing with? If so, I can make it list two columsn and copy the single html file into your docs folder via pull request.

[Mariusthvdb]

wow. that is really magic! yes, that is useful..... understatement the year.

dont know what to say tbh.

would it help if I 'promoted' you to a maintainer here, so you can have a go at it? you're my main sponsor as it is ;-)

[Mariusthvdb]

btw, just checked these repos on mobile, and it seems a 2 column table fits perfectly, while the 4 columns we have now is really nasty scrolling horizontally tbh.

[arallsopp]

Lol. Ok, I just made it handle two column in the markdown... I'll back that out and push it up to your repo, mate.

[arallsopp]

Tell you what, let's keep two columns as an option, off by default:
https://youtu.be/TWWiYac7EkI

[arallsopp]

Right. That's up as https://github.com/Mariusthvdb/custom-icons/tree/main/docs/build

We could probably make it a github pages site, so that you could just load the url directly, but what you've got should run happily in your local machine. I'm assuming you have these files somewhere on your local? Just need to pull to bring it into sync, then load the html file in a browser. There's no fault tolerance, so go carefully on the JSON. It'll tell you if its wrong, but not where. Sites like https://jsonlint.com/ make it easier to write correctly.

Apologies for wading in. I couldn't bear the thought of you having to do that manually. I remember those days all too well 🤣

[Mariusthvdb]

nvm me, ive made it... I didnt realize I had to create a local html file.... got that now, and will experiment, but it seems so very easy and straightforward I dont need to experiment at all!

magic!

[arallsopp]

Key to it will be keeping your json file up to date. As long as you have that file, you can paste it in and rebuild the table whenever you like.

I’ve created a sample.json, but it’s already out of date. Good to see icon list growing. Well done.

[arallsopp]

I’ll add a standard width to the table descriptor, mate. Looking a little irregular right now.

[Mariusthvdb]

hmm, besides a few typos I made, which I fixed meanwhile, wasnt the output supposed to have a linked author name/handle automatically?

because now it shows as

[Mariusthvdb]

hmm, maybe the hot linking on each line isnt required, just the name.
and then add a legend of sorts with unique handled with link?

[Mariusthvdb]

I think when cresting a new release, the list of new icons needs top be listed. Would that be something that can be automated too?
otherwise it soon will become quite an administrative burden....

and, I do believe it would be cool to have some automated file to paste in a lovelace config, so we can check if the icons really get loaded correctly in the HA dashboard

[Mariusthvdb]

When I look, I see the icons as different sizes, so I've just tweaked the file to generate image tags at 24px.

The big icons are a treat to look at, compared to the smaller icons. Especially on mobile, where the small ones are barely visible.
I think we need to change all icons to be that size. And let the width setting take care of the table, and probably Dashboard (but in Lovelace a size setting is used anyway)

[arallsopp]

Ok. Let me know the size you want and I’ll tweak the helper. 32px maybe?

[Mariusthvdb]

I think it's not the helper, but the icons themselves I need to edit? I am not talking about the display inside the table, but the view you get when clicking any of the icons in the table.
probably need to delete the width="24" height="24" from these icons? and keep the viewBox="0 0 24 24"

[Mariusthvdb]

[arallsopp]

I use a standard descriptor viewbox at 24px for all of my icons. Because I’m drawing them, they all come out the same size and weight.

If you copy the path from one of your big files over the path for in one of your correctly sized files, does it show correctly?

[Mariusthvdb]

I've just edited your HomePod files (wait a bit for the cache to refresh) and the cellphone-phone, which is already resized upon click, so you can see for your self. Since the .js file only holds the path, all seem to be ok doing so?
Its only about the display in the repo after all.

[arallsopp]

I'm about to push a commit that will let you specify whether to generate the markdown using image tags (which have sizes) or use the native size of the svg.