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?!?!)