Last time our application was able to create forums, but in a VERY uncontrolled way.

.hac Helma Actions
To control the creation of new forums the user should be able to hit a link or button, which says "add a forum". This link will call a function on the server, which is adding a new forum and redirects back to the main page of our application.

.hac files are functions(), which can be called via an URL.

That means our "add a new forum" function will be a .hac file, which we can call via a link on the start page. So lets create a new .hac file, which we will call "addforum.hac" in the root directory.

apps/forum/root/addforum.hac
var aNewForum = new forum();
this.add(aNewForum);
res.redirect(root.href("main"));


and clean up the code in main.hac and add there a link:

apps/forum/root/main.hac
for (var i=0; i<this.count(); i++) {
res.write('<a href="'+this.get(i).href("main")+'">');
res.write('Forum No.'+i+'</a><br>');
}
res.write('<hr>');
res.write('<a href="'+this.href("addforum")+'">add a new forum</a><br>');;


the only line which is new is
res.redirect(root.href("main"));

This means the user is send to the page "main" in root. This is the same, as the user would click a link in hers browser.

Today you will learn, how to create new forums, and how to render a list of them on our start page.

The first thing we need is a new prototype, for the forums. A prototype in Helma is represented by a new folder in our application folder. In our case this is: apps/forum

In OOP language, this folder is the class which describes the properties and holds the methods. To declare new properties we will use the type.properties file and to create new methods, we will just add .hac files or functions() in .js files.

So what does this mean for the non-programming-pro?

In our forum application we want to be able to create new forums. But Helma, doesn't know what a forum is like, what it can do and what it can store. So we need to describe a prototype of this forum. You can imagine this as the production line, or form, that will produce our forums. (with the exception, that when we change something in our production line, it will also affect the already produced objects).

To create a new prototype in Helma, we just add a folder to our application directory. We will call this folder "forum". The complete path is: apps/forum/forum . It has no meaning or relevance, that the application folder, and the folder for our first own prototype are named the same.

create a main.hac file in the newly created folder. Open it in a text editor and type in:

res.write("I'm a forum");

Now if open the URL http://localhost:8080/forum/forum/main in your browser: Nothing will happen!?

That' because we just created the prototype of a forum, and not an actual forum (-object) itself.

Adding and storing properties and objects

The only object we have so far is the root object. The root object, is created as soon as we create our new application. We can use the root folder in our application directory to describe and script it, like we did this with our start page.

And the root object is persistent! That means, when we add or change a property than it will be still there after we stop and restart Helma. To make another object, than root persistent we need to "add" it to an already persistent object. And at the beginning of an application this is the root object.

Before we add new forums, we test how to add and change properties of root. So open the main.hac in root again, script the lines, and call it with the browser via http://localhost:8080/forum. This is just for testing!

To add a new property, or change it we can say:

this.propertyName="test";
this.header="My first Helma application";

To call a property of an object we say:
object.propertyName
So when we want to print the header property of the root object to the screen, we script:
res.write(this.header);
This is the same like we would say:
res.write("My first Helma application");

Creating forums and rendering the list

The new code for root/main.hac is:

var aNewForum = new forum();
this.add(aNewForum);

for (var i=0; i<this.count(); i++) { res.write('<a href="'+this.get(i).href("main")+'"> Forum No.'+i+'</a><br>'); }

// this.renderSkin("main");

Open the URL http://localhost:8080/forum in your browser and hit the reload button for a few times. If it doesn't work right from the start you maybe have to restart Helma.

What you can see is a growing list of links to Forums. When you click on one of the links you will see: I'm a forum and when you take a look at the URL in your brwoser you will see something like: http://localhost:8080/forum/4/main

Basically the few lines of code we wrote create a new forum each time we call root/main.hac, with a browser. After we created and added a new forum, we loop through all the existing forums and render a link to this forums.

Here is a very detailed description of what is going on:

Line1: var aNewForum = new forum(); var is a keyword, and just declares a variable. A variable is a temporary placeholder for data. It will be just available within its scope. aNewForum is the name of the variable new forum() creates a new object, of the class forum. That means we produce a forum object with our forum production line and temporarily store it in the variable aNewForum the semicolone ends a line of code in JavaScript

Line2: this.add(aNewForum); this means this root object add() add is a Helma function, which appends HopObjects to an existing HopObject. That means we make the forum, that is just stored in the temporary variable aNewForum yet, persistant, by adding it to root.

Line4: for (var i=0; i<this.count(); i++) { for (initialize, test, increment) { ...code...} This is a for loop. var i=0The first time it loops it executes the initialize statement, in our case we declare the variable i and initialize it with 0 (zero). i<this.count();Each time before the loop is entered, it tests the test code. That means if i (our counter) is smaller then this.count() it will execute the code between the braces { } . this.count() This is a Helma function, which returns the number of added HopObjects of this object. That is the number of forums we already added. i++ This will be executed after the loop ended, and before the next test is executed. It just increases our counter i by 1. and is a shortform of i=i+1;

Line5: res.write(''<a href="'+this.get(i).href("main")+'">Forum No.'+i+'</a><br>'); res.write(); we already know this ... right? '<a href="'+this.get(i).href("main")+'">Forum No.'+i+'</a><br>' This is the string we want to print to the screen. You have to take care about the single and double quotes!! Strings can be combined by the plus singn. for example: "Hello "+"World!"; this.get(i) get is a Helma function that returns a HopObject that had been added to this object this.get(i).href("main") We just continue by adding another dot sepperator and call the href() function on the forum returned by this.get(i). The href() function is a Helma function, that returns a URL string for the object. "main" says that we want to get a URL for the main.hac of that forum.

Line6: } ends the loop

Line8: // this.renderSkin("main"); // says that the rest of the line is just a comment. We want to diable the rendering of the rendering of the start screen.

Helma is scripted with JavsScript!

To fully understand the code we will use in the rest of this tutorial you need to learn JavaScript or consider a book or online Tutorial about this. But even, if you are just familiar with an other programming language, like PHP, ASP, C++ or Java you should be able to read the code and follow the examples.

The fact, that we are using JavaScript doesn't mean it's the same JavaScript like you are maybe used to from scripting in a HTML page. The main difference is, that there are no special ClientSide objects, like the window object, or document.all or stuff like this. But at least the syntax is the same.

But there are a lot of other objects in exchange we will need on the server side. For example the res (response) or the req (request) object, and so on.

Next time

Next time we will learn how to control this behavior a little bit more :)

In this chapter we will script our first real Helma web application. - a small forum. You will learn how to create HopObject classes and connect them to a database (mySQL). Even if you never scripted a web application before, and have no idea about SQL, HTTP-headers and so on you should be able to understand this example. If not: kick me.

Create a new application
start Helma and create a new application called "forum" via the apps.properties file, like described in the "Hello World" example

Making the start screen
First we will create a start screen for our forum application. All we want is a header, a list of all existing forums and a button (link) to create a new forum.

With our existing knowledge we create a main.hac in root. Instead of

res.write("Hello World!");

res.write("<html>");
res.write("<head>");
res.write("<title> My first Helma application</title>");
res.write("</head>");</p><p>res.write("<body>");
res.write("<h2>My first Helma application</h2>");
res.write("<h4>existing discussion boards:</h4>");
....

<% some code %>

<html>
<head>
<title> My first Helma application</title>
</head>
....

<% some more code %>

But Helma won't allow this in .hac files. So what can we do to solve this?

What you need are "Skins".

A Skin is a template, which can be called by a function. But before we learn more about skins and hac's in detail, lets solve our start page:

First create a file called "main.skin" in root. (The name "main" has no special meaning with .skin files) Open it in a text editor and script the following simple HTML page:
<html>
<head>
<title> My first Helma application </title>
</head></p><p><body>
<h2>My first Helma application</h2>
<h4>exisiting message boards:</h4>
// here goes the list
<br>
<a href="addForum">neues Forum anlegen</a><br>
<br></p><p></body>
</html>


Then open root/main.hac and script:

root.renderSkin("main");

When you open http://localhost:8080/forum you should see the HTML page.

So why do I need "Skins"?

Helma has a very strict, but clean way to sepperate logic from presentation. It doesn't allow you to have logic in .skin files and makes it very hard to have presentation (HTML in our case) in functions or .hac files. (just see our res.write, res.write example). This may seem complicated in the beginning. But it is just a disadvantage, as long as your apps don't have mor than 10 lines of code. For bigger applications it reduces the risk of bugs and makes it possible to let the HTML guys take care about the HTML, without doing too big damage. It is possible to store skins in a database and make them editable by others than the programmers, like Antville demonstrates.

Note: This should go somewhere else
A .hac file is just a function on the server which can be called via an URL. A function is peace of code which contains the logic of our application and manages what happens when we call a page. For people who are more familiar with OOP, a function in Helma is a method of the HopObject class where it is located. In this case this is the root class. Each folder in the apps directory represents a HopObject class. (Except global). As this example continues things will become more clear.

Lets have look at our root/main.hac:

root.renderSkin("main");

The "dot"-syntax mainly says:
call the function renderSkin on root, and use the parameter "main".

next time we will learn how to write macros. (what's that?!?!)

After we succesfully installed Helma, we will write our first application: The traditional "Hello World" example.

In your Helma directory you will find a folder named "apps". There you will find the existing apps, that had been distributed with Helma, and you can access through the "Base"-application. ( http://localhost:8080 ).

To create a new application you have to open the apps.properties file in the Helma directory with a texteditor:

# list of applications to be started by helma
base
base.mountpoint = /
bloggerapi
himp
hopblog
lillebror
manage
helloworld


As you can see the apps.properties hold a list of applcation names, that are running at your server. So we add a line at the end of the file with the name of our "helloworld" application.

When you go back to the helma/apps folder you will find a newly created helma/apps/helloworld folder.

In there you will find 4 subfolders:

helma/apps/helloworld/global
helma/apps/helloworld/hopobject
helma/apps/helloworld/root
helma/apps/helloworld/user

For our "Hello World" application we will just need the root folder. As the name says this is the "root"-directory of our application, which we can access via the URL http://localhost:8080/applicationname (in our case http://localhost:8080/helloworld).

Create a textfile called "main.hac" in the root folder, and open it with a text editor. Type the following line:
res.write("Hello World!");
and save the file.

".hac" files are our "Helma Action" files, which we can access via the URL. "main.hac" is something like index.html on a static web server. That means this file will be automatically called when we access a Helma node (in this case the root-node).

So helma/apps/helloworld/root/main.hac can be called via the URL's http://localhost:8080/applicationname/main or just http://localhost:8080/applicationname .

What you can see in your browser should be the line:

Hello World!

Helma is 100% Java, that means, that you can run it on a lot of plattforms. (Windows, Linus, Mac OsX, but not Mac OS9) To run a Java program you need a Java Runtime Enviroment (JRE), which you can download for example from Sun.

Installing the JRE

1. Download a JRE for your plattform from
   http://java.sun.com/j2se/1.4/download.html
2. Install it
   on Windows just doubleclick and follow the wizard

Installing Helma

1. Download the prerelease package for your plattform
   from http://www.helma.org/files
2. Unzip it
3. You should now have a folder with all the Helma files

Starting Helma

1. In the unzipped folder you will find two startscripts. hop.bat for Windows and hop.sh for *nix Systems
2. Start the script for your plattform
3. Helma is starting its internal server at port 8080
   you have to make sure, that no other server is running on port 8080 (i.e. Tomcat)
4. Open a browser (Mozilla/IE/whatever..)
5. go to the URL: http://localhost:8080/

Now you should see a page starting with:

Welcome to Helma Object Publisher.

What you see is actually a Helma application. The so called base application. On the right side you see a list of applications running on your server (local machine)

That's it !!! Welcome to the world of Helma :)

How to run Helma with mySQL, and how to install this I will discuss later.

Helma.org is providing a lot of gates which you can enter to participate. Whether you are a programing pro, or just somebody interessted - there are ways for you to get in contact with the community and help.

project.antville.org
Here you can post your comments and questions. Report bugs or strange behavior, or suggest new features. It's just as easy as using antville.

www.helma.org
The homepage of Helma.org. This website is currently under heavy reconstruction. But you can still find a lot of information. And a very good documentation (Thanks to Tobi). (Even in some cases it is outdated)

Mailing lists
There is a mailing list (with high traffic) for Helma. Here you will find discussions about bugs, and new features of helma itself. This is a very technical list, but it helps you to be up to date.
There is NO mailing list for antville-development yet. This is all located at project.antville.org

Bug Database
Bugzilla helps us to get rid of bugs in Helma. Please read the guidelines, before you report a bug and doublecheck! (maybe with a different browser or operating system).

CVS
Concurrent Versioning System. This is a system that helps a group of people to work on the same code. Basically it keeps track of changes and helps merging different versions of a code-file. Find out more at google or see http://www.helma.org/contrib .
To get an acount at the CVS, which allowes you to contribute, write a request to the mailing list.

That's what you would love to know. .... RIGHT!

Antville is OpenSource. And it's based on Helma, which is OpenSource too. (read the intro page of antville)

What does this mean to you?

It's free! O.k. that's right, but this is not the real power of OpenSource....

You can customize and extend it!!!
I think that's the real advantage to you.

This website will try to teach you the secretes of Helma, so you can get involved and extend your personal antville, or program other nice applications with Helma. These applications don't have to be OS, and can be VERY powerfull, like a lot of ORF ON websites demonstrate.

If you want to know who is behind Helma check: http://www.helma.org/about/people/
But this is by far not a complete list of people helping. And this site is a try to increase this number.

So your comments are welcome. Where should this site go? What are you interessted in? Q, Q, Q's ...

At the beginning i will go through a simple Web-Forum application... But after that .. ? lets see ...

About me:
matthias @ knallgrau.at
We are using Helma since the first hour, and this a try to give something back.

funny, an hour ago i first saw this tool, because i was testing it on our server - and now its even online availeable.

i wanted to test the skinmanager, but all my fields were empty and so did destroy everything.

i see, i have to edit this to get on front page. no i have to switch to online mode.

the skinmanager seems pretty confusing to me, but very powerfull.

but the summer is coming, what means that there is no university, so i hope that i will have some extratime to help you improve antville. at least at the frontend, and usabillity side. had no time yet to get into the code.