View source for 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, [[GSWComponent]]s 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:
<pre>
include $(GNUSTEP_MAKEFILES)/common.make
include $(GNUSTEP_MAKEFILES)/Auxiliary/gsweb_wo.make
</pre>

Note that the second include forces GNUstepWeb to use Apple's WebObjects naming conventions. Dropping the <b>_wo</b> 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 <b><i>{PROJECTNAME}</i></b> with the name in the variables listed below
;<i>{PROJECTNAME}</i>_HAS_GSW_COMPONENTS:used to indicate that [[GSWComponent]]s are present in the project. Normally, this is set to <TT>YES</TT>
;<i>{PROJECTNAME}</i>_PRINCIPAL_CLASS:used to identify the main class of the web application
;<i>{PROJECTNAME}</i>_RESOURCE_FILES:used to indicate the list of files that are needed in the runtime bundle
;<i>{PROJECTNAME}</i>_OBJC_FILES:contains the list of Objective-C files needed to compile the web application
;<i>{PROJECTNAME}</i>_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:
<pre>
-include GNUmakefile.preamble
include $(GNUSTEP_MAKEFILES)/gswapp.make
-include GNUmakefile.postamble
</pre>
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:

<pre>
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
</pre>

The name of the project is <b>SimpleDemo</b>, 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:
;<b>main</b> 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
;<b>Session</b> 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.
;<b>GSWApplication</b> 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 <b>SimpleDemo_main.m</b>
<pre>
// 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;
}
</pre>
This creates an autorelease pool and begins the web application by invoking the application object.

Next <b>Session.h</b>:

<pre>
// Session.h from SimpleDemo

#import <WebObjects/WebObjects.h>

@interface Session: WOSession

// fill me with session instance variables

@end
</pre>

And <b>Session.m</b>:
<pre>

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

@implementation Session

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

@end
</pre>

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, <b>SimpleDemo.h</b>:

<pre>
// SimpleDemo.h

#import <WebObjects/WebObjects.h>

@interface SimpleDemo: WOApplication

@end
</pre>

And <b>SimpleDemo.m</b>:
<pre>
// SimpleDemo.m

#import "SimpleDemo.h"

@implementation SimpleDemo

@end
</pre>

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 they contain the HTML, the connections or bindings of your objects and additional information like the used encoding. Those files are suffixed .html, .wod and .woo.
A more in-depth description of [[GSWComponent|Components]] is available.

===The application dictionary===


=== Interface files ===

----

[[Category:GNUstepWeb]]
[[Category:Development]]