RocketFoo

As promised, I’m going to take you on a walkthrough of building a new site with Symphony CMS. I’ll be referring to my new personal site to demonstrate some functional examples. If you’re not sure why you should use Symphony, have a look at my previous post and then check out the Symphony beginner’s guide.

Disclaimer: anyone who makes websites can tell you that there are usually several ways to accomplish a task. More than likely, I have not done things the best way. Some of my motivation in posting this is to possibly get some corrections from people smarter than I.

Step 1: Figure Out What You’re Building
Obvious, innit? Well, not really. It takes more than a little forethought to decide what your site is going to be, but I’m going to assume you’ve already worked some of this out. (Pro Tip: if your site is a hipster blog, just use Tumblr.)

You can't build these things with Symphony. Sorry.

For the purposes of this post, let’s say you want to make a portfolio website that meets the following criteria:

1. HTML5, because Zeldman told you to.
2. A basic “about me” page with some static content.
3. A simple contact form.
4. A portfolio overview page with categorization of projects, a detail view of each project, and support for one or more images and thumbnails associated with each project. You can see mine for an example of how this might work.
5. Content imported from external sources (we’ll use Twitter and Flickr) and then displayed in some meaningful fashion.

Step 2: Figure Out Where to Build It
This is rather self-explanatory, but it bears repeating that you will need a web host (either locally or via an external provider) that supports Symphony’s server requirements, which are helpfully located in the footer of symphony-cms.com.

Not the best choice for hosting Symphony, but it runs Mouse Stampede like a champ.

I will add that for the purposes of building a Symphony site, it’s invaluable to be able to perform occasional Unix-style command-line tasks (perhaps via SSH) and run Git. For content importing, you also need to access cron on the server. Personally, I use shared hosting at Webfaction and find it delightful for both development and production sites.

Step 3: Install Symphony and Get Git Familiar
The Symphony Installation Tutorial has detailed instructions, but it’s better to use the Git instructions at the bottom of the page instead of the .zip package installation. Using Git greatly simplifies the process of upgrading extensions, which happens fairly often.

Since I’m a bleeding-edge kind of fella, I suggest switching to the latest development version, which is 2.0.8 RC3 as of this writing. To do so, clone the repository and then do:

git checkout 2.0.8RC3

Then go ahead and install the default workspace, as it provides some nice starter material that will save us some time.

git clone git://github.com/symphony/workspace.git

If you need any help with Git, this forum thread is all you need to know.

Step 4: Say Hello to Your Little Friend
With unpleasantries out of the way, let’s get going. I’m going to assume you’ve worked out Steps 2-3 and installed a core Symphony installation and the default workspace. You now have something that looks like this:

Good news! This default workspace already has an About page, which itself contains a working example of a contact form.

It’s also set up as a standard blog, with entries, categories, and archives. We can easily repurpose and extend this structure for projects in our portfolio, instead of blog posts.

At this point, take a moment to familiarize yourself with Symphony’s administrative interface by visiting http://yoursite.com/symphony. By default, it looks like this:

There are three main areas in the navigation. Content is where things like portfolio projects and blog entries will live. Blueprints is the gateway to the building blocks of your site — Pages, Components, and Sections (more on this later.) System allows you to configure various parts of your installation. I’m not going to rewrite the book on this stuff, so be sure to review the Concepts Guide.

Step 5: Pimp Your Symp

The default installation is all well and good, but it’s rather sparse. Let’s grab some extensions and utilities that will make things a little nicer for us going forward.

First, extensions. To make them easier to keep up to date, we’ll do this Git-style using the git submodule add command. Here’s a short list to get us started, but there are 182 of them, so use what you need! Note: as always, run these Git commands in your site’s root folder.

XML Importer (grab external data)
git submodule add git://github.com/rowan-lewis/xmlimporter.git extensions/xmlimporter

Codemirror (XSL syntax highlighting)
git submodule add git://github.com/oleae/codemirror extensions/codemirror.git

CacheLite (frontend caching)
git submodule add git://github.com/makenosound/cachelite.git extensions/cachelite

Configuration Settings (edit Symphony config from the web)
git submodule add git://github.com/bauhouse/configuration.git extensions/configuration

Order Entries (drag and drop content ordering)
git submodule add git://github.com/nickdunn/order_entries.git extensions/order_entries

Date and Time (custom field)
git submodule add git://github.com/nilshoerrmann/datetime.git extensions/datetime

Now let’s enable them by going to System > Extensions. Click on the new ones and choose (With Selected) > Enable > Apply.

If you need to update extensions in the future, you can just run git submodule update on the Symphony root folder, and you’re done. Woot!

Now, on to Utilities. These are little (or big) snippets of XSLT that will help us accomplish some tasks. You can add these to Symphony by copying the source code, then visiting Blueprints > Utilities > Create New. You can name each utility whatever you want, but for this tutorial, I’ll be using the names in italics.

HTML5 Output
html5.xsl

Multilevel Navigation (handle sub-pages in a nav bar)
multilevel-navigation.xsl

Twita@talinkahashifyer (linkify Twitter content)
talinkahashifyer.xsl

OK, that will do for now! At this point, we’ve added a bit of spice to our installation and we now have the bits in place to actually get to work.

That means it’s surely time to have some coffee and goof off for a while.

In part 2 of this series, I’ll explain how data works in Symphony, and we’ll get our content structure in place. We’ll also import some stuff from Twitter. In part 3, we’ll take a simple site design and convert it into Symphony pages. Stay tuned!