Embed your Forum - HL Vanilla Community
<main> <article class="userContent"> <p>Embedding <strong>Higher Logic Vanilla</strong> (<strong>Vanilla</strong>) Forums works by putting a snippet of code on your website page, and may be a choice if you want to insert your forum into a site quickly. The snippet points to some JavaScript and the forum is embedded into the page using an iFrame.</p><h2 data-id="embedding-checklist"><strong>Embedding checklist</strong></h2><ol><li>Choose the embed friendly theme. This theme has minimal padding around it and will look good at any width. (Make modifications in <em>Customize theme</em>.)</li><li>Ensure you have <strong>Enabled Embedding</strong> in your dashboard.</li><li>Make sure that the page in which you embed is free of JavaScript errors.</li><li>Your embedded forum must have the same base domain name as the hosted site. For example, if you want to embed your forum in <strong>mysite.com</strong>, create a subdomain (<strong>forum.mysite.com</strong>) and apply it to the forum. (See <a href="https://success.vanillaforums.com/kb/articles/3-setting-up-your-custom-domain" rel="nofollow noreferrer ugc">Setting up your Custom Domain</a> for more information.)</li></ol><p>When embedding a forum, consider these drawbacks:</p><ol><li>The possibility of slower loading times, as your site needs to load the forum via JavaScript along with any other content you may have loading via JavaScript.</li><li>Issues with SEO, as Google (and other search engines) don’t always do a great job of indexing framed content.</li></ol><h2 data-id="embedding-comments">Embedding comments</h2><p>If you have a blog or news site, you can use Vanilla as a <em>commenting system</em> to more fully engage readers who might otherwise just enter a comment.</p><ul><li>A single profile, reputation, and user experience across the community and the comments</li><li>Engage commenters with Vanilla’s existing gamification and curation features</li><li>Use blog traffic to quickly seed community participation and vice versa</li></ul><h3 data-id="how-to-implement-comments">How to implement comments</h3><p>There is a <a href="https://wordpress.org/plugins/vanilla-forums/" rel="nofollow noreferrer ugc">WordPress plugin</a> that you can use to enable comments on your WordPress blog from your WordPress dashboard. Alternately, we have a universal JavaScript code snippet that can be placed into any page to enable comments.</p><p>If you are using different blog software, you have to edit the blog template and replace the existing blog comments with the code that can be found in the Dashboard under <strong>Forum > Blog Comments</strong>. Use our <a href="https://success.vanillaforums.com/kb/articles/49-universal-comments" rel="nofollow noreferrer ugc">Universal Code,</a> the code snippet can be modified to create discussion threads in the appropriate forum category based on the blog post category.</p><h3 data-id="what-does-vanilla-use-as-an-excerpt-from-my-blog-article-when-creating-a-blog-comment-discussion">What does Vanilla use as an excerpt from my blog article when creating a blog comment discussion?</h3><p>When Vanilla creates a discussion thread based on a blog article, it uses the blog title, the first few lines of text, and an image. You can use Open Graph meta tags to specify which image should be used. Otherwise, it uses the first 4 images on the page and finds the “best” one it can. The "best image" is the biggest image that is at least 100x100, but smaller than 800px wide and not banner-shaped.</p><p>Readers can log in using a Disqus ID, Twitter, Google, Facebook, or via Single Sign-On.</p><h2 data-id="advanced-embedding">Advanced embedding</h2><p>The advanced embedding technique is for developers who require programmatic interaction between the Vanilla iFrame and their parent window. It employs <a href="http://easyxdm.net/wp/" rel="nofollow noreferrer ugc">easyXDM</a> and a special container layer to achieve this. It requires a more in-depth setup than Vanilla’s basic embed solution.</p><h2 data-id="testing-embedding-locally-on-docker">Testing embedding locally on Docker</h2><p>If your local environment is set up with <a href="https://github.com/vanilla/vanilla-docker" rel="nofollow noreferrer ugc">vanilla-docker</a>, local embed setups are very simple to configure.</p><p>1. Clone the <a href="https://github.com/vanilla/stub-embed-providers" rel="nofollow noreferrer ugc">stub-embed-providers repo</a> next to your vanilla-docker repo, and then do one of the following:</p><p><strong>Simple & comments embed</strong></p><p>1. Add the following to your configuration.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">$Configuration['Garden']['Embed']['Allow'] = true; </pre><p>2. Navigate to <a href="http://embed.vanilla.localhost" rel="nofollow noreferrer ugc">http://embed.vanilla.localhost</a> and test your forum.</p><p>3. Navigate to <a href="http://comments-embed.vanilla.localhost/" rel="nofollow noreferrer ugc">http://comments-embed.vanilla.localhost/</a> and test your comments embed.</p><p><strong>Advanced embed</strong></p><p>1. Add the following to your configuration.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">$Configuration['Garden']['Embed']['Allow'] = 2; </pre><p>2. Navigate to <a href="http://advanced-embed.vanilla.localhost" rel="nofollow noreferrer ugc">http://advanced-embed.vanilla.localhost</a> and test your forum.</p><h2 data-id="set-up-advanced-embedding">Set up advanced embedding</h2><p>Enable forum embedding via the Dashboard. Then set <strong>Garden.Embed.Allow</strong> to <strong>2</strong> in your config.</p><p>📝 <strong>NOTE</strong>: Cloud customers will have this done by support staff.</p><ol><li>Include easyXDM: <code class="code codeInline" spellcheck="false" tabindex="0">/js/easyXDM/easyXDM.min.js</code></li><li>Include Vanilla’s advanced embed script: <code class="code codeInline" spellcheck="false" tabindex="0">/js/vanilla.embed.js</code></li><li>Create a div to contain Vanilla and give it an ID.</li><li>Call <code class="code codeInline" spellcheck="false" tabindex="0">Vanilla.embed({options})</code>.</li></ol><h3 data-id="options">Options</h3><p>Vanilla.embed() takes an associative array of options.</p><h4 data-id="required-options">Required options</h4><p><code class="code codeInline" spellcheck="false" tabindex="0">root</code> The root URL of your Vanilla forum. Example: <a href="http://community.yoursite.com" rel="nofollow noreferrer ugc">http://community.yoursite.com</a></p><p><code class="code codeInline" spellcheck="false" tabindex="0">container</code> The ID or DOM element of the container for Vanilla.</p><h4 data-id="optional-options">Optional options</h4><p><code class="code codeInline" spellcheck="false" tabindex="0">initialPath</code> The initial path to browse to when embedding the forum. Our example below demonstrates using the hash part of the URL to automatically set this. Example: <code class="code codeInline" spellcheck="false" tabindex="0">site.com/embedpage#/categories/some-category</code></p><p><code class="code codeInline" spellcheck="false" tabindex="0">sso</code> An SSO string that will automatically sign the user into Vanilla.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">autoStart</code> Whether or not to start the embed when <code class="code codeInline" spellcheck="false" tabindex="0">embed()</code> is called. If this is false, then you must call embed.start() to start the embed. Default: <code class="code codeInline" spellcheck="false" tabindex="0">true</code></p><p><code class="code codeInline" spellcheck="false" tabindex="0">onReady()</code> A callback function to call when the embed is ready.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">notifyLocation(path)</code> A function that will be called when the URL of the embedded iFrame changes. You can use this to update your history. By default, this adds the path as the current location’s # fragment. Combine this with initialPath to implement your own custom history.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">height(x)</code> A function that is called to set the height of the embedded iFrame. If you override this method, then you can access the embedded iFrame using <code class="code codeInline" spellcheck="false" tabindex="0">this.iframe</code>.</p><h3 data-id="methods">Methods</h3><p><code class="code codeInline" spellcheck="false" tabindex="0">start()</code> Start the embed. Only call this method if you set autoStart to <code class="code codeInline" spellcheck="false" tabindex="0">false</code>.</p><p><code class="code codeInline" spellcheck="false" tabindex="0">setLocation(path)</code> Manually set the location of the embedded iFrame. Just specify the path, not the full domain of the embed.</p><h3 data-id="custom-callbacks">Custom callbacks</h3><p>The embed API allows custom JavaScript to be called between the parent and child iFrames.</p><h2 data-id="exposing-a-method-to-vanilla">Exposing a method to Vanilla</h2><p>You can expose a method to the child iFrame with the following code:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">Vanilla.embed.fn.functionName = function(args,...) { … } </pre><p>The embed requires all functions on both sides to be explicitly registered to prevent a third party hijacking the embed and calling functions with unforeseen consequences.</p><p>Vanilla embed supports a callback function on both ends of the embed. If you want to support a callback function, declare it as the last argument of your function. When the other endpoint of the embed calls your function using <code class="code codeInline" spellcheck="false" tabindex="0">callRemote()</code> it can then specify a callback and the framework will handle calling the callback across the domain.</p><h2 data-id="calling-a-method-in-vanilla">Calling a method in Vanilla</h2><p>You can call a method in Vanilla with the following code:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">Vanilla.embed.callRemote("functionName", args [, callback]); </pre><p>If you supply the callback argument to <code class="code codeInline" spellcheck="false" tabindex="0">callRemote()</code> then it will be supplied as the last argument to the remote function. It is the remote function’s job to call the function. Keep in mind that using <code class="code codeInline" spellcheck="false" tabindex="0">call()</code>, <code class="code codeInline" spellcheck="false" tabindex="0">apply()</code>, etc. to set a context for the function will not work as a context cannot be passed across the domain.</p><h3 data-id="functions-you-can-call-on-vanilla">Functions you can call on Vanilla</h3><p><code class="code codeInline" spellcheck="false" tabindex="0">Vanilla.embed.signout()</code> Calling this function will sign the user out of Vanilla. It won’t refresh the page so you may want to do that afterwards.</p><h2 data-id="example-implementation">Example implementation</h2><pre class="code codeBlock" spellcheck="false" tabindex="0"><!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Sample Embed</title> <style> body { margin: 0; } #embedVanilla iframe { width: 100%; } </style> <script type="text/javascript" src="js/easyXDM/easyXDM.min.js"></script> <script type="text/javascript" src="js/vanilla.embed.js"></script> </head> <body style="background: #ff6600;"> <div style="height: 50px">foo</div> <div id="embedVanilla"></div> <script type="text/javascript"> // Help older browsers parse JSON. easyXDM.DomHelper.requiresJSON("js/easyXDM/json2.js"); var vanillaEmbed = new Vanilla.embed({ // The element or its ID. container: "embedVanilla", // This is the location of the forum. root: "http://yoursite.local", // initial path, please start it with a "/" initialPath: window.location.hash.substring(1), onReady: function() { // A lot of the functions need to be done after the embed is ready. // This how you set the location of the embedded frame. // vanillaEmbed.setLocation('/categories'); } }); </script> </body> </html> </pre><p><br></p> </article> </main>