Wordpress Plugin

MFN has a Wordpress plugin that is available for integration with company websites for showing their company feed.

Description

The MFN Wordpress Plugin is a plugin which lets the user sync news items for a particular company from mfn.se into their Wordpress site. It also adds a WebSub compliant posthook that is used to automatically receive new news being published by mfn.se.

The plugin does not however provide any public views of the news items. This has to be implemented by the user of the plugin them self.

What it does

Once installed the plugin creates a few new things are added to your Wordpress site

1. A new post type mfn_news

2. A new taxonomy mfn-news-tag

3. New terms in the new taxonomy that describes news items

4. Adds Widgets: MFN News Feed Widget, MFN Archive Widget and the MFN Subscription Widget

Links

Releases zip of the plugin can be found at https://github.com/modfin/mfn-wp-plugin/releases

Composer https://packagist.org/packages/modfin/mfn-wp-plugin

Code at https://github.com/modfin/mfn-wp-plugin

The plugin should be compliant with both a standard WP installation and Bedrock version (https://roots.io/bedrock/)

Installation / Getting started

Start off by downloading the WP plugin, from the links above.

There are three ways to install the the plugin

1. Download and extract the zip package it into your wp-content/plugins directory

2. Upload the zip package through the built in installer of Wordpress at http://your-site.com/wp-admin/plugin-install.php (click the upload plugin button)

3. Use composer (a tool for php dependency management), simply run:$ composer require modfin/mfn-wp-plugin

Once installed, activate the plugin by pressing Activate. This will create the post type, the taxonomy and all the corresponding terms.

A new menu item, MFN News Items, should now have been added in the Admin menu.

1. Go to Settings - MFN Feed to locate the plugin settings

2. Fill in the information in the left column fields (Sync URL, Hub URL, Plugin URL and Entity Id, these fields are required to get things to work)

3. Click "Save".

4. Finally click "Sync all" in the right column

Now, if you go to MFN News Items in the Admin menu you should be able to view the feed and manage the news items individually, as well as the corresponding tags.

Constraints

The plugin has a WebSub posthook that enables MFN to inject news items when they are published. This means that the WP application must be initiated from within the plugin.

This puts some constraints on the folder structure of the Wordpress instance. In short, the plugin must be able to find wp-config.php to bootstrap the necessary parts. The plugin does this by traversing parent directories of the plugin, at a maximum height of 3. This should work for both Bedrock and a standard installation of Wordpress.

Configuration and management

Settings

Sync URL which is the URL to mfn.se and should, in most cases, be https://mfn.se This url is used by the plugin to retrieve historical news that has been published on MFN or other news weirs. It a used when an admin click on Sync Latest or Sync All.

Hub URL which is the URL to MFNs WebSub Hub and should, in most cases, https://hub.mfn.se This URL is used by the plugin to talk to the WebSub Hub in order to setup a HTTP Posthook subscription for the Plugin. This in order to let MFN push news when published into the Wordpress application.

Plugin URL which is the globally accessible url to the plugin. It is important that /wp-content/plugins/mfn-wp-plugin/posthook.php is accessible from the internet, since this php file accepts and store news being pushed from MFN in the wordpress database. The Plugin url should however point to the base path of the plugin, eg. http://your-site.com/wp-content/plugins/mfn-wp-plugin

Entity Id which is a UUID that refers to a specific companies news feed in MFN. This id will be given to you by your contact at Modular Finance on request.

Custom Query experimental field used in certain cases, but should not normally be used.

Rewrite settings makes it possible to change the name of the custom post type mfn_news as well as the archive name and singular name. When saving the changes it will apply directly to the URL.

Disable archive if checked, the news archive will no longer be reachable. (Can be useful if you want to prevent users from reaching the archive URL but access the press releases on the site).

Verify Signature is an option that is up to the user. Each press release sent from MFN is cryptographically signed in order for the receiver to be able to verify that it was indeed the sent from MFN. If this is turned on, a news item with a bad signatures will be dropped.

Use WPML will make the plugin compliant with https://wpml.org locale management.

Use Polylang will make the plugin compliant with https://polylang.pro locale management.

Reset Cache (On every new item insert, if checked, this will reset the db cache).

Status

In the status section we find five different parameters which is a result of

Subscription Id appears once the plugin has successfully subscribed via hub.mfn.se through a posthook. It should appear once you click the subscribe button below. The Subscription Id is a sensitive credential, and should not be shared. With this id, you can alter or end your subscription at MFN

Posthook Secret is generated when you click subscribe. It is random string which is used to verify messages from MFN, as described in the Verify Signature section above. It is used as a HMAC key in accordance to the specification w3 WebSub specification https://www.w3.org/TR/websub/. The Posthook Secret is a sensitive credential which give you rights to post content to the posthook. It should not be shared. Malicious actors could masquerade as MFN and sign any data with valid signatures before sending it to the WP plugin.

Posthook Name is generated when you click subscribe. It's a random string which is used as a token for posting messages to the plugin. Any call to the posthook must have this token included. Otherwise the call will be discarded.

Plugin URL is information about the plugin url added in the setting section. It should say Valid

Hub URL is information about the hub url added in the settings section. It should say Valid

Actions

There are two Sync actions

1. Sync Latest will sync the 10 most recently published items from MFN to the Wordpress site. This syncing function disregards what newswire who sent the item.

2. Sync All will sync all the news items from MFN for the entity ID. This syncing function disregards what newswire who sent the item.

You can use this functionality multiple times. The WP posts that are added to the database will not be overwritten, but terms associated with the item will.

The Subscribe function will register the WP plugins posthook with the WebSub hub, hub.mfn.se. If this is successful the Subscription Id in the status section will become visible. It is important here that your Plugin URL is valid and that posthook.php is accessible from the Internet in order for it to work.

Attachments

In all press releases sent by MFN, there is an attachment section in the text body. However this is not always the case for stories sent from other newswires such as Cision or Globe.

The attachments does exist in the wp_postmeta table and can be added through the theme.

The information is stored in these keys:

mfn_attachment_link (Contains the a href link to the attachment)

<a href='https://url_to_attachment.pdf' content='application/pdf' target='_blank' rel='noopener'>Release</a>

mfn_attachment_data (Contains further information about the attachment such as the content-type)

{"file_title":"Release","content_type":"application/pdf","url":"https://url_to_attachment.pdf","tags":[":primary"]}

To list attachments on MFN news, first duplicate your single.php-file in you theme to single-mfn_news.php and then edit it to add the following lines of code:

foreach (get_post_meta(get_the_ID(), 'mfn_news_attachment_link' ) as $link)
{
    echo $link;
}

However if you do this you must not forget to hide the attachment footer for MFN-releases, by adding this line of CSS: .mfn-attachment { display: none; }

Widgets

We recommend that the widgets below are short coded into a page.

You can most often easily insert shortcodes in your WP-theme.

Another way is to programmatically load in the widget shortcode in a post or page template (https://developer.wordpress.org/reference/functions/do_shortcode/).

Even though it is possible to affect most configurations by sending in parameters directly in the shortcode of the widgets, other plugins such as https://wordpress.org/plugins/amr-shortcode-any-widget/ allowing for multiple instances and configurations, might be a helpful alternative when you have different pages for different languages.

All widgets are left quite spars when it comes to styling, so we recommend that you to style them yourself with CSS to fit your theme.

MFN News feed

This widget creates a news room to display all the news. It can be configured only to show specific tags along the the title. You can also template the different sections.

Shortcode example

[mfn_news_feed_widget lang=all showyears=true showpreview=true previewlen=150 pagelen=10 skipcustomtags=true groupbyyear=true onlytagsallowed=mfn-regulatory,mfn-regulatory-mar showpagination=true]

Params	Values
lang The selected language of the news items, default is "en"set"all"to list releases of all languages or set"auto"to let the plugin try to figure out what lang is used	sv or en orfi, all or auto
year Filter news list by a specific year	2020 eg.
showyears Show the year filter section above the news list	true or false or 1 or 0
groupbyyear Group news items by year	true or false or 1 or 0
showpagination Show pagination, default false	true or false or 1 or 0
showpreview Show preview excerpt of a news item, default false	true or false or 1 or 0
pagelen Number of news items to show per page, default 20	10eg.
previewlen Amount of characters to show of the preview excerpt, shows a maximum of 250 characters	150eg.
tags Tags comma separated, to filter on. You can also screen out just non-regulatory press releases by entering:-regulatory or show items of a specific type with mfn-type-pr or mfn-type-ir	mfn-ci,mfn-regulatoryeg.
onlytagsallowed Tags comma separated, limits which tags to be shown in the news items list	mfn-regulatory,mfn-regulatory-mar
skipcustomtags Will prevent showing custom tags in the news list, default false	true or false or 1 or 0
timestampformat Set the timestamp format of the publish date, default 'Y-m-d H:i'	'd M, Y H:i' eg.
tzlocation Set the timezone location for the publish date, default 'Europe/Stockholm'(https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)	'Europe/Tallinn' eg.

You can also override the default template of a news item, the tag list or the years list by adding your custom template to the shortcode.

Custom news item template example

[mfn_news_feed_widget template='<div class="mfn-item"><div class="mfn-title"><a href="{{url}}">{{title}}</a></div><div class="mfn-date">{{date}}</div><div class="mfn-tags">{{tags}}</div><div class="mfn-preview">{{preview}}</div><span><a href="{{url}}">Read More <i class="icon-button-arrow"></i></a></span></div>']

Custom tag template example

[mfn_news_feed_widget tagtemplate='<span class="mfn-tag mfn-tag-{{slug}}">{{tag}}</span>']

Custom year template example

[mfn_news_feed_widget yeartemplate='<span class="mfn-year-header mfn-year mfn-year-header-{{year}}"><a href="{{url}}" class="mfn-year-header-link mfn-year-header-link-{{year}}">{{year}}</a></span>']

Query params

By adding query params to m-page, m-year and m-tags to your website url, you are able to effectively filter and paginate the content of the widget.

m-page can be used to palatinate your news feed. eg. m-page=0 m-page=1 m-page=2 ...

m-year can be used to specify only to show a specific year of the news feed. eg. m-year=2018 m-year=2015

m-tagscan be used to filter on specific tags in the news feed eg. m-tags=regulatory,report read as regulatory AND report or m-tags=report,-report-annual read as report AND NOT report-annual

This can now be put together eg. showing page 2 of all regulatory stories sent 2017 ?m-page=1&m-year=2017&m-tags=regulatory

Additionally you can filter on only news items of a specific type with &m-tags=mfn-type-pr or &m-tags=mfn-type-ir

MFN Report Archive

This widget creates an archive for financial reports. It is highly configurable and supports fiscal year offset, generic titles (eg. Interim Q1 2019) as well as displaying a thumbnails of the reports in the archive.

Shortcode example

[mfn_archive_widget showfilter=true showthumbnail=true showyear=true]

Params	Values
showfilter Show the filter section, default: false	true or false or 1 or 0
showdate Show the date, default: false	true or false or 1 or 0
showyear Show the year, default: false	true or false or 1 or 0
fromyear Set "from year" for the desired period	2017 .eg
toyear Set "to year" for the desired period	2021 .eg
showheading Show the heading, default false	true or false or 1 or 0
showthumbnail Show report thumbnail image, default false	true or false or 1 or 0
showgenerictitle Show a generic title (Instead of the title of the report), default false	true or false or 1 or 0
usefiscalyear Enable fiscal year period support, default true	true or false or 1 or 0
usefiscalyearoffset Offset for the fiscal year period	1 .eg
useproxiedattachments Use cached attachments for thumbnails if available, default true	true or false or 1 or 0
lang Set the language of the reports, default "en"set"auto"to let the plugin try to figure out what lang is used	sv or en orfi or auto
limit Limit number of reports to show, default 500	20 .eg
offset Drop X number of items from start of the list	1 eg. (skips the latest report)

MFN Subscription Widget

The subscription widget is supposed to enable users to easily add a subscription form enabling users of the website to sign up to receive the press releases.

The following setting is supported in versions of the MFN WP Plugin from version v0.0.45 and later.

Shortcode example

[mfn_subscription_widget widget_id='your_subscription_widget_id_here']

The following settings are only for versions before MFN WP Plugin version v0.0.45.

Shortcode example

[mfn_subscription_widget lang=sv langs=sv,en showlangs=true showtypes=true privacy_policy='/privacy-policy']

Params (Deprecated since v0.0.45+)	Values
lang Set the language of the subscription widget, default ensetautoto let the plugin try to figure out what lang is used	sv or en orfi or auto
langs Comma separated, what languages to show, defaultsv,en	sv or en orfi
showlangs Show the select languages section, default false	true or false or 1 or 0
showtypes Show the select types section, default false	true or false or 1 or 0
privacy_policy Enter the link to the privacy policy page (If not set, it will fallback to https://mfn.se/privacy-policy)	'{URL to privacy policy}'

Grouping by year

Our widgets will dynamically handle grouping by year in our news feed widget and report archive widget, so when it's a change to a new year it will automatically be reflected.

However, if you don't use our widgets it is important to keep in mind that when it is a new year, you must make sure that your links or dropdown's are populated dynamically (or that you manually add the new year as a category). This is critical to ensure that the press release or report will be available on the site.

Development

When testing and doing developing of the plugin, we suggest you do this locally and do not hook up a subscription. Instead sync news items and they will appear in the wp_posts table of the database. This should give you enough examples to work with when designing the public facing view.

Tags

All news items comes with tags of our taxonomy, which ends up in wp_terms. The tags are equivalent to the tags information found under Models > News Item > Properties section.

Language plugin support

The plugin supports Polylang (https://wordpress.org/plugins/polylang/) and WPML (https://wpml.org/) for multi-language support.

Polylang

In order for Polylang to be able to translate news items and tags, you'll need to enable our custom post type and taxonomy in the Polylang Settings area.

If you have already imported the news items, you should do 'Delete all MFN posts' from our plugin settings. When done deleting click 'Sync All' to import all press releases, followed by 'Sync Taxonomy' to make sure that the taxonomy is updated.

Caching

When using cache plugins in Wordpress you must make sure that the pages displaying the news feed are not being cached.

When implementing news on any website, is important to remember client side caching and that many browsers has an aggressive default cache policy. Any page that renders news should therefore ensure that the clients browser does not cache the page. This is done by setting caching policy headers on the server side. eg

Cache-Control: max-age=0, no-cache, no-store, must-revalidate Expires: Thu, 01 Jan 1970 00:00:00 GMT Pragma: no-cache

Failing this to do this could, in the worst case, be considered a violation of EUs MAR regulation that demands simultaneous publishing

Multisite

You can use our plugin with WP multisite. In that case you can install one mfn-wp-plugin instance per site and configure them individually.