As a pre-requisite for this tutorial, you should be familiar with html, css and web technologies in general. You do not need to know any CFML (ColdFusion Markup Language). You should have an understanding of databases, particularly MySQL, which we will use in this example.
For this tutorial, we are using a virtual machine (using VirtualBox) running Windows 2003 Server Standard, IIS, MySQL 5.1, and Railo 3.1.
The code we will be writing is not platform specific. You can just as easily implement this on Linux or Mac OSX Server with MySQL and Apache.
Lets assume that we have the HTML layout code provided to us for our website, and that we need to make it “work” on the web server, pulling its page content from a MySQL database. In addition, we will add the capability for any page to render itself as a PDF for printing purposes.
You will want to make sure you have done a few things first:
- Make sure Railo and MySQL are running on your server (or VM)
- Make sure you created a MySQL database, and a user that has permission to use your database
For development (as opposed to production web servers), try running Railo Express, which runs in a terminal window. This allows you to see the templates it is running, and the full stack trace of errors when they occur.
Setup the Railo Datasource
The first thing we need to do is setup a Railo datasource. This named datasource will define our database credentials for our website.
Open a web browser to the Railo Server Administrator, which is usually located at: http://your.server.com/railo-context/admin/server.cfm. Check the Railo documentation if you have trouble opening up the administrator.
Enter your password to login. Once logged in, click on the Services / Datasource link in the left navigation.
At the bottom of this page is where you can create a new datasource. Enter a datasource name (Letters and numbers only, no spaces, and start with a letter) and select MySQL as the database type.
On the next screen, enter the MySQL server host name or ip address, and username and password for the user you created. All of the other settings can be kept with their default values.
Scroll to the bottom and click on the “Create” button to complete the datasource configuration. Railo Administrator will test your connection, so you can confirm that it is setup properly.
We created the datasource in the “server” context. When you deploy an application on a production server, you should create your datasources in the “web” context, so that it is only available to the website that needs it. Datasources created in the server context are accessible from any website on the same server.
Setup the website structure
In the document root of your website (or in the directory you choose for this tutorial), you will need a couple of files.
index.cfm – this is the default document, like index.html or default.htm header.cfm – this is the top portion of web pages, what appears above your page content. This is where you would put your html “design” code. footer.cfm – this is the bottom portion of your web pages, what shows up after your page content. This is where you would put your html “design” code. layout.css – the basic CSS layout for our pages styles.css – the CSS styles for your page content
Lets look first at header.cfm:
This file contains what you would expect to see at the top of a standard HTML web page, including head, title, meta tags, etc. There are a few different tags included in the content however. Any tags that begin with <cf…> are CFML language tags, that are processed by Railo and removed from the source code before the page is sent to your web browser. Just like PHP or ASP.net code, if somebody views the source of your web page, they won’t see your CFML code, but rather, they will see the html code, and any code that your CFML tags generate.
<cfparam name="title" default="Untitled" />
This tag defines and sets a default value for a variable named “title.” This value can be overridden using a <cfset …> tag which we will see later.
Any content inside <cfoutput>…</cfoutput> tags will be included in the output to your web browser. In this case, the title variable is written to the page output. As with all <cf..> tags, the <cfoutput> tags themselves will be removed from the web page output. Anything inside # characters will be evaluated as an expression. So if your code was <cfoutput>title</cfoutput>, then the literal word “title” would be included in your page output. When you put # characters around it, Railo will evaluate the expression and replace it with the result.</cfoutput></cf..>
header.cfm also includes the two .css files we need for our layout and styles. These are standard css which should be familiar to you, and won’t be covered in this article.
Lets look at index.cfm
<cfset title="Home Page">
This first tag sets a local variable called “title” and sets its value to “Home Page.”
This tag includes the file “header.cfm” into the current page, which means that any page output (the html, head, title, etc. tags) will be included in this page’s output. Notice that we set the local variable title in our page, and it gets used in the header.cfm file. Local variables are available to any pages that are included in the requested web page.
The “Hello World” content is the main textual content of this web page, and can be any html or CFML generated content you want.
After the main content, another <cfinclude…> tag includes footer.cfm, which includes the expected end of page tags such as </body> and </html>
Take A Look At It
If you open your web browser and browse to index.cfm, you will see your basic web page layout, with a page title, and Hello World content. If you view the page source, you should see the combined content of the header.cfm, index.cfm and footer.cfm, with no <cf…> tags in the output, only pure HTML.
You can easily organize and create static web pages like this, and like many other programming languages, structuring your website like this has many benefits. If you make a change to your header or footer, then all your pages inherit the change immediately. Likewise if you design a new layout or style for your site, applying it once to your header and footer then applies it to your entire website.
Displaying Dynamic Content From Your Database
For this tutorial, lets assume we have a very simple database, with one table called “Content.” Content has three database fields:
integer primary key
In this table, we can have content for as many pages as you want in your site.
Lets create a page called “News” that pulls its main page content from this database.
First, we make sure that our database table has our content, so we add a record to the database (using mysql tools, phpMyAdmin, or whatever you are comfortable with) and enter the following data:
id = 1(or whatever the next id number is)
htmlContent = “This is content from the database”
this is obviously a simple example, try putting in some real content for the htmlContent field, perhaps something a little more interesting! I often will just copy/paste content from a news website for testing and development.
Next, create a new file in our website root called “news.cfm.”
In news.cfm, we add code, very similar to index.cfm:
News content here
If you open this in your browser, you should see the content “News content here” displayed in your layout.
Next, lets add a query to retrieve our content from the database:
Above “News content here” – add the following code:
<cfquery name="qryMyContent" datasource="RailoDemo">
SELECT * FROM Content WHERE pageName = 'news'
This <cfquery…> tag block performs a database query to the datasource “RailoDemo” – which we setup earlier, and stores the result of the query into a variable named “qryMyContent.” Just like other <cf…> tags, it will not generate any page output. If you view your page again in a web browser, it will look exactly like it did before.
Inside the <cfquery…> block is a standard SQL query. If you are not familiar with SQL, pick up a book on the topic, as it is relatively universal no matter what database you use. In this example, we are asking the database for all database columns where pageName is “news.”
In order to make sure we are actually getting the content we want, lets add a new tag to the page:
This tag will simple output the contents of the specified expression to the page content so you can see it. In this case, we are dumping out the content of the query result set from the above <cfquery…> tag.
Reload your page now, and you should see the query object that you got from the database. It should contain the content you were expecting for your web page.
Once you confirm that your query contains the content you want, lets output it to your web page.
Remove the “News content here” text and the <cfdump…> tag, and in its place, put the following code:
The <cfoutput> tag we have seen before, and it tells Railo to send any content between the <cfoutput>…</cfoutput> tags to the browser. Inside in # characters we have an expression qryMyContent.htmlContent, where qryMyContent is the name of the query result set from our
Open up your page again in your web browser, and you should see the content from your database displayed in your web page.
Rendering Your Web Page as a PDF
Now that we have a working site template that pulls content dynamically from our database, lets add a feature to our pages so that any page can be displayed as a PDF.
Open up news.cfm again, and go to the <cfoutput…> line, and remove it. In its place, lets add the following code:
<cfparam name="URL.format" default="HTML">
<cfif ucase(URL.format) EQ "HTML"><cfoutput>#qryMyContent.htmlContent#</cfoutput>
<cfelseif ucase(URL.format) EQ "PDF"><cfdocument format="PDF">
Now lets go through each part:
<cfparam name="URL.format" default="HTML">
This tag, which we have seen before, defines a variable, URL.format, and assigns a default value. The “URL.” scope prefix means that this is a variable passed in with the web address (or a “GET” method variable). Variables that are sent to a page from a form have a “FORM.” Prefix.
<cfif ucase(URL.format) EQ "HTML">
CFML code tends to be pretty easy to read left to right. Here this is an IF conditional statement. If the format is equal to “HTML”. The ucase() function makes sure that the variable is all upper case.
If the format is HTML, then the page should display content, just like we did before. Since our <cfparam> tag set HTML as the default, then this is the default way a page will display.
<cfelseif ucase(URL.format) EQ "PDF">
The second part of the conditional block says that if the format is PDF, then do some alternate code.
The <cfdocument…> tag is very powerful, but for the purpose of this demo, we will just use the basic capability. We wrap any content we want inside the <cfdocument…> tag, and set the format to “PDF” – and Railo will automatically know that the current page should be displayed as PDF content. Inside our <cfdocument…> tags, we have the same <cfoutput…> tags as before, so our dynamic content from the database will be included in the PDF.
Once you have added the above code to your page, if you open the news page in your browser, it will look exactly the same as it did before. The default format is “HTML” which means it displays as a plan web page.
To view this page as a PDF, now all we have to do is add a URL variable to our web address and change the format, so try changing the page location in your browser, and add “?format=pdf” to the end, so your URL would look something like this:
And you should now see your web page, but rendered as a PDF. Railo takes care of all the heavy lifting, where in other languages this would be a complex and involved process.
Now, you might consider adding a small link or clickable icon to all of your pages with the following html code:
<a href=”?format=pdf”>View as PDF</a>
This will let users click from any page and change its display from html to PDF.
In this tutorial, we created a simple website structure, retrieved dynamic content from our database and displayed it in our web page layout, and we added the ability for a web page to display as a PDF. Hopefully through this tutorial, you can see how Railo drastically simplifies the organization and creation of web page content, and allows you to do some very powerful features quickly and easily. I highly recommend that you dig deeper into the capabilities of Railo, and explore how Railo works along side Java objects.