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.

PreviousEventsNextRouter

Last updated