ExtraContent for developers


The strength of ExtraContent for both the theme developers and end users is the common experience in its use and application. For this reason we thought long and hard to come up with an appropriate naming convention and common application to help ensure that end users who have experience with one instance of ExtraContent will be familiar with another. This also allows for shared resources between RapidWeaver developers, such as snippets, stacks, tutorials, manuals, etc...

ExtraContent operates on a very simple principle; the end user applies a simple snippet (or stack) that wraps or envelops the users content that they want applied elsewhere in the layout (as determined by the theme developer). The ExtraContent script detects that snippet then renders its contents in a predetermined location.

User Implementation

This is the critical component that shouldn't vary from theme to theme. All users should be able to apply a simple snippet with, at a minimum, the following component; a single div with the id of myExtraContentX where X is a base integer that will correlate to a reciprocating component in the theme. The standard, base snippet is as follows:

<div id="myExtraContent1">
<!-- User content goes here -->
</div>
Expanding on the base snippet, you will learn quickly that just about anything can be contained within the tag.

All ExtraContent areas should, where possible, operate from top down. Meaning that if an ExtraContent area is to be rendered in the header and another in the footer, it would be advisable (but not a deal breaker) if #myExtraContent1 would correlate with the header while #myExtraContent2 would correlate with the footer. Where there are exceptions, for instance if a developer adds additional ExtraContent features at a later date, then the developer should be mindful that such additions are not overly disruptive and are documented. This would be purely for the end users benefit and consideration. THESE ARE ONLY GUIDELINES.

Developer Implementation

Developer implementation of ExtraContent is fairly straight forward. Simple apply the reciprocal div tag anywhere in your layout that you wish the ExtraContent to appear. The reciprocal div tag has the id of "extraContainerX" where X is a base 10 integer. It will look like this:

<div id="extraContainer1">
<!-- ExtraContent gets rendered here -->
</div>

Now you will need to decide which version of ExtraContent to use. This will depend on current the needs of your theme and whether you are already utilising the jQuery library as many themes do. If you are using jQuery in your theme then you can use the jQuery assisted version of ExtraContent. If not then it's likely faster to use the vanilla javascript version. Both are documented below.

You may wish to apply separate styling to affect the appearance of the content that appears in your ExtraContent areas. This can be done many ways, none of which are right or wrong. Here are three examples;

You can apply CSS rules to the end user "myExtraContentX" selectors like so:

#myExtraContent1 { color: red; padding: 10xp; }
#myExtraContent2 { color: green; margin-top: 1em; }

You can apply CSS rules to the themes "extraContainerX" selectors like so:

#extraContainer1 { color: red; padding: 10xp; }
#extraContainer2 { color: green; margin-top: 1em; }

You can have the user content inherit CSS rules from enclosing elements like so:

.header { color: red; padding: 10px; } /* .header contains #extraContainer1 */
#footer { color: green; margin-top: 1em; } /* #footer contains #extraContainer2 */

While all will have the same effect, it's my personal preference to go with the latter for reasons of flexibility. The choice is ultimately yours.

Vanilla Javascript Variant

Ideal to use in RapidWeaver themes that don't include a Javascript library like jQuery. The "vanilla Javascript" variant has no dependency on any third-party Javascript libraries or frameworks. This makes it good to use in specialist or lightweight RapidWeaver themes:

/* DomReady: http://code.google.com/p/domready/ */
(function() { var DomReady = window.DomReady = {}; var userAgent = navigator.userAgent.toLowerCase(); var browser = { version: (userAgent.match(/.+(?:rv|it|ra|ie)[\/: ]([\d.]+)/) || [])[1], safari: /webkit/.test(userAgent), opera: /opera/.test(userAgent), msie: (/msie/.test(userAgent)) && (!/opera/.test(userAgent)), mozilla: (/mozilla/.test(userAgent)) && (!/(compatible|webkit)/.test(userAgent)) }; var readyBound = false; var isReady = false; var readyList = []; function domReady() { if (!isReady) { isReady = true; if (readyList) { for (var fn = 0; fn < readyList.length; fn++) { readyList[fn].call(window, []); } readyList = []; } } }; function addLoadEvent(func) { var oldonload = window.onload; if (typeof window.onload != 'function') { window.onload = func; } else { window.onload = function() { if (oldonload) { oldonload(); } func(); } } }; function bindReady() { if (readyBound) { return; } readyBound = true; if (document.addEventListener && !browser.opera) { document.addEventListener("DOMContentLoaded", domReady, false); } if (browser.msie && window == top)(function() { if (isReady) return; try { document.documentElement.doScroll("left"); } catch(error) { setTimeout(arguments.callee, 0); return; } domReady(); })(); if (browser.opera) { document.addEventListener("DOMContentLoaded", function() { if (isReady) return; for (var i = 0; i < document.styleSheets.length; i++) if (document.styleSheets[i].disabled) { setTimeout(arguments.callee, 0); return; } domReady(); }, false); } if (browser.safari) { var numStyles; (function() { if (isReady) return; if (document.readyState != "loaded" && document.readyState != "complete") { setTimeout(arguments.callee, 0); return; } if (numStyles === undefined) { var links = document.getElementsByTagName("link"); for (var i = 0; i < links.length; i++) { if (links[i].getAttribute('rel') == 'stylesheet') { numStyles++; } } var styles = document.getElementsByTagName("style"); numStyles += styles.length; } if (document.styleSheets.length != numStyles) { setTimeout(arguments.callee, 0); return; } domReady(); })(); } addLoadEvent(domReady); }; DomReady.ready = function(fn, args) { bindReady(); if (isReady) { fn.call(window, []); } else { readyList.push(function() { return fn.call(window, []); }); } }; bindReady(); })();

/* ExtraContent */
DomReady.ready(function() {
var extraContent = (function() {
// change ecValue to suit your theme
var ecValue = 10;
for (var i=1;i<=ecValue;i++)
{
if(document.getElementById("myExtraContent" +i))
{
var ecContent = document.getElementById("myExtraContent" +i);
var ecContainer = document.getElementById("extraContainer" +i);
var scripts = document.getElementsByTagName("script");
var thisScript = scripts[scripts.length - 1];
if (thisScript.parentNode == ecContent) {
thisScript.parentNode.removeChild(thisScript);
};
ecContainer.appendChild(ecContent);
}
}
return ecValue;
})();
});


jQuery Javascript Variant

Most newer RapidWeaver themes include jQuery to empower things like mobile toggle navigation menus. So it probably makes sense to use the jQuery variant in themes that already use jQuery:

jQuery.noConflict();
jQuery(document).ready(function($){
var extraContent = (function() {
// change ecValue to suit your theme
var ecValue = 10;
for (i=1;i<=ecValue;i++)
{
$('#myExtraContent'+i+' script').remove();
$('#myExtraContent'+i).appendTo('#extraContainer'+i);
}
})();
});

The above code will only perform ExtraContent on the first 10 containers. This limit can be raised or lowered accordingly. It can help with performance.
19/05/2023
Web design by Will Woodgate