> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/writer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.navigaglobal.com/writer/6.5.1/api-reference/writerapi/article.md).

# Article

Basic article handling that enables functionality as clearing and creating new copies of a newsitem article

## clear(disableWarning) <a href="#clear" id="clear"></a>

Clear the article and create a new based on the configured base template.

### Parameters

| Param          | Type      | Description                                                                                  |
| -------------- | --------- | -------------------------------------------------------------------------------------------- |
| disableWarning | `boolean` | **Required -** Optional, default false. If true, the article will be cleared without warning |

## copy(name) <a href="#copy" id="copy"></a>

Attempt to execute copy hooks if at least one exists, then create a new, unsaved, article based on the current article.

### Parameters

| Param | Type     | Description                                 |
| ----- | -------- | ------------------------------------------- |
| name  | `string` | **Required -** Name or identifier of caller |

## setSourceArticle(sourceArticleUuid) <a href="#setsourcearticle" id="setsourcearticle"></a>

Remove any itemMeta links with rel "source", and add a new itemMeta link with rel "source" using supplied article uuid

### Parameters

| Param             | Type     |
| ----------------- | -------- |
| sourceArticleUuid | `string` |

## setPubStatus(data) <a href="#setpubstatus" id="setpubstatus"></a>

Sets the publication status for this document. The value is one of what is defined in the NewsML G2 standard: <https://www.iptc.org/std/NewsML-G2/latest/QuickStart-NewsML-G2-ItemBasics> under the Publication Status section, together with custom extension in the format \[customExtensionPrefix]:\[customValue], such as `imext:draft`

### Parameters

| Param          | Type     | Description                                                                                  |
| -------------- | -------- | -------------------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                                      |
| data.change    | `string` | **Required -** The value to be set in pubStatus. Expected value is in the form "stat:usable" |
| data.eventType | `string` | Type of event to be sent when data has changed. default "document:changed"                   |

### Example

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

api.Article.setPubStatus({
     'change': 'stat:withheld'
  });

<itemMeta>
  <pubStatus qcode="stat:withheld"/>
</itemMeta>
```

## \~\~addService(data) \~\~ <a href="#addservice" id="addservice"></a>

***Deprecated***

Adds a service to the itemMeta section of the article. The service tag concists of a mandatory 'qcode' value and an optional 'why' attribute with extra information.

### Parameters

| Param             | Type     | Description                                                                                              |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| data              | `object` | **Required -** The change specification                                                                  |
| data.eventType    | `string` | Type of event to be sent when data has changed. default "document:changed"                               |
| data.change       | `object` | **Required -** The change specification                                                                  |
| data.change.qcode | `string` | **Required -** The value to be set in the qcode for the service. Expected value is in the form "xxx:yyy" |
| data.change.why   | `string` | **Required -** Optional parameter for the 'why' attribute for service.                                   |

### Example

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

api.article.addService({
    change: {
     qcode: "imchn:abc",
     why: "imext:main"
   }
});


<contentMeta>
    <service qcode="imchn:abc" why="imext:main"/>
</contentMeta>
```

## removeService(data) <a href="#removeservice" id="removeservice"></a>

Removes a service from the itemMeta section of the article.

### Parameters

| Param          | Type     | Description                                                                                                |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                                                    |
| data.change    | `string` | **Required -** The qcode value matching the service to be removed. If there is no match, no event is sent. |
| data.eventType | `string` | Type of event to be sent when data has changed. default "document:changed"                                 |

### Example

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

api.article.removeService({
    change: "imchn:abc"
});
```

## setPubStart(data) <a href="#setpubstart" id="setpubstart"></a>

Sets the publish start time, using ISO\_8601 standard. If value is null, pubStart will be unset.

### Parameters

| Param          | Type     | Description                                                                  |
| -------------- | -------- | ---------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                      |
| data.change    | `string` | **Required -** The time, in ISO\_8601                                        |
| data.eventType | `string` | Type of event to send when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setPubStart({
     'change': '2018-04-21T00:00:00+02:00'
  });
<itemMeta>
  <itemMetaExtProperty type="imext:pubstart" value="2018-04-21T00:00:00+02:00"/>
</itemMeta>
```

## setPubStop(data) <a href="#setpubstop" id="setpubstop"></a>

Sets the publish stop time, using ISO\_8601 standard.

### Parameters

| Param          | Type     | Description                                                                  |
| -------------- | -------- | ---------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                      |
| data.change    | `string` | **Required -** The time, in ISO\_8601                                        |
| data.eventType | `string` | Type of event to send when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setPubStop({
     'change': '2018-04-21T00:00:00+02:00'
  });
<itemMeta>
  <itemMetaExtProperty type="imext:pubstop" value="2018-04-21T00:00:00+02:00"/>
</itemMeta>
```

## setTitle(data) <a href="#settitle" id="settitle"></a>

Sets the value of the title.

### Parameters

| Param          | Type     | Description                                                                     |
| -------------- | -------- | ------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                         |
| data.change    | `string` | **Required -** Value of the title to set. Must not be null or undefined         |
| data.eventType | `string` | Type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setTitle({
     "change": "Document title"
  });
<itemMeta>
  <title>Document title</title>
</itemMeta>
```

## setEdNote(data) <a href="#setednote" id="setednote"></a>

Sets the value of editor note

### Parameters

| Param          | Type     | Description                                                                                                |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                                                    |
| data.change    | `string` | **Required -** The text value of editor note. If null or empty, the element will be removed from document. |
| data.eventType | `string` | Type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED                            |

### Example

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

api.article.setEdNote({
     "change": "Instructions to editor"
  });
<itemMeta>
  <edNote>Instructions to editor</edNote>
</itemMeta>
```

## setItemMetaExtProperty(data) <a href="#setitemmetaextproperty" id="setitemmetaextproperty"></a>

Sets the value of a property. If value is null, the property will be removed. The type of property to change is specified by the type argument.

The type is defined by the \[customPrefix]:\[type] syntax, such as `imext:url`

### Parameters

| Param             | Type     | Description                                                                      |
| ----------------- | -------- | -------------------------------------------------------------------------------- |
| data              | `object` | **Required -** The change specification                                          |
| data.change       | `object` | **Required -** Specification of the property to set.                             |
| data.change.type  | `string` | **Required -** The identification of the property                                |
| data.change.value | `string` | **Required -** The value of the property. If null, the property will be removed. |
| data.eventType    | `string` | Type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED  |

### Example

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

api.article.setItemMetaExtProperty({
     "change": {
         type: "imext:haspublishedversion",
         value: "true"
     }
  });
<itemMeta>
  <itemMetaExtProperty type="imext:haspublishedversion" value="true"/>
</itemMeta>
```

## addItemMetaLink(data) <a href="#additemmetalink" id="additemmetalink"></a>

Adds a link to the itemMeta section of the article.

### Parameters

| Param             | Type     | Description                                                                                                                                 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| data              | `object` | **Required -** The change specification                                                                                                     |
| data.change       | `object` | **Required -** Specifies the link to be created.                                                                                            |
| data.change.rel   | `string` | **Required -** The 'rel' attribute of the link. Example: "author". This parameter is mandatory and must be defined. Must not contain spaces |
| data.change.type  | `string` | **Required -** The 'type' attribute of the link. Example: "x-im/person". This parameter is mandatory and must be defined.                   |
| data.change.uri   | `string` | **Required -** The 'uri' pointing to an external resource. This OR the 'uuid' parameter must be present.                                    |
| data.change.uuid  | `string` | **Required -** The 'uuid', which is an ID of a resource in the writer repository. This OR the 'uri' parameter must be present.              |
| data.change.data  | `string` | **Required -** An optional data block with custom tags.                                                                                     |
| data.change.links | `array`  | **Required -** Optional links for the link to be created. Should be of the same format as the top-most link.                                |
| data.eventType    | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED                                                         |

### Example

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

api.article.addItemMetaLink({
     change: {
         rel: "subject",
         title: "Mora",
         type: "x-im/category",
         uuid: "7b8461e8-4a22-11e8-aa12-b79c05b8e6d5",
         links: [
             {
                 rel: "broader",
                 title: "Dalarna",
                 uuid: "03d22994-91e4-11e5-8994-feff819cdc9f",
                 type: "x-im/category",
                 data: {
                     "placement": {
                         attributes: {
                             "type": "position"
                         },
                         value: "left"
                     }
                 }
             }
         ]
     }
  });

<itemMeta>
  <links>
      <link rel="subject" title="Mora" type="x-im/category" uuid="7b8461e8-4a22-11e8-aa12-b79c05b8e6d5">
          <links>
              <link rel="broader" title="Dalarna" uuid="03d22994-91e4-11e5-8994-feff819cdc9f" type="x-im/category">
                  <data>
                      <placement type="position>left</placement>
                  </data>
          </links>
      </link>
  </links>
</itemMeta>
```

## removeItemMetaLink(data) <a href="#removeitemmetalink" id="removeitemmetalink"></a>

Removes a link from itemMeta section

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `object` | **Required -** The link to remove                                                   |
| data.rel       | `string` | **Required -** The rel attribute of the link                                        |
| data.uri       | `string` | **Required -** The URI that identifies the link, OR                                 |
| data.uuid      | `string` | **Required -** The uuid that identifies the link.                                   |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.removeItemMetaLink({
     change: {
         rel: 'subject',
         uuid: '320938f8-db94-11e5-b5d2-0a1d41d68578'
     }
  });
```

## \~\~setAltId(data) \~\~ <a href="#setaltid" id="setaltid"></a>

***Deprecated***

Sets the alternative ID for the article. If null, the element will be removed.

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `string` | **Required -** The new ID to set                                                    |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setAltId({
     "change": "854575"
  });

<contentMeta>
  <altId>854575</altId>
</contentMeta>
```

## \~\~setSlugline(data) \~\~ <a href="#setslugline" id="setslugline"></a>

***Deprecated***

Sets the slugline for the article. If null, the element will be removed.

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `string` | **Required -** The new slugline                                                     |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setSlugline({
     "change": "This article is all about"
  });

<contentMeta>
  <slugline>This article is all about</slugline>
</contentMeta>
```

## \~\~setDescription(data) \~\~ <a href="#setdescription" id="setdescription"></a>

***Deprecated***

Sets the description of the article. If null, the element will be removed.

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `string` | **Required -** The new description                                                  |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setDescription({
     "change": "Description of the article"
  });

<contentMeta>
  <description>Description of the article</description>
</contentMeta>
```

## \~\~setBy(data) \~\~ <a href="#setby" id="setby"></a>

***Deprecated***

Sets the byline for the article. If null, the element will be removed.

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `string` | **Required -** The new byline                                                       |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setBy({
     "change": "Boris Byline"
  });

<contentMeta>
  <by>Boris Byline</by>
</contentMeta>
```

## \~\~setHeadline(data) \~\~ <a href="#setheadline" id="setheadline"></a>

***Deprecated***

Sets the headline of the article. If null, the element will be removed.

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `string` | **Required -** The new headline                                                     |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.setHeadline({
     "change": "Article headline"
  });

<contentMeta>
  <headline>Article headline</headline>
</contentMeta>
```

## \~\~addContentMetaLink(data) \~\~ <a href="#addcontentmetalink" id="addcontentmetalink"></a>

***Deprecated***

Adds a link to the contentMeta section of the article.

### Parameters

| Param             | Type     | Description                                                                                                                    |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| data              | `object` | **Required -** The change specification                                                                                        |
| data.change       | `object` | **Required -** Specifies the link to be created.                                                                               |
| data.change.rel   | `string` | **Required -** The 'rel' attribute of the link. Example: "author". This parameter is mandatory and must be defined.            |
| data.change.type  | `string` | **Required -** The 'type' attribute of the link. Example: "x-im/person". This parameter is mandatory and must be defined.      |
| data.change.uri   | `string` | **Required -** The 'uri' pointing to an external resource. This OR the 'uuid' parameter must be present.                       |
| data.change.uuid  | `string` | **Required -** The 'uuid', which is an ID of a resource in the writer repository. This OR the 'uri' parameter must be present. |
| data.change.data  | `string` | **Required -** An optional data block with custom tags.                                                                        |
| data.change.links | `array`  | **Required -** Optional links for the link to be created. Should be of the same format as the top-most link.                   |
| data.eventType    | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED                                            |

### Example

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

api.article.addContentMetaLink({
  change: {
    rel: "articlesource",
    title: "Online",
    type: "x-im/articlesource",
    uri: "im://articlesource/online"
  }
});

<contentMeta>
    <links>
        <link rel="articlesource" title="Online" type="x-im/articlesource" uri="im://articlesource/online"/>
    </links>
</contentMeta>
```

## \~\~removeContentMetaLink(data) \~\~ <a href="#removecontentmetalink" id="removecontentmetalink"></a>

***Deprecated***

Removes a link from contentMeta section

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `object` | **Required -** The link to remove                                                   |
| data.rel       | `string` | **Required -** The rel attribute of the link                                        |
| data.uri       | `string` | **Required -** The URI that identifies the link, OR                                 |
| data.uuid      | `string` | **Required -** The uuid that identifies the link.                                   |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.removeContentMetaLink({
     change: {
         rel: 'subject',
         uuid: '320938f8-db94-11e5-b5d2-0a1d41d68578'
     }
  });
```

## \~\~addContentMetadata(data) \~\~ <a href="#addcontentmetadata" id="addcontentmetadata"></a>

***Deprecated***

Adds an object element to the metadata section in contentMeta

### Parameters

| Param             | Type     | Description                                                                                                    |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| data              | `object` | **Required -** The change specification                                                                        |
| data.change       | `object` | **Required -** The specification of the object tag to add                                                      |
| data.change.id    | `string` | **Required -** A mandatory id of the object                                                                    |
| data.change.type  | `string` | **Required -** A mandatory type of object                                                                      |
| data.change.title | `string` | **Required -** A an optional title of the object                                                               |
| data.change.data  | `object` | **Required -** Optional data element, with custom tags.                                                        |
| data.change.links | `array`  | **Required -** Optional array with link elements. The link follows the same format as with #addContentMetaLink |
| data.eventType    | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED                            |

### Example

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

api.article.addContentMetadata({
    change: {
        id: "8400c74d667e",
        type: "x-im/teaser",
        title: "Sed sit amet turpis a purus fringilla",
        data: {
            subject: "In sodales lectus vel egestas rhoncus",
            text: "Duis eget magna lacus. In sodales lectus vel egestas rhoncus."
        }
        links: [
            {
                rel: "image",
                type: "x-im/image",
                uri: "im://image/znX8U1CU124n26zu7gb40_jBzSk.jpeg",
                uuid: "c382c937-8511-5d48-9677-55658c2bbb32",
                data: {
                    width: "1536",
                    height: "1024"
                }
            }
        ]
    }
})

<contentMeta>
    <metadata>
        <object id="8400c74d667e" type="x-im/teaser" title="Sed sit amet turpis a purus fringilla">
           <data>
               <subject>In sodales lectus vel egestas rhoncus</subject>
               <text>Duis eget magna lacus. In sodales lectus vel egestas rhoncus.</text>
           </data>
           <links>
               <link rel="image"
                         type="x-im/image"
                         uri="im://image/znX8U1CU124n26zu7gb40_jBzSk.jpeg"
                         uuid="c382c937-8511-5d48-9677-55658c2bbb32">
                   <data>
                       <width>1536</width>
                       <height>1024</height>
                   </data>
               </link>
           </links>
        </object>
    </metadata>
</contentMeta>
```

## \~\~removeContentMetadata(data) \~\~ <a href="#removecontentmetadata" id="removecontentmetadata"></a>

***Deprecated***

Removes an object in the contentMeta metadata section of the article.

### Parameters

| Param          | Type     | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| data           | `object` | **Required -** The change specification                                             |
| data.change    | `object` | **Required -** The specification of the object tag to remove                        |
| data.change.id | `string` | **Required -** The ID for the tag to remove. This argument is required              |
| data.eventType | `string` | The type of event to be sent when data has changed. Default Event.DOCUMENT\_CHANGED |

### Example

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

api.article.removeContentMetadata({
     change: {
         id: 'A8567B335'
     }
  });
```

## itemMeta(path) ⇒ `DocumentNode` <a href="#itemmeta" id="itemmeta"></a>

Returns the itemMeta node

**Returns**: `DocumentNode` - A node instance

**Throws**:

* Error when node does not exist

### Parameters

| Param | Description                                              |
| ----- | -------------------------------------------------------- |
| path  | **Required -** Optional path to find node under itemMeta |

## contentMeta(path) ⇒ `DocumentNode` <a href="#contentmeta" id="contentmeta"></a>

Returns the contentMeta node

**Returns**: `DocumentNode` - A node instance

**Throws**:

* Error when node does not exist

### Parameters

| Param | Description                                                 |
| ----- | ----------------------------------------------------------- |
| path  | **Required -** Optional path to find node under contentMeta |