Skip to content

Commit d73c2dd

Browse files
UnschooledGamerbajrangCoder
UnschooledGamer
and
bajrangCoder
authored
update: ✨ Editor File API documentation with detailed parameters, properties, methods, and examples (#12)
* update: ✨ Editor File API documentation with detailed parameters, properties, methods, and examples Also updates acode.md to add newEditorFile method to the docs * Improve editor-file.md * Update editor-file.md * Update acode.md --------- Co-authored-by: Raunak Raj <[email protected]>
1 parent 579ace7 commit d73c2dd

File tree

2 files changed

+379
-9
lines changed

2 files changed

+379
-9
lines changed

‎docs/editor-components/editor-file.md‎

Lines changed: 345 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,353 @@
1-
# Editor File
1+
# Editor File API
22

3-
:::warning
4-
**Note:** Work is in progress 🚧
3+
The Editor File API provides functionality to create, manage, interact with files/tabs in the Acode editor. It handles file operations, state management, editor session control, custom editor tab, etc.
4+
5+
::: tip
6+
This API is defined in the [Acode source code (src/lib/editorFile.js)](https://github.com/Acode-Foundation/Acode/blob/52bf3a59c4aebe422d8cfdecf5c85191ed6f6004/src/lib/editorFile.js).
57
:::
68

7-
We are currently working on this section to provide you with detailed and comprehensive information about how Acode plugins work. Please check back soon for updates!
9+
## Import
10+
11+
```js
12+
const EditorFile = acode.require('editorFile');
13+
```
814

9-
## Contribute to the Documentation
15+
## Constructor
1016

11-
We welcome contributions from the community! If you would like to help improve this documentation, please visit our [GitHub repository](https://github.com/bajrangCoder/acode-plugin-docs) and follow the contribution guidelines.
17+
```js
18+
new EditorFile(filename, options)
19+
```
1220

13-
:::tip
14-
You can suggest changes, add new content, or improve existing sections. Every bit of help is appreciated! 🤗
21+
::: info
22+
You can also use [`acode.newEditorFile(filename, options)`](../global-apis/acode.md#neweditorfilefilename-string-options-fileoptions-editorfile) as an alternative.
23+
Both methods are equivalent and accept & return the same parameters.
1524
:::
1625

17-
For more information, see official [Guide](https://acode.app/plugin-docs).
26+
### Parameters
27+
28+
| Parameter | Type | Description | Default |
29+
|-----------|------|-------------|---------|
30+
| filename | `string` | Name of the file | - |
31+
| options | [`FileOptions`](#fileoptions) | File creation options | - |
32+
33+
### FileOptions
34+
35+
| Property | Type | Description | Default |
36+
|----------|------|-------------|---------|
37+
| isUnsaved | `boolean` | Whether file needs to be saved | `false` |
38+
| render | `boolean` | Make file active | `true` |
39+
| id | `string` | ID for the file | - |
40+
| uri | `string` | URI of the file | - |
41+
| text | `string` | Session text | - |
42+
| editable | `boolean` | Enable file editing | `true` |
43+
| deletedFile | `boolean` | File does not exist at source | `false` |
44+
| SAFMode | `'single' \| 'tree'` | Storage access framework mode | - |
45+
| encoding | `string` | Text encoding | `appSettings.value.defaultFileEncoding` |
46+
| cursorPos | `object` | Cursor position | - |
47+
| scrollLeft | `number` | Scroll left position | - |
48+
| scrollTop | `number` | Scroll top position | - |
49+
| folds | [`Array<Fold>`](https://ajaxorg.github.io/ace-api-docs/classes/src_edit_session_fold.Fold.html) | Code folds | - |
50+
| type | `string` | Type of content (e.g., 'editor') | `'editor'` |
51+
| tabIcon | `string` | Icon class for the file tab | `'file file_type_default'` |
52+
| content | string \| [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) | Custom content element or HTML string. Strings are sanitized using DOMPurify | - |
53+
| stylesheets | `string\|string[]` | Custom stylesheets for tab. Can be URL, or CSS string | - |
54+
| hideQuickTools | `boolean` | Whether to hide quicktools for this tab | `false` |
55+
56+
## Properties
57+
58+
### Read-only Properties
59+
60+
| Property | Type | Description |
61+
|----------|------|-------------|
62+
| type | `string` | Type of content this file represents |
63+
| tabIcon | `string` | Icon class for the file tab |
64+
| content | `HTMLElement` | Custom content element |
65+
| id | `string` | File unique ID |
66+
| filename | `string` | Name of the file |
67+
| location | `string` | Directory path of the file |
68+
| uri | `string` | File location on the device |
69+
| eol | `'windows' \| 'unix'` | End of line character |
70+
| editable | `boolean` | Whether file can be edited |
71+
| isUnsaved | `boolean` | Whether file has unsaved changes |
72+
| name | `string` | File name (for plugin compatibility) |
73+
| cacheFile | `string` | Cache file URL |
74+
| icon | `string` | File icon class |
75+
| tab | `HTMLElement` | File tab element |
76+
| SAFMode | `'single' \| 'tree' \| null` | Storage access framework mode |
77+
| loaded | `boolean` | Whether file has completed loading text |
78+
| loading | `boolean` | Whether file is still loading text |
79+
| session | `AceAjax.IEditSession` | EditSession of the file |
80+
| readOnly | `boolean` | Whether file is readonly |
81+
| markChanged | `boolean` | Whether to mark changes when session text changes |
82+
83+
### Writable(setters) Properties
84+
85+
| Property | Type | Description |
86+
|----------|------|-------------|
87+
| id | `string` | Set file unique ID |
88+
| filename | `string` | Set file name |
89+
| location | `string` | Set file directory path |
90+
| uri | `string` | Set file location |
91+
| eol | `'windows' \| 'unix'` | Set end of line character |
92+
| editable | `boolean` | Set file editability |
93+
| readOnly | `boolean` | Set file readonly state |
94+
95+
## Methods
96+
97+
### File Operations
98+
99+
#### [save()](#save)
100+
Saves the file to its current location.
101+
102+
```js
103+
await file.save();
104+
```
105+
106+
#### [saveAs()](#saveas)
107+
Saves the file to a new location.
108+
109+
```js
110+
await file.saveAs();
111+
```
112+
113+
#### [remove(force = false)](#removeforce--false)
114+
Removes and closes the file.
115+
116+
```js
117+
await file.remove(true); // Force close without save prompt
118+
```
119+
120+
#### [makeActive()](#makeactive)
121+
Makes this file the active file in the editor.
122+
123+
```js
124+
file.makeActive();
125+
```
126+
127+
#### [removeActive()](#removeactive)
128+
Removes active state from the file.
129+
130+
```js
131+
file.removeActive();
132+
```
133+
134+
### Editor Operations
135+
136+
#### [setMode(mode)](#setmodemode)
137+
Sets syntax highlighting mode for the file.
138+
139+
```js
140+
file.setMode('javascript');
141+
```
142+
143+
#### [writeToCache()](#writetocache)
144+
Writes file content to cache.
145+
146+
```js
147+
await file.writeToCache();
148+
```
149+
150+
#### [isChanged()](#ischanged)
151+
Checks if file has unsaved changes.
152+
153+
```js
154+
const changed = await file.isChanged();
155+
```
156+
157+
#### [canRun()](#canrun)
158+
Checks if file can be run.
159+
160+
```js
161+
const canRun = await file.canRun();
162+
```
163+
164+
#### [writeCanRun(callback)](#writecanruncallback)
165+
Sets whether to show run button.
166+
167+
```js
168+
file.writeCanRun(() => true);
169+
```
170+
171+
#### [run()](#run)
172+
Runs the file.
173+
174+
```js
175+
file.run();
176+
```
177+
178+
#### [runFile()](#runfile)
179+
Runs the file in app.
180+
181+
```js
182+
file.runFile();
183+
```
184+
185+
#### [openWith()](#openwith)
186+
Opens file with system app.
187+
188+
```js
189+
file.openWith();
190+
```
191+
192+
#### [editWith()](#editwith)
193+
Opens file for editing with system app.
194+
195+
```js
196+
file.editWith();
197+
```
198+
199+
#### [share()](#share)
200+
Shares the file.
201+
202+
```js
203+
file.share();
204+
```
205+
206+
#### [addStyle(style)](#addstylestyle)
207+
Adds stylesheet to tab's shadow DOM.
208+
209+
```js
210+
file.addStyle('custom.css');
211+
```
212+
213+
### Event Handling
214+
215+
#### [on(event, callback)](#onevent-callback)
216+
Adds event listener.
217+
218+
```js
219+
file.on('save', (event) => {
220+
console.log('File saved');
221+
});
222+
```
223+
224+
#### [off(event, callback)](#offevent-callback)
225+
Removes event listener.
226+
227+
```js
228+
file.off('save', callback);
229+
```
230+
231+
## Events
232+
233+
The EditorFile class emits the following events:
234+
235+
| Event | Description |
236+
|-------|-------------|
237+
| save | File is saved |
238+
| change | File content changes |
239+
| focus | File gains focus |
240+
| blur | File loses focus |
241+
| close | File is closed |
242+
| rename | File is renamed |
243+
| load | File is loaded |
244+
| loadError | Error loading file |
245+
| loadStart | File loading starts |
246+
| loadEnd | File loading ends |
247+
| changeMode | Syntax mode changes |
248+
| run | File is run |
249+
| canRun | File runnable state changes |
250+
251+
## Examples
252+
253+
### Creating a New File
254+
255+
```js
256+
const file = new EditorFile('example.js', {
257+
text: 'console.log("Hello World");',
258+
editable: true
259+
});
260+
```
261+
262+
### Creating a Custom File Type
263+
264+
```js
265+
// Method 1: Using HTML string
266+
const file1 = new EditorFile('custom.html', {
267+
type: 'custom',
268+
content: '<div class="custom-content"><h1>Custom Content</h1></div>',
269+
stylesheets: [
270+
// External stylesheet
271+
'https://example.com/styles.css',
272+
// Local stylesheet
273+
'/styles/custom.css',
274+
// Inline CSS
275+
`
276+
.custom-content {
277+
padding: 20px;
278+
background: #f5f5f5;
279+
}
280+
`
281+
],
282+
hideQuickTools: true
283+
});
284+
285+
// Method 2: Using HTMLElement
286+
const customElement = document.createElement('div');
287+
customElement.innerHTML = '<h1>Custom Content</h1>';
288+
289+
const file2 = new EditorFile('custom.html', {
290+
type: 'custom',
291+
content: customElement,
292+
stylesheets: ['/styles/custom.css'],
293+
hideQuickTools: true
294+
});
295+
296+
// Add additional styles later if needed
297+
file1.addStyle('/styles/additional.css');
298+
```
299+
300+
::: warning
301+
Custom Editor Tabs are isolated from main dom using shadow dom, so don't select tab elements using main DOM(`document`).
302+
:::
303+
304+
### Saving File Changes
305+
306+
```js
307+
try {
308+
await file.save();
309+
console.log('File saved successfully');
310+
} catch (err) {
311+
console.error('Error saving file:', err);
312+
}
313+
```
314+
315+
### Handling File Events
316+
317+
```js
318+
file.on('change', (event) => {
319+
console.log('File content changed');
320+
});
321+
322+
file.on('save', (event) => {
323+
console.log('File saved');
324+
});
325+
```
326+
327+
### Running a File
328+
329+
```js
330+
if (await file.canRun()) {
331+
file.run();
332+
}
333+
```
334+
335+
## Error Handling
336+
337+
The API includes built-in error handling for file operations. Always wrap async operations in try/catch blocks:
338+
339+
```js
340+
try {
341+
await file.save();
342+
} catch (err) {
343+
console.error('Error saving file:', err);
344+
}
345+
```
346+
347+
::: tip
348+
Use the `isChanged()` method to check for unsaved changes before closing files.
349+
:::
350+
351+
::: warning
352+
Always handle file operations asynchronously and implement proper error handling.
353+
:::

0 commit comments

Comments
 (0)