Embedding a Juvia comments page

Introduction

In Juvia, comments are contained in two hierarchical layers. Comments are contained within topics. Topics are are contained within sites. A site is owned by exactly one user who can administer everything within it. This is similar to how many web forums works.

Sites must be registered (created) manually, but topics are automatically created upon posting a comment to a particular topic.

Embedding a Juvia comments page only involves embedding some JavaScript code. Embedding happens entirely in the browser: the page in which Juvia comments are embedded does not require any server-side modifications. Juvia uses various cross-domain request techniques in order to pull this off.

Juvia does not use any iframes. The HTML for displaying the comments and the form is directly embedded inside the page. In order to work well with AJAX web pages, Juvia never reloads the current page, nor does it ever redirect to another page.

<script type="text/javascript" class="juvia"> (function() { var options = { container : '(a CSS path)', site_key : '(some site key)', topic_key : location.pathname, topic_url : location.href, topic_title : document.title || location.href, include_base : !window.Juvia, include_css : !window.Juvia, comment_order: 'latest-first' }; function makeQueryString(options) { var key, params = []; for (key in options) { params.push( encodeURIComponent(key) + '=' + encodeURIComponent(options[key])); } return params.join('&'); } function makeApiUrl(options) { // Makes sure that each call generates a unique URL, otherwise // the browser may not actually perform the request. if (!('_juviaRequestCounter' in window)) { window._juviaRequestCounter = 0; } var result = 'https://comments.musical-artifacts.com/api/show_topic.js' + '?_c=' + window._juviaRequestCounter + '&' + makeQueryString(options); window._juviaRequestCounter++; return result; } var s = document.createElement('script'); s.async = true; s.type = 'text/javascript'; s.className = 'juvia'; s.src = makeApiUrl(options); (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(s); })(); </script>

The beginning of the JavaScript is where the options are. Some of them must be set before the JavaScript works properly.

• The container path. This is a CSS path referring to the DOM element in which you want to embed the Juvia comments page, for example #comments or .main .comment-container > div.
• The site_key. This is a unique identifier for a site, which was automatically generated by Juvia upon registering one.

• The topic_key. This is a unique identifier within the context of a site (it is allowed for another topic within another site to have the same topic key). Unlike the site key, the topic key is not pre-generated: you can pick one yourself, but it must not be longer than 255 characters.

  When a comment is posted it is automatically stored within the topic that is referred to by the given site key and the topic key. If there is no topic with such a topic key within the site, then the topic is created.

  The site key and the topic key are merely identifiers necessary for Juvia to work. They are never shown to the visitor.

• The topic_url (optional) is a permalink URL to the page that contains the comments. If a new topic needs to be created, then it will be associated with this URL. Otherwise, the value of topic_url is unused.
• The topic_title specifies a title for topic_url. If a new topic needs to be created, then it will be given this title. Otherwise, the value of topic_title is unused.
• include_base (optional, boolean, default: true) specifies whether the base Juvia runtime JavaScript code should be loaded. Useful for saving bandwidth if it has already been loaded before. See AJAX support for more information.
• include_css (optional, boolean, default: true) specifies whether the Juvia CSS should be loaded. Useful for saving bandwidth if it has already been loaded before. See AJAX support for more information.
• comment_order (optional, 'latest-first' or 'earliest-first', default: 'latest-first') specifies whether the comments should be displayed with the latest post at the top, or with the earliest post at the top instead. Latest-first is Juvia's default sort order.

Cross-domain requests

Fetching from and posting to on other domains is usually forbidden by the browser's same origin policy. Newer browsers support a mechanism called Cross-Origin Resource Sharing (CORS) which allows browsers to perform AJAX calls to other domains, and Juvia uses this whenever possible.

On older browsers that don't support CORS, Juvia falls back to a JSONP-like technique that involves injecting script tags to perform cross-domain requests. Request parameters are embedded in the tag's URL. However, because browsers impose a limit on the maximum size of URLs, only a limited amount of data can be posted. The lowest common denominator seems to be Internet Explorer which imposes a limit of 2083 characters. This means that on non-CORS capable browsers, the user will be unable to post large comments. In order to reduce the impact of this problem, Juvia compresses the comment text with zlib.

AJAX support

Juvia has full support for AJAX web pages, i.e. web pages that are dynamically updated without reloading the page itself or redirecting to another page. Simply execute the Juvia embedding code again (with possibly different options) and everything will work as expected. It is even possible to embed multiple Juvia comment pages on a single web page.

However the second time you load a Juvia comment page may result in some things to be redundantly loaded again. To see what's redundant, let's consider what a Juvia comment page consists of:

1. The base Juvia runtime code in JavaScript.
2. The Juvia CSS.
3. The actual comments.

Items 1 and 2 are already loaded the first time you load a Juvia comment page. You can omit them by setting the include_base and include_css options to false.

Embedding multiple comment pages on a single web page

It is possible to embed multiple Juvia comment pages on a single web page. Just specify different container paths for each of them. And just as described in AJAX support, the base runtime code and the CSS are redundantly loaded the second time, so you can omit them by settings include_base and include_css to false.