0
# Mode Management
1

2
Mode switching functionality enabling dynamic transitions between different editor interfaces and behaviors, plus mode registration system for custom editor plugins.
3

4
## Capabilities
5

6
### Set Editor Mode
7

8
Dynamically change the editor mode, switching between different editing interfaces.
9

10
```javascript { .api }
11
/**
12
 * Change the mode of the editor
13
 * @param mode - Target mode (tree, view, form, code, text, preview)
14
 */
15
setMode(mode: "tree" | "view" | "form" | "code" | "text" | "preview"): void;
16
```
17

18
**Usage Example:**
19

20
```javascript
21
// Switch to code mode
22
editor.setMode("code");
23

24
// Switch to tree mode
25
editor.setMode("tree");
26

27
// Switch to text mode
28
editor.setMode("text");
29
```
30

31
### Get Current Mode
32

33
Retrieve the currently active editor mode.
34

35
```javascript { .api }
36
/**
37
 * Get the current mode of the editor
38
 * @returns Current active mode
39
 */
40
getMode(): "tree" | "view" | "form" | "code" | "text" | "preview";
41
```
42

43
**Usage Example:**
44

45
```javascript
46
const currentMode = editor.getMode();
47
console.log(`Current mode: ${currentMode}`); // e.g., "Current mode: tree"
48
```
49

50
### Register Custom Mode
51

52
Register a custom mode plugin that extends the editor with new functionality.
53

54
```javascript { .api }
55
/**
56
 * Register a plugin mode for the JSON Editor
57
 * @param mode - Mode definition object or array of mode definitions
58
 */
59
static registerMode(mode: ModeDefinition | ModeDefinition[]): void;
60
```
61

62
**Usage Example:**
63

64
```javascript
65
// Register a custom readonly mode
66
const readonlyMode = {
67
  mode: "readonly",
68
  mixin: {
69
    create: function(container, options) {
70
      // Custom mode implementation
71
      this.container = container;
72
      this.options = options;
73
      // Create readonly interface
74
    },
75
    get: function() {
76
      return this.json;
77
    },
78
    set: function(json) {
79
      this.json = json;
80
      // Update readonly display
81
    },
82
    getText: function() {
83
      return JSON.stringify(this.json);
84
    },
85
    setText: function(jsonString) {
86
      this.json = JSON.parse(jsonString);
87
      // Update readonly display
88
    }
89
  },
90
  data: "json"
91
};
92

93
JSONEditor.registerMode(readonlyMode);
94

95
// Use the custom mode
96
const editor = new JSONEditor(container, { mode: "readonly" });
97
```
98

99
### Mode Configuration Access
100

101
Access the global mode configuration registry.
102

103
```javascript { .api }
104
/**
105
 * Configuration for all registered modes
106
 * Object mapping mode names to their definitions
107
 */
108
static modes: { [modeName: string]: ModeDefinition };
109
```
110

111
**Usage Example:**
112

113
```javascript
114
// Check available modes
115
const availableModes = Object.keys(JSONEditor.modes);
116
console.log("Available modes:", availableModes); // ["tree", "view", "form", "code", "text", "preview"]
117

118
// Get specific mode configuration
119
const treeMode = JSONEditor.modes.tree;
120
console.log("Tree mode data type:", treeMode.data); // "json"
121
```
122

123
## Built-in Modes
124

125
### Tree Mode
126
- **Description**: Interactive tree editor with expand/collapse, drag-drop, context menus
127
- **Best for**: Structured JSON editing, visual data manipulation
128
- **Data type**: JSON
129
- **Features**: Node manipulation, search, selection, validation highlighting, undo/redo
130

131
### View Mode  
132
- **Description**: Read-only tree view with same visual structure as tree mode
133
- **Best for**: JSON data inspection without editing capabilities
134
- **Data type**: JSON
135
- **Features**: Expand/collapse, search, selection (read-only)
136

137
### Form Mode
138
- **Description**: Form-like editor where only values can be changed
139
- **Best for**: Editing JSON values while preserving structure
140
- **Data type**: JSON  
141
- **Features**: Value editing, structure is read-only, validation
142

143
### Code Mode
144
- **Description**: Syntax-highlighted code editor powered by Ace
145
- **Best for**: Direct JSON text editing with advanced editor features
146
- **Data type**: Text
147
- **Features**: Syntax highlighting, code folding, find/replace, themes
148

149
### Text Mode
150
- **Description**: Plain text editor for JSON strings
151
- **Best for**: Simple JSON text editing without syntax highlighting
152
- **Data type**: Text
153
- **Features**: JSON formatting, validation, repair
154

155
### Preview Mode
156
- **Description**: Read-only preview for large JSON documents (up to 500MB)
157
- **Best for**: Viewing and transforming large JSON files
158
- **Data type**: Text
159
- **Features**: Large document handling, transformations, formatting, search
160

161
## Mode Definition Interface
162

163
```javascript { .api }
164
interface ModeDefinition {
165
  /** Unique name for the mode */
166
  mode: string;
167
  
168
  /** Mixin object containing mode implementation */
169
  mixin: ModeMixin;
170
  
171
  /** Data type the mode operates on */
172
  data: "text" | "json";
173
  
174
  /** Optional load function called after mode initialization */
175
  load?: () => void;
176
}
177

178
interface ModeMixin {
179
  /** Required: Create the mode interface */
180
  create: (container: HTMLElement, options: JSONEditorOptions) => void;
181
  
182
  /** Get current data (return type depends on mode.data) */
183
  get?: () => any;
184
  
185
  /** Set data (parameter type depends on mode.data) */
186
  set?: (data: any) => void;
187
  
188
  /** Get data as text string */
189
  getText?: () => string;
190
  
191
  /** Set data from text string */
192
  setText?: (text: string) => void;
193
  
194
  /** Destroy the mode and clean up resources */
195
  destroy?: () => void;
196
  
197
  /** Additional mode-specific methods */
198
  [methodName: string]: any;
199
}
200
```
201

202
## Mode Switching Behavior
203

204
When switching modes, JSONEditor automatically:
205

206
1. **Preserves data**: Converts between JSON and text representations as needed
207
2. **Maintains name**: Root node name is preserved across mode switches  
208
3. **Triggers callbacks**: Calls `onModeChange(newMode, oldMode)` if configured
209
4. **Handles validation**: Re-applies schema validation in the new mode
210
5. **Updates UI**: Recreates the entire editor interface for the new mode
211

212
**Usage Example:**
213

214
```javascript
215
const options = {  
216
  mode: "tree",
217
  modes: ["tree", "code", "text"], // Enable mode switching UI
218
  onModeChange: (newMode, oldMode) => {
219
    console.log(`Switched from ${oldMode} to ${newMode}`);
220
  }
221
};
222

223
const editor = new JSONEditor(container, options);
224

225
// Programmatic mode switching
226
editor.setMode("code"); // Triggers onModeChange callback
227
```
228

229
## Error Handling
230

231
Mode operations can throw errors in certain conditions:
232

233
```javascript
234
try {
235
  editor.setMode("nonexistent");
236
} catch (error) {
237
  console.error(error.message); // "Unknown mode 'nonexistent'"
238
}
239

240
try {
241
  JSONEditor.registerMode({
242
    mode: "tree", // Already exists
243
    mixin: {},
244
    data: "json"
245
  });
246
} catch (error) {
247
  console.error(error.message); // "Mode 'tree' already registered"  
248
}
249
```
250

251
## Advanced Mode Registration
252

253
```javascript
254
// Register multiple modes at once
255
JSONEditor.registerMode([
256
  {
257
    mode: "debug",
258
    mixin: { /* debug mode implementation */ },
259
    data: "json",
260
    load: () => console.log("Debug mode loaded")
261
  },
262
  {
263
    mode: "compact", 
264
    mixin: { /* compact mode implementation */ },
265
    data: "text"
266
  }
267
]);
268

269
// Mode with custom load function
270
const customMode = {
271
  mode: "custom",
272
  mixin: {
273
    create: function(container, options) {
274
      this.container = container;
275
      this.options = options;
276
    }
277
  },
278
  data: "json",
279
  load: function() {
280
    // Called after mode is loaded and mixin is applied
281
    console.log("Custom mode ready");
282
    this.setupCustomFeatures();
283
  }
284
};
285

286
JSONEditor.registerMode(customMode);
287
```