immber
4d41d999fb
* added storyURL and storyID * added story scraping section * fixed typo on sso * rebaseing on latest release/4 branch * updated version on slack docs * added Contributing a Translation section to developing * fixing typos * updated v5 config page, reorder list, add toc * added cli sect, fixed contact menu link * updated talk to coral on contact page * added a new v5 auth section * added session length to auth docs * added an admin settings page to v5 * added v5 css section * added a v5 notifications section * updated faq and troubleshooting, moved out of v4 menu * added migrating to v5 and moved migrating section out of v4 * added plugins note to migration pg * fix: linting and extra HTML * change sidebar migrating v5 to v5.0+ Co-Authored-By: Wyatt Johnson <wyattjoh@gmail.com> * downtime being likely is too optimistic, it will be required Co-Authored-By: Wyatt Johnson <wyattjoh@gmail.com> * rewords plugins note on migrating to v5 Co-Authored-By: Wyatt Johnson <wyattjoh@gmail.com> * tag code block as html Co-Authored-By: Wyatt Johnson <wyattjoh@gmail.com> * added link to contributing * rephrased openid connect description * fixed link to contributing * correcting descriptions of email auth behavior Co-Authored-By: Wyatt Johnson <wyattjoh@gmail.com> * Adding link to css classnames Co-Authored-By: Wyatt Johnson <wyattjoh@gmail.com> * renamed new auth to Social and Email Authentication * pulled extra line breaks Co-authored-by: Wyatt Johnson <accounts+github@wyattjoh.ca>
4.4 KiB
title, permalink
| title | permalink |
|---|---|
| Integrating on your site | /v5/integrating/cms/ |
With Coral setup and running locally you can find your Embed code under Configure > Advanced (logged in as an ADMIN). It should look something like this, but with your domain in place of CORAL_DOMAIN_NAME. You can test placing the comment stream embed on your page with this sample embed script:
<div id="coral_thread"></div>
<script type="text/javascript">
(function() {
var d = document, s = d.createElement('script');
var url = '{{ CORAL_DOMAIN_NAME }}';
s.src = '//' + url + '/assets/js/embed.js';
s.async = false;
s.defer = true;
s.onload = function() {
Coral.createStreamEmbed({
id: "coral_thread",
autoRender: true,
rootURL: '//' + url,
});
};
(d.head || d.body).appendChild(s);
})();
</script>`;
NOTE: Replace the value of
{% raw %}{{ CORAL_DOMAIN_NAME }}{% endraw %}with the location of your running instance of Coral.
Story Creation
Lazy Story Creation enables stories to be automatically created when they are published from your CMS. Triggering the embed script above renders the comment stream iFrame on your page. By default that script dynamically generates Stories in Coral for seamless integration.
storyURL
If you do not specify a storyURL when rendering the embed, the storyURL is first inferred from the Canonical link element, which takes the form of a element in your <head> of the page:
<!DOCTYPE html>
<html>
<head>
<link rel="canonical" href="https://example.com/page" />
</head>
<body>
...
</body>
</html>
The url must reference an existing Permitted Domain. If your articles/stories always have unique urls, then you will not need to modify the default behavior.
If this tag is not present, or if the canonical URL references a different url than your site such as a wire service, you can specify the storyURL parameter in the render function.
The url will be used by Coral to build user facing links, and should reference the location where you would direct a user back to this particular story or article.
storyID
To more tightly couple Coral with your CMS you can provide your CMS's unique identifier to Coral by including a storyID parameter in the render function. Doing so will allow you to target the Story for later updates via Coral's Graphql API, such as updating the URL if it changes.
Integration via API
Story creation can also be controlled by direct calls to Coral's API. When Lazy Story Creation is disabled embed streams can only be created by data migration or API POST request.
See GraphQL API Overview for help with the API.
Story Scraping
By default, stories have their metadata scraped when they are loaded. This provides the easiest way for newsrooms to integrate their CMS’s into Coral in a simple way. We use the following meta tags on the target pages that allow us to extract some properties.
Metadata scraping is performed by the scraper job which is enabled by default.
If your production site is behind a paywall or otherwise prevents scraping, you might need to confiugre a Scraper Proxy URL. When specified it allows scraping requests to use the provided proxy. All requests are then passed through the appropriote proxy as parsed by the npm proxy-agent package.
| Asset Property | Selector |
|---|---|
title |
See metascraper-title |
description |
See metascraper-description |
image |
See metascraper-image |
author |
See metascraper-author |
publication_date |
See metascraper-date |
modified_date |
meta[property="article:modified"] |
section |
meta[property="article:section"] |