Confused about script field template in docs

Configuration
1

hi,

never noticed the field option before, so trying to understand what is does (if anything)

reading the example on the docs it reads

    fields:
      minutes:
        description: 'The amount of time to wait before turning on the living room lights'
        example: 1

but under the delay: part it shows nothing. Thought that might have been a typo, so went ahead and checked the source (to maybe PR that typo), but then it reads:

      - delay:
          # supports seconds, milliseconds, minutes, hours
          minutes: {{ minutes }}

which isnt transported to the doc example apparently.

So, what does the ‘field’ variable do? Is it merely an explanation of what the minutes variable would do in the script, or is it actually being used by the {{minutes}} template in the script itself…?

hope this is all clear .

2

Isn’t it what will appear in the dev tools when you select that script?

I think it’s a pointless addition personally, same as description and most of the other ‘stuff’ that’s been added to automations and scripts in recent months. No improvement in productivity, and just makes a mess of the configuration for no real purpose.

3

tbh, I don’t know, hence my question. Which I fear underlines your summary :wink:

at the very least, we now have a doc page not showing a value for the delay, which seems incorrect. o well.

1 Like
4

It lets you pass service data to the script. Look at the notify example, particularly this part:

  action:
    service: script.notify_pushover
    data:
      title: 'State change'
      message: 'The light is on!'

It lets you pass the title and message to the script instead of putting those data directly in the script so you can use the same script for multiple things.

5

Yes, but you could do that long before the fields key existed.

6

Didn’t know that. How so?

7

The fields field is a way to provide documentation for the fields of your script. When you go to the “Services” tab of the “Developer Tools” and select your script there, you should see the description field of the script and a table of the parameters you described with fields.

It has no other purpose than documentation. You do not need to list a parameter in fields in order to be able to use it.

Also the source of the example you checked does in fact have an error, it should be:

      - delay:
          # supports seconds, milliseconds, minutes, hours
          minutes: {% raw %}{{ minutes }}{% endraw %}

Note the {% raw %} and {% endraw %} that I’ve added. The source is actually a template that is processed prior to show the documentation to the user. So the variables that must appear as-is in the final display have to be escaped with raw. If you check other examples in the same page, you’ll see they are escaped like this.

8

By typing it exactly how you do now. Passing variables to scripts has nothing to do with the fields key

1 Like
9

Oh lol. I haven’t ever done that with or without fields so I didn’t know that was possible. Good to know.

1 Like
10

very nice explanation, thank you very much.

will you pr the documentation with this :wink:

also, doing so, would it show a value in the documentation example? It really should because now it just seems to allow an empty delay field, which I would think is an error also.

11

Nope. I got bigger fish to fry. Feel free to file a PR if you want, and reap all the glory. :slight_smile:

12

A very old thread but this is still a problem. I wasted so much time with not understanding why the default values from field always were giving None …
field really is just for docs purposes…