A card using manually created HTML elements

[lisz8]

I was told to show a real-world example using hand-crafted HTML elements. The purpose of the card is to list files containing text. This is a wrapper around shell_command that calls grep (I have a HAOS installation; the shell_command may not work in other installation types). The card code includes predefined options: where to search, subfolders to exclude, and filename masks to include. These options can then be enabled/disabled for each search.

Using HTML elements requires noticeably more code than using just yaml; I have a template containing repeatable code and I added part of that template (the whole template is large). I'm not a professional programmer, so keep that in mind :) I'd be grateful for any opinions and advice.

The idea is that the template creates an object in the window containing all the helper functions and data. The object name is the _UUID variable, and each card using the template should have it set to an unique string. The object should also be extended by adding at least a few functions that will be called by the template when an UI event occurs. The function names are just convention: tabChange2, btnPress2, etc. Within such a function, elements can be distinguished by their IDs.

Shell command

shell_command:
  files_containing: >-
    bash -c 'grep -lr {{- 'i' if not caseSensitive|default(false,true) }} {{ '--include=' ~ ' --include='.join(includes) ~ ' ' if includes|   default(false,true) -}} {{ '--exclude-dir=' ~ ' --exclude-dir='.join(exdirs) ~ ' ' if exdirs|default(false,true) -}} {{ ' '.join(dirs) }} -e "{{text}}" || echo "No results"'

Template:

button_card_templates:
  ui_elements:
    name: '[[[ return variables._UUID ? null : ''Set the variable _UUID''; ]]]'
    disable_kbd: true
    variables:
      _UUID: ''
      _DIVIDER_COLOR: lightgray
      _DIVIDER_WIDTH: 2px
      _TABLE_HOVER_COLOR: var(--primary-background-color)
      _TABLE_SELECT_COLOR: var(--light-primary-color)
      _ICON_COLOR: var(--state-icon-color)
      _ICON_EXCITED_COLOR: var(--accent-color)
      _all: |
        [[[
          if (!variables._UUID) return;
          const UUID = variables._UUID;
          const DIVIDER_COLOR = variables._DIVIDER_COLOR;
          const DIVIDER_WIDTH = variables._DIVIDER_WIDTH;
          const TABLE_HOVER_COLOR = variables._TABLE_HOVER_COLOR;
          const TABLE_SELECT_COLOR = variables._TABLE_SELECT_COLOR;
          const ICON_COLOR = variables._ICON_COLOR;
          const ICON_EXCITED_COLOR = variables._ICON_EXCITED_COLOR;
          if (!window[UUID]) window[UUID] = {
            IS_TOUCH: 'ontouchstart' in window || navigator.maxTouchPoints > 0 || navigator.msMaxTouchPoints > 0,
            UUID, DIVIDER_COLOR, DIVIDER_WIDTH, TABLE_HOVER_COLOR, TABLE_SELECT_COLOR, ICON_COLOR, ICON_EXCITED_COLOR,

            /* functions that will be called after the card update */
            updateListeners: [],
            async addUpdateCallback(callback,timeout=2000,autoremove=true) {
              if (!callback) return;
              let listener = {
                presolve: null,
                update() { this.presolve?.(); },
              };
              this.updateListeners.push(listener);
              let pSuccess = new Promise(resolve => listener.presolve = resolve);
              let toAwait = timeout > 0 ? [pSuccess, new Promise((_,reject) => setTimeout(reject,timeout))] : [pSuccess];
              try {
                await Promise.race(toAwait);
                callback(true,this.card);
              } catch (ex) {
                callback(false,this.card);
              } finally {
                if (autoremove) this.updateListeners = this.updateListeners.filter(l => l !== listener);
              }
            },
            /* card = this custom button */
            get card() { return this.live.card; },
            set card(c) {
              /* live = an object to get/store references to "live" HTML objects */
              this.live = {
                card: c,
                get(id) { return (this[id] ??= this.card.shadowRoot.getElementById(id)); }
              };
              this.VERSION = new Date().getTime();
              for (let li of this.updateListeners) li.update();
            },
            /* HA Core version as pure number */
            get haVersion() { return (this._haVersion ??= parseInt(this.card._hass.connection.haVersion.replace(/\D/g,''))); },
            
            /* card's data */
            data: {
              /* active tab in tab group, e.g. data.activeTab['group_name'] = '0' */
              activeTab: {},
              /* active radio button in radio group */
              activeRadio: {},
            },

            /* visual feedback: icon, color, animation */
            async changeIcon(id,icon,color,animation,timeout=1000,bicon,bcolor) {
              if (!id || !(icon || color || animation)) return;
              let ico = this.live.get(id);
              if (icon) {
                if (!bicon) bicon = ico.getAttribute('icon');
                ico.setAttribute('icon', icon);
              }
              if (color) {
                if (!bcolor) bcolor = ico.style.getPropertyValue('color');
                ico.style.setProperty('color', color);
              }
              if (animation) {
                ico.style.setProperty('animation',animation);
              } else if (ico.style.getPropertyValue('animation')) {
                ico.style.removeProperty('animation');
              }
              if (timeout > 0) {
                await new Promise(r => setInterval(r,timeout));
                if (icon) ico.setAttribute('icon', bicon);
                if (color) ico.style.setProperty('color', bcolor);
                if (animation) ico.style.removeProperty('animation');
              }
            },

            makeTabGroup(id, group, tabs=[]) {
              /* tabs: { active:true/false, disabled: true/false, text: 'tab name' } */
              
              if (!this.data.activeTab[group]) this.data.activeTab[group] = '0';
              /* tabs changed in ha core 2025.10.0 */
              const V1 = 2025100;
              let gName = this.haVersion < V1 ? 'sl-tab-group' : 'ha-tab-group';
              let tName = this.haVersion < V1 ? 'sl-tab' : 'ha-tab-group-tab';
              let tabElements = '';
              tabs.forEach((t,idx) => tabElements += `<${tName} slot="nav" panel="${idx}" ${t.active ? 'active=""' : ''} ${t.disabled ? 'disabled=""' : ''}
                            onpointerdown="window['${UUID}'].tabClick(event, this,'${id}',)">${t.text}</${tName}>`);
              return `
                <${gName} id="${id}" data-name="${group}" style="--track-color:${DIVIDER_COLOR};--track-width:${DIVIDER_WIDTH};">
                  ${tabElements}
                </${gName}>
              `;
            },
            /* tab "click" handler, here I add handler for non starndard "tab change" event of tabs group */
            tabClick(ev, tab, groupId) {
              ev.stopPropagation();
              let o = window[UUID];
              let tgroup = o.live.get(groupId);
              if (tgroup && !tgroup[UUID]) {
                /* tabs changed in ha core 2025.10.0 */
                const V1 = 2025100;
                let eName = this.haVersion < V1 ? 'sl-tab-show' : 'wa-tab-show';
                tgroup.addEventListener(eName, o.tabChange);
                tgroup[UUID] = true;
              }
              /* on touch devices "tab change" event isn't fired, so I fire it manually */
              if (o.IS_TOUCH) setTimeout(() => { tgroup.show(tab.panel); },50);
            },
            tabChange(ev) {
              /* "panel" from html code */
              let tabNumber = ev.detail.name;
              /* I store group name in the "data-name" attribute */
              let tabGroup = ev.target.dataset.name;
              let o = window[UUID];
              o.data.activeTab[tabGroup] = tabNumber;
              if (o.tabChange2) o.tabChange2(ev);
            },
            makeLabel: (text='',style='',id) => `<label ${id ? 'id="${id}"' : ''} style="${style};">${text}</label>`,
            makeTextField(id,label,value='',required,disabled,readonly,type) {
              let clickEnhance = this.IS_TOUCH ? 'this.focus()' : '';
              return `<ha-textfield id="${id}" data-version="${this.VERSION}" label="${label}" value="${value}" ${required ? 'required=""' : ''} ${readonly ? 'readonly=""' : ''}
                ${type ? `type="${type}"` : ''} ${disabled ? 'disabled=""' : ''} style="flex:1 1 60px;" onpointerdown="${clickEnhance}" oninput="window['${UUID}'].tfChange(event,this)"></ha-textfield>`;
            },
            tfChange(ev) {
              ev.stopPropagation();
              let o = window[UUID];
              if (o.tfChange2) o.tfChange2(ev);
            },
            /* force new line/row when style is "display: flex; flex-wrap: wrap" */
            makeBreak: () => '<div class="break"></div>',
            /* "chip" with label and checkbox */
            makeChkChip(id,label,checked,tag='none') {
              return `
                <div style="display:flex;align-items:center;height:28px;background-color: lightgray;border-radius:16px;">
                  ${this.makeLabel(label,'font-size:12px;margin-left:8px;margin-top:0px;margin-bottom:0px;padding:0px;')}
                  <ha-checkbox id="${tag}-${id}" data-version="${this.VERSION}" data-tag="${tag}" data-id="${id}" ${checked ? 'checked=""' : ''} 
                  style="--mdc-ripple-color:none;transform:scale(0.8);" onpointerup="window['${UUID}'].chkChipChange(event,this)"></ha-checkbox>
                </div>`;
            },
            chkChipChange(ev) {
              ev.stopPropagation();
              let chk = ev.target;
              let tag = chk.dataset.tag;
              let id = chk.dataset.id;
              let newVal = chk.getAttribute('checked','') === null;
              if (newVal) chk.setAttribute('checked','');
              else chk.removeAttribute('checked');
              let o = window[UUID];
              if (o.chkChipChange2) o.chkChipChange2(tag,id,newVal);
            },
            makeIcon: (icon,color,size,style,id,moreStuff) => {
              icon ??= 'mdi:comment-question';
              color ??= ICON_COLOR;
              size ??= '24px';
              style ??= '';
              moreStuff ??= '';
              return `<ha-icon ${id ? `id="${id}"` : ''} data-version="${this.VERSION}" icon="${icon}" style="height:${size};width:${size};color:${color};${style}" ${moreStuff}></ha-icon>`;
            },
            /* ha-icon-button; title = tooltip */
            makeIconButton: (id,title,icon,iconId,disabled,iconColor,style) => {
              title ??= ''; 
              icon ??= 'mdi:comment-question';
              iconColor ??= ICON_COLOR;
              return `<ha-icon-button id="${id}" title="${title}" onpointerup="window['${UUID}'].btnPress(event,this)" ${disabled ? 'disabled=""' : ''} ${style ? `style="${style}"` : ''}>
                ${window[UUID].makeIcon(icon,iconColor,'24px',`padding-bottom:10px;${disabled ? 'opacity:0.4' : ''}`,iconId)} </ha-icon-button>`
            },
            makeHaButton: (id,variant,appearance,txt,disabled,title='',size='medium') => `<ha-button id="${id}" data-version="${this.VERSION}" variant="${variant}" appearance="${appearance}" size="${size}" 
                          title="${title}" onpointerup="window['${UUID}'].btnPress(event,this)" ${disabled ? 'disabled=""' : ''}>${txt}</ha-button>`,
            async btnPress(ev, btn) {
              ev.stopPropagation();
              if (btn.getAttribute('disabled') !== null) return;
              let o = window[UUID];
              if (o.btnPress2) o.btnPress2(ev,btn);
            },
          }
          window[UUID].card = this;
          return window[UUID];
        ]]]
    styles:
      card:
        - cursor: default
        - padding: 16px
        - pointer-events: auto

Card:

type: custom:button-card
template: ui_elements
variables:
  _UUID: 24e6f389-7103-437c-bafa-efeea0c20627
  all: |
    [[[
      /* ###################### SETTINGS ############################################################ */
      
      /* paths to search; active = selected by default */
      const DIR = [
        {path: '/config', active: true},
      ];
      /* excluded paths (within the above) --exclude-dir= */
      const EXDIR = [
        {path: 'www', active: true},
        {path: 'custom_components', active: true},
      ];
      /* file names to search (masks): --include= */
      const INCL = [
        {name: '.jaml/.jinja', config: ['\\*.{yaml,jinja}'], active: true},
        {name: 'lovelace', config: ['lovelace', 'lovelace.\\*'], active: true},
        {name: '.js', config: ['\\*.js'], active: false},
        /* no config means all files */
        {name: 'all files', active: false},
      ];
      /* case sensitive */
      const OPTS = [
        {name:'case sensitive', config: 'cs', active: true},
      ];
      
      /* ###################### END OF SETTINGS ############################################################ */

      const UUID = variables._UUID;
      const NO_RESULTS = 'No results';

      /* I extend "my" object from the template */
      if (!window[UUID].searchStuffAdded) window[UUID] = {
        __proto__: window[UUID],
        /* I also extend "data" object */
        data: {
          __proto__: window[UUID].data,
          dir: DIR,
          exdir: EXDIR,
          incl: INCL,
          opts: OPTS,
          toSearch: '',
          results: [],
        },
        /* known HTML element IDs that I need to access */
        IDS: { mainTab:'idMainTab', tbSearch:'idTbSearch', btnSearch:'idBtnSearch', iconSearch:'idIconSearch', },
        /* which custom fields should be displayed */
        get searchDisplay() { return this.data.activeTab.main === '0' ? 'flex' : 'none'; },
        get settingsDisplay() { return this.data.activeTab.main === '1' ? 'flex' : 'none'; },
        get searchBtnEnabled() { return this.data.toSearch?.length > 0 && this.data.dir?.filter(d => d.active).length > 0; },
        /* template calls this function when the current tab changes */
        tabChange2(ev) {
          this.live.get('settings').style.setProperty('display', this.settingsDisplay);
          this.live.get('search').style.setProperty('display', this.searchDisplay);
        },
        /* template calls this function when "check chip" changes */
        chkChipChange2(tag,id,newVal) {
          let item = this.data[tag][id];
          item.active = newVal;
          this.adjustSearchEnabled();
        },
        /* template calls this function when textfield text changes */
        tfChange2(ev) {
          this.data.toSearch = ev.target.value;
          this.adjustSearchEnabled();
        },
        adjustSearchEnabled() {
          if (this.searchBtnEnabled) {
            this.live.get(this.IDS.btnSearch).removeAttribute('disabled');
            this.live.get(this.IDS.iconSearch).style.removeProperty('opacity');
          } else {
            this.live.get(this.IDS.btnSearch).setAttribute('disabled','');
            this.live.get(this.IDS.iconSearch).style.setProperty('opacity','0.4');
          }
        },
        /* template calls this function when a button is pressed */
        async btnPress2(ev, btn) {
          if (btn.id === this.IDS.btnSearch) {
            if (this.data.searching) return;
            this.data.searching = true;
            let success = false;
            try {
              /* visual feedback */
              this.changeIcon(this.IDS.iconSearch,'mdi:cog-outline', null, 'rotating 2s linear infinite');
              let data = {
                dirs: this.data.dir.filter(d => d.active).map(d => d.path),
                text: this.data.toSearch,
              };
              let exDirs = this.data.exdir?.filter(d => d.active).map(d => d.path);
              if (exDirs?.length > 0) data.exdirs = exDirs;
              let incl = this.data.incl?.filter(i => i.active && i.config).map(i => i.config).flat();
              let all = this.data.incl?.filter(i => i.active && !i.config).length > 0 || incl === null || incl.length === 0;
              if (!all) data.includes = incl;
              data.caseSensitive = this.data.opts?.filter(o => o.config === 'cs' && o.active).length > 0;

              let result = await hass.callService('shell_command', 'files_containing', data, {}, true, true);
              let r = result?.response;
              success = r?.returncode === 0;
              this.data.results = success ? r.stdout.split('\n') : [r.stderr];
            } catch (ex) {
              this.data.results = [ex.toString()];
              console.error(ex);
            } finally {
              this.data.searching = false;
              this.data.selectedIndex = -1;
              /* function to be executed after card update */
              this.addUpdateCallback(_ => this.changeIcon(this.IDS.iconSearch, success ? 'mdi:check-all' : 'mdi:exclamation-thick',
                success ? 'var(--success-color)' : 'var(--error-color)',null,1000,'mdi:search-web',this.ICON_COLOR));
              /* update card */
              this.card.update();
            }
          }
        },
        makeResultsTable() {
          let rows = '';
          let bb = this.data.results;
          if (this.data.results.length > 0) {
            this.data.results.forEach((r,idx) => rows += `<tr ${r !== NO_RESULTS ? `data-idx="${idx}"` : ''} ${idx == this.data.selectedIndex ? 'data-selected="yes"' : ''}
                                    data-version="${this.VERSION}" onpointerup="window['${UUID}'].trClick(event, this)"><td title="${r}" data-name="">${r}</td></tr>`);
          }
          return `
            <table class="my_results_table">
              <tr> <th>Results</th> </tr>
              ${rows}
            </table>
          `;
        },
        trClick(ev, tr) {
          ev.stopPropagation();
          /* proper results have the "data-idx" attribute; the selected row has the "data-selected" attribute  */
          if (tr.dataset?.idx) {
            for (let r of tr.offsetParent.rows) {
              if (r !== tr && r.dataset.selected)
                r.removeAttribute('data-selected');
            }
            tr.setAttribute('data-selected','yes');
            let index = parseInt(tr.dataset.idx);
            this.data.selectedIndex = index;
          }
        },
        searchStuffAdded: true,
      };
      return window[UUID];
    ]]]
custom_fields:
  header: |
    [[[
      let a = variables.all;
      return `
        ${a.makeTabGroup(a.IDS.mainTab, 'main', [
          {active: a.data.activeTab.main == '0', text: 'Find in files'},
          {active: a.data.activeTab.main == '1', text: 'Settings'}
        ])}
        `;
    ]]]
  settings: |
    [[[
      let a = variables.all;
      let chipsDiv = (label,chips,br) => `<div style="display:flex;gap:8px;align-items:start;">
                                          ${a.makeLabel(label,'font-size:15px;padding-top:4px;')}
                                          <div class="my_chips">${chips}</div></div>${br ? a.makeBreak() : ''}`;
      let dirs = '';
      a.data.dir?.forEach((d,i) => dirs += a.makeChkChip(i, d.path, d.active, 'dir'));
      let exdirs = '';
      if (a.data.exdir?.length > 0) {
        let chips = '';
        a.data.exdir.forEach((d,i) => chips += a.makeChkChip(i, d.path, d.active, 'exdir'));
        exdirs = chipsDiv('except',chips,true)
      }
      let includes = '';
      a.data.incl.forEach((d,i) => includes += a.makeChkChip(i, d.name, d.active, 'incl'));
      let opts = '';
      a.data.opts.forEach((d,i) => opts += a.makeChkChip(i, d.name, d.active, 'opts'));
      return `
        ${chipsDiv('Folders:',dirs,true)}
        ${exdirs}
        ${chipsDiv('Files:',includes,true)}
        ${chipsDiv('Other:',opts,true)}
      `;
    ]]]
  search: |
    [[[
      let a = variables.all;
      return `
        ${a.makeTextField(a.IDS.tbSearch,'Text to find',a.data.toSearch,true)}
        ${a.makeIconButton(a.IDS.btnSearch,'Search','mdi:search-web',a.IDS.iconSearch,!a.searchBtnEnabled)}
        ${a.makeBreak()}${a.makeResultsTable()}
      `;
    ]]]
styles:
  grid:
    - display: flex
    - align-content: start
    - flex-wrap: wrap
  custom_fields:
    header:
      - flex: auto
      - flex-basis: 100%
      - margin-bottom: 16px
    settings:
      - display: "[[[ return variables.all.settingsDisplay; ]]]"
      - flex-wrap: wrap
      - align-items: center
      - gap: 8px
    search:
      - display: "[[[ return variables.all.searchDisplay; ]]]"
      - flex-wrap: wrap
      - align-items: center
      - gap: 8px
      - flex-basis: 100%
section_mode: true
grid_options:
  rows: 5
  columns: 12
extra_styles: |
  [[[
    return `
      /* force a new line */
      .break {
        flex-basis: 100%;
        height: 0;
      }

      .my_chips {
        display: flex;
        flex-wrap: wrap;
        align-items: center;
        gap: 8px;
      }

      /* style for results table */
      table.my_results_table {
        border-collapse: collapse;
        font-size: 13px;
        max-height: 155px;
        overflow-y: auto;
        display: inline-block;
      }
      .my_results_table th, .my_results_table td {
        padding: 8px;
        text-align: left;
        border-bottom: 1px solid #ddd;
      }
      .my_results_table td {
        max-width: 100%;
        overflow: hidden;
        text-overflow: ellipsis;
      }
      .my_results_table tr[data-idx]:hover {
        background-color: ${variables.all.TABLE_HOVER_COLOR};
      }
      .my_results_table tr[data-selected] {
        background-color: ${variables.all.TABLE_SELECT_COLOR} !important;
      }
    `;
  ]]]

[Mariusthvdb]

cheers...!
got a picture of the card?
btw, for readability, can we not 'hide' code here, like in the community?

[dcapslock]

btw, for readability, cant we not 'hide' code here, like in the community?

Yep. HERE

Tips for collapsed sections

You can add a header

You can add text within a collapsed section.

You can add an image or a code block, too.

what_are_we_fixing_today:
  dialogs: true

[lisz8]

OK I'm on it ... made it! It's somehow more difficult than on community forums, it doesn't work without blank lines :)

[Mariusthvdb]

forgot I even use that myself in my markdown cards inside the HA views ;-)
off topic here, but since were talking...
trying to format that collapsible summary itself seems difficult

content: >

  <details>

  <summary>Samenvatting</summary> 

want that 'Samenvatting' in bold and adding header tags is erratic, though it does react to the hover setting in card_mod:

card_mod:
  style:
    ha-markdown:
      $: |
       :hover {color: var(--info-color);}

keeps closing with clicking though, I guess it updates upon each state change in the markdown....