Embedding Higher Logic Vanilla (Vanilla) 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.
Embedding checklist
- Choose the embed friendly theme. This theme has minimal padding around it and will look good at any width. (Make modifications in Customize theme.)
- Ensure you have Enabled Embedding in your dashboard.
- Make sure that the page in which you embed is free of JavaScript errors.
- Your embedded forum must have the same base domain name as the hosted site. For example, if you want to embed your forum in mysite.com, create a subdomain (forum.mysite.com) and apply it to the forum. (See Setting up your Custom Domain for more information.)
When embedding a forum, consider these drawbacks:
- 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.
- Issues with SEO, as Google (and other search engines) don’t always do a great job of indexing framed content.
Embedding comments
If you have a blog or news site, you can use Vanilla as a commenting system to more fully engage readers who might otherwise just enter a comment.
- A single profile, reputation, and user experience across the community and the comments
- Engage commenters with Vanilla’s existing gamification and curation features
- Use blog traffic to quickly seed community participation and vice versa
How to implement comments
There is a WordPress plugin 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.
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 Forum > Blog Comments. Use our Universal Code, the code snippet can be modified to create discussion threads in the appropriate forum category based on the blog post category.
What does Vanilla use as an excerpt from my blog article when creating a blog comment discussion?
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.
Readers can log in using a Disqus ID, Twitter, Google, Facebook, or via Single Sign-On.
Advanced embedding
The advanced embedding technique is for developers who require programmatic interaction between the Vanilla iFrame and their parent window. It employs easyXDM and a special container layer to achieve this. It requires a more in-depth setup than Vanilla’s basic embed solution.
Testing embedding locally on Docker
If your local environment is set up with vanilla-docker, local embed setups are very simple to configure.
1. Clone the stub-embed-providers repo next to your vanilla-docker repo, and then do one of the following:
Simple & comments embed
1. Add the following to your configuration.
$Configuration['Garden']['Embed']['Allow'] = true;
2. Navigate to http://embed.vanilla.localhost and test your forum.
3. Navigate to http://comments-embed.vanilla.localhost/ and test your comments embed.
Advanced embed
1. Add the following to your configuration.
$Configuration['Garden']['Embed']['Allow'] = 2;
2. Navigate to http://advanced-embed.vanilla.localhost and test your forum.
Set up advanced embedding
Enable forum embedding via the Dashboard. Then set Garden.Embed.Allow to 2 in your config.
📝 NOTE: Cloud customers will have this done by support staff.
- Include easyXDM:
/js/easyXDM/easyXDM.min.js - Include Vanilla’s advanced embed script:
/js/vanilla.embed.js - Create a div to contain Vanilla and give it an ID.
- Call
Vanilla.embed({options}).
Options
Vanilla.embed() takes an associative array of options.
Required options
root The root URL of your Vanilla forum. Example: http://community.yoursite.com
container The ID or DOM element of the container for Vanilla.
Optional options
initialPath 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: site.com/embedpage#/categories/some-category
sso An SSO string that will automatically sign the user into Vanilla.
autoStart Whether or not to start the embed when embed() is called. If this is false, then you must call embed.start() to start the embed. Default: true
onReady() A callback function to call when the embed is ready.
notifyLocation(path) 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.
height(x) 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 this.iframe.
Methods
start() Start the embed. Only call this method if you set autoStart to false.
setLocation(path) Manually set the location of the embedded iFrame. Just specify the path, not the full domain of the embed.
Custom callbacks
The embed API allows custom JavaScript to be called between the parent and child iFrames.
Exposing a method to Vanilla
You can expose a method to the child iFrame with the following code:
Vanilla.embed.fn.functionName = function(args,...) { … }
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.
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 callRemote() it can then specify a callback and the framework will handle calling the callback across the domain.
Calling a method in Vanilla
You can call a method in Vanilla with the following code:
Vanilla.embed.callRemote("functionName", args [, callback]);
If you supply the callback argument to callRemote() 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 call(), apply(), etc. to set a context for the function will not work as a context cannot be passed across the domain.
Functions you can call on Vanilla
Vanilla.embed.signout() Calling this function will sign the user out of Vanilla. It won’t refresh the page so you may want to do that afterwards.
Example implementation
<!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>