# Document

Document manipulation methods

## insertTextNode(options) ⇒ `object` | `undefined` <a href="#inserttextnode" id="inserttextnode"></a>

Insert a text node in specified place of the document using an insert strategy based on the options object. The options object and all properties are optional. Return the created node only if using an existing transaction (tx).

* tx: Optional TransactionDocument
* mode: Insert node where: first, last, before or after
* refNode: If insert mode is before or after a reference node is mandatory
* text: Optional text content
* type: Text style type, ie paragraph, preamble, etc

### Parameters

| Param   | Type     | Description                                             |
| ------- | -------- | ------------------------------------------------------- |
| options | `Object` | **Required -** Optional object with optional properties |

### Example

```javascript
// Insert new empty paragraph at cursor position (or last if no cursor in text)
import {api} from 'writer'
api.document.insertTextNode()
```

### Example

```javascript
// Insert a preamble with content after the first node in the document as part of your own transaction
import {api} from 'writer'
const firstNode = api.document.nodes()
api.editorSession.transaction(tx => {
  api.document.insert({
    tx: tx,
    type: 'preamble',
    text: 'My new preamble',
    mode: 'after',
    refNode: nodes[0] // First node
  })
})
```

## insertBlockNode(options) ⇒ `object` | `undefined` <a href="#insertblocknode" id="insertblocknode"></a>

Insert a block node in specified place of the document using an insert strategy based on the options object. The data property that defines the node is mandatory. All other properties are optional. (To insert a node the node type must be defined by a plugin and known to the Writer.) Return the created node only if using an existing transaction (tx).

* data: Mandatory object describing the node, may or may not have an id
* tx: Optional TransactionDocument
* mode: Insert node where: first, last, before or after
* refNode: If insert mode is before or after a reference node is mandatory

### Parameters

| Param   | Type                 | Description                                             |
| ------- | -------------------- | ------------------------------------------------------- |
| options | `Object` \| `string` | **Required -** Optional object with optional properties |

### Example

```javascript
// Insert a new node of type "myquote"
import {api} from 'writer'

api.document.insertBlockNode({
  data: {
    type: 'myquote',
    content: 'People who deny the existence of dragons are often eaten by dragons'
    attribution: 'Ursula K. Le Guin'
  }
})
```

### Example

```javascript
// Insert a new node after the first node in the document as part of your own transaction
import {api} from 'writer'

const firstNode = api.document.nodes()
api.editorSession.transaction(tx => {
  api.document.insert({
    tx: tx,
    data: {
      type: 'myquote',
      content: 'People who deny the existence of dragons are often eaten by dragons'
      attribution: 'Ursula K. Le Guin'
    },
    mode: 'after',
    refNode: nodes[0] // First node
  })
})
```

## nodes(filter) ⇒ `array` <a href="#nodes" id="nodes"></a>

Fetch all nodes in the document, optionally filtered by type

### Parameters

| Param  | Type               | Default | Description                                           |
| ------ | ------------------ | ------- | ----------------------------------------------------- |
| filter | `string` \| `null` | `null`  | **Required -** Optional filter returned nodes by type |

### Example

```javascript
// Fetch all image nodes in the document
import {api} from 'writer'

const nodes = api.document.nodes('ximimage')
```

## triggerFetchResourceNode(node, info) <a href="#triggerfetchresourcenode" id="triggerfetchresourcenode"></a>

Triggers a fetch resource from a nodes url property. For example when node has properties that is only referenced through an external url.

### Parameters

| Param | Type        | Description                                                             |
| ----- | ----------- | ----------------------------------------------------------------------- |
| node  | `BlockNode` | **Required -** The resource node                                        |
| info  | `Object`    | **Required -** Object with information to created substance transaction |

### Example

```javascript
import {api} from 'writer'

// Fetch oauth from Instagram, don't save this fetch in undo/redo history
api.document.triggerFetchResourceNode(this.props.node, { history: false })
```

## insertInlineNode(name, data) ⇒ `*` <a href="#insertinlinenode" id="insertinlinenode"></a>

Insert an inline node at current selection

### Parameters

| Param | Type     | Description                                         |
| ----- | -------- | --------------------------------------------------- |
| name  | `string` | **Required -** The plugin which inserts inline node |
| data  | `object` | **Required -** Data defined by node schema          |

## getPreviousNode(nodeId) ⇒ `*` <a href="#getpreviousnode" id="getpreviousnode"></a>

Retrieve the previous node. Uses the focused surface to get all nodes in that surface/container and then returns the previous node from the one sent in

### Parameters

| Param  | Type     |
| ------ | -------- |
| nodeId | `string` |

## deleteNode(name, node, options) <a href="#deletenode" id="deletenode"></a>

Deletes a node from the document. Triggers a 'document:changed' event to all document:changed listeners except the plugin making the change.

### Parameters

| Param   | Type     | Description                                                                                                           |
| ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| name    | `string` | **Required -** Plugin name                                                                                            |
| node    | `object` | **Required -** Node to delete, must contain an id                                                                     |
| options | `object` | **Required -** Optional options object. Set replaceWithDefaultTextNode to true to replace node with default text node |

### Example

```javascript
import {api} from 'writer'
api.deleteNode(this.props.node);
```

## ~~getDocumentNodes() ⇒ `Array`~~ <a href="#getdocumentnodes" id="getdocumentnodes"></a>

***Deprecated***

Get all nodes in the document


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.navigaglobal.com/writer/6.3.1/api-reference/writerapi/document.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.