Conventions 1: Directory Structure And Special Files
Golf provides a fairly complex and flexible framework in which to build and deploy your web applications. One of the overriding design goals has been to simplify app development as much as possible.
In order to reduce the amount of time spent editing configuration files we chose convention over configuration. Golf aims to provide a very consistent and predictable set of conventions and consistent, sensible defaults.
Golf applications are contained in a single directory. This directory is what we call the app root directory. Inside this directory there are a number of (optional) subdirectories that have special significance.
- The components directory contains all of the application’s components. Within this directory is a heirarchy similar to the Java package system. The component namespace is determined by the location of the component directory. For example, the component located at <approot>/components/com/example/Hello would be instantiated as
- The plugins directory is where the jQuery plugins and component mixins are located. For example, if there is a script <approot>/plugins/script.js, you would load it from your JS code as
var script = $.require("script"), etc.
- Scripts placed in the scripts directory are evaled in the global scope when the app first loads on the client. This is done after the DOM is loaded but before any other app code is run. Use scripts in this directory for installing global functions and objects. (Not jQuery plugins!)
- The styles directory is where global CSS files go. They provide app-wide styling options (components can override these global styles with their own local styles, however).
Any other directories in the app root are considered to be global resources, and are accessible via the
Certain files, if present, have special significance to the Golf server. These files can be used to modify the way the Golf server operates. Additionally, there are a few files that are created by the Golf server’s startup process, and removed when the server is shut down. Here is a comprehensive list of all of these special files.
- The forceclient.txt file, if present, tells the Golf server to force client mode for certain clients, based on the user agent string supplied in the initial request. This file should contain a list of regular expressions, one per line. Incoming requests will have the user agent string matched against each regular expression in the file. If the one of the regexes matches then the client will not be permitted to access the app in proxy mode. This means that this client will only be able to access the site with JS enabled. In the case that the client has disabled JS, they will see an error page requesting that they enable JS.
- The forceproxy.txt file, if present, works like the forceclient.txt file, except that user agents matching one of the regexps in the file will be automatically served in proxy mode. In this case no JS detection takes place. This this file has a higher priority than the forceclient.txt file.
- the forcebot.txt file, if present, works like the forceproxy.txt file, except that matching user agents are not only served in proxy mode, but additionally they are not sent presentation-only items, such as CSS. This streamlines the response while maintaining complete accessibility to content. This file has a higher priority than both the forceclient.txt and forceproxy.txt files.
- The components.js file is a temporary file created by the Golf server. It contains, more or less, a compiled version of the app. There’s nothing configurable inside.
- The new.html file is created by the Golf server at runtime. It contains the HTML skeleton into which the Golf app is loaded. Don’t mess with it, there isn’t anything good you can do to it.
- The new.fc.html file is created by the Golf server at runtime, also. Like the new.html file, it contains an HTML skeleton page, but for clients that are not allowed to use proxy mode. Structurally it’s the same, but the error message that is presented to the client if JS is disabled is different. Not much you want to do wtih this one either, so leave it alone.
- The error.html file, if present in the app root, will be sent in place of the standard Golf error page. It should be a complete HTML document. The tag
<%error%> in this file will be replaced with text describing the reason for the error.
- The contents of the head.html file, if present in the app root, are appended to the HTML skeleton page’s
<head>. This can be used to add metatags or tricky conditional css.
- The noscript.html file provides a way to customize the way the new.html page looks to a client who disables JS after loading the app with JS enabled first. The new.html page’s
<noscript> tag’s contents will be replaced with the contents of this file.
- The noscript.forceclient.html file is analogous to the noscript.html file, but it modifies the new.fc.html file’s appearance.