Settings Panel (settings)

The settings panel allows you to add visual configuration forms for scripts. Users can easily modify these settings in the iClick console without manually editing configuration files.

Basic Usage

Add settings field in manifest.json:

{
  "settings": [
    {
      "key": "api_url",
      "name": "API Address",
      "type": "text",
      "value": "https://api.example.com",
      "placeholder": "Enter API address",
      "require": true
    }
  ]
}

Common Field Description

Each configuration item supports the following fields:

Field	Type	Required	Description
key	string	✅	Unique configuration identifier, used to read config values in programs
name	string	✅	Configuration display name, shown in configuration form
type	string	✅	Configuration type (see type list below)
value	any	✅	Default value, type should match type
placeholder	string	Optional	Input placeholder text
require	boolean	Optional	Whether required, default false

Configuration Types

text - Single-line Text Input

Suitable for short text input, such as API Key, URL, etc.

{
  "key": "api_key",
  "name": "API Key",
  "type": "text",
  "value": "",
  "placeholder": "Enter your API key",
  "require": true
}

Use Cases:

• API keys
• URLs
• Usernames
• Short text configuration

---

number - Number Input

Suitable for number input, such as port numbers, timeout values, etc.

{
  "key": "timeout",
  "name": "Timeout (seconds)",
  "type": "number",
  "value": 30,
  "placeholder": "Enter timeout in seconds"
}

Use Cases:

• Timeout values
• Port numbers
• Quantity limits
• Time intervals

---

checkbox - Checkbox

Suitable for boolean (on/off) options.

{
  "key": "enable_log",
  "name": "Enable Logging",
  "type": "checkbox",
  "value": true
}

Use Cases:

• Feature toggles
• Enable/disable options
• Debug mode switches

---

select - Dropdown Select

Suitable for selecting one value from predefined options.

{
  "key": "mode",
  "name": "Run Mode",
  "type": "select",
  "value": "auto",
  "options": [
    { "label": "Auto Mode", "value": "auto" },
    { "label": "Manual Mode", "value": "manual" },
    { "label": "Debug Mode", "value": "debug" }
  ]
}

Special Fields:

• options: Options array, each option contains label (display text) and value (actual value)

Use Cases:

• Run mode selection
• Log levels
• Theme selection
• Language selection

---

textarea - Multi-line Text

Suitable for long text or multi-line content input.

{
  "key": "config_content",
  "name": "Config File Content",
  "type": "textarea",
  "value": "",
  "placeholder": "Enter config file content (JSON or other format)"
}

Use Cases:

• Configuration file content
• Script code
• Long text descriptions
• JSON configuration

---

file - File Selector

Allows users to select a file.

{
  "key": "cert_file",
  "name": "Certificate File",
  "type": "file",
  "value": "",
  "placeholder": "Select certificate file"
}

Use Cases:

• Certificate files
• Configuration files
• Data files
• Image files

---

path - Folder Selector

Allows users to select a folder path.

{
  "key": "output_dir",
  "name": "Output Directory",
  "type": "path",
  "value": "",
  "placeholder": "Select output directory"
}

Use Cases:

• Output directories
• Working directories
• Data storage paths
• Log directories

---

date - Date Picker

Allows users to select a date.

{
  "key": "start_date",
  "name": "Start Date",
  "type": "date",
  "value": "2024-01-01",
  "placeholder": "Select start date"
}

Value Format: YYYY-MM-DD

Use Cases:

• Start/end dates
• Expiration dates
• Scheduled dates

---

time - Time Picker

Allows users to select time.

{
  "key": "backup_time",
  "name": "Backup Time",
  "type": "time",
  "value": "02:00:00",
  "placeholder": "Select backup time"
}

Value Format: HH:mm:ss

Use Cases:

• Scheduled task times
• Daily execution times
• Reminder times

---

datetime - Datetime Picker

Allows users to select date and time.

{
  "key": "schedule_time",
  "name": "Scheduled Execution Time",
  "type": "datetime",
  "value": "2024-01-01 12:00:00",
  "placeholder": "Select execution time"
}

Value Format: YYYY-MM-DD HH:mm:ss

Use Cases:

• Scheduled task times
• Event times
• Deadline times

Auto-Generated Config File

When users modify and save settings in the iClick console, the system will automatically generate a settings.json file in the script package directory.

File Location:

%APPDATA%/iClick/Scripts/com.example.myscript/settings.json

Generated Config File Example:

{
  "api_url": "https://api.example.com",
  "api_key": "your_api_key_here",
  "timeout": 30,
  "enable_log": true,
  "log_level": "info"
}

Your external program can directly read this file to get user-configured values.

Reading Configuration

Your external program can read the auto-generated settings.json file to obtain user configuration.

Python Example

import json
import os

# Read config file
script_dir = os.path.dirname(os.path.abspath(__file__))
settings_file = os.path.join(script_dir, 'settings.json')

with open(settings_file, 'r', encoding='utf-8') as f:
    settings = json.load(f)

# Use configuration
api_url = settings.get('api_url')
api_key = settings.get('api_key')
timeout = settings.get('timeout', 30)
enable_log = settings.get('enable_log', False)

print(f"API URL: {api_url}")
print(f"Timeout: {timeout}s")

Node.js Example

const fs = require('fs');
const path = require('path');

// Read config file
const scriptDir = __dirname;
const settingsFile = path.join(scriptDir, 'settings.json');

const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'));

// Use configuration
const apiUrl = settings.api_url;
const apiKey = settings.api_key;
const timeout = settings.timeout || 30;
const enableLog = settings.enable_log || false;

console.log(`API URL: ${apiUrl}`);
console.log(`Timeout: ${timeout}s`);

C# Example

using System;
using System.IO;
using Newtonsoft.Json;
using System.Collections.Generic;

class Program
{
    static void Main(string[] args)
    {
        // Read config file
        string scriptDir = AppDomain.CurrentDomain.BaseDirectory;
        string settingsFile = Path.Combine(scriptDir, "settings.json");
        
        string json = File.ReadAllText(settingsFile);
        var settings = JsonConvert.DeserializeObject<Dictionary<string, object>>(json);
        
        // Use configuration
        string apiUrl = settings["api_url"].ToString();
        string apiKey = settings["api_key"].ToString();
        int timeout = Convert.ToInt32(settings["timeout"]);
        bool enableLog = Convert.ToBoolean(settings["enable_log"]);
        
        Console.WriteLine($"API URL: {apiUrl}");
        Console.WriteLine($"Timeout: {timeout}s");
    }
}

Best Practices

1. Provide Reasonable Default Values

Provide reasonable default values for all configuration items to ensure scripts work properly without modifying configuration.

{
  "key": "retry_count",
  "name": "Retry Count",
  "type": "number",
  "value": 3  // Provide default value
}

2. Use Meaningful Names

Configuration item name should clearly describe the purpose of the configuration.

// ✅ Good naming
{
  "key": "api_timeout",
  "name": "API Request Timeout (seconds)",
  "type": "number"
}

// ❌ Poor naming
{
  "key": "timeout",
  "name": "Timeout",
  "type": "number"
}

3. Add Placeholder Hints

Add placeholder to text input boxes to hint users about what to enter.

{
  "key": "webhook_url",
  "name": "Webhook URL",
  "type": "text",
  "placeholder": "e.g., https://hooks.example.com/webhook"
}

4. Use Required Fields Appropriately

Only set require: true for truly necessary configuration items.

{
  "key": "api_key",
  "name": "API Key",
  "type": "text",
  "require": true  // API key is required
}

5. Choose Appropriate Configuration Types

Select the most appropriate configuration type based on actual needs:

Need	Recommended Type
Passwords, keys	text
Toggle options	checkbox
Fixed options	select
Long text	textarea
File paths	file or path
Date/time	date, time, or datetime

Related Documentation

• Script Integration Overview - Learn about script extension mechanism
• Manifest File - Complete manifest.json reference
• Operations - Command syntax and usage
• Complete Examples - Real-world scenario examples
• API Reference - WebSocket API documentation