SuperSatellite ||

Following up the completion of one of our first successful forays into using dotCMS on campus, I thought it would be time to discuss what we did and how we did it, to give you an idea of what is possible within the platform. I mentioned in past articles that dotCMS is a powerful CMS (Content Management System) framework, you just have to assemble the pieces. Think of templates, structures, containers, and content like Lego blocks. You can have tons of them, different shapes and sizes, and depending on how you assemble them, you can control what the end result is.  This is exactly how you build more complex displays in the system.

That was the case with the Gorilla Geeks’ newsletter (alternate here). This was the first advanced usage we tackled, and we did so as part of a proof of concept to show others what we’d be able to do in the new CMS to help sell it around campus. It was created to provide a web page based newsletter that would have a URI (Uniform Resource Identifier) emailed out to people when new issues were made available (based on the schedule they settle on). Note that this was not a newsletter that was embedded in an email, and we didn’t use any of dotCMS’s CRM capabilities. The email just told people to visit the page. It is very similar to a blog, in that it has articles and categories. The main difference is how we display the articles and navigate.

Step one was to plot out how to arrange the content. I needed a way to refer to articles individually, or in groups by newsletter, or groups by category. That was clearly a relationship issue for the former, and category issue for the latter. I needed two content structures to do this. One was the “Blog/news item” structure. This already existed in the system and works well as a generic post-type content handler (title, body, image, tags). The second structure was one I created called “Newsletter.” This was a very basic structure that contained a publish date and an issue number. I then created a one to many relationship between newsletters and news items. What this means is that one newsletter could be related to many news items (Newsletter 1 could have 12 articles under it, Newsletter 2 could have 8). First you go in a make a newsletter, giving it an issue number. Then you create a news item, and on the relationships tab tell it that it’s parent is the newsletter that you just created. That solved the basic content question for the project.

Next I started looking at templates and functionality to actually make the display presentation work. The template provides all the basic display information up until articles show up; that includes the headline and sections region. Initially, the template checks to see if an article or issue number is passed in the URI and uses that to see if it needs to call a specific newsletter or if it should call the newest one. It also looks to see if the user has requested a printable version and will serve a custom CSS (Cascading Style Sheets) for that. As for the newsletter call, it starts with:

This is just checking to see if the $displayIssue variable was set (which happens on page load using $request.getParameter()), which indicates a preference for a specific issue. If not, it calls the current newsletter issue, and sets $displayIssue to that. All of this leads into the relationship needed to pull in the issue’s headlines, and the newsletter body, if needed. Once the page enters the body, we move to a container for generic web content. There, a widget is loaded that builds out the article(s) based on the request:

Basically, it figures out which of three Lucene queries to execute, and runs a loop to display them.  This allows one page to serve as the display mechanism for three different views: newsletter, category, single post.  Think of it kind of like how The Loop works in Wordpress.  I could just as easily kick them into another page for different views if I wanted, but that’s the benefit of widgets, which are cleverly crafted content items allowing dynamic content display somewhere that normally would require one piece of static content.

This ended up being a fairly simple setup: one relationship, one template, and one widget does this newsletter make.  With it, they get newsletter functionality, RSS, print versions, categorizing, search (via our Google Mini), and nice archiving.  The biggest catch is just making sure to tell a news item which newsletter it needs to relate to.  From here, I’d like to refine the theme and improve the usability some, but none of that changes the basic setup.  I’ll be happy to share more of the code with anyone if you like.