About this repository

This repository is intended to give you a great starting point for integrating with our iframe widget.

Want to jump straight to the action? Go to the demo >

To use the Learning Diary (the name for our CPD recorder) via the widget, the user needs a FourteenFish account. We try and make it nice and easy for them to create their account if they don't already have one.

article-simple.html

Go to the demo page >

This is the easiest option for you to implement. You put a button in any pages of your website that you want the user to be able to record CPD from. When the user clicks this button, you show an iframe with some special parameters:

• integrationid
• intent (newentry or list)
• pagetitle
• pageurl

You can use demo as the integrationid for testing, but before too long you should contact us and we will set you up with your own integrationid. At the same time we can do things like customise the text on the login widget for you as needed.

postMessage() communication with the parent page

The iframe widget uses postMessage() to enable it to communicate with the parent page. This includes sending its height, avoiding scrollbars on the iframe and improving usability and overall appearance. The code for handling this is in all of the demo pages and is contained in the scripts/message.js file. You don't have to implement this, but we recommend it. The same script also handles closing the popover once the user has saved their CPD entry. Examples of postMessage() communications include:

• { event: "height", iframeHeight: 414 } – iframe content height has changed
• { event: "account_created" } – the user has made a new account
• { event: "empty_list" } – the user is viewing an empty CPD list
• { event: "normal_list" } – the user is viewing thier CPD list which contains at least one entry

Optional parameters

As well as the parameters above, you can optionally pass some of the user's personal details to make it quicker for them to create a FourteenFish account if they don't already have them. Of course this only works if you have user accounts on your website and the user is logged in.

You can also pass a minutes parameter if you want to give the user a suggestion of how much CPD they should allocate to their entry. If not specified, this defaults to 30 minutes.

• minutes (eg. 90 for 1h30m)
• email
• salutation (eg. Mr, Mrs, Dr)
• firstname
• lastname
• county (eg. Wiltshire)
• profession (eg. Nurse)
• userid
• incomingid

Passing us the userid from your database is a good idea as it allows us to record this in our database. If you then decide to move to one of our more complex APIs in future then this will be useful and will save people from linking their accounts again.

Once the entry is saved by the user, we will pass back the incomingid just in case you want to use it to update something at your end. For example this could be posted back to your server to record that the user has transfered a specific entry to FourteenFish.

article-callback.html

Go to the demo page >

If putting the user's personal details in the iframe src attribute feels messy but you still want to assist the user with account creation, you can just send us your userid and usercallback set to true and we will then use this to perform a serverside callback to get their details.

With the demo integrationid we just use a dummy callback. You can see the JSON data that we use to mock the response from the callback in the userdatacallback.json file. If you want to use this method then we will ask you for your callback URL when we set up your integrationid. We'll also give you a secret key that you can use to validate requests.

Just to clarify, there is nothing wrong with putting the user's personal details in the src of the iframe. This method just feels a little neater 🤓.

list-simple.html

Go to the demo page >

This demo contains a single iframe for displaying a list of the user's CPD entries. The code in the scripts/message.js file ensures that the iframe is always tall enough to accomodate its content and avoids the iframe having scrollbars.

You could argue that it's strange to show a link to this page to the user before they have recorded any CPD. If you'd like to hide the page initially, let us know and we can send a callback to your server when the user records their first CPD entry along with their userId to enable you to show or hide the link to this page.

list-record.html

Go to the demo page >

This demo contains two iframes, one for listing existing entries and one for recording new entries which is triggered by the link on the right hand side of the page.

When the message refreshlist is received then the list of entries is reloaded to display the new entry. This message is sent earlier than the saved message to allow the iframe to be reloaded in advance of the popover closing.

Other pages

Patient review >