# 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 |


---

# 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.5.1/api-reference/writerapi/article.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.