> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/everyware/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/everyware/starter-kit-packages/everyware-newsml/usage.md).
# Usage
This package helps with parsing NewsML articles created in the Digital Writer into a format that can be easily used by Everyware.
The package contains parsers corresponding to the various items and embeds that can be added in the Digital Writer. The goal is to add new parsers whenever there is support for new types of content in the Digital Writer. It can also be extended on a project level if the customer has their own Digital Writer plugins.
If you're not using everyware-resources and wish to make your own implementation see below for a quick guide on getting started.
Before you attempt to parse an item you need to instantiate your objectParsers. After you've instantiated your parsers you create a transformer by calling either
`createTransformer` - For elements with tag idf
`createObjectTransformer` - For elements with tag object
`createMetaDataTransformer` - For elements with tag metadata
Returns an instance of `NewsMLTransformer` that exposes the `transform` function which takes an xml string as its argument.
Example:
```php
$objectParsers = [
ImageParser::OBJECT_TYPE => new ImageParser(),
];
foreach ($objectParsers as $type => $parser) {
NewsMLTransformerManager::registerObjectParser($type, $parser);
}
$newsml = '
';
$transformer = NewsMLTransformerManager::createTransformer($newsml);
$result = $transformer->transform($newsml);
```
Response:
```
array:1 [▼
0 => ImageItem {#554 ▼
#el: SimpleXMLIterator {#556 ▶}
#properties: array:8 [▼
"rel" => "self"
"type" => "x-im/image"
"uri" => "im://image/RuoKvhPu89C9qYQmsbBvje1uqzU.jpg"
"uuid" => "2d6ac910-6c0a-51cc-8d4c-fbcf12e250dd"
"width" => SimpleXMLIterator {#557 ▼
+"0": "800"
}
"height" => SimpleXMLIterator {#559 ▼
+"0": "534"
}
"text" => null
"alttext" => null
]
}
]
```
All parsers return an array containing `Item` or an extended class of `Item` like `TeaserItem`, `ImageItem` or `ContentPartItem`.
In addition to the default data some parsers modify the data or return additional data. Read description for more information of a each parsers behaviour.
**ObjectParsers**
| `Name` | `OBJECT_TYPE` | `Description` |
| ------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ContentPartParser | x-im/content-part | |
| HtmlEmbedParser | x-im/htmlembed | |
| ImageGalleryParser | x-im/imagegallery | **caption:** elements data.text. |
| ImageParser | x-im/image | Uses `ImageLinkParser` |
| LinkObjectParser | x-im/link | |
| MapEmbedParser | x-im/mapembed | |
| PdfParser | x-im/pdf | If the elements link rel="self" it also includes the following properties. **title:** text, **file:** uri without 'im://pdf/' and **url:** `CF_PDF` + / + `file`. `url` requires global `CF_PDF` to be defined. |
| ReviewParser | x-gm/review | **text:** html elements parsed through `ElementParser` |
| SocialEmbedParser | x-im/socialembed | **content:** data returned by `LinkParser` |
| TableParser | x-im/table | |
| TeaserParser | x-im/teaser | **links:** Uses `ImageLinkParser`, **headline:** the elements data.title. |
| YouplayParser | x-im/youplay | **thumb:** if link type="image/jpg" uses `ImageLinkParser`, **config:** extracts data-config from embedCode, **video(array):** `url` + uri without x-im://youplay/ + /720?fmt=mp4, **format:** mp4, **api\_url:** if data-config is set it equals `https://delivery.youplay.se/videos/api/v2/videodata?zone_id=data-config['zone_id']&part_id=data-config['part_id']` |
| YoutubeParser | x-im/youtube | **uri:** uri with 'watch?v=' replaced by 'embed/', thumb width, height and url. Is only set if link type="image/jpg". |
| ContactinfoParser | x-im/contact-info | |
| PersonParser | x-im/person | |
| PolygonParser | x-im/polygon | |
**LinkParsers**
| `Name` | `OBJECT_TYPE` | `Description` |
| ----------------------- | :-----------------: | ------------------------------------------------------------------------------------------------------------------------------ |
| ArticleLinkParser | x-im/article | Parse related links. Used by `LinkParser` |
| AuthorLinkParser | x-im/author | Parse author links. Used by `ImageLinkParser` |
| CropLinkParser | x-im/crop | Parse crop links. Used by `ImageLinkParser` |
| FacebookPageLinkParser | x-im/facebook-page | Parse Facebook *page* links. Used by `SocialEmbedParser` |
| FacebookPostLinkParser | x-im/facebook-post | Parse Facebook *post* links. Used by `SocialEmbedParser` |
| FacebookVideoLinkParser | x-im/facebook-video | Parse Facebook *video* links. Used by `SocialEmbedParser` |
| FocalPointLinkParser | x-im/focal-point | Parse focal-point links. Used by `ImageLinkParser` |
| ImageLinkParser | x-im/image | Parse Image links. **crop:** if link rel="self" |
| InstagramLinkParser | x-im/instagram | Parse Instagram links. **embed\_url:** `https://api.instagram.com/oembed/?url=`. Used by `SocialEmbedParser` |
| SoundcloudLinkParser | x-im/soundcloud | Parse Soundcloud links. Used by `SocialEmbedParser` |
| TwitterLinkParser | x-im/tweet | Parse Twitter links. Used by `SocialEmbedParser` |
| VimeoLinkParser | x-im/vimeo | Parse Vimeo links. Used by `SocialEmbedParser` |
**Tag Parsers** These are the parsers that uses the parsers mentioned above. They take a xml block and loop over it and parsers each element according to its tag name.
| `Name` | `TAG` | `Description` |
| -------------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| ElementParser | element | Parses elements with element tag. Removes all elements which are not the following: `span, i, b, em, strong, sup, sub, br, hr, a, script, iframe`. |
| GroupParser | group | Parses elements with group tag. Uses `ElementParser` and `ObjectParser`. |
| LinkParser | | Accepts an array of LinkParsers. |
| IdfParser | | Parses idf elements. Uses `ElementParser`, `ObjectParser` and `GroupParser`. |
| ObjectParser | object | This parser accepts an array of parses that should be used to parse objects. |
| MetaDataParser | metadata | Parses elements with metadata tag. Uses `ObjectParser`. |