Hello Speck!

Yes, it's the obligatory Hello World application. In this section we'll create a new Speck application from scratch.

Creating the New Application

Step 1 - The Application Configuration File
Each Speck application requires its own application configuration file, stored in the Speck config/apps directory (e.g. c:\inetpub\webapps\speck\config\apps). Create a new text file called "hellospeck.app" with the content below and save it in the config/apps directory.
hellospeck.app
[settings]
description = Hello Speck
appInstallRoot = c:\inetpub\webapps\hellospeck
dbtype = access

Step 2 - Application Directories
Create a new directory in your webapps directory called "hellospeck" (e.g. c:\inetpub\webapps\hellospeck). Then create a "www" sub-directory (e.g. c:\inetpub\webapps\hellospeck\www).

Step 3 - ColdFusion Templates
Ok, we'll keep this really simple for now. Create Application.cfm and index.cfm files in the www directory with the content below.
Application.cfm
<cf_spApp name="hellospeck" refresh="no">
<cf_spToolbar>

index.cfm
<cfoutput>
<html>
<head>
<title>Hello!</title>
</head>
<body>
<h2>Hello from Speck...</h2>
</cfoutput>

<cf_spContent type="Blurb" label="home" method="display">

<cfoutput>
</body>
</html>
</cfoutput>

Note how cfoutput is used even for outputting HTML in Speck applications. This is because Speck uses the cfsetting tag to force enablecfoutputonly="true" to reduce whitespace. Also note how the call to cf_spContent is not within a cfoutput block. This too is done to reduce whitespace.

Step 4 - Database and Datasource
Create a blank MS Access database called "hellospeck.mdb" and save it in the hellospeck directory. Using the ColdFusion administrator, create a new datasource called "hellospeck" to connect to this database.

You can use another database system if you like. Just make sure you change the dbtype setting in your hellospeck.app file to one of the supported database types (e.g. postgresql, mysql, sqlserver, oracle). To check if your database system is supported, look for an entry in the databases.cfg system configuration file. You can add one if you need to :-)

Step 5 - Web Server Settings
First, modify the home directory of your default web site (or create a new web site and set the home directory) to the hellospeck www directory (e.g. c:\inetpub\webapps\hellospeck\www).
Then add a "speck" virtual directory / directory alias at the root of the site and set the local path to the Speck www directory (e.g. c:\inetpub\webapps\speck\www).

Running the Application

Ok, everything should be ready to roll. Open the index page in your web browser (the URL should be something like http://localhost/index.cfm).

A JavaScript alert should pop up telling you that the hellospeck security zone was created automatically. More on that later, but for now just take a note of the password that was generated for you.



The first time you load the page; it might take some time so please be patient. This is because not only might CFMX have to compile the templates for the application and Speck API tags, but also because when a Speck application is initialised, configuration files are read, database tables are created if necessary and so on. If you reload the page after the application has initialised, you'll notice it load much, much faster.

When the page finally loads, all you'll see is the "Hello from Speck..." text that you hard-coded into the index.cfm page. Let's log in and add some other content...

Adding Content

Although you can create your own login page and probably will for other applications, there is a default one included with Speck that'll do just fine for this app. Open http://localhost/speck/login.cfm?app=hellospeck and log in using the username "admin" and the password you wrote down a minute ago (if you didn't write it down, you can find it in the hellospeck.users file in the speck config/security directory).

Note: the app parameter for the login.cfm file is only required if you access it via the speck virtual directory. If you copy the file to the www directory for your application, you'll be able to log in without specifying the app parameter.

After you log in, you should see a toolbar along the top of the page. Check the "Admin Links" box on the toolbar and the option to "Add HTML Blurb" will appear.

Click on the Add HTML Blurb link and a new window will open. If the new window does not open, you may have a popup blocker enabled that is stopping Speck from launching the edit window.

Enter some content into the Blurb field, then save the changes and close the window. The main window (i.e. the hello speck homepage) will be refreshed and your content now appears.

Whoa Dude! How Does That Work?

The cf_spContent tag used in the index.cfm file is a bit like a cfquery and cfoutput all wrapped up into on. It gets Speck content and outputs it. It also outputs admin links for the content if the admin links are enabled. The particular call to cf_spContent in question tells Speck to get a content item of type "Blurb" labelled "home" and display it using the method called "display".

By using the label attribute, we're telling Speck we only want to retrive one content item, the one called "home". This is why the link to add a content item disappeared once you added one. You can use another cf_spContent attribute, keywords, to retrieve multiple content items with matching keywords. Let's try it...

Modify the call to cf_spContent in the index.cfm file. Just change the label attribute to read "keywords" and leave the value as "home". i.e. <cf_spContent type="Blurb" keywords="home" method="display">.

Now reload the home page. Your content will disappear. This is because the content you added was labelled "home", but was not associated with any keywords. Add a content item and notice that the link to add a content item remains. Add another and you'll see both on the same page.