From 95435f079385475d66a94e83546b8433155410f7 Mon Sep 17 00:00:00 2001 From: immber Date: Fri, 14 Dec 2018 09:05:52 -0800 Subject: [PATCH] Docs update (#2120) * merging in typo fixes from docs (rtd) branch * revert generateIntrospectionResult.json * revert git ignore * added asset mgmt to prelaunch checklist * updated cusotm plugin docker onbuild instructions * add google to auth options * add google to auth options * added yarn watch to from source * added dev links to quickstart * typo on following * fixed typos * fixing links * added lazy render and updated lazy load * added version note * renamed asset management to cms-integration * added link to asset scraping --- docs/_config.yml | 4 +- docs/source/01-05-pre-launch-checklist.md | 2 +- ...asset-management.md => cms-integration.md} | 81 ++++++++++++++++--- 3 files changed, 74 insertions(+), 13 deletions(-) rename docs/source/integrating/{asset-management.md => cms-integration.md} (75%) diff --git a/docs/_config.yml b/docs/_config.yml index 57fe6d666..d9de09850 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -104,8 +104,8 @@ sidebar: children: - title: Authentication url: /integrating/authentication/ - - title: Asset Management - url: /integrating/asset-management/ + - title: CMS Integration + url: /integrating/cms-integration/ - title: Asset Scraping url: /integrating/asset-scraping/ - title: Configuring the Comment Stream diff --git a/docs/source/01-05-pre-launch-checklist.md b/docs/source/01-05-pre-launch-checklist.md index 854ead062..01e42b9bd 100644 --- a/docs/source/01-05-pre-launch-checklist.md +++ b/docs/source/01-05-pre-launch-checklist.md @@ -29,7 +29,7 @@ permalink: /pre-launch-checklist/ - See [Authenticating with Talk](/talk/integrating/authentication/) - [ ] Do you want to integrate Talk with your CMS to automate embedding Talk Comment Stream into your site? - - See [Asset Management](/talk/integrating/asset-management/) + - See [CMS Integration](/talk/integrating/cms-integration/) - [ ] Do you want to use Social sign-on? - Facebook diff --git a/docs/source/integrating/asset-management.md b/docs/source/integrating/cms-integration.md similarity index 75% rename from docs/source/integrating/asset-management.md rename to docs/source/integrating/cms-integration.md index 190b67c63..521ab5cf8 100644 --- a/docs/source/integrating/asset-management.md +++ b/docs/source/integrating/cms-integration.md @@ -1,23 +1,81 @@ --- -title: Asset Management -permalink: /integrating/asset-management/ +title: CMS Integration +permalink: /integrating/cms-integration/ --- +## Embedding Comments on Your Site +Talk provides an embed script that you can drop into your site where you want a comments section to appear. By default that script dynamically generate Assets +in Talk in order to make it easier for lighter installations. + +You can find the embed script inside talk under `Configure > Tech Settings > Embed Script`. It should look something like this, but with your domain in place of ``: +``` +
+ +``` + +## Triggering the Comments Section (client side, i.e. Your site) + +When the embed script is triggered on your page load several things are initiated inside Talk, including fetching all comments for the specified article, establishing websocket connections for this user, and checking user’s session for SSO/authentication. + +Instead of greedily triggering the embed to render on _EVERY PAGE LOAD_, we highly recommend implementing a _“lazy”_ rendering strategy to only render the comments section if a user wants to interact with it. This will greatly improve your initial page load performance, and will be critical to managing server resources if you’re running Talk on a heavy-traffic production site. + +We recommend using one of these _“lazy”_ loading strategies: + +#### Scroll to Comments Section +Wait for user to scroll to the comment section before triggering the embed to render. + +You can pass lazy: true to the render options, like so: +``` +Coral.Talk.render(document.getElementById('container'), { + talk: 'https://my-talk-installation.com', + lazy: true, +}); +``` + +Or you can enable lazy rendering by default on all assets using ENV variable `TALK_DEFAULT_LAZY_RENDER=TRUE` + +_*Note: This feature requires Talk version 4.6.8 or greater_ + +#### Show Comments Button + You can hide the comments section until a user clicks button, then trigger the embed to render + +This example uses jQuery to render the embed on the button's click event +``` + + +
+ +
+ + +``` + +## Creating Assets in Talk (server side, i.e. What you need to send to Talk) One of the most frequent questions that we get asked by organizations trying to integrate Talk is: _How do we hook our CMS up to Talk so that articles are in sync?_ -This guide is designed to explain the steps to take your base installation of -Talk and configure it to allow only assets pushed into it from your CMS, and -keep your URL/title in sync. We won't cover here how to install the plugin, as -it is covered in our [Plugins Overview](/talk/plugins/). +### “Lazy Asset Creation” +Talk’s provided embed script by default dynamically generates Assets in Talk based on each unique url that triggers it. 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. -## Why do we need to create a plugin? +Assets created in this way will then be scraped to load metadata, see [Asset Scraping](/talk/integrating/asset-scraping/) -By default, Talk will use "Lazy Asset Creation" to dynamically generate Assets -in Talk in order to make it easier for lighter installations. In order to have -more strict control over this flow, we will create a plugin that will: +## Customizing the Integration with a Plugin +In order to have more strict control over the asset creation flow to allow only assets pushed into it from your CMS, and keep your URL/title in sync we will create a plugin. +We will create a plugin that will: 1. Disable "Lazy Asset Creation" by [Overriding a Resolver](#overriding-a-resolver). 2. Create Assets from our CMS by [Creating a New Asset Route](#creating-a-new-asset-route). @@ -25,6 +83,9 @@ more strict control over this flow, we will create a plugin that will: We will then modify our embed so that we can [Target the Asset](#target-the-asset). + +This guide is designed to explain the steps to take your base installation of Talk and configure it. We won't cover here how to install the plugin, as it is covered in our [Plugins Overview](/talk/plugins/). + But first we should grab our basic plugin structure: ```sh