From 340052cdf034cc2d6b8017391db7ac76c439254b Mon Sep 17 00:00:00 2001 From: immber Date: Wed, 10 Jul 2019 09:41:52 -0700 Subject: [PATCH] DOCS | Add `asset_url` note to CMS integration & Update FB config (#2393) * added note RE passing asset_url, and updated fb configs * fix: syntax tweaks * feat: small tweaks to embedding --- docs/source/integrating/cms-integration.md | 172 ++++++++++++++------ plugins/talk-plugin-facebook-auth/README.md | 2 +- 2 files changed, 121 insertions(+), 53 deletions(-) diff --git a/docs/source/integrating/cms-integration.md b/docs/source/integrating/cms-integration.md index 521ab5cf8..852591c91 100644 --- a/docs/source/integrating/cms-integration.md +++ b/docs/source/integrating/cms-integration.md @@ -4,47 +4,87 @@ 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 ``: -``` +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 `${TALK_ROOT_URL}`: + +```html
- +" +> ``` +The URL for the asset is first inferred from the _Canonical link element_, which +takes the form of a `` element in your `` of the page: + +```html + + + + + + + ... + + +``` + +If this tag is not present, you can also pass a `asset_url` parameter into the +render function as: + +```js +Coral.Talk.render(document.getElementById("coral_talk_stream"), { + talk: "${TALK_ROOT_URL}", + asset_url: "https://example.com/page" +}); +``` + +Which will explicitly force Talk to reference a particular url. This is +recommended if your canonical url does not match the current url. + +> **NOTE:** If the canonical link tag or `asset_url` parameter are not present, Talk will use the current URL excluding the query and hash elements. This may lead to undesired behavior, and it is recommended to use one of the above methods of specifying the URL. + ## 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. +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. +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. + +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, + +```js +Coral.Talk.render(document.getElementById("container"), { + talk: "${TALK_ROOT_URL}", + 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_ +_\*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 + +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 -``` + +```html
@@ -52,10 +92,10 @@ This example uses jQuery to render the embed on the button's click event
+" +> ``` We'll modify this to the following: ```html
- +" +> ``` Adding the `asset_id` parameter to the render function will accomplish a very @@ -369,8 +435,10 @@ the URL in the future, the embed will still reference the correct Asset. The `${ASSET_ID}` should be replaced by your CMS with the correct Asset id using your desired scripting/templating tools. +> **NOTE:** When used in conjunction with `asset_url`, you can explicitly force Talk to use a specified URL, rather than the canonical for link references. When used together, both `asset_id` and `asset_url` will be treated as unique identifiers for Talk assets. + At this point, you should have a fully built Talk plugin that can be paired with some work on your CMS to create a fully integrated asset management pipeline! To view the fully completed source code, visit -https://github.com/coralproject/talk-plugin-asset-manager-example. \ No newline at end of file +https://github.com/coralproject/talk-plugin-asset-manager-example. diff --git a/plugins/talk-plugin-facebook-auth/README.md b/plugins/talk-plugin-facebook-auth/README.md index 4a3dbe44f..6fd224bbc 100644 --- a/plugins/talk-plugin-facebook-auth/README.md +++ b/plugins/talk-plugin-facebook-auth/README.md @@ -36,7 +36,7 @@ You can learn more about getting a Facebook App ID at the * add a link to your privacy policy * add a link to your terms of service * In Settings > Advanced: - * turn on "Require App Secret" + * disable "Require App Secret" * Add a "Product" (Under "Products" click + to add a Product): * Setup "Facebook Login" * choose `www`