@cgjgh/node-red-dashboard-2-ui-scheduler/nodes/locales/en-US/ui-scheduler.html

A UI scheduler node that integrates with Node-RED Dashboard 2.0

<script type="text/javascript">
    function _popoutSchedulerHelp (tag) {
        const startTag = (name) => `<${name}>`
        const endTag = (name) => `</${name}>`
        const winHtml = `
            ${startTag('html')}
                ${startTag('head')}
                    ${startTag('title')}ui-scheduler help${endTag('title')}
                    ${startTag('style')}
                    .fade-in {
                        transition: opacity 1.5s ease-in-out;
                    }
                    .hidden {
                        opacity: 0;
                        visibility: hidden;
                    }
                    ${endTag('style')}
                ${endTag('head')}
                ${startTag('body')}
                    ${startTag('script')}
                        const styles = ${JSON.stringify([].map.call(document.querySelectorAll('[rel="stylesheet"]'), e => e.href))}
                        const head = document.head || document.getElementsByTagName('head')[0]
                        styles.forEach(href => {
                            const el = document.createElement('link');
                            el.rel="stylesheet"
                            el.href = href
                            head.appendChild(el);
                        })
                    ${endTag('script')}
                    <div class="red-ui-editor help-content hidden" style="height: 100%">
                        <div class="red-ui-sidebar-info">
                            <div class="red-ui-sidebar-help-stack red-ui-panels" style="height: 100%;">
                                <div class="red-ui-panel" style="overflow-y: auto;height: 100%;">
                                    <div class="red-ui-help" style="padding: 6px;height: 100%;">
                                        <h1 class="red-ui-help-title">ui-scheduler</h1>
                                        <div class="red-ui-help">
                                            <span class="red-ui-text-bidi-aware">
                                                ${RED.nodes.getNodeHelp('ui-scheduler')}
                                            </span>
                                        </div>
                                    </div>
                                </div>
                            </div>
                        </div>
                    </div>
                    ${startTag('script')}
                        if (navigator.clipboard) {
                            document.querySelector('.ui-scheduler-link-button').classList.add('hidden')
                            const content = document.querySelector('.help-content');
                            content.classList.add('hidden')
                            content.classList.remove('hidden')
                            content.classList.add('fade-in')
                            const copyButtonLabel = "Copy"
                            const blocks = document.querySelectorAll("pre.ui-scheduler-code")
                            blocks.forEach((block) => {
                                const button = document.createElement("button")
                                button.innerText = copyButtonLabel
                                button.classList.add('ui-scheduler-copy-button')
                                button.addEventListener("click", copyCode)
                                block.appendChild(button)
                            })
                        }
                        async function copyCode(event) {
                            const button = event.srcElement
                            const pre = button.parentElement
                            const code = pre.querySelector("code")
                            const text = code.innerText
                            await navigator.clipboard.writeText(text)
                        }
                    ${endTag('script')}
                ${endTag('body')}
            ${endTag('html')}`

        const BOM = new Uint8Array([0xEF, 0xBB, 0xBF])
        const winUrl = URL.createObjectURL(
            new Blob([BOM, winHtml], { encoding: 'UTF-8', type: 'text/html;charset=UTF-8' })
        )
        const win = window.open(
            winUrl + (tag ? '#' + tag : ''),
            'win',
            'width=800,height=600'
        )
    }
</script>

<script type="text/markdown" data-help-name="ui-scheduler">
    
    # 🕙 UI Scheduler Help Documentation

This document provides a comprehensive guide to configuring the settings for the UI Scheduler node, usage in the Dashboard UI, and additional info. The UI Scheduler allows users to automate tasks based on time, solar events, or cron expressions.

## 👆 Using the UI Scheduler in Dashboard 2.0

#### 🖥️ Main Interface

- **🛠️ Toolbar**: 
  - **🔍 Topic Selector**: Filter schedules by topic.
  - **➕ Add Schedule Button**: Open the dialog to create a new schedule.
  - **☰ Menu**: Access additional options like checking for updates or reporting issues.

- **📋 Schedule Table**: Displays all schedules with details such as name, description, and status. You can expand rows to view more details.

#### 🗓️ Creating a Schedule

1. **🖱️ Open the Schedule Dialog**: Click the ➕ button in the toolbar.
2. **✏️ Enter Schedule Details**:
   - **🏷️ Name**: Enter a unique name for the schedule.
   - **📂 Topic**: Select a topic from the dropdown. Topics are defined in **Node Settings**
   - **⏲️ Type**: Choose between Time, Solar, or Cron scheduling.
   - **🔄 Period**: For time-based schedules, select the recurrence period.
   - **🕒 Time/Date**: Set the start time and, if applicable, the end time or duration.
   - **📦 Payload**: Choose the payload type and define custom payloads if needed.
3. **💾 Save the Schedule**: Click "Save" to add the schedule.

#### ✏️ Editing a Schedule

- **🖊️ Edit**: Click on schedule in table to expand rows to view more details. Click the pencil icon  to open the edit dialog. Make changes and save.
- - **🗑️ Delete**: Click the delete icon to remove a schedule.

#### 🔄 Importing and Exporting Schedules

- **📤 Export**: Click the export icon to copy the schedule JSON to your clipboard. _Only available when editing a schedule._
- **📥 Import**: Click the import icon and paste the JSON to import a schedule. _Only available when creating a schedule._

#### ⚙️ Managing Schedules

- **🔄 Enable/Disable**: Use the toggle switch to enable or disable schedules.

### 🚀 Advanced Features

#### 🌞 Solar Events

- Customize schedules based on solar events with offsets.
- Supported events include sunrise, sunset, and various twilight phases.

#### ⏰ Cron Expressions

- Use cron syntax for complex scheduling needs.
- Supports standard cron fields and special characters.

#### 📦 Custom Payloads

- Use custom payloads for schedule output. Payloads are defined in **Node Settings**
- Supports JSON and other data formats.

## 🛠️ Node Settings

#### 🏷️ Name
- **Field**: `Name`
- **Description**: Enter a unique name for the scheduler. This name will be used to identify the scheduler within the system.
- **Input Type**: Text (string)

#### 👥 Group
- **Field**: `Group`
- **Description**: Select the group to which this scheduler belongs. Groups help organize widgits within the UI.
- **Input Type**: Dropdown (string)

#### 📏 Size
- **Field**: `Size`
- **Description**: Adjust the size of the scheduler widget within the UI. This can be set manually or using the element sizer.
- **Input Type**: Button (Element Sizer)

#### 🏷️ Label
- **Field**: `Label`
- **Description**: Set a label for the scheduler that will be displayed in the UI.
- **Input Type**: Text (string)

### 🌍 Localization Settings

#### 🌐 Language
- **Field**: `Language`
- **Description**: Select the language for the scheduler interface. 
  - Supported languages include English, Deutsch, Français, Italiano, Nederlands, and Español.
  - Also edit <code>~/.node-red/settings.js</code> and add/uncomment the following line: <code>lang: 'en'</code>. 
Available languages codes are: <code>en</code>, <code>de</code>, <code>fr</code>, <code>it</code>, <code>nl</code>, <code>es</code>
This will set the language used in the UI Scheduler node on the Node-Red server.
- **Input Type**: Dropdown (string)

#### ⏰ Time Zone
- **Field**: `Time Zone`
- **Description**: Specify the time zone for the scheduler. This affects how times are calculated and displayed.
  - Leave blank for system timezone. 
  - Alternatively, enter UTC or a timezone in the format of Region/Area ([list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)).
- **Input Type**: Autocomplete Text (string)

#### 🕒 24-Hour Format
- **Field**: `Use 24-Hour Format`
- **Description**: Toggle between 24-hour and 12-hour time formats.
- **Input Type**: Checkbox (boolean)

### 📍 Location Settings

#### 🌐 Location
- **Field**: `Location`
- **Description**: Set a default geographical location for solar event calculations. This can be a fixed location or an environment variable.
- **Input Type**: Typed Input (string)

### 📤 Output Settings

#### 📬 Command Response Message Output
- **Field**: `Command Response Message Output`
- **Description**: Choose how command responses are output. Options include:
  - 1 output: All messages to output 1 (schedules + command responses)
  - 2 outputs: Command responses to output 1, Schedule messages to output 2
  - Fan out: Separate outputs for command messages and each topic
- **Input Type**: Dropdown (string)

#### 📝 Output property
- **Field**: `Output Field`
- **Description**: Specify the property in the message object where the output will be stored.
  - e.g. if 'Output property' is set to **data.value** then `msg.data.value` will contain the value of the *payload*
  - `msg.topic` will contain the name of the topic. This simplifies separating out which schedule has triggered
  - Additional properties are also added to the msg object. Check the debug output (use show complete msg)

- **Input Type**: Typed Input (string)

### 📊 State Settings

#### 📅 Send State of Schedules
- **Field**: `Send State of Schedules`
- **Description**: Configure how often the state of schedules is sent and whether to send active or inactive states.
  - This is grouped by topic, so if two schedules are `active` (in range of start and end times) for the same topic, only one message will be sent with payload `true`. 
  - Likewise, if one schedule for a topic is `inactive`, and the other is `active`, only one message will be sent with payload `true`. 
  - If both schedules are `inactive`, only one message will be sent with payload `false`.
- **Input Type**: Number (Interval), Checkbox (Active/Inactive State) (number, boolean)

### 💾 Storage Settings

#### 🗄️ Store Name
- **Field**: `Store Name`
- **Description**: Select the storage method for persisting schedules. Options include:
  - None: Don't persist schedules. Schedules will be lost when the node is redeployed
  - Local File System: Persist schedules to local file system. The schedules are saved in a directory called `schedulerdata` under your node-red folder
  - Node Context Stores: Persist schedules to the node context. These stores will be automatically loaded from your node-red settings file. See the [Node-RED Contexts](https://nodered.org/docs/user-guide/context) documentation for more information.
- **Input Type**: Dropdown (string)

### 📨 Topics and Payloads

#### 🗂️ Topics
- **Field**: `Topics`
- **Description**: Define topics for the scheduler. Topics help categorize and manage schedules.
  - These topics can be used in the `Topic` field of schedules, and can be selected in Node-Red Dashboard 2.0 UI. 
  - In Fan Out mode, schedule messages will be sent to the output corresponding to the topic.
- **Input Type**: Editable List (string)

#### 📦 Custom Payloads
- **Field**: `Custom Payloads`
- **Description**: Define custom payloads to be sent when a schedule is triggered. 
  - Payloads can be of various types including string, number, boolean, and JSON.
  - Payloads defined here can be selected in the Dashboard UI.
  - Changing payload value here will automatically update the payload values of all schedules using the payload 
- **Input Type**: Editable List with Typed Input (string, number, boolean, JSON)

### ⚙️ Advanced Settings

#### 🕰️ Use New Time Picker
- **Field**: `Use New Time Picker`
- **Description**: Enable or disable the new time picker interface.
- **Input Type**: Checkbox (boolean)

## 🔧 Inputs (Advanced Usage)

#### Topic
Most of the commands can be provided in the topic with the name of schedule in the payload (where appropriate). Supported command topics...

- trigger
- status
- export
- remove
- pause
- stop
- start

This includes the `-all`, `-all-dynamic`, `-all-static`, `-topic`, `-active`,  `-active-dynamic`,  `-active-static`, `-inactive`, `-inactive-dynamic` and `-inactive-static` command topics (e.g. export-all, stop-all-dynamic, start-all-static, remove-inactive-dynamic). See [commands](#ui-scheduler-commands-info) below for details.

#### 📦 Payload
It is possible to dynamically add, remove and control schedules by injecting a payload into the node. The format of the payload object (or array of objects) depends on the operation. See below for details. You can also export schedules from Dashboard UI in edit window and paste the resulting JSON.

#### ➕ Adding one (or more) schedules
Example...
```json
payload: {
  "command": "add",
  "schedule": [
    {
      "name": "Schedule",
      "topic": "Topic 1",
      "enabled": true,
      "scheduleType": "time",
      "period": "daily",
      "time": "00:00",
      "endTime": null,
      "days": [
        "sunday",
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday",
        "saturday"
      ],
      "payloadType": true,
      "payloadValue": true
    },
    {
      "name": "Schedule 2",
      "topic": "Topic 1",
      "enabled": true,
      "scheduleType": "solar",
      "timespan": "time",
      "solarEvent": "sunrise",
      "offset": 5,
      "solarEventStart": false,
      "solarEventTimespanTime": "21:00",
      "payloadType": "true_false",
      "payloadValue": true,
      "endPayloadValue": false
    },
    {
      "name": "Schedule 3",
      "topic": "Topic 1",
      "enabled": true,
      "scheduleType": "time",
      "period": "minutes",
      "duration": 1,
      "timespan": "duration",
      "minutesInterval": 7,
      "payloadType": "true_false",
      "payloadValue": true,
      "endPayloadValue": false
    }
  ]
}
```

### 📊 Getting status of a schedule or removing / stopping / pausing / starting a schedule

#### Topic Method
```json
msg.topic = "command"; // command name - *see details below*,
msg.payload = "name"; //  name of the schedule
```

#### Payload Method
```json
payload: {
  "command": "*see details below*",
  "name": "* name of schedule",
}
```

#### Details
- command: (string|required) The operation to perform - this can be one of the following...
  - "trigger"
  - "status"
  - "export"
  - "remove"
  - "stop"
  - "pause"
  - "start"
- name: (string|optional) The name of the schedule to affect (not required when using the -all, -active or -inactive filters)

#### 📝 Notes
- `trigger` fires schedule named in `msg.payload`
- `status` returns an object with the config and status of the named schedule
- `export` returns an object with the config of the named schedule
- `remove` will stop and remove the schedule. This option has no output.
- `stop` will stop the schedule specified by `name` and reset its internal counter. This option has no output.
- `pause` will stop the schedule specified by `name` but will not reset its internal counter. This option has no output.
- `start` will (re)start all schedules. Any schedule that reached its limit will start from the beginning. Paused schedules will resume. This option has no output.
- FILTER: adding `-all` to any of these commands will operate on all schedules. e.g. `status-all` will return the status of all schedules
- FILTER: adding `-all-dynamic` to any of these commands will only affect dynamic schedules e.g. `remove-all-dynamic` will remove all dynamic schedules
- FILTER: adding `-all-static` to any of these commands will only affect static schedules e.g. `stop-all-static`
- FILTER: adding `-topic` to any of these commands will only affect schedules whose topic matches the topic specified in payload e.g. `stop-topic`
- FILTER: adding `-active` to status, export and remove commands will operate on all active schedules. e.g. `status-active`
- FILTER: adding `-active-static` to status, export and remove commands will operate on all static schedules that are active. e.g. `status-active-static`
- FILTER: adding `-active-dynamic` to status, export and remove commands will operate on all dynamic schedules that are active. e.g. `status-active-dynamic`
- FILTER: adding `-inactive` to status, export and remove commands will operate on all inactive schedules. e.g. `status-inactive`
- FILTER: adding `-inactive-static` to status, export and remove commands will operate on all static schedules that are inactive. e.g. `status-inactive-static`
- FILTER: adding `-inactive-dynamic` to status, export and remove commands will operate on all dynamic schedules that are inactive. e.g. `status-inactive-dynamic`

#### 📖 Examples
- Using a simple topic command to manually trigger a schedule named "schedule1"
  ```json
  msg: {
    "topic": "trigger",
    "payload": "schedule1"
  }
  ```
- Using a simple topic command with a topic in payload to start all schedules with specified topic
  ```json
  msg: {
    "topic": "start-topic",
    "payload": { "topic": "Topic 1" }
  }
  ```
- Using a simple topic command to export all dynamically added schedules...
  ```json
  msg: {
    "topic": "export-all-dynamic"
  }
  ```
- Using a simple topic command to delete a schedule named "schedule1"
  ```json
  msg: {
    "topic": "remove",
    "payload": "schedule1"
  }
  ```
- Using a cmd payload to pause all schedules...
  ```json
  payload: {
    "command": "pause-all"
  }
  ```
- Using a simple topic command to delete all dynamic schedules that have finished
  ```json
  msg: {
    "topic": "remove-inactive-dynamic"
  }
  ```

### 🔍 Describe

#### Example: cmd payload to describe a cron expression
```json
{
  "command": "describe",
  "expressionType": "cron",
  "expression": "0 */5 * * * MON *",
  "timeZone": "Europe/London"
}
```

#### Example: cmd payload to get all solar event times + solar state at this time
```json
{
  "command": "describe",
  "expressionType": "solar",
  "location": "54.9992500,-1.4170300",
  "solarType": "all",
  "timeZone": "Europe/London"
}
```

#### Example: cmd payload to get 4 solar event times + solar for a specific point in time
```json
{
  "command": "describe",
  "expressionType": "solar",
  "time": "2020-03-22 18:40",
  "location": "54.9992500,-1.4170300",
  "solarType": "selected",
  "solarEvents": "civilDawn,sunrise,sunset,civilDusk",
  "timeZone": "Europe/London"
}
```

#### Details
Returns an object in payload containing human readable info for the given expression.

- command: (string|required) The operation to perform
- expression: (string|required) The expression to describe
- timeZone: (string|optional) A timezone to use. Leave blank for system timezone. Alternatively, enter UTC or a timezone in the format of Region/Area ([list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones))

## Additional Info

### ⏰ CronExpression
A CRON expression, a date, a comma separated list of dates or an array of dates.

##### 📅 Date or Date Sequence Format
When you wish to use a fixed date or sequence of dates, the expression can be a string date, comma separated list of dates, an array of dates (The array can contain a mix of string, date objects and timestamps). When specifying a string date, you can use timezone e.g. "2020-01-01 00:00 GMT+2". You can even mix time zones e.g. "2020-01-01 00:00 GMT+2, 2020-01-01 00:00 GMT-7".

##### ⏲️ CRON Format
```
* * * * * * *    Field              Allowed values    Special symbols
| | | | | | |    -----------------  ---------------   ---------------
`-|-|-|-|-|-|->  Second (optional)  0-59              * / , -
  `-|-|-|-|-|->  Minute             0-59              * / , -
    `-|-|-|-|->  Hour               0-23              * / , -
      `-|-|-|->  Day of Month       1-31              * / , - ? L W
        `-|-|->  Month              1-12 or JAN-DEC   * / , -
          `-|->  Day of Week        0-7 or SUN-SAT    * / , - ? L #
            `->  Year (optional)    1970-2099         * / , -
```

##### 📝 Notes
- `*` Asterisks indicate that the cron expression matches for all values of the field. For example, "*" in the minute field means every minute.
- `?` Question marks are used to specify 'no specific value' and is allowed for the day-of-month and day-of-week fields. It is used instead of the asterisk (*) for leaving either day-of-month or day-of-week blank.
- `-` Hyphens are used to define ranges. For example, "10-12" in the hour field means the hours of 10, 11, and 12.
- `,` Commas are used to separate items of a list. For example, "MON,WED,FRI" in the day-of-week field means the days Monday, Wednesday, and Friday.
- `/` Forward slash are used to indicate increments. For example. "0/15" in the seconds field means the seconds 0, 15, 30, and 45. Additionally, "1/3" in the day-of-month field means every 3 days starting on the first day of the month.
- `L` Short-hand for "last" and is allowed for the day-of-month and day-of-week fields. The "L" character has a different meaning in each of the two fields. For example, "L" in the day-of-month field means the last day of the month. If used in the day-of-week field, it means 7 or SAT. However, if used in the day-of-week field after another value, it means the last xxx day of the month. For example, "6L" in the day-of-week field means the last Friday of the month.
- `W` Short-hand for "weekday" and is allowed for the day-of-month field. The "W" character is used to specify the weekday nearest the given day. For example, "15W" in the day-of-month field means the nearest weekday to the 15th of the month. Therefore, if the 15th is a Saturday, the job runs on Friday the 14th. The "L" and "W" characters can be combined in the day-of-month field. For example, "LW" means the last weekday of the month.
- `#` Hash marks specify constructs. For example, "6#3' in the day-of-week field means the third Friday of the month.

##### 📖 Examples
- `* * * * * *` Every Second
- `0 * * * * *` Every minute
- `0 */10 * * * *` Every 10 minutes
- `0 */20 1 * * *` Every 20 minutes, between 01:00 AM and 01:59 AM
- `0 15,30,45 * * * *` At 15, 30, and 45 minutes past the hour
- `0 0 12 * * *` Every day at noon - 12pm
- `0 0 2 29 FEB * 2020/4` At 02:00 AM, on day 29 of February (leap years)
- `0 0 7 * * MON#1 *` At 07:00 AM, on the first Monday of the month
- `0 0 12 * JAN,FEB,MAR,APR *` Every day at noon in January, February, March and April
- `* * 1W * *` Every minute, on the first weekday of the month
- `* * * * Tue#3` Every minute, on the third Tuesday of the month
- `0 12 * * MONL` At 12:00 PM, on the last Monday of the month

See [here](https://github.com/jaclarke/cronosjs) for more examples and info.

#### 🌅 Solar Events
| Event ID | Event | Information |
|----------|-------|-------------|
| nightEnd | night end / astronomical dawn | night ends, astronomical twilight starts (-18°) |
| nauticalDawn | nautical dawn | astronomical twilight ends, nautical twilight starts (-12°) |
| civilDawn | civil dawn / golden hour | nautical twilight ends, civil twilight and golden hour starts (-6°) |
| sunrise | sunrise | top edge of the sun appears on the horizon (-0.833°) |
| sunriseEnd | sunrise end | bottom edge of the sun touches the horizon (-0.3°) |
| morningGoldenHourEnd | morning golden hour ends | when the sun is 6 degrees above the horizon (6°) |
| solarNoon | solar noon | sun is at its highest position |
| eveningGoldenHourStart | evening golden hour start | when the sun is 6 degrees above the horizon (6°) |
| sunsetStart | sunset start | bottom edge of the sun touches the horizon (-0.3°) |
| sunset | sunset | civil twilight starts, sun disappears below the horizon (-0.833°) |
| civilDusk | civil dusk / golden hour end | civil twilight and golden hour ends, nautical twilight starts (-6°) |
| nauticalDusk | nautical dusk | nautical twilight ends, astronomical twilight starts (-12°) |
| nightStart | astronomical dusk / night start | astronomical twilight ends, night starts (-18°) |
| nadir | solar midnight | when the sun is closest to nadir and the night is equidistant from dusk and dawn |

#### 📝 General Notes
- Adding a schedule with the same name as an existing schedule will replace the existing one
- When a ui-scheduler node outputs a msg in response to a command, `msg.commandResponse` will be `true` to indicate the message is in response to a command and not a scheduled event
- When a ui-scheduler node outputs a msg for a cron/solar event, `msg.scheduledEvent` will be `true` to indicate the message is due to a scheduled event and not a control response
</script>