Modulo2 Theme: Important Notes

Load whatever content you want with AJAX
The Modulo2 Theme is the most complex theme I ever developed for RapidWeaver. I had some ideas in mind I liked to be implemented in a RW theme. Especially loading content from scratch without a page reload was a thing I ever missed (actually there is a theme JaxPRO which includes this feature). Producing electronic music is a hobby of me and whenever I liked to showcase my work on a page had one disadvantage: when you add an audio player on a page and you navigate to another page, the player will stop and start from the beginning again. There are several solutions to this problem but the nicest one is a web2.0 technology: AJAX.

Automatic Shadowbox
In Modulo2 everything is built around the idea of loading content dynamically into the content container without reloading other page structures (e.g. the menu, background images, …). You not only can load other RW pages into the content, no, you even can load external pages into your content like a wordpress blog or any other remote web content. As this content is fetched and inserted in your page, the styles match perfectly your design.
Of course some content is better loaded in another manner like movies and images. Those media will automatically load in shadowbox – a stylish lightbox clone. You already should have read about shadowbox in this manual, so I won’t describe it here again. I just want to tell you that I implemented automatic shadowbox in the theme. Whenever the fetched content isn’t a standard HTML page with a "content" div, the content is loaded in shadowbox. So, whenever you have a link to a media asset or an external page which hasn’t a content div, those media/pages will automatically be loaded into shadowbox.

Background Images / Slideshow
Adding your own background images was always complicated. Even I ever tried to make this process very easy by providing a special "Image Admin Utility" with my themes, it was not just we excpected from other Mac apps. In Modulo2 adding your own background images is the easiest thing you can do: just drag n’ drop them into the content of your page. That’s all – well "almost". And when you add more than 1 image, a slideshow is automatically created, fading through the bg images.

Floating Box(es)
The Modulo2 Theme includes a special box which is the brain of your site. This box on the left side is called "Control Box" as it controls all vital things of your site. It includes the navigation and sidebar per default but you can add your own content to it. There are several spots you can insert your own content to that box: as a new tab container, below the tab content (so it is always visible) or also at the very bottom, which acts like a toolbar. The control box should hold things that should always be available on each page.
It is also possible to create a second box at the right side of the main content and add special content there.
Those two boxes can be dragged around and stay fix when you scroll the page. The control box also has a switch to automatically hide the box after a while.

Easy Slideshow Creation
There are several ways to create a slideshow to present images or banners. In Modulo2 I implemented a very easy way to create such slides using the cycler plugin for jQuery – no Flash is used. Of course you can define what Transition you like to use (e.g. fade, scroll, zoom, …) and set the transition duration and duration of the slides.

Automatic Accordion
The last thing I want to talk about in this overview section is the automatic accordion effect. Whenever you add a H2 header title to your content this will act as an accordion bar. Clicking on it will show/hide the content immediatly below it.

AJAX is the core feature of the Modulo2 theme. All content is fetched asynchronous without a page reload. All added pages will load into the content container but also any other external content from the same domain which is a HTML page and has a div container with the id of "content". Many pages do have such a container and so those pages are loaded automatically and are inserted in your own page design.

I want to make the process of Content Fetching very clear and if you don’t understand everything, just ignore it.
If you want to load a special page into the content of your page, you have to make sure, this page has a container with an id of "content". Only content inside of this container will be inserted into your page. So, if you like to insert external content to your page and you do have access to the source of the page, you can wrap it into such a container. Here is an example how to do it:

1. Open the external page you like to include in a simple text editor
2. Search for the main content you like to fetch
3. Wrap this content in a div container with the id of "content:

<div id="content">
Content To Be Fetched
</div>
4. Save the page

All other pages (and other media) will not be inserted in the theme content but will be loaded automatically into shadowbox.

As all content is loaded into the page’s main content container without a page reload, it is best to think about it some more.
Actually you are always on 1 page only (the first page that is loaded in the browser). You will never leave this page. Even it will look to you that you browser your site you don’t. Have a look at the address bar and you will see it: the address will never change. Only loaded parts will be added to the URL after a dash (#). This helps in bookmarking/browsing your site but has no other meaning. You are on 1 page as long as you stay at your site.
This means you should spend more time on building this first page in your project. You will add your background images here and also other content you like to add to the boxes. Also all styles are set here and setting other styles on other pages will have no effect. So, this first site is a kind of "Master Page" where you will define everything, the layout, the design, colors and add the core features here.
This will first sound like it’s a little bit difficult and has some disadvantages but you soon will find it is a very cool thing. You don’t have to care about other pages design and you only have to define your fundamental things once. This will also help making your page as consistent as possible.

Adding your own background images is probably one of the first thing you will do. Of course there is absolutly no need to use background images but it is too cool to miss.
The background images are always automatically resized to match the window width so make sure you are using high quality images in a good resolution for the background images (a width about 1600px should be enough). It is not necessary that all images have the same dimensions and they can be in any format you like (JPG, GIF or PNG) but I think JPG is the best as you can bring down the file size.
To add a background image just create a HTML div container with an id of "background" and add your image by drag n’ drop from the Finder to this div:

<div id="background">YOUR_IMAGE</div>

If you add more than 1 image to this container a slideshow automatically is created, cycling through the images with a fading effect. Just make sure you don’t have any line break between the images. Else there will be "black" backgrounds between the sliding images.

If you don’t like the background images be automatically resized, just add the class "noresize" to the background div:

<div id="background" class="noresize">IMAGE(S) HERE</div>

Adding an Accordion effect is a nice addition to this dynamic theme. I assume you know what an "Accordion" is. If not, just try it out!
You can create an accordion by just adding a H2 header title to your content. The next container will then be hidden/shown whenever you click on the title. Here is an example code fragment:

<h2>Accordion Title 1</h2>
<p>This content will be hidden/shown whenever you click on the title above</p>
<h2>Accordion Title 2</h2>
<div><p>You can add more things in the Accordion content when you wrap it in a div</p>
<p>So this content will also be hidden</p>
</div>

Sometimes it is nice to define what content should be visible on page load. To do so, just add a class of "showOnInit" to the "visible" container:

<h2 class="showOnInit">Accordion Title 1</h2>
<p>This content will be hidden/shown whenever you click on the title above and will be expanded/visible when the page loads</p>
<h2>Accordion Title 2</h2>
<div><p>You can add more things in the Accordion content when you wrap it in a div</p>
<p>This content will be hidden when the page loads as the h2 header doesn’t have a class of "showOnInit"</p>
</div>

With some simple code you can add a rotating banner or nice slideshows to your pages. All you have to do is wrapping the images (or other containers) in a div with a class of "slides":

<div class="slides">YOUR_IMAGES_HERE</div>

If you want to use other content than images, just wrap the different part in their own div:

<div class="slides">
<div>CONTENT_SLIDE_1</div>
<div>CONTENT_SLIDE_2</div>
<div>CONTENT_SLIDE_3</div>
</div>

There are several options you can set by defining the corresponding variables using Javascript in a script block just below the slides div:

<script type="text/javascript">
var slideDur=1000;
var slideWait=8000;
var slideFX=’scrollLeft’;
</script>

Here is an explanation:
slidesDur: The transition duration between each slide (in ms)
slidesWait: How long each slide will be shown (in ms)
slidesFX: The transition effect you want to use.

Here is a list of effects you can use:
blindX
blindY
blindZ
cover
curtainX
curtainY
fade
fadeZoom
growX
growY
scrollUp
scrollDown
scrollLeft
scrollRight
scrollHorz
scrollVert
shuffle
slideX
slideY
toss
turnUp
turnDown
turnLeft
turnRight
uncover
wipe
zoom

Modulo2 let’s you add your own content to the control box at the left of the main content. There are three parts where you can insert content:

a) as a new tab container you can switch between all content (implemented like the navigation or the sidebar content)
b) below the tab containers. Content added here will always stay visible
c) at the very bottom of the box. Best suited for options (like the "autohide" checkbox)

To insert content as a new tab container, you have to wrap your content in special HTML divs:

<div class="cbox">
<div class="cboxTitle">TAB_TEXT</div>
<div class="cboxContent">MAIN_CONTENT</div>
</div>

The text in the "cboxTitle" div will be used for naming the tab. The tab content (container below) is inserted in the div with the class "cboxContent".

To insert content below the tab containers, use the example code below:

<div class="cboxbottom">
<div id="UNIQUE_ID">YOUR_CONTENT_HERE</div>
</div>

Be sure to use a unique id when you add more than 1 such box.

To insert content to the very bottom of the control box, use the example code below:

<div class="tbar">
<div id="UNIQUE_ID">YOUR_CONTENT_HERE</div>
</div>

If such code is new to you just go ahead and try it out. It is very simple, even it may look a little bit confusing to you first. Just copy/paste this code and see what happens.

It is also a good idea to mark any HTML code (like the code above) and select "Ignore Formatting" and to be sure "HTML->None" from the "Format menu in RW.

Per default, the tab for the navigation is named "Pages". If you like to change this, just add the following code to the javascript field in the page inspector:

var navbarTitle=’Tab Title’;

So, if you like to rename it to "Navigation":

var navbarTitle=’Navigation’;

You can also create an additional box like the control box at the right side of the main content. To create such a box, all you have to do is writing some code which is very similar to the control box code:

<div class="box">
<div class="boxTitle">TAB_TEXT</div>
<div class="boxContent">MAIN_CONTENT</div>
</div>

Note that due to the limited size of iDevices, the right box will be hidden on a iPhone/iPad/iPod.

The Modulo2 Theme comes with several Snippets which help you adding the needed code, so I recommend you install them in RW. In the Snippets folder there are five snippets (suffix "rwsnippet"). Double click them to install them in RapidWeaver.
Once installed you can access the snippets by bringing up the snippets window by pressing "Command-5" or by going into the "View" menu.
At the top of the Snippets Window you will find a "Search" field. Type in "Modulo2" and only the Modulo2 Snippets are listed.
To use the snippets, just drag n’ drop them into the content part of your page and make the needed adjustments.

You can adjust many colors in the theme in the style variations but the Boxes are different as they use jQuery UI themes. There are some themes already included for many design possibilities but maybe you further like to change it. With the jQuery UI Theme Roller this is an easy task:

1) Go to the jQuery UI Theme Roller site:

http://jqueryui.com/themeroller/

2) Adjust the design to your needs on that site and click on the "Download Theme" button

3) Once downloaded and expanded you will have a folder with a css folder in it. Inside of the CSS folder you will have a folder with the name of your theme. Add this folder to the page assets in RW

4) In the Header tab in the page inspector, add the following example code:

<link rel="stylesheet" type="text/css" href="assets/sunny/jquery-ui-1.8.2.custom.css" />

In the example above I simply downloaded the pre-existing "sunny" theme. You may need to adjust the folder/file name here according to the added theme.

Now the boxes should use your new design.

As the Modulo2 Theme is very dynamic I could not test everything. It is possible that some pages you link to simply don’t work – they should work in most cases, but I can’t guarantee it. Also some 3rd party plugins for RW may not work. One of those non-working plugins seem to be the "RapidCart" plugin. So, what can you do if a page or plugin doesn’t work? One solution of problematic pages is by loading them into shadowbox than into the content. This can easily be done by adding a "rel" attribute to the link. More on this can be found in the Shadowbox section of this manual.

If you don’t like to load those pages in shadowbox (or you can’t as they are linked from the main menu), there are two other options to make incompatible page types and plugins work with Modulo2. They are described in the next sections.

You have seen above that some plugins don’t work well with the Modulo2 theme. That’s because they need some javascripts in the page header which isn’t evaluated when loading the page in Modulo2. But there is a way to make many plugins work by just loading them in an iFrame. Of course setting up the iFrame is easy in Modulo2. I managed that you only have to add one line of code to the problematic page:

<div id="loadiFrame" />

You can add this line wherever you want. The easiest place to add is the main content. But some page types don’t give you a content pane to add your text. Some plugins use a header/footer field. If you don’t find any way to insert the code on the page you can also insert it in the sidebar.
Whenever such a page is loaded an iFrame is automatically created and resized to fill the needed height without scrollbars appearing. Calculating the size can only be made after the content is loaded and so you will probably note a small timeout before the height is adjusted.

Of course it doesn’t look nice when a full page is loaded inside your content. So you really should set a page specific theme for the "iframed" page where you can disable the navigation and other useless stuff. I have created a free theme for this purpose (CAEmpty.rwtheme) which is included in the download package of the modulo2 theme. The Empty theme can also be freely downloaded from here:

http://www.rapid-ideas.com/free/index.html

In the style variations in the page inspector you will find an option to set the AJAX Loading to On or Off. Per default all content is fetched via AJAX and is inserted in the content of your page. This is the main idea of the theme. But some users have some problems with this as it doesn’t work like any other theme for RapidWeaver. So, if you just want to use the design but don’t like the AJAX feature you can disable it by setting the AJAX Mode to "Off". Note that many features won’t work when AJAX mode is off. You can’t dynamically load other pages in your content and you will have a page reload when browsing which also means that some modules (e.g. AudioPlayer) won’t work nice.
But the option is there, just in case you need it.
Note that you will have to set this option similar on all pages, else it may be confusing. So, decide first if you want to disable AJAX loading. If you do, set the option to OFF on every page you create.

Sometimes Page Templates are using exported files like the contact form uses a phpmailer file which is exported into a "files" directory. As with AJAX everything works a little bit different exported files won’t be at the proper location. One way to try fixing it is by setting the page’s folder and file name in the page inspector, so the page is at the root level of your site. To do this, just add a slash ("/") in the folder name field and any name in the file name field. This will force the files to be exported into the root level assets folder.
So, if you receive the message that some files can’t be found (e.g. via the "Activity" window in Safari under -> Window -> Activity, try to use this option.

There is still a much more simpler fix for this: load the page in an iFrame. That way, there is no need for a special page structure. I recommend this option as it is easier and works without much fumbling.