Documentation

Contents


Getting started

What the plugin does

The plugin allows administrators to send NewsML-G2 documents directly to WordPress with a HTTP POST Request. It supports NewsItems and KnowledgeItems.

The plugin also validates NewsItems by default.



How the plugin interacts with WordPress

All requests are made with WordPress functions.


No new tables are created in the WordPress database.


When you delete an article (WordPress post) it will also delete all the meta data Rewpert stored in the database.



Requirements

PHP Version

5.4 or higher


Wordpress Version

Works for 4.0.1 and up. (20. November 2014)

Should work for older versions aswell, but untested.


php.ini

extension=php_pdo_sqlite.dll

extension=php_sqlite3.dll

file_uploads = On (Not required for use of REST API, just for manual upload)



Installation

1. Download the latest version

2. Extract and add the folder to the WordPress plugins folder ( /wp_content/plugins/ )

3. Activate plugin through the WordPress administration panel


How to use

1. Go to the WordPress administration panel


2. Go to the "Posts" submenu named "Rewpert-G2" - (Visible if you click the Posts menu)


3. Send a HTTP POST request with the NewsML-G2 XML document to the URL

NewsItem -> creates a new WordPress post with your NewsItem

KnowledgeItem -> update the plugin database of QCodes (subjects and mediatopics).


That's it, the NewsItem should now be shown under "Posts" and on the front page, depending on pubStatus (NewsML-G2 tag)



The pubStatus describes what will happen to the article when it’s being imported.

<pubStatus qcode="stat:usable" />  - Publish immediately


<pubStatus qcode="stat:withheld" /> - Article will be imported, but the administrator/editor must publish it through WordPress.


<pubStatus qcode=”stat:canceled” /> - The article is moved to trash. You need to send this pubStatus if you have a already published article that you need to move to trash.


If there is an embargo date present in the NewsML the publication status is set to be published at a future date matching the embargo.


The publication date in Wordpress is set to the date in <versionCreated>


Multiple Author Support

WordPress does not support multiple authors out of the box, and some modifications have to be made to your theme.


There may be some differences between themes, but these methods should take care of most. The file names and structure mentioned here is based on the default Twenty-Fifteen theme.


1. Find your theme in the wp_contents folder


2.Paste this right over (have_posts() in Archive.php)

Lim dette inn rett over if ( have_posts() ):

// NML2_MULTI_AUTHOR SUPPORT:
if(isset($_GET['author'])){
	$ID = $_GET['author'];
}else{
	$ID = get_the_author_ID();
}

if(is_numeric($ID)){
	$wp_query->is_author = true;

	// Replaces the have_posts stack with a new stack, making it true and iterate as normal
	// Also sets the author, so that the author is shown correctly, instead of empty or just as "Archive"	
	if(is_numeric($ID) && function_exists('nml2_get_author_posts')){
		global $wp_query;
		$posts = nml2_get_author_posts();
		$wp_query->post_count = count($posts);
		$wp_query->post = $posts;

		// Triggers "Author: * " instead of just "Archive" in the display.
		$wp_query->is_author = true;
		global $authordata;
		$authordata = get_user_by('id', $ID);
	}else{
		"function does not exist";
	}

}
// END NML2_MULTI_AUTHOR SUPPORT


		

3. Replace get_the_author() in Template_tags.php

nml2_get_all_authors()


		

Uninstall

Important notes

The inline-images on the NewsML-G2 posts will be removed when removing the plugin. To avoid this you should leave the 'Image' folder in the plugin folder intact, and delete everything else. Deactivating the plugin should not prevent the images from being shown correctly.


All text from WordPress posts (NewsItems) and meta-data will be intact.

Architectural structure

Debug information

If something went wrong, you can add the &debug=true parameter to the URL when sending a HTTP Post request. The debug information will point you in the right direction if something went wrong.




NewsML-G2 Validation

The validator used is written by Stefan Grunert

https://github.com/arasix/newsmlvalidator (MIT License)


Validation is enabled by default, and happens right before the NewsItem is parsed. If validation is enabled and the document fails validation, the entire import will be stopped.


REST API

Most important purposes

  • Handles POST Requests (Authenticate and delegate)
  • Handles all communication with WordPress, except the admin panel
  • Handles communication with NewsItem
  • Handles almost all communication

This file handles communication between most modules, and the communication with the WordPress core/database.

Pattern

  1. Authenticate (ALWAYS)
  2. Simple HTTP REQUEST validation
  3. Delegate POST data to the QCodes class. (KnowledgeItems)
  4. Validate NewsML-G2 (NewsItem)
  5. Delegate POST data to the NewsItemParser (Returns array)
  6. Process returned array, by first fixing date.
  7. Process QCodes (Subjects and mediatopics)
  8. Insert / update from the WordPress database
  9. Return header (ALWAYS)

NewsItemParser

NewsItemParse converts the NewsML-G2 document into a multidimensional array that the REST API needs to import the document to the WordPress database. It uses DOMXPath to find specific information such as headline, author and images of the news article. See the start of newsItemParse.php to find the full array returned from the parser.

The 'meta' array

Each index under $returnArray contains an array called 'meta'. The information not related to article content, images, users or categories is stored in the ‘meta’ array. Adding additional metadata to the WordPress database is simple. All indexes and values in the 'meta' array is stored in the WordPress database. (See below)

Adding more information to $returnArray

To add more information to $returnArray you can for example add another index in the meta array and create a new function to find the information you need:

$meta = array(
    'nml2_guid' => self::getMetaGuid($newsItem),
    'nml2_version' => self::getMetaVersion($newsItem),
    'nml2_firstCreated' => self::getMetaFirstCreated($newsItem),
    'nml2_versionCreated' => self::getMetaVersionCreated($newsItem),
    'nml2_embarogDate' 	 => self::getMetaEmbargo($newsItem),
    'nml2_newsMessageSendt' => self::getMetaSentDate(),
    'nml2_language' => self::getMetaLanguage($newsItem),
    'nml2_copyrightHolder' => self::getMetaCopyrightHolder($newsItem),
    'nml2_copyrightNotice' => self::getMetaCopyrightNotice($newsItem),
    'new_informaiton' => self::newFunction()
    );

private static function newFunction() {
    //Function body
}

          

The status code

The 'status_code' index in the return array is set to 200 by default (HTTP code for OK). It is changed to 400 (HTTP code for Bad request) in the function setStatusCode if:

  • The post payload is empty
  • No newsItems were found,
  • If the body text, the headline, the guid or the version number is missing.
  • The payload sent is not valid xml (validator is off)

Structure of contentSet

This plugin supports three ways of structuring the contentSet. The first two is to use inlineXML with either NITF (namespace: http://iptc.org/std/NITF/2006-10-18/) or XHTML (namespace: http://www.w3.org/1999/xhtml). You can also use a tag called inlineData.

Things to be aware of

If the information is not written correctly the parser is not able to find the body text associated with a specific image. If for some reason there is one or more whitespaces at the start of the XML file, the parser will remove them. The parser will perform all queries regardless of what namespace is present in or if there is a namespace in the outermost tag of the XML file at all. If the NewsML document contains a newsItem with a quote or other text that is supposed to be supplementary to the main article, this text will be stored as its own article. The plugin has no way of handling this type of text correctly and we advise that you exclude it from the xml sent you are importing.

Unit testing

Unit test is performed with PHPUnit. All tests can be found in the testing folder located in the root plugin folder

Functions.php

This file contains important functions required by the REST API.

KnowledgeItemParser

Retrieves a set of QCodes and corresponding values and language from a NewsMl-G2 XML document with a KnowledgeItem.


Supports: Subjects and mediatopics.


It is only used and called through the QCodes.php file.

HTMLView.php

Creates a styled HTML document based on the input. The HTML document is styled by the OutputCSS file in the same folder.

DateParser.php

Converts date from the ISO 8601 standard to the WordPress Standard (MySQL DateTime)

httpHeader.php

Sets the HTTP statuscode in the HTTP Response sent from the REST API.

QCodes.php

Controls and updates a database with QCodes. The database contains different QCodes og their corresponding values and language, the main role is to be a controller for KnowledgeItemParse and the SimpleStorage (API.php) file. The API.php mentioned below stores the values, and the KnowledgeItemParser is told to parse documents by the QCodes class.

SimpleStorage (API.php)

A simple database storage, for storing parameters quickly and easy. By using the prepare(true) statement and executing afterwards, you should make sure you only do one group of queries at the time, as the stacked queries are executed this order all insert, all update, all delete.

Testing (Unit tests)

Rewpert comes with several PHPUnit tests under root/testing/

Misc

Image implementation

When inline images are found, they are stored in the Rewpert-G2 plugin folder under /images/, and the inline link is replaced with a new one


Use of the WordPress database

No new tables are created in the WordPress SQL database. All information stored in the WordPress database are stored by the WordPress function library / their API.


This is important because:

  • This ensures compatibility with newer versions of WordPress.
  • When you remove a post and meta data created by Rewpert, it will also remove the metadata (for that post) from the WordPress database.
  • Uninstalling the plugin should be a breeze.

Supported ContentSet

  • XHTML
  • NITF
  • <inlineData> (NewsMl-G2 - Plaintext)

Name explanation

Rewpert-G2 

REST NewsMl- G2 to WordPress