docex_editor
Version:
A powerful, cloud-based document editor for React applications
307 lines (251 loc) • 8.29 kB
Markdown
# DocEx Editor
A powerful, cloud-based document editor for React applications. Create beautiful documents with a familiar word processor interface, complete with tables, formatting, and export capabilities.
## Installation
```bash
npm i docex_editor
```
```bash
yarn add docex_editor
```
```bash
pnpm add docex_editor
```
## Quick Start
```typescript
import React, { useEffect, useState } from "react";
import {
createEditor,
createEditorComponent,
EditorWidgetProps,
} from "docex_editor";
export default function App() {
const [EditorComponent, setEditorComponent] =
useState<React.ComponentType<EditorWidgetProps> | null>(null);
useEffect(() => {
async function loadEditor() {
try {
const ctrl = await createEditor("YOUR_API_KEY");
const Component = await createEditorComponent(ctrl);
setEditorComponent(() => Component);
} catch (err) {
console.error("Failed to load editor:", err);
}
}
loadEditor();
}, []);
return (
<div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
{EditorComponent && (
<EditorComponent
content="Hello world"
showToolbar={true}
style={{ height: "100vh" }}
/>
)}
</div>
);
}
```
## Component Props
The `EditorComponent` accepts the following optional props:
### `content?: string`
Initial content to load into the editor. You can pass plain text or HTML. If omitted, the editor will start empty.
### `showToolbar?: boolean`
Whether to show the editor toolbar. Defaults to `true`.
### `style?: React.CSSProperties`
CSS styles to apply to the editor container.
### `initialPageMargin?: number`
The margin (in points) around each page. Defaults to `96`.
### `initialPageGap?: number`
The vertical gap (in points) between pages. Defaults to `76`.
### `initialPagePadding?: number`
The padding (in points) inside each page. Defaults to `96`.
## Editor Methods
The `createEditor` function returns an `EditorController` instance that provides programmatic access to editor functionality. You can use these methods to build custom toolbars or trigger editor actions programmatically.
### Text Formatting
- `toggleBold()` - Toggle bold formatting
- `toggleItalic()` - Toggle italic formatting
- `toggleUnderline()` - Toggle underline formatting
- `toggleStrike()` - Toggle strikethrough formatting
### Block Formatting
- `setParagraph()` - Set current block to paragraph
- `toggleHeading(level: 1 | 2 | 3)` - Set heading level
- `toggleBulletList()` - Toggle bullet list
- `toggleOrderedList()` - Toggle numbered list
### Table Operations
- `insertTable(rows?, cols?, withHeaderRow?)` - Insert new table
- `addColumnBefore()` - Add column before current
- `addColumnAfter()` - Add column after current
- `deleteColumn()` - Delete current column
- `addRowBefore()` - Add row before current
- `addRowAfter()` - Add row after current
- `deleteRow()` - Delete current row
- `mergeCells()` - Merge selected cells
- `splitCell()` - Split current cell
- `toggleHeaderCell()` - Toggle header cell
- `deleteTable()` - Delete current table
### Utility Methods
- `isActive(name: string)` - Check if formatting is active
- `undo()` - Undo last action
- `redo()` - Redo last undone action
- `exportToDocx(fileName?: string, toDownload?: boolean): Promise<Blob>` - Export to DOCX format
## Examples
### Minimal Setup
```typescript
import React, { useEffect, useState } from "react";
import {
createEditor,
createEditorComponent,
EditorWidgetProps,
} from "docex_editor";
export default function App() {
const [EditorComponent, setEditorComponent] =
useState<React.ComponentType<EditorWidgetProps> | null>(null);
useEffect(() => {
async function loadEditor() {
try {
const ctrl = await createEditor("YOUR_API_KEY");
const Component = await createEditorComponent(ctrl);
setEditorComponent(() => Component);
} catch (err) {
console.error("Failed to load editor:", err);
}
}
loadEditor();
}, []);
return (
<div style={{ height: "100vh" }}>
{EditorComponent && <EditorComponent />}
</div>
);
}
```
### Custom Content and Styling
```typescript
import React, { useEffect, useState } from "react";
import {
createEditor,
createEditorComponent,
EditorWidgetProps,
} from "docex_editor";
export default function App() {
const [EditorComponent, setEditorComponent] =
useState<React.ComponentType<EditorWidgetProps> | null>(null);
useEffect(() => {
async function loadEditor() {
try {
const ctrl = await createEditor("YOUR_API_KEY");
const Component = await createEditorComponent(ctrl);
setEditorComponent(() => Component);
} catch (err) {
console.error("Failed to load editor:", err);
}
}
loadEditor();
}, []);
return (
<div style={{ height: "100vh", padding: "20px" }}>
{EditorComponent && (
<EditorComponent
content="<h1>Welcome!</h1><p>Start editing your document here.</p>"
showToolbar={true}
initialPageMargin={80}
initialPageGap={50}
initialPagePadding={80}
style={{
border: "1px solid #e5e7eb",
borderRadius: "8px",
height: "calc(100vh - 40px)"
}}
/>
)}
</div>
);
}
```
### Custom Toolbar with Controller
```typescript
import React, { useEffect, useState } from "react";
import {
createEditor,
createEditorComponent,
EditorController,
EditorWidgetProps,
} from "docex_editor";
export default function App() {
const [controller, setController] = useState<EditorController | null>(null);
const [EditorComponent, setEditorComponent] =
useState<React.ComponentType<EditorWidgetProps> | null>(null);
useEffect(() => {
async function loadEditor() {
try {
const ctrl = await createEditor("YOUR_API_KEY");
setController(ctrl);
const Component = await createEditorComponent(ctrl);
setEditorComponent(() => Component);
} catch (err) {
console.error("Failed to load editor:", err);
}
}
loadEditor();
}, []);
return (
<div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
{/* Custom toolbar */}
<div style={{ padding: "10px", borderBottom: "1px solid #ccc" }}>
<button onClick={() => controller?.toggleBold()}>Bold</button>
<button onClick={() => controller?.toggleItalic()}>Italic</button>
<button onClick={() => controller?.setParagraph()}>Paragraph</button>
<button onClick={() => controller?.toggleHeading(1)}>H1</button>
<button onClick={() => controller?.exportToDocx("document.docx", true)}>
Export DOCX
</button>
</div>
{/* Editor */}
<div style={{ flex: 1, overflowY: "auto", position: "relative" }}>
{EditorComponent && (
<EditorComponent
content="Hello world"
showToolbar={false}
style={{ height: "100%" }}
/>
)}
</div>
</div>
);
}
```
### Checking Active States
Use the `isActive` method to check if formatting is currently applied:
```typescript
// Check if text is bold
const isBold = controller?.isActive("bold");
// Use in button styling
<button
onClick={() => controller?.toggleBold()}
style={{
backgroundColor: controller?.isActive("bold") ? "#0070f3" : "transparent",
color: controller?.isActive("bold") ? "white" : "black"
}}
>
Bold
</button>
```
## API Key
You'll need an API key to use DocEx Editor. Visit [your dashboard](https://docex.dev) to get your API key.
## Requirements
- React 17.0.0 or higher
- ReactDOM 17.0.0 or higher
## TypeScript Support
DocEx Editor is written in TypeScript and includes full type definitions. All interfaces and types are exported for your convenience:
```typescript
import {
EditorController,
EditorWidgetProps,
EditorComponent
} from "docex_editor";
```
## License
Commercial license required. See [docex.dev](https://docex.dev) for pricing and licensing information.
## Support
For support, documentation, and examples, visit [docex.dev](https://docex.dev) or contact our team.