Creating A Simple GSWeb Application

Introduction

GNUstepWeb is a framework for creating web-based applications using Objective-C. This guide aims to provide an overview of what is required in the creation and design of a very simple web application.

It is assumed you are familiar with GNUstep, and have a working GNUstep installation, including the GDL2 and GSWeb frameworks. Pre-requisites for GSWeb application deployment should also be in place.

File Components

In building your web application you will need to create a number of files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, some mandatory "plumbing" code in Objective-C, GSWComponents to provide the pages and subpage elements of the web application, and run-time resources.

The Makefile

For a web application, a special makefile is needed: luckily it's very similar to makefiles you may have used for other kinds of project. There is currently no out-of-the-box way to have these files built for you, so you'll have to do it manually.

GNUmakefile

Initial makefile includes needed to set up the make environment should be:

include $(GNUSTEP_MAKEFILES)/common.make
include $(GNUSTEP_MAKEFILES)/Auxiliary/gsweb_wo.make

Note that the second include forces GNUstepWeb to use Apple's WebObjects naming conventions. Dropping the _wo in the included filename will enable GSW naming conventions. It is useful to decide which convention you plan to use in the application early on because changing later will involve changing the naming convention of class names in many files in your project.

The key variables used in a web application's makefile are:

GSWAPP_NAME

used to define the project's name in the makefile, replace the {PROJECTNAME} with the name in the variables listed below

{PROJECTNAME}_HAS_GSW_COMPONENTS

used to indicate that GSWComponents are present in the project. Normally, this is set to YES

{PROJECTNAME}_PRINCIPAL_CLASS

used to identify the main class of the web application

{PROJECTNAME}_RESOURCE_FILES

used to indicate the list of files that are needed in the runtime bundle

{PROJECTNAME}_OBJC_FILES

contains the list of Objective-C files needed to compile the web application

{PROJECTNAME}_COMPONENTS

lists the names of the components that will be used to create pages and other elements in the web application

The final makefile includes needed to set up the make environment should be:

-include GNUmakefile.preamble
include $(GNUSTEP_MAKEFILES)/gswapp.make
-include GNUmakefile.postamble

The preamble and postamble files are optional includes and will not error if they don't exist. It's good practice to have these in place to allow compile-time modifications during the development process and also for others if you distribute the code.

A worked-out example of a simple GNUmakefile for a GSWeb application is:

include $(GNUSTEP_MAKEFILES)/common.make
include $(GNUSTEP_MAKEFILES)/Auxiliary/gsweb_wo.make

GSWAPP_NAME = SimpleDemo
SimpleDemo_HAS_GSW_COMPONENTS = YES
SimpleDemo_PRINCIPAL_CLASS = SimpleDemo
#SimpleDemo_RESOURCE_FILES = Resources/SimpleDemo.eomodeld
SimpleDemo_OBJC_FILES = \
    SimpleDemo.m \
    Session.m \
    SimpleDemo_main.m \
    Main.m \
    Details.m

SimpleDemo_COMPONENTS = \
    Main.wo Details.wo

-include GNUmakefile.preamble
include $(GNUSTEP_MAKEFILES)/gswapp.make
-include GNUmakefile.postamble

The name of the project is SimpleDemo, and it contains GSWComponents (the basic building blocks of GSWeb), its principal class is SimpleDemo, there are no resource files for the runtime (there is an entry, but it's hashed-out), there are five Objective-C source files, and two components. You can see that the syntax allows you to break lines using the backslash \ character as the last on the line to assist readability, especially for long lists of values, like the OBJC_FILES.

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

Mandatory code

GNUstepWeb expects a small amount of glue code and several classes to be present at runtime. Initial implementation of a web application may leave these in boiler-plate form, but most real-world projects end up adding significant extra functionality through the extension mechanisms they offer.

The mandatory code is as follows:

main function

the runtime jumps to the beginning of the main function, which is used for initialisation of the the web application and can be used for initialisation of other resources such as C libraries etc

Session class definition

used for per-session initialisation in the web application, in addition to holding instance variables and methods for each session. This class should be literally named Session.

GSWApplication or WOApplication-derived class definition

used for web application instance-wide initialisation, and it may hold instance variables and methods across the entire instance.

Some worked out examples for the SimpleDemo web application follow. First SimpleDemo_main.m

// SimpleDemo_main.m

#import <WebObjects/WebObjects.h>

int main (int argc, const char *argv[])
{
    int rc;
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    rc = WOApplicationMain(@"SimpleDemo", argc, argv);
    [pool release];
    return rc;
}

This creates an autorelease pool and begins the web application by invoking the application object.

Next Session.h:

// Session.h from SimpleDemo

#import <WebObjects/WebObjects.h>

@interface Session: WOSession

// fill me with session instance variables

@end

And Session.m:

// Session.m from SimpleDemo
#import "Session.h"

@implementation Session

- (id) init
{
    [super init];
    [self setStoresIDsInCookies: YES];
    [self setStoresIDsInURLs: NO];
    return self;
}

@end

The Session.m code above implements a small change in the normal behaviour of GNUstepWeb, forcing it to store session identifiers in cookies and not in the URL. There are good reasons not to do this in practice for some real web applications, but it does show the Session object may be used to change behaviour on a per-session basis.

Now for the application object, in two parts, SimpleDemo.h:

// SimpleDemo.h

#import <WebObjects/WebObjects.h>

@interface SimpleDemo: WOApplication

@end

And SimpleDemo.m:

// SimpleDemo.m

#import "SimpleDemo.h"

@implementation SimpleDemo

@end

The application can run quite successfully with very little other than this boilerplate code. Of course, real functionality requirements may mean creating or overriding methods in these classes (especially the -init methods), creation of new instance variables and so on.

Components

GSWeb uses a directory for every component. A component can represent a whole web page or just a part of it. It is easy to re-use pieces needed multiple times.

A component contains three files containing the HTML, the connections or bindings of your objects and additional information like the text-encoding used in the component. Those files are suffixed .html, .wod and .woo.

Additionally, a component is normally implemented with a corresponding subclass of GSWComponent or WOComponent.

In the SimpleDemo web application there are only two components defined. In a real application it's usual to have custom components providing style sheet information, headers, footers, navigation bars and so on that are reused in the components that correspond to pages.

Main.wo

The Main component normally provides the first page when a connection is made to the web application. The name is not arbitrary, and normally every GNUstepWeb application contains a Main component. Our implementation will consist of five files:

1. Main.h the Objective-C class header for the Main component
2. Main.m the Objective-C class implementation for the Main component
3. Main.wo/Main.html containing the HTML markup
4. Main.wo/Main.wod containing the bindings of the dynamic elements that exist in the HTML to the application's objects, and
5. Main.wo/Main.woo which contains the text-encoding information.

Details.wo

The Details component is used to see how multiple page interactions and show additional component capabilities. The name is arbitrary.

Our custom component implementation will consist of five files:

1. Details.h the Objective-C class header for this component
2. Details.m the Objective-C class implementation for this component
3. Details.wo/Details.html containing the HTML markup
4. Details.wo/Details.wod containing the bindings of the dynamic elements that exist in the HTML to the application's objects, and
5. Details.wo/Details.woo which contains the text-encoding information.

Want to know more?

The .woo files can seem a little mysterious in that they are only being used here to identify the text-encoding information of the component. In actual fact, they can be used for a number of other, quite powerful purposes including serialised information related to direct database transactions initiated from the .html and .wod files - in other words to avoid writing code!

A more in-depth description of Components is available.

---