Home
Facts
Guides
Example
Forum
Help
This page provides some basic guides to get to know Building Block and to set it up for common applications. It targets entry level users with a good knowledge of HTML.
To start using Building Block, you should first set up a basic website. Then think about it - where does dynamic content fit in? Next you have to check the technical prequisites. We go through this in detail:
Buidling Block is not a system to start fom scratch with. So, first put all your thoughts about dynamic content and CMSs aside and create a static, plain HTML website. To start out, even one single page will do. Use headings, a navigation, and create stubs for content, news items, blog entries or whatever you feel like.
If you do not know how to write web pages, you have to learn it before you can use Building Block. Search the web for tutorials or grab a good book on HTML. You can start out with "Getting started with HTML":
http://www.w3.org/MarkUp/Guide/
If you are familiar to HTML, you can download and customize a design from Open Source Web Design to speed things up:
A side effect of this step ist that you get back into HTML editing and train to think about your site from a HTML source point of view.
So now you want to use a CMS. But what for? Think about it: Which part of your page does consist of items that change frequently?
You may find that parts of your pages do not change often enough to justify to put them under CMS control. This might be a project description, an employee list, a biography or just the title image.
Other parts within the page may require regular updates. Typically these are news items or blog entries. This is where Building Block comes in: it cares for the dynamic parts of your otherwise static pages. What you are going to do is to remove the stubs for these and put in a Building Block Display for dynamic content instead.
Before that you have to check some technical prequisites and to set up Building Block.
Make sure you have a web server account which allows you to run your own Perl CGI scripts. If unsure, ask your provider. Note that a "webspace account" is normally not sufficient.
In particular, your web account must have a directory called "/cgi-bin/". If it is not there, do not create it. Contact your provider.
If not already done so, you should also keep a HTML editor software at hand. This does not have to be anything fancy, but Building Block requires you to write and edit some HTML pages where you can embedd the projects.
Now continue with the next topic "How do I set it up and use it?".
Download the latest version of Building Block from the 
users page. It comes as a zip-compressed archive.
Unzip the archive. You'll get several folders; move to the folder "serverroot". You have to upload everything in there into the root folder of your webserver account. So, start the FTP tool of your choice, connect to your webserver and first upload all the PNG images to the root directory (it is often called "html"). Next, move to the subfolder "cgi-bin" from the zip file. Upload the file buildingblock.cgi to the cgi-bin directory of your web server.
Since buildingblock.cgi is a program, it needs so-called execution permissions on the server. You FTP tool provides tools to check the permissions of a file, either via display or the "ls -l" command. Make sure that anyonce can execute the file buildingblock.cgi. Look for a display line as "-rwxr-xr-x". If unsure, refer to the help facility of your FTP tool.
Now, open a browser and point it to
http://your.server.here/cgi-bin/buildingblock.cgi
This should give you a dialog saying "Set Master Password". You need the master password each time you want to create a new project. So choose a good password (letters and numbers mixed), enter it twice and confirm.
A new page with two forms opens: "Login" and "Create New Project". This is the standard login page for the Building Block administrator interface.
You will need a Building Block project for each set of dynamic items on your pages. To start out, pick a simple set, such as a news ticker. Create the according project now: enter a name, a good password, your name and your email address. These are required for alert messages; Building Block will never display this information in public. Confirm with the master password set in the previous step and hit "Create New Project".
You are now logged in into the administrator interface. This is the backend of Building Block where you can tweak all settings to taste. We'll take a quick tour and make important settings as we pass. Note that there are paragraphs within the interface which explain each section.
First have a look at the head of the page. There is a box telling the current version of Building Block, the current project and giving a status message. The status field is very important; take a look at it after every action in the administrator interface. There is also the possibility to log in into a different project.
The Administrator section holds contact information of the project administrator, in this case you. The data you entered when creating the project should display here.
To update information, change the field contents, confirm with the project password and hit "Update". Note that you must update each section seperately.
The Editors section holds a list of people who may edit the project and possibly receive notification email. You can add or delete editors here. If there is only you working on the project, then the default editor "Guest" is just fine.
The Homepage section holds the address of the web page where you want to be redirected to after changing something. If you are working on your start page, enter it's URI here. Most probably this is going to be
http://your.server.here/index.shtml
We skip the next sections, Backups and Maximum characters. Have a look at them later.
The HTML section is very important. If you enter tags in projects, such as <p>, <img>, <a ...>, then Building Block per default rejects the submission. This serves as a protection from spam and cross site scripting attacks. If you want to use HTML tags, you have to unlock them using the two whitelists provided here. The first list is for tags which do not need attribures (p, br, h1, ...). The second is for tags requiring attributes (a, img). You can also disable rejection. Tags which are not in whitelists will display verbatim in angle backets then.
In the Transformations section you set how project entries should be displayed. An entry consists of a heading, responsible editors, a modification date and the content. Each part can be wrapped into customized HTML, and this can be set here. You do not have to change that now; have a look at it and customize it later on. Note, you can not set whether or not you want to see a modification date or latest editor here; this is done in the display setting.
In the final Displays section you create "views" of the project which you can embed in your up to now static pages. First give a name, say "public". Leave "Number of entries" blank to display all entries. Leave all "Show ..." fields checked. To see what you can do with entries, check all "Viewers may ..." fields and set "Viewers may add entries: at the bottom". Leave all other fields just as they are and confirm with the project password.
Now you see two additional boxes above your just-created display. The first one is a direct link to the display on it's own. The second one is important: it holds the code to include this display in your HTML page.
Now open the HTML page in question in your HTML editor and locate the stub set of items you want to put under Building Block control. Ideally it is enclosed in a table cell or a div tag. Now delete the complete stub and insert the code from the "Code to include in .shtml file" field. Save the file using the extension ".shtml" and upload it to your server.
To add new entries, you use the according form which now appears on your web page.
To edit, move or delete entries, you use the according buttons below the entry on the web page.
To change the display properties, you log into the administrator interface, check or uncheck boxes for your display, and confirm with the password. The changes take effect immediately, just reload the .shtml page in question.
To change the look or HTML around entries, you log into the administrator interface and edit the "Transformations" section. This should be pretty straightforward, just try a little.
You may not want everyone to be able to add or change entries. In this case, uncheck all "Viewers may ..." fields in the "Display" section and create a second display where adding and changing is allowed, probably protected by a password. You can access this display right away through the link provided and save a bookmark.
Alright, here are some short instructions for popular dynamic content. However, please note that to use the full power of Building Block, you have to learn about it's concept and interfaces. If you are looking for a quick and easy out-of-the-box solution with no backend tweaking, then Building Block may not be the tool for you.
The following assumes that you have read, understood and completed the instructions from the previous sections.
A blog is essentially a guestbook for one user. The form to add entries is kept secret and not available to the public.
A newsticker is some kind of mini-blog. The setup is the same as with the blog, but we are going to limit the number of items displayed now.
The handling of a forum is a bit different compared to the other applications. A forum consists of two elements: a posting/thread list with a form to add a post below, and the actual postings and threads. Each thread gets an own Building Block project, which is automatically created. What we are going to do is set up the thread list with an add-form and enable the automated creation of new projects.
It is recommended that you try out Building Block with some simpler applications (see above) to find out how it works.
Software, Webdesign and Contents © Ingenieurbüro Florian Berger, Leipzig, Germany
Kontakt: info@buildingblockcms.org