NewsItem

News item manipulation methods

save()

Save news item. Triggers a validation of the news item.

replaceSource(sourceXml, [etag])

Replace the NewsML source. Will effectively replace the current article with anything in the incoming NewsML.

Parameters

Param	Type	Default
sourceXml	string
etag	string	null

~~setSource() ~~

Deprecated

Use api.newsItem.replaceSource() instead

getGuid() ⇒ string | null

Return the GUID in the NewsItemArticle Can return null if no GUID is found in NewsItem

setGuid(uuid)

Set news item guid (uuid)

Parameters

Param	Type	Description
uuid	string	Required - New uuid or null to clear

getLocale() ⇒ string

Gets locale from article's idf-element. Formatted with underscore, eg. sv_SE, en_GB, nl_NL. Uses fallback languages if the article's language only uses two characters. If fallback fails, will return the configured "language"-property from writer-config.

getLanguageParts() ⇒ Object

Gets a language parts object parsed from article's NewsML.

setLanguage(name, languageCode, textDirection)

Sets xml:lang property on article's idf-element. Language code should be two two-character codes separated by a dash, eg. sv-SE, en-GB

Parameters

Param	Type	Default	Description
name	string		Required - Plugin-id that set language
languageCode	string		Required - Two two-character language-region codes, separated by a dash. eg. sv-SE, en-GB, nl-NL
textDirection	string	"ltr"	Required - 'ltr' or 'rtl'

getNewsPriority() ⇒ Object

Get news priority.

Returns: Object - News priority object in JXON format

createNewsPriority(name, newsPriority)

Create and insert a new newsPriority object into the news item content meta data. Triggers a documentChanged event to all documentChanged listeners except the plugin making the change.

Parameters

Param	Type
name	string
newsPriority	object

setNewsPriority(name, newsPriority)

Set news priority.

Parameters

Param	Type	Description
name	string	Required - Name of the plugin making the call
newsPriority	Object	Required - News priority object

getMainChannel() ⇒ object

Get main channel (channel with attribute why="imext:main")

getSections() ⇒ Array | *

Get Sections. Finds all the service nodes with a qCode containing imsection:

Renames @qcode to qcode so plugins doesn't have to handle

getSection() ⇒ *

Get Section.

Find section on article if any. If no section null is returned. Note that by using this function it is presumed that there can be max one section on an article.

getChannels() ⇒ Array

Get Channels Finds all the service nodes with a qCode containing imchn:

Renames @qcode to qcode so plugins doesn't have to handle

updateSection(name, section)

Update Section. Removes existing section and add new. Note expects article to only allow one section.

Throws:

• Error

Parameters

Param	Description
name	Required - Name of plugin.
section	Required - Section object to set on article.

removeSection(name, section, muteEvent)

Removes .

Throws:

• Error

Parameters

Param	Type	Description
name	string	Required - Name of plugin.
section	string	Required - Section object to remove.
muteEvent	boolean	Required - Optional. Mute event if set to true, only used internally.

addChannel(name, channel, setAsMainChannel)

Add a channel as a . Renaming qcode to @qcode.

Throws:

• Error

Parameters

Param	Type	Description
name	string	Required - Name of plugin
channel	string	Required - Name of channel
setAsMainChannel	boolean	Required - Set this channel as main channel

removeChannel(name, channel, muteEvent)

Removes .

Throws:

• Error

Parameters

Param	Type	Description
name	string	Required - Name of plugin
channel	string	Required - Name of channel
muteEvent	boolean	Required - Optional. Mute event if set to true, only used internally.

getPubStatus() ⇒ Object

Get the pubStatus of document

Returns: Object - Return object with current pubStatus of document

setPubStatus(name, pubStatus)

Set pubStatus Creates a pubStatus node in itemMeta if it not exists

Parameters

Param	Type
name	string
pubStatus	object

getPubStart() ⇒ object

Get pubStart

Returns: object - Object {value: "2016-02-08T20:37:25 01:00", type: "imext:pubstart"}

setPubStart(name, pubStart)

Set pubStart

Parameters

Param	Type	Description
name	string	Required - Plugin name
pubStart	object	Required - Expect object with value property. Type is ignored. Object {value: "2016-02-08T20:37:25 01:00"}

removePubStart(name)

Remove the node for the pubStart

Parameters

Param

name

getPubStop() ⇒ object

Get pubStop

setPubStop(name, pubStop)

Set pubStop.

Parameters

Param	Type
name	string
pubStop	object

removePubStop(name)

Remove the node for pubStop.

Parameters

Param	Type	Description
name	string	Required - Plugin name

getEdNote() ⇒ String

Get editorial note from edNote element in itemMeta section.

setEdNote(content)

Set editorial note content in edNote element in itemMeta section

Throws:

• Error

Parameters

Param	Type	Description
content	string	Required - String content of editorial note

getNewspilotArticleId() ⇒ *

Get Newspilot article id (if any).

getAuthors() ⇒ *

Get all author links in itemMeta links

getSharedWith()

Get IMID organisation and unit(s)

getUnits()

Get IM

removeAuthorByUUID(name, uuid)

Remove an author from newsItem.

Throws:

• NotFoundError When no node is found by provided UUID the NotFoundError is thrown

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
uuid	string	Required - The UUID of the author to be deleted

addAuthor(name, author)

Add an known author with a specified uuid to the newsItem

Parameters

Param	Type	Description
name	string	Required - Plugin name
author	object	Required - Author object with the properties name and uuid

addSimpleAuthor(name, author)

Add an simple/unknown author to the newsItem

Parameters

Param	Type	Description
name	string	Required - Plugin name
author	object	Required - Author object with the properties name and uuid

updateAuthorWithUUID(name, uuid, author)

Updates itemMeta > links > link[type="x-im/author"]/@name for specified uuid.

If parameter author object contains any of

• email

• firstName

• lastName

• phone

• facebookUrl

• twitterUrl

• shortDescription

• longDescription a child element, 'data', will be created and a child element to that element with the name of object field will be created, e.g. data > phone.

  Note that an existing 'data' element will be removed from link.

Parameters

Param	Type	Description
name	string	Required - Plugin name
uuid	string	Required - The uuid for the author in the newsItem
author	object	Required - Object containing name and, optional, fields (see above)

updateConcept(name, conceptObject, propertyMap, triggerDocumentChanged)

Update existing concept link with new data

Parameters

Param	Type	Default	Description
name	string		Required -
conceptObject	object		Required -
propertyMap	object		Required -
triggerDocumentChanged	boolean	true	Required - set to false to suppress document changed event, default is set to true

updateRelationalLinks(relation, conceptObject, conceptNode, propertyMap)

Recursive function that will add a concepts Broader relations as links in the existing concept link

Parameters

Param	Type
relation	string
conceptObject	object
conceptNode	object
propertyMap	object

updateConceptData(conceptObject, conceptNode)

Update a concept links data node

Parameters

Param	Type
conceptObject	object
conceptNode	object

createExtendedGeoLink(relatedGeoPolygons)

Attach link with related-geo data to article meta

Parameters

Param	Type
relatedGeoPolygons	object

removeAuthorByTitle(name, authorName)

Remove an author from newsItem

Throws:

• NotFoundError When no node is found by provided authorName the NotFoundError is thrown

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
authorName	string	Required - The name of the author to be deleted

getLinksByType(name, types, subject) ⇒ *

Generic method to retrieve links with a certain type from the itemMeta section

Parameters

Param	Type	Description
name		Required - Plugin name
types	array	Required - Types of links to select
subject	string	Required - optional Which kind of subject to select, defaults to "subject"

Example

import {api} from 'writer'
api.newsItem.getLinksByType(this.name, [ 'x-im/organisation', 'x-im/person', 'x-im/topic' ], "subject")

getTags(types) ⇒ *

Get tags (link elements from the itemMeta section)

Returns: * - Return array of tags in JSON or null if no links was found

Example:: { rel: "subject", title: "Dalarna", type: "x-im/category", uuid: "03d22994-91e4-11e5-8994-feff819cdc9f" }

Parameters

Param	Description
types	Required - An array of types considered being tags. Example ['x-im/person, x-im/channel']

addTag(name, tag)

Adds a tag to itemMeta > links section in newsItem

The format used is identical to the search response provided by concepts backend

Parameters

Param	Type	Description
name	string	Required - The name of the plugin
tag	object	Required - Must containt title, type and uuid

Example

{
    "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
    "name": ["2016 Eurovision Song Contest"],
    "type": ["story"],
    "typeCatalog": ["imnat"],
    "imType": ["x-im/story"],
    "inputValue": "s"
}

updateTag(name, uuid, tag)

Update a tag in itemMeta > links section

Throws:

• NotFoundError When no node is found by provided UUID the NotFoundError is thrown

Parameters

Param	Type	Description
name	string	Required - The name of the plugin
uuid	string	Required - The UUID of the link element
tag	object	Required - The tag, same format as concept backend provides in search {"name": [ "2016 Eurovision Song Contest" ], "type": [ "story" ], "typeCatalog": [ "imnat" ], "imType": [ "x-im/story" ] }

removeLinkByUUID(name, uuid)

Removes a link in itemMeta links by providing an UUID

Parameters

Param	Description
name	Required - The name of the plugin calling the method
uuid	Required - The uuid of the link to be removed

removeLinkByURI(name, uri)

Removes a link in itemMeta links by providing an URI

Parameters

Param	Type	Description
name	string	Required - The name of the plugin calling the method
uri	string	Required - The URI of the link to be removed

removeAllLinksByType(name, type)

Removes all links in itemMeta links by providing a type

Parameters

Param	Type	Description
name	string	Required - of the plugin calling the method
type	string	Required - of the links to be removed

removeLinkByUUIDAndRel(name, uuid, rel)

Remove a link from itemMeta links section by type and rel attributes

Parameters

Param	Type
name	string
uuid	string
rel	string

removeLinkContentMetaByTypeAndRel(name, type, rel)

Remove a link from contentMeta links section by type and rel attributes

Parameters

Param	Type
name	string
type	string
rel	string

removeLinkContentMetaByTypeAndMatchingFilter(name, type, filter)

Removes links from contentMeta links section that matches provided filter and type.

The filter function is called for each link mathing the type. If the filter returns 'true', the link is removed.

Parameters

Param	Type	Description
name	string	Required - The name of the plugin performing the remove.
type	string	Required - The link type that should be part of removal
filter	function	Required - A function that gets the a link as a argument. Should return 'true' if the link should be removed.

addLocation(name, location)

Adds a new x-im/place link into itemMeta links

Parameters

Param	Description
name	Required - Plugin name calling function
location	Required - The location in JSON containing

Example

{
 "data":
   {
     "position":"POINT(16.570516 56.774485)"
   },
 "rel":"subject",
 "title":"Rälla",
 "type":"x-im/place",
 "uuid":"6599923a-d626-11e5-ab30-625662870761"
}

updateLocation(name, location)

Update a location

Throws:

• Error

Parameters

Param	Type	Description
name	string	Required - Name of plugin
location	object	Required - The location in JSON

getLocations(entity) ⇒ array

Get all location with link type x-im/place, x-im/polygon or x-im/position with the specified entity

Returns: array - {"data":{"position":"POINT(16.570516 56.774485)"},"rel":"subject","title":"Rälla","type":"x-im/place","uuid":"6599923a-d626-11e5-ab30-625662870761"}

Parameters

Param	Type	Description
entity	string	Required - Optional entity specification, either "all", "position" or "polygon"

addLink(name, link, triggerDocumentChanged)

Adds a link to itemMeta links section

Parameters

Param	Type	Default	Description
name	string		Required - The name of the plugin adding the link
link	object		Required - Uses jxon.unbuild to transform JSON to XML. Make sure to use @ property names for attributes.
triggerDocumentChanged	boolean	true	Required - set to false to suppress document changed event, default is set to true

Example

import {api} from 'writer'

api.newsItem.addLink('Pluginname', {
      '@rel': 'channel',
      '@title': 'Jeremy Spencer',
      '@type': 'x-im/author',
      '@uuid': '5f9b8064-d54f-11e5-ab30-625662870761'
  });
<link rel="author" title="Jeremy Spencer" type="x-im/author" uuid="5f9b8064-d54f-11e5-ab30-625662870761"/>

updateLinkRel(name, link)

Updates the rel value on a meta link

Parameters

Param	Type	Description
name	string	Required - The name of the plugin that is triggering the change
link	object	Required - a link object with a valid uuid and valid rel

Example

api.newsItem.updateLinkRel('pluginName', {
     uuid: '5f9b8064-d54f-11e5-ab30-625662870761',
     rel: 'mainchannel'
})

addContentMetaLink(name, link)

Adds a link to contentMeta links section

Parameters

Param	Type	Description
name	string	Required - The name of the plugin adding the link
link	object	Required - Uses jxon.unbuild to transform JSON to XML. Make sure to use @ property names for attributes.

Example

import {api} from 'writer'

api.newsItem.addContentMetaLink('PluginName', {
      '@rel': 'gender',
      '@title': 'Male',
      '@type': 'x-im/gender',
      '@uri': 'im://gender/male'
  });
<link title="Male" uri="im://gender/male" rel="gender" type="x-im/gender"/>

getLinkByTypeAndRel(name, type, rel) ⇒ array

Retrieve links from itemMeta section by specified type and rel

Returns: array - Array of links

Parameters

Param	Type
name	string
type	string
rel	string

getLinkByType(name, type) ⇒ array

Retrieve links from itemMeta section by specified type

Returns: array - Return array of links transformed to JSON

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
type	string	Required - The link type

getContentMetaLinkByType(name, type) ⇒ array

Get links in contentMeta links section by specified type

Returns: array - Return array of links transformed to JSON

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
type	string	Required - The link type

getStories() ⇒ array

Get stories

Returns: array - Array of stories found

getConceptSections() ⇒ array

Get concept sections

Returns: array - Array of concept sections

addStory(name, story)

Add a story link to itemMeta links section

Parameters

Param

name

story

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

updateStory(name, story)

Updates title on existing story

Throws:

• NotFoundError

Parameters

Param	Type	Description
name	string	Required - Plugin name
story	object	Required - A story object that atleast contains title and uuid

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

~~addConceptProfile(name, contentprofile) ~~

Deprecated

Adds a content-profile link to NewsItem

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
contentprofile	object	Required - A contentprofile object containing uuid and title

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

addContentProfile(name, contentprofile)

Adds a content-profile link to NewsItem

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
contentprofile	object	Required - A contentprofile object containing uuid and title

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

addCategory(name, category)

Adds a category link to NewsItem

Parameters

Param	Type	Description
name	string	Required - Name of the plugin
category	object	Required - A category object containing uuid and title

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

~~updateConceptProfile() ~~

Deprecated

Use updateContentProfile instead.

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

updateContentProfile(name, contentprofile)

Updates title on existing story

Parameters

Param	Type	Description
name	string	Required - Plugin name
contentprofile	object	Required - A concept profile object that atleast contains title and uuid

Example

{
 "uuid": "88d36cbe-d6dd-11e5-ab30-625662870761",
 "title": "A name"
}

getContentProfiles() ⇒ array | null

Returns a list of all existing content-profiles in NewsItem

getConceptByUuid() ⇒ object | null

Returns a conceptItem with matching UUID

Returns: object | null - ConceptItem or null

getCategories() ⇒ array | null

Returns a list of all existing categories in NewsItem

getArticleSubType() ⇒ String

Get the sub-type of the article (if there is one) For regular stories/articles this will return an empty string Other types includes: x-im/print, x-im/fact etc

Returns: String - Subtype or empty string

getExtProperty(sectionName, type, raw) ⇒ string | Element

Retrieve either an itemMetaExtProperty or contentMetaExtProperty value from the item or content meta sections. Optionally return full element if raw parameter is set to true.

Parameters

Param	Type	Default	Description
sectionName	string		Required - Either 'itemMeta' or 'contentMeta'
type	string		Required -
raw	boolean	false	Required - Optional, return as raw dom element, default is false

setExtProperty(name, sectionName, type, value)

Create new or set a value of existing itemMetaExtProperty or contentMetaExtProperty

Parameters

Param	Type	Description
name	string	Required - Identifier of caller
sectionName	string	Required - Either 'itemMeta' or 'contentMeta'
type	string	Required - Type string
value	string	Required - Value

deleteExtProperty(name, sectionName, type)

Delete a specified itemMetaExtProperty or contentMetaExtProperty

Parameters

Param	Type	Description
name	string	Required - Identifier of caller
sectionName	string	Required - Either 'itemMeta' or 'contentMeta'
type	string	Required - Type

getTemporaryId() ⇒ * | null

Returns the generated temporary id for the article. Temporary id is used when a new article is created and before it's saved the first time.

setTemporaryId(temporaryArticleID)

Set a temporaryId for the article

Parameters

Param

temporaryArticleID

hasTemporaryId() ⇒ boolean

Checks if current article has a temporary id

getIdForArticle() ⇒ string

Get the id for the article

getHasPublishedVersion() ⇒ bool

Get value of itemMetaExtProperty element with type imext:haspublihedversion that indicates whether the newsitem has published version or not.

setHasPublishedVersion(name, value)

Set itemMetaExtProperty element with type imext:haspublihedversion to true/false in item > meta sections to indicate whether this newsitem has a published version or not.

Parameters

Param	Type	Description
name	string	Required - Identifier of caller
value	bool	Required - True or false

getContentMetaObjectsByType(objectType) ⇒ Array

Retrieve objects from contentmeta.medata section based on type.

Returns: Array - Array of objects in jxon format

Parameters

Param	Type	Description
objectType	string	Required - The type of object

getContentMetaObjectById(id) ⇒ Object

Retrieve object from contentmeta.medata section based on id.

Returns: Object - Object in jxon format

Parameters

Param	Type	Description
id	string	Required - The id of object

setContentMetaObject(name, jxonObject)

Create and add an object into the contentmeta.metadata section. The object is encoded as a jxon object with the mandatory attributes id and type. All data must reside in the sub data structure. If an object with the specified id already exists it is silently replaced. Triggers a document:changed event.

Parameters

Param	Type	Description
name	string	Required - Name of the plugin making the call
jxonObject	Object	Required - The jxon encoded object

Example

import {api} from 'writer'

var idGen = require('writer/utils/IdGenerator');

api.newsItem.setContentMetaObject('ximimage', {
     '@id': idGen(),
     '@type': "x-im/newsvalue",
     data: {
         score: "2",
         description: 'My description',
         format: "lifetimecode",
         end: "2016-01-31T10:00:00.000+01:00"
     }
});

Example (Results in)

<object id="8400c74d665x" type="x-im/newsvalue">
    <data>
        <score>2</score>
        <description>My description</description>
        <format>lifetimecode</format>
        <end>2016-01-31T10:00:00.000+01:00</end>
    </data>
</object>

removeContentMetaObject(name, id)

Remove a specific object identied by id from the contentmeta.metadata section. Triggers a document:changed event.

Parameters

Param	Type	Description
name	string	Required - Name of the plugin making the call
id	string	Required - The id of the object

invalidate()

Invalidate document and displays notification that document is invalid

getVersionCreated() ⇒ *

Get version created date. Resides in newsItem > itemMeta block. If no version created date was found, null is returned.

getFirstCreated() ⇒ *

Get first created date. Resides in newsItem > itemMeta block. If no first created date was found, null is returned.

getContentCreated() ⇒ *

Get content created date. Resides in newsItem > contentMeta block. If no content created date was found, null is returned.

getContentModified() ⇒ *

Get content modified date. Resides in newsItem > contentMeta block. If no content modified date was found, null is returned.