** Warning: The server side functionality for this is yet to be implemented - so saving Immediate alerts will cause duplicate entries in your Author Alert preferences! **
A widget providing the UI and functionality to subscribe to Author Alerts on FT.com
##Construction
A product must provide the source HTML as shown below, based on the use case.
The Alerts buttons are automatically initialised when the o.DOMContentLoaded
event is triggered.
Alternatively, you can use the init
method, as follows:
var oAuthorAlerts = require('o-author-alerts');
oAuthorAlerts.init(rootEl);
where rootEl
defaults to document.body
if not specified.
####Configuration You can optionally change some of the configuration. The object that you specify will be deep merged with the default configuration, overwriting values for the same fields.
The configuration can be changed be using the setConfig
static method.
oAuthorAlerts.setConfig({
lazyLoad: false, // the default behaviour for the widget is to only load metadata on hover/click. Set to false to fetch data on page load.
startAlertingText: "Follow %entityName%", //default: 'Start Alerts'
stopAlertingText: "Unfollow %entityName%", //default: 'Alerting '
widgetText: 'Your Alerts', //default: 'Author Alerts'
popoverHeadingText: 'You are following:' //default: null,
displayName: "Get email for %entityName%" //default: '%entityName%'. Set to false to hide the name.
});
%entityName%
will be replaced with the name of the entity in the above examples.
As on the event o.DOMContentLoaded
the widgets declared in the DOM are automatically initialized, it is preferred to call this function before the o.DOMContentLoaded
event is triggered.
In order to change the configuration, you can add a script tag in your page source with the format in the example below:
<script data-o-author-alerts-config type="application/json">
{
lazyLoad: false, // the default behaviour for the widget is to only load metadata on hover/click. Set to false to fetch data on page load.
startAlertingText: "Follow %entityName%", //default: 'Start Alerts'
stopAlertingText: "Unfollow %entityName%", //default: 'Alerting '
widgetText: 'Your Alerts', //default: 'Author Alerts'
popoverHeadingText: 'You are following:' //default: null,
displayName: "Get email for %entityName%" //default: '%entityName%'. Set to false to hide the name.
}
</script>
{
"getFollowingUrl": "http://personalisation.ft.com/follow/getFollowingIds",
"startAlertsUrl": "http://personalisation.ft.com/follow/update",
"stopAlertsUrl": "http://personalisation.ft.com/follow/stopFollowing",
"stopAllUrl": "http://personalisation.ft.com/follow/stopFollowingAll",
"metadataUrl": "http://metadata-cache.webservices.ft.com/v1/getAuthors/",
"lazyLoad": true, // the default behaviour for the widget is to only load metadata on hover/click. Set to false to fetch data on page load.
"entityType": "Author",
"startAlertsText": "Start alerts",
"stopAlertsText": "Alerting<i class=\"o-author-alerts__icon--tick\"></i>",
"widgetText": "Author alerts",
"popoverHeadingText": null,
"displayName": "%entityName%",
"frequencies": [
{
"key": "daily",
"text": "Daily email"
},
{
"key": "immediate",
"text": "Immediate email"
}
]
}
{
"getFollowingUrl": "http://test.personalisation.ft.com/follow/getFollowingIds",
"startAlertsUrl": "http://test.personalisation.ft.com/follow/update",
"stopAlertsUrl": "http://test.personalisation.ft.com/follow/stopFollowing",
"stopAllUrl": "http://test.personalisation.ft.com/follow/stopFollowingAll"
}
####Font family
<button>
elements need to be assigned a font-family
or browsers will display the system default. Personalise the font like this:
// your-app.scss
// Override the default font in both o-forms and o-author-alerts
$o-author-alerts-button-font: BentonSans, sans-serif;
$o-forms-font-family: BentonSans, sans-serif;
// Then, import the module
@import 'o-author-alerts/main';
##Content The buttons can be created for you by passing in a data attribute on the root element:
data-o-author-alerts-article-id="<article UUID>"
data-o-author-alerts-user
- `data-o-author-alerts-entities='[{"name": "", "id": ""}, {"name": "", "id": ""}]'
##Appearance
By default, the Alerts component applies minimal styles to the list and header. There is also an option of displaying it as a widget. To do so, construct the HTML as shown in use case 2 below, with the o-author-alerts--theme
class.
##Examples
-
Given an Article ID, I want a list of buttons that lets me start/stop getting alerts all authors of that article
<div class="o-author-alerts" data-o-component="o-author-alerts" data-o-author-alerts-article-id="{{articleId}}"></div>
-
Given an Article ID, I want a widget that displays the list of authors on hover
<div class="o-author-alerts o-author-alerts--theme" data-o-component="o-author-alerts" data-o-author-alerts-article-id="{{articleId}}"></div>
-
Given a logged in user, I want to create buttons for all the users that the user currently gets alerts for
<div class="o-author-alerts" data-o-component="o-author-alerts" data-o-author-alerts-user></div>
-
I want to create a standalone author alert button for an author I already have.
<div class="o-author-alerts" data-o-component="o-author-alerts" data-o-author-alerts-entities="[{"name": "Roman Olearchyk", "id": "Q0ItMDAwMDY0Mg==-QXV0aG9ycw=="}]"></div>
##Events
The Alerts component fires the following events:
-
oAuthorAlerts.userPreferencesLoad
- triggered ondocument.body
- Fired when the user preferences have been successfully loaded
- sends a list of entities being alerted as the event detail.
-
oAuthorAlerts.show
- triggered on the root element- Fired if the alerts widget/list is made visible on the page (i.e. if all backend calls were successful, and there is at least one entity to display.)
-
oAuthorAlerts.saveChanges
- triggered on the root element- Fired when the save button is clicked (irregardless of whether it was successful or not)
-
oAuthorAlerts.updateSave
- triggered ondocument.body
- Fired when a request to start/stop has been successfully saved to the server
- event.detail
{ data: <response from server>, action: <'start' or 'stop'>, entity: { id: <entity id>, name: <entity name> }, userId: <userId> }
-
oAuthorAlerts.serverError
- triggered ondocument.body
- Fired when the personalisation service comes back with an error, either when updating or loading user preferences.
- event.detail
{ data: <response from server>, action: <'start' or 'stop'>, entity: { id: <entity id>, name: <entity name> }, userId: <userId> }
There are also tracking events fired for various events on the page: * When a widget is shown on a page * When the widget is opened * When a user starts/stops getting alerts for someone * On the server update/errors
##Development Notes
- To test, run
npm test
in the root directory - The alerts functionality only works if there is a valid
FT_User
cookie with an eRights ID. You'll need to make sure this cookie exists when running the demos locally.