Getting Started Using Basis

Welcome to CF-Basis, yet another CFML MVC convention-over-configuration framework. This is a small framework used by Adam Presley over time on various CFML projects, who has decided to place the project on GitHub. This guide will get new users of Basis started by walking you through a basic Hello World application.

Basis is a simple, straightforward MVC framework (http://en.wikipedia.org/wiki/Model–view–controller) that favors convention over configuration (http://en.wikipedia.org/wiki/Convention_over_configuration). This means that Basis provides the basic components core to MVC concepts: a controller, view pages, and simple model components you may extend from. I say "may" because the usage of the base model components is completely optional.

Without Further Ado

So without any further formalities let's start making a Hello World application. This guide assumes that you have a running CFML engine of some type, be it Adobe ColdFusion, OpenBD, or Railo. If not there are plenty of great guides available on the internet to assist in setting up one of these CFML engines (Google is your friend here). It also assumes you have a brand new, blank directory that will run your new web application using Basis. For demonstration purposes we will pretend this directory lives at /code/newapp.

To begin you will need to download the Basis framework. Here on GitHub, at the top of this page, is a button labelled Code. If you click on that button you will be taken to a view of the code repository. On this page, underneath the Code button and description, is a smaller button/link labelled ZIP. Clicking this will download a ZIP file of the Basis framework.

Once you have downloaded the framework ZIP file open it in your favorite archive manager. You should see a folder in this archive named skeleton. Extract the contents of that folder (not the folder itself) into the root of your application folder (/code/newapp for our demo).

Once you have done this you should be able to browse to your application URL in your favorite browser (http://localhost, for example) and see a page that has the text Welcome to the Basis framework Skeleton application. Congratulations, you have a working Basis application.

How It Works

Basis works off of actions. By default an action is defined, or requested, in the URL with a parameter of action. So if, as an example, you have a page to create a new contact in your application, you might have an action that looks like this on your URL: http://localhost/?action=contact.new. In this example contact is the section and new is the method. It is possible to use search-engine friendly URLs in Basis (there is a setting for that), but it will require you to have setup some type of URL rewrite using something like Apache mod_rewrite, Tuckey's URL rewrite for Java, etc...

Controller First

All requests go through Application.cfc, which should extend Basis.App, to begin processing. Basis will parse the requested action and immediately looks for a controller component in your controllers directory (also configurable). The controller component that it looks for must be named the same as the section portion of the requested action. In the above example of contact.new the controller that Basis will try to instantiate is named contact.cfc, and it will extend Basis.Controller. Once Basis has created the controller it will attempt to execute the method named the same as the method requested in the action, which would be new in this example.

The RC Object

The RC object is a structure passed around in the request scope that is initially populated with values from the URL and FORM scopes, with FORM taking precedence over URL. It is available in your controllers and views and you may add or remove whatever you wish to and from it.

Next Comes the View

Once the controller has finished executing Basis will look for the appropriate view page to display. Views inclusion logic works very much like the controller logic. Views are CFM files that are stored in a directory named after the section they belong to stored under a views directory (configurable). So for the above example of contact.new we would create a CFM page named new.cfm in the /code/newapp/views/contact directory.

Concerning Layouts

A view page is typically a very light, small page. The bulk of your HTML layout should be stored in a layout CFM file. Layouts are stored in the layouts directory (configurable), and by default Basis looks for a file named default.cfm in that folder (also configurable). If at any point you wish to use a different layout you can simply set the variable request.layoutName to the name of the layout file (without the extension .CFM) and Basis will use that layout instead of the default.

buildURL()

The buildURL function is used to generate the correct url for your basis actions regardless if your application uses traditional URLs like
/?action=main.index or search engine friendly URLs like /index.cfm/main/index.

Examples Below:

buildURL('book.list')

Will generate:

• /?action=book.list - friendly URLs off
• /index.cfm/book/list - friendly URLS on

Next up: Handling Application Events