FieldCollectionNEW

FieldCollection:

{
  all(options?: FieldQueryOptions): Field[];
  get(id: string): Field | undefined;
  add(input: AddFieldInput): Field | undefined;
}

The fields of a document.

Methods

all()

all(options?): Field[]

Lists fields in document order: the body first, including table cells, footnotes, endnotes and shape text, then each section’s headers and footers. Fields inside comments are not listed.

Parameters

options?

FieldQueryOptions

Filters to apply

Returns

Field[]

The matching fields

Example

List the page references of every table of contents entry, which are nested in it:

const references = draft
  .fields()
  .all({ includeNested: true })
  .filter((field) => field.definition.type === 'pageReference' && field.parentId !== null);

---

get()

get(id): Field | undefined

Finds a field by its id, nested or not.

Parameters

id

string

The field’s Field.id

Returns

Field | undefined

The field, or undefined when the document has no field with that id

Remarks

A shortcut for finding the field with this id in all({ includeNested: true }).

Example

Find, in a later transaction, a field added earlier:

const id = await doc.transaction(async ({ draft }) => {
  const paragraph = draft.body().content().blocklevels()[0];
  if (paragraph?.type !== 'paragraph') return { commit: false, result: undefined };
  const field = draft.fields().add({
    definition: { type: 'pageNumber' },
    at: { type: 'point', point: { textView: paragraph.asTextView(), placement: 'after' } },
  });
  return { commit: true, result: field?.id };
});

await doc.transaction(async ({ draft }) => {
  const field = id ? draft.fields().get(id) : undefined;
  return { commit: false, result: field?.definition };
});

---

add()

add(input): Field | undefined

Adds a field.

Parameters

input

AddFieldInput

The field’s definition and where it goes

Returns

Field | undefined

The new field, or undefined when the input is invalid or the participant may not edit; the document is then unchanged

Remarks

A page number or page count goes inline at the point. A table of contents is whole paragraphs, so it can only go at the start or end of a paragraph, where it becomes a new paragraph before or after it.

The new field has no value yet: its value is '' until the document is next laid out, which fills it in, or its fields are updated.

Adding a field on existing text keeps that text as the field’s value. The span must not be empty, must not partly overlap another field (a field it fully covers becomes nested in the new one, and a field fully covering it becomes the new one’s parent), and for a table of contents must cover whole paragraphs.

In a review transaction a field added at a point is a tracked insertion; adding one on existing text is not available and returns undefined.

Examples

Add a page number at the end of the footer:

await doc.transaction(async ({ draft }) => {
  const footer = draft.body().sections()[0].headersAndFooters().footers().default();
  const paragraph = footer?.blocklevels()[0];
  if (paragraph?.type !== 'paragraph') return false;
  const textView = paragraph.asTextView();
  textView.setText('Page ');
  draft.fields().add({ definition: { type: 'pageNumber' }, at: { type: 'point', point: { textView, placement: 'after' } } });
  return true;
});

Turn a page number typed by hand into a page number field, keeping its text:

await doc.transaction(async ({ draft }) => {
  const paragraph = draft.body().content().blocklevels()[0];
  if (paragraph?.type !== 'paragraph') return false;
  const textView = paragraph.asTextView();
  const hit = textView.searchText(/\d+$/);
  if (!hit) return false;
  draft.fields().add({ definition: { type: 'pageNumber' }, at: { type: 'text', span: { from: { textView, range: hit.range } } } });
  return true;
});

Add “see page N” pointing at a bookmark, and fill in N when the transaction is committed:

await doc.transaction(async ({ draft }) => {
  const paragraph = draft.body().content().blocklevels()[0];
  if (paragraph?.type !== 'paragraph') return false;
  const textView = paragraph.asTextView();
  textView.addInlineText(' (see page ');
  const reference = draft.fields().add({
    definition: { type: 'pageReference', bookmark: 'Results', hyperlink: true },
    at: { type: 'point', point: { textView, placement: 'after' } },
  });
  textView.addInlineText(')');
  reference?.update();
  return true;
});