Glen Mazza's Weblog

« Testing JPA entity... | Main | Hosting an Apache... »

https://web-gmazza.rhcloud.com/blog/date/20130617 Monday June 17, 2013

Better Blogging with Apache Roller

Note: I've switched to TightBlog, which started off as a fork of Apache Roller in May 2015 and was released in July 2016. This blog is still on Roller however, awaiting OpenShift 3.0 availability before I switch to it.

Suggestions to maximize your Apache Roller blogging experience:

  1. Have a backup process in place for your Roller blog entries. I would recommend looking into this matter first, as it's probably a show-stopper if you can't back up your blog entries, requiring you to evaluate other blogging options (such as WordPress or Google Blogger) instead. Local backups protect against the website hosting Roller abruptly discontining or having an unrecoverable database failure by allowing you to save your blog entries for either re-importing into another Roller instance or (since the blog entries are portable HTML) into another blogging tool product. Thankfully, a server-side loss has never happened to me, but to play it safe I back up my blog entries on at least a monthly basis.

    The Roller Wiki shows how to automate blog backups using an Apache-licensed utility developed by Roller founder Dave Johnson. You'll need to have Java on your machine for the utility to work. Best to create a few test blog entries and run the utility to confirm you can back up those articles. The utility runs very quickly (around 20-30 seconds for me, for about 100-150 blog articles), places the blog entries in a "saved" folder relative to where you ran the application and also creates an index HTML file with hyperlinks to the local copies of each blog entry created. Note the utility backs up just the text; you'll need to manually back up any images you're storing within Roller (although you probably have them already on your local machine) and, if desired, any CSS and template overrides you make.

    If you're not planning on making many blog entries it may be sufficient to just manually save the HTML to your local machine instead of using the above-mentioned utility. Due to the large number of blog entries I have as well as frequent updates made to them, the automated tool is a must for me.

  2. Use GitHub to store your source code and make it easily accessible to blog readers. Using GitHub allows blog readers to quickly download your source code without needing to copy-and-paste from blog articles. Further, it allows you easy access to your samples from anywhere and an ability to make source code updates can propagate immediately to your blog entries. I use the same sentence for each blog entry with downloadable source code, namely: "The finished tutorial source code is available from GitHub by using either the download ZIP button or git clone -v git://github.com/gmazza/blog-samples.git command." My samples are Mavenized and most share a common parent POM to further help reduce maintenance.

    The next question is how to display the source code to the users in your blog entries. Here my goals are minimal maintenance (in particular, avoiding a need to maintain the code both on GitHub and within the blog entry) and speed of blog page loading, so I suggest this order:

    1. Linking to the source code file on GitHub, with optional highlighting of specific lines of code of interest, such as here. Providing just a link results in the fastest loading blog pages and requires the least amount of maintenance: no duplication of source code, and GitHub updates propagate immediately to the blog article. Of course, if you're using highlighting, the lines highlighted in the anchor might need to change if you alter the source file.

    2. Directly duplicating the source file within the blog entry. This is best for small source files possibly not on GitHub that rarely change and are highly relevant to the blog tutorial. All code snippets I have in this blog entry fall into this category. You'll probably want to use the <pre/> tag for these. Two customizations: For long source files, add a style="height: Xpx" attribute (where X for me varies from 300-500) to this tag to introduce a vertical scrollbar to avoid having the source code eat up too much vertical space; also, add an attribute class="sourceCode" (or whatever class name you like) to attach CSS formatting to the pre tag. In my Roller CSS file (available from Preferences|Templates) I created a class "code2" with the following formatting:

      pre.code2 {
          background-color: #f8f8ff;
          font-family: 'Bitstream Vera Sans Mono', 'Courier', monospace;
          margin: 0 !important;
          border: none !important;
          padding: .25em .5em .5em .5em !important;
      }
      
    3. Use GitHub's free Gist service for long source code files not already in a GitHub repository that you don't want to maintain within the blog entry. This blog entry has several monstrously long SOAP messages that I wouldn't want to maintain within the blog entry HTML. So I just copied them into Gist and embedded them in my blog entry instead. Putting the vertical scroll bars in for an embedded Gist, however, can be tricky as you have to analyze the embedded Gist's HTML source for the CSS class names that Gist uses, and define CSS overrides with them. From my analysis I created 5 CSS rules of this format:

      div.sizeXXX div.gist div.file-data, div.sizeXXX pre.prettyprint {
          height:XXXpx
      }
      

      Where XXX ranges from 300-500 in 50 pixel increments. (The "div.sizeXXX div.gist div.file-data" is all that's needed for Gist, the "div.sizeXXX pre.prettyprint" is for Gist-It described next.) Then, when embedding a Gist, instead of declaring a height I just choose the CSS class name for the vertical height desired, e.g.:

      <div class="size400">
      <script src="https://gist.github.com/gmazza/2790055.js">
      </div>
      
    4. Finally, use the third-party tool Gist-It with Google App Engine (GAE) to embed GitHub source code files within your blog entries. As of this writing, GitHub unfortunately doesn't provide embedding of project source code files like it does for Gists, requiring use of an external tool. Here is an example of a Gist-It of a GitHub source file. Warning, Gist-It renders fine with Chrome and Firefox, however, last I checked Windows Internet Explorer can't render it properly. While Gist-It is a valuable utility that formats code nicely, it does slow down page loading and can eat up allowed daily limits on a free Google App Engine account rather quickly, so you may wish to be moderate with its usage and also use the Roller Summary field (discussed next) to make sure that Gist-It activates only when people click "Read More..." or go to the specific URL for that blog entry. After you host your instance of Gist-It on your GAE account (say at http://myblogname.appspot.com/), you can refer to specific GitHub source code files as follows (note the class attribute being used to introduce vertical scroll bars as discussed previously for Gists):

      <div class="size500">
      <script src="http://myblogname.appspot.com/github/gmazza/blog-samples/blob/master/soap_client_tutorial/pom.xml?footer=minimal"></script>
      </div>
      
  3. To speed page loading and limit bandwidth usage, use the Summary field and restrict the number of blog entries to show at one time. The Preferences | Settings tab of Roller allows for configuring the number of blog entries to show at a time. You might wish to choose a lower number of entries (say 5-7) to speed up HTML rendering of your blog. Also, in Roller there is a Summary field below the blog entry edit box. If you use that field to put in a one-or-two sentence blurb about your blog article, general visitors to your blog's home page will see just the short summary and a "Read More" link if they wish to see the entire blog entry. However, those who access a single blog entry using its direct URL will always see the full entry. Using a summary field is especially recommended for blog entries using the resource-intensive Gist-It, both in speeding up page downloads as well as limiting Google App Engine usage.

  4. Add a Google Analytics account to your blog to view website traffic. Google Analytics is a free service that uses Javascript to find out about the people visiting your blog: How many view each article, where they are located, which terms (keywords) they used in a search engine to get to each blog entry or the site which referred them, the browser they are using, and several other fields. For me it's most helpful in determining which blog articles are most popular and which websites are referring to my blog as part of other articles. Once you're given the tiny Google Analytics "urchin" script to insert into your blog, I've found placing it at the top of the "_sideColumn" Roller template to work fine in getting GA to be able to detect my blog traffic.

  5. Choose a useful URL for the blog entry. An easily understandable blog entry URL helps when communicating your new blog entry to others and also assists in search engine optimization (SEO). Apache Roller creates the URL based on the first five words of the blog entry's title the first time you enter "Save as Draft" or "Post to Weblog". Later, if/when you change the title, the URL will not change. What this normally means is that you'll usually want to place the URL desired in the title field, hit "Save as Draft", and then change the blog title to whatever you want it to be.

    For example if your blog title is "Fun things to do when travelling with your kids to Florida", if you don't first save the blog URL, the unhelpful "fun_things_to_do_when" will serve as the blog entry URL. But if you first save the title as "kids in florida travel tips", save as draft, and then change to the desired blog entry title, you'll get a useful and easy-to-read URL for your new blog entry.

    Roller lacks a direct ability to change blog URLs, but the workaround is not that bad considering the need for this is normally infrequent. What I do is create a new (empty) blog entry with the desired URL and post it on the day of the original blog entry (Roller allows for pre- & postdating of blog entries). Then I copy the old blog entry text to the new one, make sure it saved properly, and then delete the old blog entry. Finally, if you're changing the URL for SEO purposes, go to Google Webmaster Tools and ask them to un-index the old blog entry (make sure it returns a 404 first) and index the new one. The latter step is optional, as usually Google will update its indices to the new URL within a short period of time anyway.

    On a related topic, the upcoming Apache Roller 5.1 will also offer blog entry-specific meta descriptions that search engines may use in returning the web page (however, seemingly more often than not don't, unfortunately.) If using Roller 5.1 in the future you may wish to populate this field for your blog entries and edit the weblog's header template, adding <meta name="Description" content="$model.weblogEntry.description"/>, so it will appear in the HTML header section of each blog entry.

  6. Add a Blog index page holding links to your entries. My blog index provides an all-in-one place for readers to look for related articles that might be of interest for them. Blogs that don't provide an index result in users needing to Google externally to get back to the blog (something unlikely to happen), or thumb repeatedly through blog entry pages to find topics of interest. Creating a blog index also helps me in scanning blog entries to find those that need updating or deletion.

  7. Keep your blog current by either updating or removing old entries. People tend to overestimate the shelf life of a blog article, not realizing how out of date a blog entry can become after 12-18 months or so. Numerous times I've updated one of my older blog entries and realized not just that the Maven poms and code need updating but that I can make significant text improvements to the blog article, including optimizations and matters that just didn't occur to me when I initially wrote the article. On the other hand, some articles are fully obsolete and should just be deleted.

    Usually when I update a blog entry I'll add an Updated (Month) (Year) comment at the top, so newcomers looking at say, a 2010 blog entry don't have to worry about the source code being obsolete today. However, for articles that were posted more than two years ago, I'll frequently move it to the current date anyway as part of updating the article. That helps SEO, keeps my blog up-to-date, and also further ensures to the reader they're not reading an out-of-date article.

  8. Choose your blog theme (template) wisely and modify the templates and CSS to suit your needs. If you plan on providing lots of coding examples you'll want a blog theme with wide margins to display the source code well. If you plan on mostly writing, however, it's best to choose a theme with narrower margins as wide paragraphs aren't particularly pleasant to read. Roller comes pre-packaged with about a half-dozen themes and offers extra themes as an optional install, this blog uses the "Rolling" theme from that latter set. As for altering blog layout, Roller's Velocity-based templates offer significant customization possibilities, and you also have considerable control over the CSS used by the template. Most customization will probably occur in the side menu template. Some Velocity snippets you might like to add there:

    • A list of X most recent blog entries (here, 20):

      #set($recentEntries = $model.weblog.getRecentWeblogEntries("nil", 20))
      #showWeblogEntryLinksList($recentEntries)
      
    • A list of X most recent blog comments (here, 10):

      #set($comments = $model.weblog.getRecentComments(10))
      <ul class="rEntriesList">
           #foreach( $comment in $comments )
              <li class="recentcomments">
              #if ($comment.url == "")
                 - $comment.name    
              #else
                 - <a href="$comment.url">$comment.name</a> 
              #end
             on <a href="http://web-gmazza.rhcloud.com/blog/entry/$comment.weblogEntry.anchor">$comment.weblogEntry.title</a><li/>
           #end
      </ul>
      
    • A listing of blog hits for the day:

      Today's Blog Hits: $weblog.todaysHits
      

    You may also wish to customize the footer that appears after each blog entry, which can be done by editing the Roller "_day" template. For my footer I use the following:

    <span class="dateStamp">Category $entry.category.name | #showEntryPermalink( $entry ) | #showCommentsPageLink( $entry ) |
       <a href="http://web-gmazza.rhcloud.com/blog/entry/blog_article_index">Blog Index</a></span>
    

    Some other useful properties: $entry.creator.fullName for blog author name (useful in case of multi-author blogs) and #showTimestamp($entry.pubTime or $entry.updateTime) -- print the time/date of posting or last update. See the WeblogEntry data object in the Roller template guide for the full list or properties available for each blog entry.

  9. Blog in raw HTML. While an initial time-saver, in my view the training wheels provided by rich text editors ultimately end up slowing one down and result in less well-formatted entries. One can think of HTML as just standard writing with some additional punctuation thrown in, and just nine tags (p, a, ol/ul, li, em, strong, pre, div) take care of nearly all your needs. HTML tables are more complex to create, but once you create (or copy) one, you can copy-and-paste it as a template wherever else needed in your blog entries. I've blogged in raw HTML for several years now and rarely give the HTML tags a second thought, no more than I would typing commas and periods.

  10. Enhance your blog with third-party widgets. Some suggestions:

    • Twitter widget - You can have a feed of your own tweets, tweets on a desired topic, or an accumulated feed of several Twitter accounts.

    • Google Custom Search Engine - A better search box than those provided with Roller.

    • Social media icons (Twitter, Google+, LinkedIn, ohLoh, etc.) - Best to choose icons of a similar size (mine are mostly 24x24 pixels). I embed them in a right-aligned HTML <td/> using the following format:

      <a href='http://www.flickr.com/photos/glenmazza/' title='Flickr'>
        <img alt='Flickr' src='http://web-gmazza.rhcloud.com/blog/resource/flickr-icon24.png' />
      </a>
      

      The title in the a tag refers to the pop-up text when the mouse hovers over the icon; the alt in the img tag refers to the replacement text should the image not be available or if the browser is not of a type to render images.

    • AddThis -- I don't personally use this service yet, but Nicolas on the Roller User's mailing list recommended it for adding social media icons to each blog entry to allow readers to "favorite" blog articles that they like. An example can be seen at the end of the text of this blog entry.

    • Embedding images - In order to both speed up blog page loading and limit bandwidth demands on other people's servers, best to upload images within your Roller blog and access them from there (as I do above with the Flickr icon) instead of embedding external third-party URLs. For many images, I use a two column HTML table with the text on the left and the image on the right (see here for example, have your browser display the HTML source to show the table layout used.)

    • Embedding YouTube videos: The main page of most YouTube videos include an embed URL which I simply paste into the right column of a two-column table, as shown here.

For more information: Check the Roller Wiki for more tips and remember the Roller Users' mailing list is available for assistance. For system documentation, I recommend users first consult the latest nightly docs in OpenOffice format in our Subversion repository, as significant updates have occurred (particularly in the Install Guide) since the last (5.0.x) documentation release.

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed

Valid HTML! Valid CSS!

This is a personal weblog, I do not speak for my employer.