User Handbook

Welcome to The Boxes Paradise!

The Boxes Paradise (TBP) gives you the power to embed any box (aka "rounded corners" or "rounded box") in your website without any extensive programming, html or css knowledge. If you are new to TBP, then this handbook is for you.

The following pages introduce you to the TBP project, how to browse through the box gallery and embed your desired box in your website with ease. It's easy. It's free!

TBP allows Box developers to submit their creations to expand the library, as well as allows normal users to make Box Requests. Thus, the number of Boxes available for you to pick and use will only get more and more!

But let's take a quick look at how easy you can embed a TBP Box in your html code. To view more demo, click here.

 

Output Code Source
A Sample This demo here uses just 5 calls to achieve this boxing effect. In fact, these 5 calls are the same for any Box you use from TBP.
  1. <script type="text/javascript" src="http://theboxes.paradise.sg/
    sites/theboxes.paradise.sg/files/Box/75/
    files/theboxesparadise_75.js"> </script>
  2. <script type="text/javascript"> tbp_75_getHeader(); </script>
  3. <script type="text/javascript"> tbp_75_getStartTitle(); </script>
  4. A Sample
  5. <script type="text/javascript"> tbp_75_getMid(); </script>
  6. This demo here uses just 5 calls to achieve this boxing effect. In fact, these 5 calls are the same for any Box you use from TBP.
  7. <script type="text/javascript"> tbp_75_getEnd(); </script>

Understanding The Boxes Paradise

Introduction

For beginners trying to display a rounded rectangle, or a rounded box, or rounded corners on your website, it often starts with a search on the Internet. In our TBP project site, we shall use "box" to refer to it. TBP aims to give you the extreme ease to integrate any box without any complicated CSS / HTML / Javascript programming. TBP hides all the coding from you.

You just need to know one set of commands TBP offers, and you can tap into the vast library of boxes available here.

 

Example of a Box

Example of a Box
Figure 1 - Example of a box

On the right hand side, we have an example of a box on a web page. The contents are contained within the box, with a title at the top.

Notice that the corners are rounded and there is a shadow at the bottom of the box. This gives the box a 3D feel.

 

Drupal

For Drupal users, if you are using the Panels module, you might notice that there is a Panels Style directory which stores information about building a box around a Panel or a Pane. The majority of the boxes found in the library here comes with a zip file containing the required files to copy to the Panels Style directory. You can thereafter use it to box your Panel or Pane easily. More information about this can be found in the Drupal Solution section of this handbook.

If you are not using the Panels module, you can still use the Html Solution to add or attach a Box to your Drupal Node's content.

Box developers are encouraged to submit a Drupal Panel Style solution together with the normal Html Solution.

 

Box Developer

If you are a Box developer, you can read the Developer's Handbook to learn how to build a box and upload it to TBP Box library. By contributing to this library, you are promoting your personal or corporate expertise.

Demo

The demos here give you an overview of how you can embed the Boxes easily into your existing html code. Best of all, you just need to know one set of small API calls to build any Box found in the TBP library!

How small exactly is the number of API calls? Just 5! And that is the maximum number if you are building a Box with a Title. If you do not need a Title for the box, you can make do with just 4!

Since the TBP Project allows any person to create a Box and add to the library, you can tap into the vast amount of Boxes that will only grow by the day. It's easy. It's free. And you can spend your time on other parts of your website, and put your mind at ease, knowing building a Box is just a-few-minutes task!

 

 

Output Code Source

 

Demo 1 Box is built with a Title.

The css markup for the Title is set by the Box Developer. However, you can overwrite the css style if you wish.
  1. <script type="text/javascript" src="http://theboxes.paradise.sg/
    sites/theboxes.paradise.sg/files/Box/75/files/theboxesparadise_75.js"> </script>
  2. <script type="text/javascript"> tbp_75_getHeader(); </script>
  3. <script type="text/javascript"> tbp_75_getStartTitle(); </script>
  4. Demo 1
  5. <script type="text/javascript"> tbp_75_getMid(); </script>
  6. Box is built with a Title. [more contents]
  7. <script type="text/javascript"> tbp_75_getEnd(); </script>

Demo 2

Box is built without a Title.

This is the simplest rounded Box found in the standard TBP library set.
  1. <script type="text/javascript" src="http://theboxes.paradise.sg/
    sites/theboxes.paradise.sg/files/Box/28/
    files/theboxesparadise_28.js"> </script>
  2. <script type="text/javascript"> tbp_28_getHeader(); </script>
  3. <script type="text/javascript"> tbp_28_getStart(); </script>
  4. <p>Demo 2</p>
  5. <p>Box is built without a Title. [more contents]</p>
  6. <script type="text/javascript"> tbp_28_getEnd(); </script>
Demo 3

Box is built with a Title.

Notice that you have to call an additional getMid() if your Box has a Title.
  1. <script type="text/javascript" src="http://theboxes.paradise.sg/
    sites/theboxes.paradise.sg/files/Box/28/
    files/theboxesparadise_28.js"> </script>
  2. <script type="text/javascript"> tbp_28_getHeader(); </script>
  3. <script type="text/javascript"> tbp_28_getStartTitle(); </script>
  4. Demo 3
  5. <script type="text/javascript"> tbp_28_getMid(); </script>
  6. <p>Box is built with a Title. [more contents]</p>
  7. <script type="text/javascript"> tbp_28_getEnd(); </script>
Demo 4

Box is built with a Title, with pillow emboss effect.

More fanciful Boxes can be found in the TBP library, and the best thing is, you just build the Box with the same simple set of API calls!

Neat.
  1. <script type="text/javascript" src="http://theboxes.paradise.sg/
    sites/theboxes.paradise.sg/files/Box/95/
    files/theboxesparadise_95.js"> </script>
  2. <script type="text/javascript"> tbp_95_getHeader(); </script>
  3. <script type="text/javascript"> tbp_95_getStartTitle(); </script>
  4. Demo 4
  5. <script type="text/javascript"> tbp_95_getMid(); </script>
  6. <p>Box is built with a Title, with pillow emboss effect.</p>
  7. <script type="text/javascript"> tbp_95_getEnd(); </script>

Anatomy of a Box

Anatomy of a Box
Figure 2 - Anatomy of a box

 

3 Regions, 5 Regions

A Box can have either 3 or 5 regions, depending on whether there is a Title. If a Box has a Title, then it has 5 regions. Otherwise, 3 regions (Region 1, 4, 5).

 

1st Region

 This is the beginning of the Box. If the Box has a Title, the code generated for this region will prepare the Box up to the point where the Title is just about to be printed out.

If a Box does not have a Title, the code generated for this region will prepare the Box up to the point where the Contents is just about to be printed out.

 

2nd Region

 No code is needed to produce this part. Instead, the user just types out the Title in normal HTML codes.

 

3rd Region

 This is the middle of the Box. If a Box has a Title, this region must exist to generate the code to close up the Title, and prepare the Box up to the point where the Contents is just about to be printed out.

If a Box does not have a Title, this region is not needed.

 

4th Region

 No code is needed to produce this part. Instead the user just types out the Contents in normal HTML codes.

 

5th Region

 This is the end of the Box. The code generated for this region will close the Box appropriately.

 

 

 

 

 

 

Html Solution

This section is for normal Html users. Drupal users should read a later section - Drupal Solution in this handbook.

 

Simple

The only important thing you need to add to your web page will be a javascript file which belongs to a particular Box. You can then use a standard set of API calls to help build the Box.

Read on further in this section to learn more.

API

Below illustrates all the available calls to help build a Box. The number 3 here refers to a Box ID. Depending on which Box you choose from TBP library, this ID must change to reflect your choice.

 

API

Loads the required javascript file.

<script type="text/javascript"
    src="http://theboxes.paradise.sg/sites/theboxes.paradise.sg/files/Box/3/files/theboxesparadise_3.js">
</script>

 

Loads the required CSS file and additional JS files (if any).

<script type="text/javascript"> tbp_3_getHeader(); </script>

 

Builds the starting region of the box, which has a Title.

<script type="text/javascript"> tbp_3_getStartTitle(); </script>

 

Builds the starting region of the box, which does not have a Title.

<script type="text/javascript"> tbp_3_getStart(); </script>

 

Builds the middle region of the box. Required if the Box has a Title.

<script type="text/javascript"> tbp_3_getMid(); </script>

 

Builds the end region of the box.

<script type="text/javascript"> tbp_3_getEnd(); </script>

A Html file example

Download a sample Html file

To demonstrate the extreme ease of embedding a box in your web site, a sample Html file can be downloaded here. (You need to right-click and choose Save As. Otherwise, the html file will be loaded in your browser immediately.)

There is no need to download any other javascript file, css file, or tool to make this work. You will be just downloading one single file. View the Html file in your favourite web browser to see a box loaded with a title and some contents. You can view the source to see the simplicity.

 

Overview

<html>
<head>
...
<script type="text/javascript"
    src="http://theboxes.paradise.sg/sites/theboxes.paradise.sg/files/Box/3/files/theboxesparadise_3.js">
</script>
<script type="text/javascript"> tbp_3_getHeader(); </script>
...
</head>
<body>
Some text here ...
...
<script type="text/javascript"> tbp_3_getStartTitle(); </script>

Box's title goes here.

<script type="text/javascript"> tbp_3_getMid(); </script>

Your content inside the box goes here.

<script type="text/javascript"> tbp_3_getEnd(); </script>

Some more text here ...
...
</body>
</html>

 

 

Drupal Solution

If you are a normal Html user, you should read the Html Solution instead. This section describes how to use a Box in a Drupal Panels module. If you are a Drupal user who is not using the Panels module, you can still use the Html Solution to add or attach a Box to your Drupal Node's content.

Panel Style
Figure 3 - Panel Style

 

Brief Introduction of Panels

For Drupal users who use the Panels module, you might know a Pane or Panel can be boxed up. Refer to Figure 3 on the right.

This is a screenshot of part of the page when you access a Panel Page > Layout Settings. In a Panel Page, you can create many Panels. And in each Panel, you can create many Panes.

 

Panel Style

By default, Panels assigns a default panel style for all Panels on the Panel Page. You can alternatively assign different panel style for each panel.

When you are editing your content, you are further allowed to assign different panel style for each pane.

Panels by default ships with 3 styles:

  1. Default
  2. Rounded Corners
  3. List

 

How TBP extends Panels

The default 3 styles are not enough for building more customised themes. Moreover, developing your own Box requires time, patience and effort. Some Drupal users might already built some panel styles for your own use. But there are many others who hope to have instant solutions.

The majority of the Boxes found in the TBP library has a zip file which contains a Drupal solution. More detailed information on how to integrate a Box in Drupal can be found in the later part of this handbook. Thus, all you need to do is to browse through the library of boxes here at TBP, download the zip file, and unpack the contents to add on to the existing panel styles.

After you have added a TBP Box in your Drupal site, you will be able to use this Box as an option to box up any panel or pane.

Because TBP aims to build a big library of boxes, Drupal users can tap into this vast library. Box Developers are encouraged to include a Drupal solution as well when they submit their Box.

 

Panels 3

For Boxes with Box ID up to 122, TBP has included both Panels 2 (P2) and Panels 3 (P3) versions. When the TBP Library was first setup, there isn't any P3. Thus, the Boxes are all written for P2 users. Now that the Panels developers have ceased development on P2, and are focusing only on P3, TBP has upgraded existing P2 Boxes to P3, and will put up only P3 compatible Boxes in future.

P2 users can continue to search for P2 compatible Boxes in the library. If you are using the Search function, you can check the P2 or P3 checkbox to filter your search results. If you are looking at a Box's details, a P2 compatible Box will have the Panels 2 tag.

If there is a heavy request on a P3 Box to be available in P2, TBP will provide a P2 version on a case-by-case basis.

How to install a Box in Panels?

This section of the User Handbook has 2 subsections

  1. What you need
  2. Steps

In each of these sections, the contents employs the use TBP's set of Box commands described earlier in Html Solution to box each logical block of text up. If you view the html source of the above mentioned sections, you will be able to find such a statement in it:

<script type="text/javascript"> tbp_3_getStart(); </script>

What you need

A Box's zip file

This is the zip file which you download from the TBP Box library. The majority of the Boxes found in the library has a Drupal solution. Box developers are encouraged to provide this solution on top of the Html Solution.

FTP username and password

Depending on where you installed your Drupal, whether you need a FTP username and password varies. If you have installed in your local machine, then you will not need them.

If you have installed Drupal on a webhosting space, it is most likely you have been given a FTP username and password to gain access to your public_html directory. Also, if you have installed additional modules in Drupal before, you would have prior knowledge how to FTP in.

Panels module for Drupal (optional)

The Drupal solution here teaches you how to install the Box in the Panels module, so that you can select the Box as one of the Panel Style to box up your Panel or Pane.

Nevertheless, this is optional. If you are not using the Panels module, you can still use the Html Solution to add or attach a Box to your Drupal Node's content, in which case, you do not need to upload any file to the Drupal installation folder.

 

Steps

Zip file Directory Structure
Figure 3 - Zip file Directory Structure

Unpack the Box's zip file.

 

The contents should have the following directory structure as shown in Figure 3.

html contains all the necessary files to build the javascript file
res contains all the necessary files to build the box (image files, and extra javascript files)
file_v2.inc a Drupal Panel 2 file containing code to build the box

Note: some Boxes might not have a Panels 2 version inc file
file_v3.inc a Drupal Panel 3 file containing code to build the box
file.js a javscript file to include in your Html page


Panels module Directory Structue
Figure 4 - Panels module Directory Structure

Upload files to Panels module


Only the res folder and the theboxesparadise_x.inc file need to be uploaded to Panels module's styles directory.

 

More Information

  • Figure 4 shows the directory structure of the Drupal Panels module. Only the relevant directories are shown to present the information clearly. As illustrated, there is a styles directory which we are interested in.
     
  • This is the directory which stores the styles which Panels use to box up each Panel or Pane. By default, there are 4 INC files provided by Panels itself. The sub-directory corners contains image resources for the rounded_corners.inc.
     
  • Since each Box's resources are stored in the res directory, you might have a lot of image files and css files mixed up altogether in it when you install mutiple boxes. This could get very messy. To deal with this, TBP recommends that each Box must store its resources not in res, but in res/box_id. Thus, with multiple Boxes, you will see just one res directory within the styles directory, and since each Box has an unique id, resources are well-organised within res.
     
  • For Panels 3, the styles directory is now inside the plugins directory.
     
  • IMPORTANT: Depending on the Panels version you are using, you should use the correct inc file and rename the file by removing either _v2 or _v3 from the filename.

Refresh Drupal Cache


This step is to ensure Panels recognise the files there. To clear the theme registry, do one of the following things:

  1. On the "Administer > Site configuration > Performance" page, click on the "Clear cached data" button. (recommended)
  2. With devel block enabled (comes with devel module), click the "Empty cache" link.
  3. The API function drupal_rebuild_theme_registry.

If you need help

You can

  1. read the FAQ in the next section of this handbook, or
  2. create Help posts here, or
  3. visit the menu link at My Menu > Create Content > Post. More information can also be found here, or
  4. Do a search on this site before submitting your enquiry. It may be the case that your enquiry has been asked and resolved. The quick search is located at the top right of the TBP site.

FAQ

I still cannot see the Box after calling the APIs.

Is the Box's resources copyrighted?

Are the Box's resources copyrighted?

Yes.

The resources (images, javascript files and such) used by the Box belong to the intellectual property of the respective Box Developer. Proper attribution must be displayed on your site. A link to his website or TBP website is recommended. An exception will be that the developer charges a fee for your usage of his Box in your website, in which case, you are allowed to remove the attribution.

Under normal situations where you use the Html Solution, you will not be downloading any resources into your machine. Thus, there is no copyright issue to deal with. However, if your site is a commercial, or profit-based, you have to read the Box's description to find out if the Developer has a policy of charging a nominal fee, even if you do not download any resources into your machine.

For Drupal users who want to use the Box for the Panel styles, TBP by default grants permission for anyone to download the Box's zipped file, which contains the relevant resources to build the Box, and to only use it on sites which are non-commercial based. Commercial or profit-based sites have to read the Box's description to find out if the Developer has a policy of charging a nominal fee.

I still cannot see the Box after calling the APIs.

Read through the instructions at the following pages: API, and A Html file example. Ensure that you have typed the API calls correctly, and you have placed them in the right places.

The javascript file can be loaded at any part of your html code, as long as it is before any other TBP Box API call. tbp_boxID_getHeader() must be right after the javascript file, and should only be called just once.

Thereafter, you can call the rest of the APIs in the appropriate parts of your html to build the Box.

Ensure also that Box ID matches your desired Box. The Box ID is part of the API calls.