Paths

HTGM works by assigning handler functions to handle specific paths, which will be run when a browser or other HTTP client makes a request. A path is the part of the URL following the domain name. e.g in https://example.com/path/to/something, the /path/to/something part is the path.

There are multiple ways of assigning a handler to a path, ranging from simple functions, to render structs, to specialized pre-built functionality. A typical web server made using HTGM will consist of multiple paths.

Simple Callback Functions

The simplest way to have HTGM respond to a path is to use the add_path(), which accepts the path, and the function to run when a client accesses that path. When the function is called, it will be provided with a single context argument of the type Struct.HttpServerRequetsContext, which contains the methods needed to return data to the client.

// Create a server on port 5000
global.server = new HttpServer(5000);
		
// Add a path
global.server.add_path("demos/hello", function(_context) {
	_context.response.send_html("<h1>Hello World</h1>")
});
		
// This must run after entering the first room
global.server.start();

In the above example, a new HTTP server is created, listening on port 5000, and the path for "/demos/hello" is added, which will return a simple HTML page. You can see the demo here.

Render Structs/Constructors

HTGM can also accept a render struct/constructor, which contains extra methods and properties it can use to make paths more self-contained. Render structs/constructors can be added to the server using add_render().

// Create a server on port 5000
global.server = new HttpServer(5000);
		
// This is a render constructor
function MyView(): HttpServerRenderBase() constructor {
	static path = "demos/hello2";
	
	static render = function() {
		return "<h1>Hello World 2</h1>";
	}
}

global.server.add_render(MyView);
		
// This must run after entering the first room
global.server.start();

In the above example, a new constructor is created, using HttpServerRenderBase as the base constructor. This constructor sets the path static variable, and provides the render() function which will be called when the client accesses the path.

The render() method will be provided a Struct.HttpServerRequestContext context argument, however, unlike the a Simple Callback function, the return value of the function is sent back to the client as an HTML document, rather than needing to use the context's response argument. You can see the demo here.

The render() method can return a Struct.Chain for asynchronous responses.

Automatically adding by Asset Tag

There may often be many files to add. Rather than specifying them manually, one by one using add_render(), there is a convenience function that will add all the constructor assets that have been tagged in the asset browser with a given tag.

// Create a server on port 5000
global.server = new HttpServer(5000);
		
// Add all constructors that have their assets tagged
global.server.add_renders_by_tag("http_view");
		
// This must run after entering the first room
global.server.start();

For this to work, the asset name must match the constructor name exactly.