word.contentcontrolcollection.yml

### YamlMime:TSType
name: Word.ContentControlCollection
uid: 'word!Word.ContentControlCollection:class'
package: word!
fullName: Word.ContentControlCollection
summary: >-
  Contains a collection of [Word.ContentControl](xref:word!Word.ContentControl:class) objects. Content controls are
  bounded and potentially labeled regions in a document that serve as containers for specific types of content.
  Individual content controls may contain contents such as images, tables, or paragraphs of formatted text. Currently,
  only rich text and plain text content controls are supported.
remarks: '\[ [API set: WordApi 1.1](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]'
isPreview: false
isDeprecated: false
type: class
properties:
  - name: context
    uid: 'word!Word.ContentControlCollection#context:member'
    package: word!
    fullName: context
    summary: >-
      The request context associated with the object. This connects the add-in's process to the Office host
      application's process.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'context: RequestContext;'
      return:
        type: '<xref uid="word!Word.RequestContext:class" />'
  - name: items
    uid: 'word!Word.ContentControlCollection#items:member'
    package: word!
    fullName: items
    summary: Gets the loaded child items in this collection.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly items: Word.ContentControl[];'
      return:
        type: '<xref uid="word!Word.ContentControl:class" />[]'
methods:
  - name: getByChangeTrackingStates(changeTrackingStates)
    uid: 'word!Word.ContentControlCollection#getByChangeTrackingStates:member(1)'
    package: word!
    fullName: getByChangeTrackingStates(changeTrackingStates)
    summary: Gets the content controls that have the specified tracking state.
    remarks: '\[ [API set: WordApi 1.5](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getByChangeTrackingStates(changeTrackingStates: Word.ChangeTrackingState[]): Word.ContentControlCollection;'
      parameters:
        - id: changeTrackingStates
          description: Required. An array of content control change tracking states.
          type: '<xref uid="word!Word.ChangeTrackingState:enum" />[]'
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: getById(id)
    uid: 'word!Word.ContentControlCollection#getById:member(1)'
    package: word!
    fullName: getById(id)
    summary: >-
      Gets a content control by its identifier. Throws an `ItemNotFound` error if there isn't a content control with the
      identifier in this collection.
    remarks: |-
      \[ [API set: WordApi 1.1](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Run a batch operation against the Word object model.
      await Word.run(async (context) => {

          // Create a proxy object for the content control that contains a specific id.
          const contentControl = context.document.contentControls.getById(30086310);

          // Queue a command to load the text property for a content control.
          contentControl.load('text');

          // Synchronize the document state by executing the queued commands,
          // and return a promise to indicate task completion.
          await context.sync();
          console.log('The content control with that Id has been found in this document.');
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getById(id: number): Word.ContentControl;'
      parameters:
        - id: id
          description: Required. A content control identifier.
          type: number
      return:
        type: '<xref uid="word!Word.ContentControl:class" />'
        description: ''
  - name: getByIdOrNullObject(id)
    uid: 'word!Word.ContentControlCollection#getByIdOrNullObject:member(1)'
    package: word!
    fullName: getByIdOrNullObject(id)
    summary: >-
      Gets a content control by its identifier. If there isn't a content control with the identifier in this collection,
      then this method will return an object with its `isNullObject` property set to `true`<!-- -->. For further
      information, see [*OrNullObject methods and
      properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
      -->.
    remarks: |-
      \[ [API set: WordApi 1.3](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Run a batch operation against the Word object model.
      await Word.run(async (context) => {

          // Create a proxy object for the content control that contains a specific id.
          const contentControl = context.document.contentControls.getByIdOrNullObject(30086310);

          // Queue a command to load the text property for a content control.
          contentControl.load('text');

          // Synchronize the document state by executing the queued commands,
          // and return a promise to indicate task completion.
          await context.sync();
          if (contentControl.isNullObject) {
              console.log('There is no content control with that ID.')
          } else {
              console.log('The content control with that ID has been found in this document.');
          }
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getByIdOrNullObject(id: number): Word.ContentControl;'
      parameters:
        - id: id
          description: Required. A content control identifier.
          type: number
      return:
        type: '<xref uid="word!Word.ContentControl:class" />'
        description: ''
  - name: getByTag(tag)
    uid: 'word!Word.ContentControlCollection#getByTag:member(1)'
    package: word!
    fullName: getByTag(tag)
    summary: Gets the content controls that have the specified tag.
    remarks: >-
      \[ [API set: WordApi 1.1](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/90-scenarios/doc-assembly.yaml


      await Word.run(async (context) => {
          const contentControls = context.document.contentControls.getByTag("customer");
          contentControls.load("text");

          await context.sync();

          for (let i = 0; i < contentControls.items.length; i++) {
            contentControls.items[i].insertText("Fabrikam", "Replace");
          }

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getByTag(tag: string): Word.ContentControlCollection;'
      parameters:
        - id: tag
          description: Required. A tag set on a content control.
          type: string
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: getByTitle(title)
    uid: 'word!Word.ContentControlCollection#getByTitle:member(1)'
    package: word!
    fullName: getByTitle(title)
    summary: Gets the content controls that have the specified title.
    remarks: |-
      \[ [API set: WordApi 1.1](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Run a batch operation against the Word object model.
      await Word.run(async (context) => {

          // Create a proxy object for the content controls collection that contains a specific title.
          const contentControlsWithTitle = context.document.contentControls.getByTitle('Enter Customer Address Here');

          // Queue a command to load the text property for all of content controls with a specific title.
          contentControlsWithTitle.load('text');

          // Synchronize the document state by executing the queued commands,
          // and return a promise to indicate task completion.
          await context.sync();
          if (contentControlsWithTitle.items.length === 0) {
              console.log(
                  "There isn't a content control with a title of 'Enter Customer Address Here' in this document.");
          } else {
              console.log(
                  "The first content control with the title of 'Enter Customer Address Here' has this text: " + 
                  contentControlsWithTitle.items[0].text);
          }
      });

      // The Word-Add-in-DocumentAssembly sample has another example of using the getByTitle method.
      // https://github.com/OfficeDev/Word-Add-in-DocumentAssembly
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getByTitle(title: string): Word.ContentControlCollection;'
      parameters:
        - id: title
          description: Required. The title of a content control.
          type: string
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: getByTypes(types)
    uid: 'word!Word.ContentControlCollection#getByTypes:member(1)'
    package: word!
    fullName: getByTypes(types)
    summary: Gets the content controls that have the specified types.
    remarks: '\[ [API set: WordApi 1.3](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getByTypes(types: Word.ContentControlType[]): Word.ContentControlCollection;'
      parameters:
        - id: types
          description: Required. An array of content control types.
          type: '<xref uid="word!Word.ContentControlType:enum" />[]'
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: getFirst()
    uid: 'word!Word.ContentControlCollection#getFirst:member(1)'
    package: word!
    fullName: getFirst()
    summary: Gets the first content control in this collection. Throws an `ItemNotFound` error if this collection is empty.
    remarks: |-
      \[ [API set: WordApi 1.3](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Run a batch operation against the Word object model.
      await Word.run(async (context) => {

          // Create a proxy object for the first content control in the document.
          const contentControl = context.document.contentControls.getFirstOrNullObject();

          // Queue a command to load the text property for a content control.
          contentControl.load('text');

          // Synchronize the document state by executing the queued commands,
          // and return a promise to indicate task completion.
          await context.sync();
          if (contentControl.isNullObject) {
              console.log('There are no content controls in this document.')
          } else {
              console.log('The first content control has been found in this document.');
          }
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getFirst(): Word.ContentControl;'
      return:
        type: '<xref uid="word!Word.ContentControl:class" />'
        description: ''
  - name: getFirstOrNullObject()
    uid: 'word!Word.ContentControlCollection#getFirstOrNullObject:member(1)'
    package: word!
    fullName: getFirstOrNullObject()
    summary: >-
      Gets the first content control in this collection. If this collection is empty, then this method will return an
      object with its `isNullObject` property set to `true`<!-- -->. For further information, see [*OrNullObject
      methods and
      properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
      -->.
    remarks: >-
      \[ [API set: WordApi 1.3](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/10-content-controls/insert-and-change-checkbox-content-control.yaml


      // Toggles the isChecked property of the first checkbox content control found in the selection.

      await Word.run(async (context) => {
        const selectedRange = context.document.getSelection();
        let selectedContentControl = selectedRange
          .getContentControls({
            types: [Word.ContentControlType.checkBox]
          })
          .getFirstOrNullObject();
        selectedContentControl.load("id,checkboxContentControl/isChecked");

        await context.sync();

        if (selectedContentControl.isNullObject) {
          const parentContentControl = selectedRange.parentContentControl;
          parentContentControl.load("id,type,checkboxContentControl/isChecked");
          await context.sync();

          if (parentContentControl.isNullObject || parentContentControl.type !== Word.ContentControlType.checkBox) {
            console.warn("No checkbox content control is currently selected.");
            return;
          } else {
            selectedContentControl = parentContentControl;
          }
        }

        const isCheckedBefore = selectedContentControl.checkboxContentControl.isChecked;
        console.log("isChecked state before:", `id: ${selectedContentControl.id} ... isChecked: ${isCheckedBefore}`);
        selectedContentControl.checkboxContentControl.isChecked = !isCheckedBefore;
        selectedContentControl.load("id,checkboxContentControl/isChecked");
        await context.sync();

        console.log(
          "isChecked state after:",
          `id: ${selectedContentControl.id} ... isChecked: ${selectedContentControl.checkboxContentControl.isChecked}`
        );
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getFirstOrNullObject(): Word.ContentControl;'
      return:
        type: '<xref uid="word!Word.ContentControl:class" />'
        description: ''
  - name: getItem(id)
    uid: 'word!Word.ContentControlCollection#getItem:member(1)'
    package: word!
    fullName: getItem(id)
    summary: Gets a content control by its ID.
    remarks: '\[ [API set: WordApi 1.1](/javascript/api/requirement-sets/word/word-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getItem(id: number): Word.ContentControl;'
      parameters:
        - id: id
          description: The content control's ID.
          type: number
      return:
        type: '<xref uid="word!Word.ContentControl:class" />'
        description: ''
  - name: load(options)
    uid: 'word!Word.ContentControlCollection#load:member(1)'
    package: word!
    fullName: load(options)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        load(options?: Word.Interfaces.ContentControlCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions):
        Word.ContentControlCollection;
      parameters:
        - id: options
          description: Provides options for which properties of the object to load.
          type: >-
            <xref uid="word!Word.Interfaces.ContentControlCollectionLoadOptions:interface" /> & <xref
            uid="word!Word.Interfaces.CollectionLoadOptions:interface" />
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: |-


          #### Examples

          ```TypeScript
          // Run a batch operation against the Word object model.
          await Word.run(async (context) => {

              // Create a proxy object for the content controls collection.
              const contentControls = context.document.contentControls;

              // Queue a command to load the id property for all of the content controls.
              contentControls.load('id');

              // Synchronize the document state by executing the queued commands,
              // and return a promise to indicate task completion.
              await context.sync();
              if (contentControls.items.length === 0) {
                  console.log('No content control found.');
              }
              else {
                  // Queue a command to load the properties on the first content control.
                  contentControls.items[0].load(  'appearance,' +
                                                  'cannotDelete,' +
                                                  'cannotEdit,' +
                                                  'color,' +
                                                  'id,' +
                                                  'placeHolderText,' +
                                                  'removeWhenEdited,' +
                                                  'title,' +
                                                  'text,' +
                                                  'type,' +
                                                  'style,' +
                                                  'tag,' +
                                                  'font/size,' +
                                                  'font/name,' +
                                                  'font/color');

                  // Synchronize the document state by executing the queued commands,
                  // and return a promise to indicate task completion.
                  await context.sync();
                  console.log('Property values of the first content control:' +
                      '   ----- appearance: ' + contentControls.items[0].appearance +
                      '   ----- cannotDelete: ' + contentControls.items[0].cannotDelete +
                      '   ----- cannotEdit: ' + contentControls.items[0].cannotEdit +
                      '   ----- color: ' + contentControls.items[0].color +
                      '   ----- id: ' + contentControls.items[0].id +
                      '   ----- placeHolderText: ' + contentControls.items[0].placeholderText +
                      '   ----- removeWhenEdited: ' + contentControls.items[0].removeWhenEdited +
                      '   ----- title: ' + contentControls.items[0].title +
                      '   ----- text: ' + contentControls.items[0].text +
                      '   ----- type: ' + contentControls.items[0].type +
                      '   ----- style: ' + contentControls.items[0].style +
                      '   ----- tag: ' + contentControls.items[0].tag +
                      '   ----- font size: ' + contentControls.items[0].font.size +
                      '   ----- font name: ' + contentControls.items[0].font.name +
                      '   ----- font color: ' + contentControls.items[0].font.color);
              }
          });

          // The Silly stories add-in sample shows how the load method is used
          // to load the content control collection with the tag and title properties.
          // https://aka.ms/sillystorywordaddin
          ```
  - name: load(propertyNames)
    uid: 'word!Word.ContentControlCollection#load:member(2)'
    package: word!
    fullName: load(propertyNames)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(propertyNames?: string | string[]): Word.ContentControlCollection;'
      parameters:
        - id: propertyNames
          description: A comma-delimited string or an array of strings that specify the properties to load.
          type: 'string | string[]'
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: load(propertyNamesAndPaths)
    uid: 'word!Word.ContentControlCollection#load:member(3)'
    package: word!
    fullName: load(propertyNamesAndPaths)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ContentControlCollection;'
      parameters:
        - id: propertyNamesAndPaths
          description: >-
            `propertyNamesAndPaths.select` is a comma-delimited string that specifies the properties to load, and
            `propertyNamesAndPaths.expand` is a comma-delimited string that specifies the navigation properties to load.
          type: '<xref uid="office!OfficeExtension.LoadOption:interface" />'
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: toJSON()
    uid: 'word!Word.ContentControlCollection#toJSON:member(1)'
    package: word!
    fullName: toJSON()
    summary: >-
      Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to
      `JSON.stringify()`<!-- -->. (`JSON.stringify`<!-- -->, in turn, calls the `toJSON` method of the object that is
      passed to it.) Whereas the original `Word.ContentControlCollection` object is an API object, the `toJSON` method
      returns a plain JavaScript object (typed as `Word.Interfaces.ContentControlCollectionData`<!-- -->) that contains
      an "items" array with shallow copies of any loaded properties from the collection's items.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'toJSON(): Word.Interfaces.ContentControlCollectionData;'
      return:
        type: '<xref uid="word!Word.Interfaces.ContentControlCollectionData:interface" />'
        description: ''
  - name: track()
    uid: 'word!Word.ContentControlCollection#track:member(1)'
    package: word!
    fullName: track()
    summary: >-
      Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand
      for
      [context.trackedObjects.add(thisObject)](https://learn.microsoft.com/javascript/api/office/officeextension.clientrequestcontext#office-officeextension-clientrequestcontext-trackedobjects-member)<!--
      -->. If you're using this object across `.sync` calls and outside the sequential execution of a ".run" batch, and
      get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the
      object to the tracked object collection when the object was first created. If this object is part of a collection,
      you should also track the parent collection.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'track(): Word.ContentControlCollection;'
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
  - name: untrack()
    uid: 'word!Word.ContentControlCollection#untrack:member(1)'
    package: word!
    fullName: untrack()
    summary: >-
      Release the memory associated with this object, if it has previously been tracked. This call is shorthand for
      [context.trackedObjects.remove(thisObject)](https://learn.microsoft.com/javascript/api/office/officeextension.clientrequestcontext#office-officeextension-clientrequestcontext-trackedobjects-member)<!--
      -->. Having many tracked objects slows down the host application, so please remember to free any objects you add,
      once you're done using them. You'll need to call `context.sync()` before the memory release takes effect.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'untrack(): Word.ContentControlCollection;'
      return:
        type: '<xref uid="word!Word.ContentControlCollection:class" />'
        description: ''
extends: '<xref uid="office!OfficeExtension.ClientObject:class" />'