Greetings! In our last episode we completed a Symphony CMS installation and loaded some nice bits of additional functionality with Extensions and XSLT Utilities. Finally, it’s time to get our hands dirty and build something. The demo site I’m building will be visible at symdemo.rocketfoo.com.
Before we begin, please note that since our last post, Symphony has been updated to version 2.1.0. You may want to update your installation.
As you’ll recall, we’re going to make a portfolio site that has:
- An overview page containing a thumbnail list of all projects organized by categories.
- A project detail page with a big image, headline, and blurb about the project.
- Support for storing any number of thumbnails and images per project.
OK then, let’s get started. In the interest of being lazy, we’re going to reuse the structure of Symphony’s default workspace, which is set up as a blog, but works remarkably well for portfolio projects.
Symphony organizes content into Sections. You define the fields that make up a Section, using field types such as Text Input, Date, and Checkbox. You can also link fields to other Sections. It’s powerful and awesome.
Once you have a Section defined, you will create Entries (i.e., blog posts, portfolio projects, or any other repetitive content such as pictures of kitties.)
Let’s take a look at Sections by logging into the Symphony administration panel and selecting Blueprints > Sections.
Symphony's Really Excellent Default Sections™
As you can see, there are several pre-made Sections here. The ones we care about are Articles, Categories, and Images. You can opt to use Comments, too, but I’m excluding that for now.
Click on the Articles link.
Fields in the Articles Projects Section
There are five fields in the Articles section: Title, Body, Date, Categories, and Publish. Conveniently, these are the essentials for our portfolio (except for Images — more on that in a minute.)
There are lots of options in the Section editor, but we can mostly ignore them at the moment — full details are in the Symphony Concepts Guide. Note that you can drag and drop a field to reorder it, and you can add fields at the bottom of the page (click on the Text Input menu to see the field types, and Add item to add it.)
There is only one change we need to make in the Articles section: rename the whole section to Projects. Do this and Save.
Now go to Blueprints > Sections and select Images.
Images is linked to Projects using a Select Box Link field. This allows us to upload as many images as we want and have them associated to a project in our portfolio. (Database geeks or people with lots of kids might call this a “one-to-many” relationship.)
This link field was originally named “Article” but we want to rename it “Project”:
Renaming the Select Box Link field
With that done, let’s add one more field, called Type. This will be a Select Box field with two options, Thumbnail and Primary, allowing us to designate which images should be used for different purposes.
Note: Symphony has an extension called Just In Time (JIT) Image Manipulation which can transform (crop or resize) images on the fly; you may prefer this for your thumbnail purposes. Personally, I’m a control freak and enjoy doing my cropping and resizing offline.
To add the field, choose Select Box in the Field Type menu at the bottom of the page, and click Add Item. Enter Type in the Label field and put the two options in the Static Options box (separated with a comma.)
Typin' in Image Types
While we’re here, if you think you’ll be uploading a ton of images, you might want to “unhide” this section by unchecking this box at the top of the page:
Show yourself, Images!
now you will be able to directly select the Images section in the Content menu. Save your changes.
With the section setup done, let’s look at our actual content. First, let’s define some categories for our portfolio projects. Go to Content > Categories.
Removing the default Category entries
Hey, who put those generic Categories here? Oh right, the developers of this fine demo workspace. Despite their quality work, we don’t need the sample entries, so click on each one and choose With Selected > Delete. Apply the change.
Let’s make some actually useful categories. Using the Create New button, create categories called Web, Print, and Miscellaneous.
Categorically Accurate
Looking good! Time to create some projects. Go to Content > Projects, and once again delete the sample items in this section, then create some dummy projects (or if you have real ones, go for it.) Be sure to add at least one project in each category.
The Best Web Site Ever
When you’re done, go back to the main Projects view to take a look at your work.
Our sample portfolio. Don't expect any job offers yet.
Now we need to add some images to these projects. There are two ways to do this: either click on the “0 →” for a Project, or go to Content > Images.
Gone Image Uploadin'
Click Create New and fill out the fields appropriately, uploading two images (Primary and Thumbnail) for each project:
The Best Fantastic Head Ever
When you’re done, you can view all the Image entries.
A fleet of images
Woot. Now that we have some extremely high quality content loaded, it’s time to wreck this joint. For our last trick, we’re going to import some data from Twitter. Get ready, you’re going to have your first taste of XPath!
First, we need to make a new section to hold our imported Tweets. I’m not going to run through this in detail, just make sure your new Tweets section matches the settings below. I like to put my imported stuff in its own Navigation Group, called “Data” – this adds a new dropdown menu in the admin interface.
Gotta Make The Tweets
Next, we’ll make an XML Importer. This does all the painful work of mapping XML from a Twitter feed to the fields in the Tweets section we just created. Once the two are hooked up, Symphony will grab Twitter’s XML and put its content into your section. Each tweet becomes an Entry in Symphony, just like our projects, categories, and images.
To add the importer, go to Blueprints > XML Importer.
Bask at Your Future of XML Wizardry
Click Create New. Start by naming this importer “Tweets.”
Naming the Importer
Twitter provides a bunch of different kinds of feeds via their API. I’ve had good success using the XML output from a URL in this format:
http://twitter.com/statuses/user_timeline.xml?user_id=16454301&count=150
You will need to swap in your own Twitter user_id but otherwise you can just use this as-is. Paste this URL into the URL field.
The faucet from which your Tweets will flow
To finish this step, check “Automatically discover namespaces.” In the Included Elements field, enter statuses/status. This is a small XPath expression that selects only the status elements from the Twitter XML feed.
Last, we have to tell Symphony where each piece of data from a Tweet should go. In the Destination area, select Tweets from the Section field. Then add each of the three fields that make up a Tweet (Permalink, Tweet, and Date.) Make sure the settings match the screenshot below (don’t forget to set Permalink to “Is unique.”)
Tweet Fields
each XPath Expression selects a specific element from the Twitter XML feed and uses the text() function to obtain that element’s content.
OK, we’re done! Click Create XML Importer. Once it’s created, go back to Blueprints > XML Importers, and click on our new Importer.
Getting Ready for a Tweet Flood
Choose: With Selected > Run > Apply. You should see something like this:
Woo! It worked.
Now if you proceed to the Data > Tweets section, you will see a swath of Tweets.
Indeed, a swath.
Excellent! After all this work, we have content loaded in our custom sections, and some imported Tweets. Let’s take a look at the site now.
Demo-tastic
Still looks like a blog. Don’t worry! In the next episode, we’ll configure an HTML template for the site and instruct Symphony to display our content exactly as we want, using Data Sources and some XSLT mojo. We’ll also get our About page and contact form in order.
Anything else you’d like to see? Leave a comment and ye shall receive.
Hi Jonas,
Thanks for another fine introduction to (parts of) Symphony. I’m learning Symphony myself at the moment and tutorials like this one are very valuable.
What I’ve noticed: I found the way in which you connect images to articles/projects confusing. Ideally you would like to add the appropriate images in a (newly created) article, not link them later on (in a separate section). This can be done, I believe, through a SBL (when you’ve added the images before) in article. Alternatively you could work with an extension such as Mediathek, correct?
What is the reason you link from images to articles and not the other way around. Why edit/link them apart?
As for “stuff I’d like to see discussed”: ‘static pages’!
One of the most confusing things of Symphony for me (and I believe many others) is the fact that, out of the box, it is not simple for editors(!) to manage (add, nest and reorder) content-pages as entries(!).
I understand (and appreciate) the fact that, in Symphony, the assumption is that the IA and site/navigation structure is worked out in advance.
However, most simple CMS’es (like Radiant, Wolf and even WordPress) allow non-technical editors to add, nest and reorder content-pages.
In Symphony this would involve creating Pages and editing XSL templates.
I’ve read about many ways to do this (pages as entries) but they seem to involve ‘hacks’ (and extension). It seems to me to be one of the main issues in ‘building a website with Symphony’. Please describe your view and the way you go about doing this.
Thanks again for the time you’re putting into this.
Symphony seems a wonderful CMS (-framework) and I am eager to learn more of it.
Is there a way to automate the XML importer so it automagialy stays up-to-date?
I currently use a cron job to run a PHP script that does something similar, but I’d like to be able to do the same thing from the Symphony admin area.
@David
I think there are 2 types of CMSs: Dynamic and Page-based. Symphony is not a page-based CMS. Even WordPress isn’t page-based (even though it has some basic page functionality).
What you are asking for will have to be a special extension that does specifically what you need. Not everyone needs pages that can be nested and duplicated. What if one of those pages needs to have different fields? Different datasources? Also, not everyone wants people going in and arbitrarily adding pages to a site after spending a lot of time perfecting the IA.
You can go about making pages in Symphony a number of different ways depending on what you need. You can easily set up all of your sections and have each entry in that section be a new page. If you need to nest them, then use the select box link field and use it to choose the parent page. The hard part will be writing the XSLT and pulling the right data to build your dynamic navigation.
The point is, you and I both have different ways we want to incorporate “pages.” The Symphony core CMS will not ever assume one way or another. It has been built to be lean and only contain the parts every site needs. Extra, specific, functionality is added with extensions.
In the end, there isn’t one CMS that will do everything. You have to pick the right tool for the job. If your client has creating and organizing the site’s pages as a high priority, Symphony is not the right CMS for that job.
@David: thanks for your comments!
Regarding the treatment for images, there are surely other ways to do it depending on your needs (Mediathek being one of them.)
In this case, I went with the linked sections for two reasons: 1) it’s easy, as it reuses the demo workspace, and 2) treating images as entries allows you to arrange them programmatically in the site template. This will become much more clear in part 3. For the record, I would probably do things a little differently if we were building a blog (with embedded images in articles) instead of a portfolio site. If you’ve ever used Drupal, there is a similar issue as to whether you treat images as Nodes or as embedded content.
About static pages — that really is a whole post in itself! I’ve never attempted to build a Symphony site that required a significant number of pages or a complex hierarchy of pages, and for now, I probably wouldn’t attempt it. As Josh said, it currently isn’t the best tool for such a task, though I believe there are several developers working on a set of extensions that would provide this functionality — some of which is already available.
@Josh – the method for cron-tasked XML Importer I’m currently using is as follows:
1) Set up a new Symphony author that will act as a robot account. When you do this, check the “Allow remote login via…” box and make note of the random numerical string at the end of the URL.
2) In your host’s crontab, use a command like so:
curl http://yoursite.com/symphony/extension/xmlimporter/importers/run/tweets/?auth-token=1234a5b6 >/dev/null 2>&1where the auth-token is the piece from the URL in step 1, and “tweets” is the name of your importer.
You can do this a little nicer by using the Shell and Cron extensions as outlined in this post, but the method above has been working fine for me.
@Jonas, @Josh thanks for the reply. I understand Symphony is not page-based and I’ve already mentioned it’s often preferable to define a proper IA/site structure in advance.
However, I believe it is seen as a must-have for many editors/clients, even if they happen never to create new pages.
http://symphony-cms.com/discuss/thread/47932/
Anyway, even though it is not Symphony’s main focus, I believe it would be very beneficial to its adoption to add this (‘trivial’) functionality.
I’ll keep an eye out for extensions such as Page Prototypes etc.
Re: the linking of articles with images. It’s clear it’s often preferable to have images-as-entries. My main question here was, however, why define an ‘articles’ Link in images and not the other way around?
Personally, I would not have chosen to base this tutorial on the installed Ensemble but on a complete blank Symphony install. Maybe you would, in that case, choose an even simpler site, but this would have given you the freedom to build what you want, the way you want it, and it would probably have given us a bit more insight into Symphony.
Anyway, thanks again: looking forward to the rest of your tutorials!
Agreed about pages. Wolf, Concrete5, and ExpressionEngine (with Structure extension) handle this pretty gracefully, and I’d love to see a similar implementation in Symphony.
Re: images: the reason to link images to articles, and not vice-versa, is that we want to allow multiple images to be associated with a single article, not multiple articles associated with a single image.
As to whether to use ensembles or not…I considered starting with a blank installation, but the default workspace provides a fair bit of functionality that is beneficial for a beginner, particularly with regards to XSLT templates and utilities that are preloaded.
My goal with this series was to produce a functional website with the least work possible, and using the default workspace helps get you there a little faster. But you could certainly do it leaner and meaner without the workspace, once you have some experience using the system.
I would like to see several extensions that adds support for building/nesting pages as well. We have a few, but this is certainly an area that could use some more options.
The linking images to entries is a little bit hard to grasp, but the fact that you can link content like this is what makes Symphony so powerful. Not many CMSs do that.
At the Symphony Meetup, there was a presentation that showed how Airlock creates a front-end editing UI to make it easier for clients to add complex content to pages. The admin area can quickly get out of hand when you start linking a lot of content. It’s worth a read and might give you some ideas: http://symphony-cms.com/discuss/thread/39550/10/#position-197
Thanks for these brilliant tutorials to an exciting CMS, I’ve found them very useful. Can I expect the third part soon?
Hi Jamie, part 3 will be up within the next week or so. Thanks for reading!
Eagerly awaiting part 3!
I’m in the process of redesigning my portfolio in Symphony, so far going well. Hoping to pick up some good practice and tips from this series of tutorials!
Sorry all, part 3 has gotten delayed a bit — coming soon!
Thanks for this tutorial series, this was my first intro to Symphony and it all went quite nicely… until…
When I go to XML Importers > Run, I get the following error:
Import Failed
No entries to import.
I have followed the tutorial to the letter, except that I used the provided user_id rather than specifying my own (I don’t have a twitter account). I can’t image this would make any difference though as I can access the feed via http://twitter.com/statuses/user_timeline.xml?user_id=16454301&count=50.
The only possible idea I have is that there appears to be a bug, when I go to edit the Tweets XML Importer, the “Automatically discover namespaces” option is unchecked, it doesn’t appear to be remembering this preference.
Thoughts?
P.S. Looking forward to part 3!
just a quick follow-up – I tried out the XML Importer on a WordPress RSS feed I had handy, I saw how the namespaces are supposed to work, and the import was then successful.
I think I can narrow the issue down just to detecting the namespaces on the twitter feed, it doesn’t work for me.
[...] budding Symphonists, and welcome to the long-delayed part 3 of our tutorial series! In the last episode, we did some relatively mundane work prepping the structure of our portfolio website. Part [...]