mirror of
https://github.com/ntop/ntopng.git
synced 2026-04-30 16:09:32 +00:00
* Added ch flows export to file before ttl delete. Need to add pref for path getter * Added clickhouse ttl export path pref * Fixed naming in clickhouse flow archive * Updated naming in clickhouse flow archive pref * Removed clickhouse archive path pref * Added IXP mode pref #9421 * Removed unused prefs ch flows archive
This commit is contained in:
GabrieleDeri
GitHub
parent
0f0e949868
commit
935146cfac
11 changed files with 738 additions and 14 deletions
269
doc/developers/README.pref_input_box.md
Normal file
269
doc/developers/README.pref_input_box.md
Normal file
|
|
@ -0,0 +1,269 @@
|
|||
# prefsInputFieldPrefs Component Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
`prefsInputFieldPrefs` is a Lua function that creates input field components for ntopng preferences. It handles form rendering, validation, Redis persistence, and runtime notification for preference changes.
|
||||
|
||||
## Function Signature
|
||||
|
||||
```lua
|
||||
function prefsInputFieldPrefs(label, comment, prekey, key, default_value, _input_type, showEnabled, disableAutocomplete, allowURLs, extra)
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
### Required Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `label` | string | Display label for the input field |
|
||||
| `comment` | string | Help text shown below the label |
|
||||
| `prekey` | string | Redis key prefix for the preference |
|
||||
| `key` | string | Unique identifier for the input field |
|
||||
| `default_value` | string/number | Default value when preference is not set |
|
||||
|
||||
### Optional Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `_input_type` | string | "text" | HTML input type (text, number, password, etc.) |
|
||||
| `showEnabled` | boolean | true | Whether to display the field |
|
||||
| `disableAutocomplete` | boolean | false | Disable browser autocomplete |
|
||||
| `allowURLs` | boolean | false | Enable URL pattern validation |
|
||||
| `extra` | table | {} | Additional configuration options |
|
||||
|
||||
### Extra Configuration Options
|
||||
|
||||
The `extra` parameter accepts a table with the following optional fields:
|
||||
|
||||
#### Validation Options
|
||||
- `min` - Minimum value (for number inputs)
|
||||
- `max` - Maximum value (for number inputs)
|
||||
- `minlength` - Minimum string length
|
||||
- `maxlength` - Maximum string length
|
||||
- `step` - Step value for number inputs
|
||||
- `pattern` - Regex pattern for validation
|
||||
- `required` - Mark field as required
|
||||
|
||||
#### UI Options
|
||||
- `width` - Custom width for the input
|
||||
- `inputBoxWidth` - Specific input box width (e.g., "20em")
|
||||
- `style` - Additional CSS styles (table)
|
||||
- `attributes` - Additional HTML attributes (table)
|
||||
- `append` - HTML to append after the input
|
||||
- `disabled` - Disable the input field
|
||||
|
||||
#### Special Options
|
||||
- `skip_redis` - Skip Redis operations (for testing)
|
||||
- `tformat` - Time format for resolution buttons
|
||||
- `format_spec` - Format specification for time inputs
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Text Input
|
||||
|
||||
```lua
|
||||
prefsInputFieldPrefs(
|
||||
"Server Name", -- label
|
||||
"Enter the server name", -- comment
|
||||
"myapp.server", -- prekey
|
||||
"name", -- key
|
||||
"localhost", -- default_value
|
||||
"text" -- input_type
|
||||
)
|
||||
```
|
||||
|
||||
### Number Input with Validation
|
||||
|
||||
```lua
|
||||
prefsInputFieldPrefs(
|
||||
"Port Number",
|
||||
"TCP port for the service (1-65535)",
|
||||
"myapp.network",
|
||||
"port",
|
||||
"8080",
|
||||
"number",
|
||||
true, -- showEnabled
|
||||
false, -- disableAutocomplete
|
||||
false, -- allowURLs
|
||||
{
|
||||
min = 1,
|
||||
max = 65535,
|
||||
required = true,
|
||||
inputBoxWidth = "8em"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Password Input
|
||||
|
||||
```lua
|
||||
prefsInputFieldPrefs(
|
||||
"Database Password",
|
||||
"Password for database connection",
|
||||
"myapp.db",
|
||||
"password",
|
||||
"",
|
||||
"password",
|
||||
true,
|
||||
true, -- disable autocomplete for passwords
|
||||
false,
|
||||
{
|
||||
required = true,
|
||||
minlength = 8,
|
||||
maxlength = 64
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### URL Input with Pattern Validation
|
||||
|
||||
```lua
|
||||
prefsInputFieldPrefs(
|
||||
"API Endpoint",
|
||||
"REST API base URL",
|
||||
"myapp.api",
|
||||
"endpoint",
|
||||
"https://api.example.com",
|
||||
"url",
|
||||
true,
|
||||
false,
|
||||
true, -- allow URLs
|
||||
{
|
||||
pattern = "https?://.*",
|
||||
required = true,
|
||||
inputBoxWidth = "25em"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Conditional Display
|
||||
|
||||
```lua
|
||||
local showAdvanced = ntop.getPref("myapp.show_advanced") == "1"
|
||||
|
||||
prefsInputFieldPrefs(
|
||||
"Advanced Setting",
|
||||
"This setting is only for advanced users",
|
||||
"myapp.advanced",
|
||||
"setting",
|
||||
"default",
|
||||
"text",
|
||||
showAdvanced, -- only show if advanced mode is enabled
|
||||
false,
|
||||
false,
|
||||
{
|
||||
style = { ["font-family"] = "monospace" }
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### 1. Form Submission
|
||||
When a form is submitted via POST:
|
||||
- Function checks `_POST[key]` for the submitted value
|
||||
- Validates the input based on type and constraints
|
||||
- Stores the value in Redis using `ntop.setPref()`
|
||||
- Notifies the runtime ntopng instance via `notifyNtopng()`
|
||||
|
||||
### 2. Initial Load
|
||||
When rendering the form:
|
||||
- Retrieves current value from Redis using `ntop.getPref()`
|
||||
- Falls back to `default_value` if no stored value exists
|
||||
- Sets the default value in Redis if not present
|
||||
|
||||
### 3. URL Processing
|
||||
When `allowURLs` is true, the function automatically fixes common URL formatting issues:
|
||||
- `ldaps:__` → `ldaps://`
|
||||
- `http:__` → `http://`
|
||||
- `smtp:__` → `smtp://`
|
||||
- etc.
|
||||
|
||||
## Client-Side Validation
|
||||
|
||||
The component includes JavaScript validation that:
|
||||
- Validates numeric ranges on focus out
|
||||
- Shows error indicators for invalid values
|
||||
- Removes error styling on focus in
|
||||
- Prevents form submission with invalid data
|
||||
|
||||
## Redis Key Construction
|
||||
|
||||
The Redis key is constructed as:
|
||||
- If `prekey` ends with ".", then key = `prekey + key`
|
||||
- Otherwise, key = `prekey + "." + key`
|
||||
|
||||
Example:
|
||||
```lua
|
||||
prekey = "myapp.database"
|
||||
key = "port"
|
||||
-- Result: "myapp.database.port"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Consistent Naming
|
||||
Use hierarchical naming for related preferences:
|
||||
```lua
|
||||
-- Good
|
||||
"myapp.database.host"
|
||||
"myapp.database.port"
|
||||
"myapp.database.timeout"
|
||||
|
||||
-- Avoid
|
||||
"db_host"
|
||||
"port_db"
|
||||
"timeout"
|
||||
```
|
||||
|
||||
### 2. Meaningful Defaults
|
||||
Choose sensible default values:
|
||||
```lua
|
||||
-- Good
|
||||
default_value = "localhost" -- for hostname
|
||||
default_value = "443" -- for HTTPS port
|
||||
|
||||
-- Avoid
|
||||
default_value = "" -- for required fields
|
||||
default_value = "0" -- when 0 is invalid
|
||||
```
|
||||
|
||||
### 3. Proper Validation
|
||||
Always validate user input:
|
||||
```lua
|
||||
{
|
||||
min = 1,
|
||||
max = 65535,
|
||||
required = true,
|
||||
pattern = "^[0-9]+$" -- only digits
|
||||
}
|
||||
```
|
||||
|
||||
### 4. User-Friendly Labels
|
||||
Use clear, descriptive labels:
|
||||
```lua
|
||||
-- Good
|
||||
label = "Maximum Connection Timeout (seconds)"
|
||||
comment = "How long to wait before timing out connections"
|
||||
|
||||
-- Avoid
|
||||
label = "Timeout"
|
||||
comment = "Timeout value"
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The component handles several error conditions:
|
||||
- Invalid numeric ranges (shows visual error indicator)
|
||||
- Missing required values (HTML5 validation)
|
||||
- Pattern mismatches (browser validation)
|
||||
- Redis connection issues (graceful fallback to defaults)
|
||||
|
||||
## Integration with ntopng
|
||||
|
||||
This component integrates with ntopng's preference system by:
|
||||
- Storing values in Redis for persistence
|
||||
- Notifying the runtime instance of changes
|
||||
- Supporting enterprise/pro feature flags
|
||||
- Following ntopng's UI conventions and styling
|
||||
Loading…
Add table
Add a link
Reference in a new issue