Insert, delete, and move text

The Google Docs API lets you insert or delete text in a document. Moving text involves both operations, preceded by a get of the content.

You can insert or delete text in any of a document's segments (header, footer, footnotes, or body).

Inserting text

To insert text into a document, use the BatchUpdate method and include an InsertTextRequest with the text and location as the payload.

The following example shows how you might insert a series of text strings at specified index locations in the body of a document. The example picks three target offsets (25, 50, and 75) and inserts a ten-character string at each location.

Indexes are measured in UTF-16 code units. For more information, see Start and end index.

Java

        List<Request> requests = new ArrayList<>();
        requests.add(new Request().setInsertText(new InsertTextRequest()
                .setText(text1)
                .setLocation(new Location().setIndex(25))));

        requests.add(new Request().setInsertText(new InsertTextRequest()
                .setText(text2)
                .setLocation(new Location().setIndex(50))));

        requests.add(new Request().setInsertText(new InsertTextRequest()
                .setText(text3)
                .setLocation(new Location().setIndex(75))));

        BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
        BatchUpdateDocumentResponse response = docsService.documents()
                .batchUpdate(DOCUMENT_ID, body).execute();

PHP

$requests = array();
$requests[] = new Google_Service_Docs_Request(array(
    'insertText' => array(
        'text' => $text1,
        'location' => array(
            'index' => 25,
        ),
    ),
    'insertText' => array(
        'text' => $text2,
        'location' => array(
            'index' => 50,
        ),
    ),
    'insertText' => array(
        'text' => $text3,
        'location' => array(
            'index' => 75,
        ),
    ),
));

$batchUpdateRequest = new Google_Service_Docs_BatchUpdateDocumentRequest(array(
    'requests' => $requests
));

$response = $service->documents->batchUpdate($documentId, $batchUpdateRequest);

Python

    requests = [
         {
            'insertText': {
                'location': {
                    'index': 25,
                },
                'text': text1
            }
        },
                 {
            'insertText': {
                'location': {
                    'index': 50,
                },
                'text': text2
            }
        },
                 {
            'insertText': {
                'location': {
                    'index': 75,
                },
                'text': text3
            }
        },
    ]

    result = service.documents().batchUpdate(
        documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Each insertion increments all the higher-numbered indexes by the size of the inserted text. The example precalculates the result of these index changes so that subsequent insertions happen at the new, corrected offset. Thus to insert at the original target offsets of 25, 50, and 75, the actual insertion indexes are:

• First insertion adds 10 characters at offset 25.
• Second insertion adds 10 characters at offset 50+10=60.
• Third insertion adds 10 characters at offset 75+10+10=95.

Simplify matters by writing backwards. To avoid having to precalculate these offset changes, order your insertions to "write backwards": do the insertion at the highest-numbered index first, working your way towards the beginning with each insertion. This ordering ensures that each write's offsets are unaffected by the preceding ones.

Deleting text

To delete text from a document, first construct a Range that defines the range of text to delete. Then use the BatchUpdate method and include a DeleteContentRangeRequest.

Be sure you understand the rules and behavior associated with deleting content.

The following example shows how you might delete the text between index 10 and index 24 in the body of a document.

Java

        List<Request> requests = new ArrayList<>();
        requests.add(new Request().setDeleteContentRange(
                new DeleteContentRangeRequest()
                        .setRange(new Range()
                                .setStartIndex(10)
                                .setEndIndex(24))
            ));

        BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
        BatchUpdateDocumentResponse response = docsService.documents()
                .batchUpdate(DOCUMENT_ID, body).execute();

PHP

$requests = array();
$requests[] = new Google_Service_Docs_Request(array(
    'deleteContentRange' => array(
        'range' => array(
            'startIndex' => 10,
            'endIndex' => 24
        ),
    ),
));

$batchUpdateRequest = new Google_Service_Docs_BatchUpdateDocumentRequest(array(
    'requests' => $requests
));

$response = $service->documents->batchUpdate($documentId, $batchUpdateRequest);

Python

    requests = [
        {
            'deleteContentRange': {
                'range': {
                    'startIndex': 10,
                    'endIndex': 24,
                }

            }

        },
    ]
    result = service.documents().batchUpdate(
        documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Simplify matters by writing backwards. As with insertions, deleting text alters the indexes of all the text "below" in the segment. Again, writing backwards can simplify your handling of indexes.

Moving text

To move text, you delete it in one location and then insert it at another location. But deleting content doesn't give you a copy of it (there is no equivalent concept to the clipboard, for example) so you must extract the contents of the range to use in your insert request.