gem update --system

Then install the Phusion Passenger gem

gem install passenger

Once complete you can run the Phusion Passenger install that compiles mod_rails for you.

passenger-install-apache2-module

Once this completes it will give you some code to past into your httpd.conf file and you are ready to start configuring your sites.. Well actually if you have been using Mongrels then time to strip most of the configuration out of your https.conf file. You can have as simple a configuration as shown below. Note: The DocumentRoot should be set to the public folder within your app. Passenger automatically detects that this is a rails app.

    ServerName www.stubmatic.com
    DocumentRoot /websites/stubmatic/public

One thing to note is that by default Passenger disables ModRewrite for that VirtualHost and in our case we use ModRewrite for a number of things such as providing a Maintenance page when maintenance.html is in our public folder allowing us to take the app offline. We also use ModRewrite to hide .svn folders, so we needed to use ModRewrite. Thankfully Passenger provides a solution. Note: You must first make sure you remove the .htaccess file in your rails public folder!

So our new Apache configuration looks like this:

    ServerName www.stubmatic.com
    DocumentRoot /websites/stubmatic/public
 
    RailsAllowModRewrite on
 
    RewriteEngine On
 
    RewriteRule ^(.*/)?.svn/ - [F,L]
 
    RewriteCond %{DOCUMENT_ROOT}/maintenance.html -f
    RewriteCond %{SCRIPT_FILENAME} !maintenance.html
    RewriteRule ^.*$ /maintenance.html [L]

If you want to setup an Apache / Phusion Passenger testing server you will also need to add the following directive to your VirtualHost configuration:

RailsEnv development

As you can see Phusion Passenger make deployment of Ruby on Rails as trivial as deploying a PHP. You can easily reload Phusion Passenger by running the following command from within your Rails project root.

touch tmp/restart.txt

In terms of performance, Phusion Passenger holds it’s own against Mongrel and there are plenty of details on Phusion’s website.

For more information:

1. Phusion Passenger
2. Phusion Passenger Documentation

**** UPDATE: ActiveMerchant recently removed the functionality to use PayPal’s NVP API and so this code will no longer work with the latest ActiveMerchant. Raymond Law has kindly ported the code to use the SOAP API and you can find out more information and usage on his blog. ****

Active Merchant is very easy to extend so I have written a Ruby class that can be dropped into /vendor/plugins/active_merchant/billing/gateways/ within your Rails project (assuming you have AM installed as a plugin)

Below is the code: (I have also attached the .rb file: paypal_express_recurring_nv.rb)

# simple extension to ActiveMerchant for basic support of recurring payments with Express Checkout API
#
# See http://http://www.gotripod.com/2008/09/07/ruby-on-rails-paypal-express-recurring-payments-using-active-merchant/
# for details on getting started with this gateway
#
#
module ActiveMerchant #:nodoc:
  module Billing #:nodoc:
    class PaypalExpressRecurringNvGateway < Gateway
      include PaypalNvCommonAPI
 
      LIVE_REDIRECT_URL = 'https://www.paypal.com/cgibin/webscr?cmd=_customer-billing-agreement&token='
      TEST_REDIRECT_URL = 'https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_customer-billing-agreement&token='
 
      def redirect_url
        test? ? TEST_REDIRECT_URL : LIVE_REDIRECT_URL
      end
 
      def redirect_url_for(token)
          "#{redirect_url}#{token}"
      end
 
      def setup_agreement(description, options = {})
        requires!(options, :return_url, :cancel_return_url)
        commit 'SetCustomerBillingAgreement', build_setup_agreement(description, options)
      end
 
      def get_agreement(token)
        commit 'GetBillingAgreementCustomerDetails', build_get_agreement(token)
      end
 
      def create_profile(money, token, options = {})
        commit 'CreateRecurringPaymentsProfile', build_create_profile(money, token, options)
      end
 
      def get_profile_details(profile_id)
        commit 'GetRecurringPaymentsProfileDetails', build_get_profile_details(profile_id)
      end
 
      def manage_profile(profile_id, action, options = {})
        commit 'ManageRecurringPaymentsProfileStatus', build_manage_profile(profile_id, action, options)
      end
 
      def update_profile(profile_id, options = {})
        commit 'UpdateRecurringPaymentsProfile', build_update_profile(profile_id, options)
      end
 
      def bill_outstanding(profile_id, money, options = {})
        commit 'BillOutstandingAmount', build_bill_outstanding(profile_id, money, options)
      end
 
      private
 
      def build_setup_agreement(description, options)
        post = {}
        add_pair(post, :billingagreementdescription, description)
        add_pair(post, :returnurl, options[:return_url])
        add_pair(post, :cancelurl, options[:cancel_return_url])
        add_pair(post, :billingtype, "RecurringPayments")
        add_pair(post, :paymenttype, options[:payment_type]) if options[:payment_type]
        add_pair(post, :localecode, options[:locale]) if options[:locale]
        add_pair(post, :billingagreementcustom, options[:custom_code]) if options[:custom_code]
        post
      end
 
      def build_get_agreement(token)
        post = {}
        add_pair(post, :token, token)
        post
      end
 
      def build_create_profile(money, token, options)
        post = {}
        add_pair(post, :token, token)
        add_amount(post, money, options)
        add_pair(post, :subscribername, options[:subscriber_name]) if options[:subscriber_name]
        add_pair(post, :initamt, options[:initamt]) if options[:initamt]
        add_pair(post, :failedinitamtaction, options[:failedinitamtaction]) if  options[:failedinitamtaction]
        add_pair(post, :profilestartdate, Time.now.utc.iso8601)
        add_pair(post, :billingperiod, options[:billing_period] ? options[:billing_period] : "Month")
        add_pair(post, :billingfrequency, options[:billing_frequency] ? options[:billing_frequency] : 1)
        add_pair(post, :totalbillingcycles, options[:billing_cycles]) if [:billing_cycles]
        add_pair(post, :profilereference, options[:reference]) if options[:reference]
        add_pair(post, :autobillamt, options[:auto_bill_amt]) if options[:auto_bill_amt]
        add_pair(post, :maxfailedpayments, options[:max_failed_payments]) if options[:max_failed_payments]
        add_pair(post, :shippingamt, amount(options[:shipping_amount]), :allow_blank => false) if options[:shipping_amount]
        add_pair(post, :taxamt, amount(options[:tax_amount]), :allow_blank => false) if options[:tax_amount]
        add_shipping_address(post, options[:shipping_address]) if options[:shipping_address]
        post
      end
 
      def build_get_profile_details(profile_id)
        post = {}
        add_pair(post, :profileid, profile_id)
        post
      end
 
      def build_manage_profile(profile_id, action, options)
        post = {}
        add_pair(post, :profileid, profile_id)
        add_pair(post, :action, action)
        add_pair(post, :note, options[:note]) if options[:note]
        post
      end
 
      def build_update_profile(profile_id, options)
        post = {}
        add_pair(post, :profileid, profile_id)
        add_pair(post, :note, options[:note]) if options[:note]
        add_pair(post, :desc, options[:description]) if options[:description]
        add_pair(post, :subscribername, options[:subscriber_name]) if options[:subscriber_name]
        add_pair(post, :profilereference, options[:reference]) if options[:reference]
        add_pair(post, :additionalbillingcycles, options[:additional_billing_cycles]) if options[:additional_billing_cycles]
        add_amount(post, options[:money], options)
        add_pair(post, :shippingamt, amount(options[:shipping_amount]), :allow_blank => false) if options[:shipping_amount]
        add_pair(post, :autobillamt, options[:auto_bill_amt]) if options[:auto_bill_amt]
        add_pair(post, :maxfailedpayments, options[:max_failed_payments]) if options[:max_failed_payments]
        add_pair(post, :taxamt, amount(options[:tax_amount]), :allow_blank => false) if options[:tax_amount]
        add_shipping_address(post, options[:shipping_address]) if options[:shipping_address]
        post
      end
 
      def build_bill_outstanding(profile_id, money, options = {})
        post = {}
        add_pair(post, :profileid, profile_id)
        add_amount(post, money, options)
        add_pair(post, :note, options[:note]) if options[:note]
        post
      end
 
      def build_response(success, message, response, options = {})
        PaypalExpressNvResponse.new(success, message, response, options)
      end
 
    end
  end
end

With this class installed using Active Merchant to set up a subscription / recurring payment through PayPal Express Checkout is easy. Firstly setup your gateway object:

gw = ActiveMerchant::Billing::PaypalExpressRecurringNvGateway.new( :login => 'PAYPALEMAIL', :password => 'PASSWORD', :signature => 'PAYPALAPISIGNATURE' )

Then make a request to PayPal to setup the recurring payment. At this stage you pass through a description (which is what is shown to the user when they are asked to authorise the subscription so make it descriptive) and you also need to provide URLs on your site, that PayPal should redirect the subscriber back to when they either complete the payment, or alternatively if they choose to cancel.

response = gw.setup_agreement("Subscription £25 per month", :cancel_return_url => "https://mysite.com/cancel", :return_url => "https://mysite.com/complete" )

The request above returns us a token in the response from paypal and at this point we need to redirect the user to PayPal to authorise this subscription. The user will see the description “Subscription £25 per month” as sent in the previous request. We need to redirect the subscriber to PayPal using the following line of ruby:

redirect_to gw.redirect_url_for(response.token)

Once the user has authorised the subscription they are returned to the :return_url we specified earlier, at which point we can create the actual subscription using the following:

response = gw.create_profile(2500, response.token, :currency => "GBP", :reference => "34")

Note: PayPal are really confusing having one API for the US and another for the UK but if you are using PayPal Express (which is free) independently of PayPal Website Payments Pro (Which you need to pay for) the US PayPal Express API works for all countries (apart from Germany I believe) and as you can see above I am passing in the UK currency. I am using the US API and I have a UK PayPal account. Also note that I have passed in a reference (I have an IPN URL setup in my PayPal account – Unfortunately you cannot pass an IPN URL with the request) to be sent in the IPN.

The previous step completes the set up of our Subscription. However if we need to later get information on the subscription or change it, we need to extract the Profile ID from the response as follows:

profile_id = response.params["profileid"]

With this profile_id we can then later use these additional methods that I have included, such as getting details of the subscription profile using:

gw.get_profile_details(profile_id)

Update the subscription using various options (i.e. changing subscription amount shown below):

gw.update_profile(profile_id, :money => 3000, :currency => "GBP")

Manage the subscription, for example cancel it as follows:

gw.manage_profile(profile_id, "Cancel", :note => "Your subscription has been cancelled by us")

And finally bill any outstanding subscription balance:

gw.bill_outstanding(profile_id, 2500, :currency=> "GBP", :note => "£20 Overdue Subscription")

Please note that as of yet this class is not part of Active Merchant, however it has been added to Active Merchants case #17 If you want to use this you will have to add it manually as above.

I recommend reading PayPals Express Checkout Integration Guide and the Name Value Pair API Developer Guide and Reference for more information on what variables can be passed in each request to PayPal.

Chatopica is created by Tom Bray and Robert Cadena of SearchCoders, Tom being the presenter of the excellent eSeminar on an Easy MVC approach to developing flex apps, I blogged about.

What you can currently chat about in Chatopica

Currently Chatopica offers the following topics, but the guys are working on the ability to create custom topics and you can register to be notified when this feature is added on their homepage :

1. Adobe Flash (Flash Programming and Design)
2. Adobe Flex (Flex Programming)
3. Adobe Photoshop
4. AJAX (AJAX Programming)
5. Book Club (Discussions on Books and Novels)
6. Chatopica (Chatopica)
7. ColdFusion (ColdFusion Programming)
8. Java (Java Programming)
9. PHP (PHP Programming and Web Development)
10. Python (Pythonistas Unite!)
11. Ruby On Rails
12. Video Games

I like the widget so much that I have added two topics to my own blog, so if you would like to chat with like minded developers about Ruby on Rails or Adobe Flex you can access these here anytime:

• http://www.www.gotripod.com/flexchat (For Adobe Flex Chat)
• http://www.www.gotripod.com/railschat (For Ruby on Rails CHat)

Note There are not many Rails developers on here yet, but if you are in the Rails community, please spead the word.

Or even better, why not add this widget to your own Flex or Rails blog / website!

Adding a Chatopica topic to your own site..

Adding Chatopica to your own site is a piece of cake, simply visit the Chatopica Topics section, choose the topic(s) you would like on your site and copy and paste the one line of Javascript into the HTML of your page. For those that have added other widgets to your sites, you will be familiar with this. It’s that easy. (That’s why I pasted one into this article.)

Overview of Features

When Chatopica first loads, it automatically assigns you a guest ID. You can change this at any time by clicking on the assigned guest ID in the top bar and entering a new nicname / display name. If you enter a name currently in use, the system smartly handles duplicate by appending a unique ID to the duplicate name you entered. If you don’t like this you can simply change it to something else.

Another nice feature for developers is that you can click the code button and copy and paste in, some source code. Not only does chatopica colorize your code, it also folds it so those who are not interested in seeing the code can ignore it without it filling their chat screen, while those that are interested can click the {} icon to expand the source code.

Chatopica, like many chat clients automatically scrolls to the latests message posted. A nice feature to Chatopica is the ability to turn the Autoscroll feature off by clicking the padlick icon in the bottom right of the widget. This then prevents the chat window from scrolling to the bottom when someone posts a new message, which is handy while examining someones source code.

With the ability to create your own custom chat room coming soon, we will all be able to add a little peice of Chatopica to our websites and blogs.

For more information

• Chatopica

I have already pre-ordered my copy and looking forward to the 300 new features.

In particular:

Ruby on Rails – “Work in a developer’s dreamland. Leopard is the perfect platform for Ruby on Rails development, with Rails, Mongrel, and Capistrano built in”

For more information, scoot over to Apple’s Website

To an extent I am going to assume you are already familiar with Ruby and the Rails Web Development Framework, but where possible I hope to keep things as simple as possible.

First of all one of the best ways to go about learning how to create a custom template / theme is to download one of the existing themes you like from the Mephisto Themes Gallery and look inside the .zip file and see how these template authors have gone about implementing their themes.

To get started you will need a copy of Mephisto to test your themes against. You can easily checkout the latest version from subversion. Follow the instruction from the Mephisto Site . Mephisto themes are stored under the /themes/ directory in your Rails application root. If you have a default single host installation, you need to create a new empty folder under /themes/site1/ . You can call the folder whatever you like, this is where we will create our theme.

Mephisto themes are made up of Liquid template files (basically html files with extra markup tags to inject content into your template), images used by your template as well as CSS stylesheets and Javascript files.

Understanding liquid files

Liquid files were created by the developers at Shopify so that their users could customize their shops. These templates work exactly as Rails .rhtml files do however they are safe in the sense that if a variable is nil or undefined they don’t throw an exception or server error, they simply do not generate any content. For non Rails developers .rhtml files store the html for pages and have special <% > tags where Ruby code can be entered and <= > tags where we can output to the page. Liquid files are pretty much the same, however instead of < > tags we have { } and instead of <= %> we have {{ }} tags.

More information can be found on Shopify’s Site and I recommend you read through this, in addition to this article.

Mephisto provides a variety of variable that can be used not only to put content on the page, but also to generate the navigation links, to link between pages. For example in the template that is used to display an article such as this, we have a {{ }} tags which specify to output the article body text like this {{ article.body }}.

Iteration

If the item is an array we can loop through each element using the following:

1. {% for blog_section in site.blog_sections }
2. {{ blog_section.name }}
3. { endfor %}

Conditions

We can also test the values in these Liquid variables and conditionally display content:

1. {% if section.is_home }
2. Welcome to the site…
3. { endif %}

Variable Reference

Before we get into creating templates there are two places to look for the Liquid variables available in Mephisto, directly on Mephisto’s Site and also on Mephisto’s old Wiki

There are various examples on how to do things like formatting dates etc., especially in the latter link above.

Structure of Mephisto

In addition to being simply a blog, Mephisto provides a Content Management System, this allows you to create content pages, such as an about page or portfolio (At the time of writing, something I am still meaning to do )

When we design a theme, we need to bear these different types of content (blog / pages) in mind.

Required Liquid Files

To make up a theme, Mephisto looks for a minimum of the following files, which need to be stored in a folder called ‘templates’ within the folder you created above under /themes/site1/. You need to be careful the folder is spelt exactly as written here as this is where Mephisto will look.

• section.liquid – The template is used for blog sections and normally show several articles, this template is generally also used as the template for your home page.
• single.liquid – The template used for showing a single article, often we only show short articles or excerpts in the blog sections above.
• tag.liquid – The template used to show articles for a particular tag.
• search.liquid – The template used to display search results.
• archive.liquid – The template used to display articles for a particular month.
• error.liquid – The template used to show a custom error, when an article or resource is not found.

layout.liquid

In addition to the above templates, we have an overall template which provides content for every page called layout.liquid where we can put our main look and feel. This file is located, not in ‘templates’ as above, but in a subfolder (again within out theme) called ‘layouts’.

Creating a layout template (layout.liquid)

As mentioned above, this file is located within the layouts folder in our theme folder. This file is used no matter where we are in the blog so we can use it to put any content that appears on every page, for example the header with logos and in my case my search form, our side bars and footer. This page is also the only page that holds the html head and body tags, so at a minimum we need:

1. <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”>
2. <html>
3. <head>
4. <title>My Blog</title>
5. </head>
6. <body>
7. {{ content_for_layout }}
8. </body>
9. </html>

Head Section

Instead of having a static page title, we can dynamically insert the site title or if we are looking at a blog article, the article’s title is displayed. This not only gives the users a better experience but also shows as the title for search engine listings and in stats services such as Feedburner

1. <title>{{ site.title }} {% if article } – {{ article.title }} { else } {{ site.subtitle }} { endif %}</title>

Above we are displaying the site title, and if we are viewing an article, the article object is available, so we can show the title or we show the site subtitle, as set in the Admin Settings.

We also want to make sure our RSS feed to be auto discoverable to browsers etc, so we want to add the following to our head section:

1. {{ head.feed }}
2. <!— If you are using feed burner, set it up with your RSS feed http://yourdomain/feed then use the feedburner address —>
3. <link href=“http://feeds.feedburner.com/miletbaker“ title=“Jon Milet Baker’s Blog“ type=“application/rss+xml“ rel=“alternate“/>

We also want to reference any external Javascript or Stylesheet files by using the following tags:

1. {{ ‘stylesheetfilename’ | stylesheet }}
2. {{ ‘javascriptfilename’ | javascript }}

Body Section

In layout.liquid we want to create our navigation links to access the different page or blog sections. I generally create navigation using unordered list tags , styling them using css. I can then generate the list items I need using a liquid iteration as below:

1. <ul>
2. {% for section in site.page_sections }
3. <li><a href=“{{ section.url }}“>{{ section.name }}</a></li>
4. { endfor %}
5. </ul>

The above, creates links to our page sections, we can also create links to the blog sections by changing line 2 to:

1. {% for section in site.blog_sections %}

We also likely want to add a search box to every page, we want to add the following:

1. <form method=“get“ action=“/search“>
2. <input type=“text“ class=“search“ value=““ name=“q“ id=“q“ size=“15“/>
3. </form>

As we would likely have the side bar defined in this file we would need to use the technique we used to conditionally display the title, for conditionally displaying content in the side bar. One example for this is displaying related articles to the current article. My related articles technique lists other articles tagged with the same tags. We can do this as follows:

1. {% if article }
2. {{ article.tags | tagged_articles | assign_to: ‘rel_articles’}}
3. { for rel_article in rel_articles limit: 5 }
4. <a href=‘{{rel_article.url}}‘>{{ rel_article.title }}
5. { endfor }
6. { endif %}

The above code only shows when an article is being displayed, we pass all the tags for the current article and send it to a Mephisto function which returns a collection of articles, which we in turn store in a variable called rel_articles.

In addition to showing related articles we can also show our archive links using the following (in this case we only want this to display in a section):

1. {% for month in section.months }
2. {{ section | monthly_articles: month | size | assign_to: ‘articles_count’ }}
3. { if articles_count > 0 }
4. <a href=“{{ section.path }}/{{ section.archive_path }}/{{ month | strftime: “Y/m“ }}“>{{ month | strftime: “%B %Y” }} ( {{ articles_count }} )</a>
5. { endif }
6. { endfor %}

You may also like to add a list of tags here. My site uses the Mephisto Tag Cloud plugin by Hank to generate different sized tag links based on their use, You could use the Technorati Widget or simply list all the site tags using:

1. {{ site | linked_tag_list }}

Now we have a basic layout template that contains our common page content, we can get on with the individual templates.

Section template (section.liquid)

The sectiom template as mentioned before acts as the index or contents page for your blog items for each blog section, including the home section. Here you have access to not only the site level variable, but also the Section variables.

1. {% if articles.size > 0 }
2. <h1>Articles</h1>
3. { for article in articles }
4. <!— Within this loop we have access to the article variables. We will need to display each article and some useful properties
5. of the article variable are shown below:—>
6. {{ article | link_to_article }}
7. {{ article.published_at | date: ‘%b %d’ }}
8. {{ article.author.login }}
9. {{ article | linked_tag_list }}
10. <a href=“{{ article.url }}#comments“>{{ article.comments_count | pluralize: ‘comment’ }}</a>
11. {{ article.body | textilize }}
12. { endfor }
13. { else }
14. <p>No articles found.</p>
15. { endif %}

Line 10 allows us to display the number of comments with a link to the part of the page where our comments are located, note the use of pluralize that automatically pluralizes the work comment, based on the number of comments, i.e. “1 comment” or “2 comments”.

Also as this is our contents page and we may have long articles rather than use the {{ article.body | textilize }} at line 11, Mephisto provides us with the functionality to write an excerpt. We can write a conditional statement that outputs the articles excerpt (if one exists) or the artilces body for shorter articles. This then requires you to Add an excerpt when writing longer articles, for example this article has all the text up to the ‘Understanding liquid files’ heading in the excerpt. The rest of the text is in the body.

We can then replace {{article.body | textilize }} with :

1. {% if article.excerpt.size > 0 }
2. {{ article.excerpt | textilize }}
3. <a href=‘{{ article.url }}‘ >More…</a><br/><br/>
4. { else }
5. {{ article.body | textilize }}
6. { endif %}

Note: I have found that the Mephisto feed outputs the article.excerpt followed by the article.body for each article. So I have found the best way to handle this is to use the excerpt to create a divider for long articles and not have the text in the excerpt repeated in the article. However it is up to you how you implement this, you could output the article excerpt for article in quotes at the top of your article, literally as an excerpt as an excerpt of the body text.

Single template (single.liquid)

The single.layout template is used to display a particular blog item. It is also used by default to display page items.

On this page we have access to the variables in the article object and want to have the following output to the page:

1. <h1>{{ article.title }}</h1>
2. <p>Posted: {{ article.published_at | date: ‘%d %B %Y’ }}, by {{ article.author.login }}<br/>
3. Tags: {{ article | linked_tag_list }}<br/>
4. Comments: <a href=“{{ article.url }}#comments“>{{ article.comments_count | pluralize: ‘comment’ }}</a></p>
5. {{ article.excerpt | textilize }}
6. {{ article.body | textilize }}

Above we list the article title, when it was published and by who along with the tags. As I am using the excerpt as to separate large articles I simple output the excerpt, immediately followed by the body text. If there is no excerpt only the body text is output.

In addition to the above we will want the ability for people to add comments to our articles (and I suggest you sign up for and use Akismet).

We need to add the following code to display out comments:

1. <a name=‘comments‘></a>
2. {% if article.comments.size != 0 }
3. { for comment in article.comments }
4. {{ comment.author_link }}
5. {{ comment.published_at | date: ‘%d %B %Y’ }}
6. {{ comment.body | textilize }}
7. { endfor }
8. { endif %}

The a tag at the top is used so that when a user navigates to the article url #comments they are taken directle to the required location on the page. You can also include the Gravatar of the commentor, if they have set one up using the following tag within the for loop above:

1. {{ comment | gravatar: 80, “/images/mephisto/avatar.gif” }}

The numeric value 80 is the size of the gravatar display, you can specify any size upto 80px

We also need to provide the user with a form to add comments if we are still accepting comments on that article, we do this as follows:

1. {% commentform }
2. <!- comment form ->
3. <label for=“comment_author“>Nick Name</label><br/>{{ form.name }}<br/>
4. <label for=“comment_author_email“>Email (optional)</label><br/>{{ form.email }}<br/>
5. <label for=“comment_author_url“>Website (optional)</label><br/>{{ form.url }}<br/>
6. <label for=“comment_body“>Let the thoughts flow….</label><br/>{{ form.body }}<br/>
7. <input type=“submit“ value=“Add“ />
8. { endcommentform %}

Tag template (tag.liquid), Archive template (archive.liquid) & Search template (search.liquid)

There are three ways users can find articles on your blog using Mephisto, using the tag facility to find articles tagged under a particular tag, the archive facility to find articles by date and the search facility.

All of these will generally look the same and will likely simply list page titles and dates and perhaps the body or excerpt content, as we did for the section.layout template.

In addition we may want to list the number of articles, for example using

1. {{articles.size | pluralize: ‘article’ }} found.

Paging

Mephisto will only display the number of items on a page as specified in the Admin Settings. Unfortunately Mephisto only implements paging on the search template when used in conjunction with a search. Here we can add to search.liquid the following to allow users to navigate through the pages.

1. {% if previous_page != “” }<a href=“{{ previous_page }}“>< Previous Page </a>{ endif } { if next_page != “” }<a href=“{{ next_page }}“>Next Page ></a>{ endif %}

Because the articles.size contains the number of articles to output to the page, with searches that span multiple pages, we would not display the total number of articles found. In this case we need to chnage the example above from articles.size to search_count as follows:

1. {{search_count | pluralize: ‘article’ }} found.

Error template (error.liquid)

The final template we need to create is the error.liquid template that displays whenever the user requests an article or resource that does not exist. It is good practice to give the user options to find what they are looking for, so I like to firstly display my recent articles, but also provide the search form (see layout.liquid) on the page too, allowing the user to search for the required content.

Partials

As with Rails if we have content that we will use on more than one Liquid template, we can store it in a partical and include it in the templates where needed, for example our tag, archive and search, all list our article listing in the same way. In this case, rather than repeat ourselves for each file we could include the heading in each of the tag, archive and search files and for the actual listing place the code that is repeated in a file called _articles.liquid, i.e.

1. {{ article | link_to_article }}
2. {{ article.published_at | date: ‘%b %d’ }}
3. {{ article.author.login }}
4. {{ article | linked_tag_list }}
5. <a href=“{{ article.url }}#comments“>{{ article.comments_count | pluralize: ‘comment’ }}</a>

and then in tag.liquid, archive.liquid and search.liquid include this file for each article in our articles object as follows:

1. {% include ‘article’ with articles %}

Distributing Templates

Finally if we want to distribute our templates, or if you think you have a good template, why not upload it to the Mephisto Theme Gallery . To do this we need to package the contents of our theme direcory into a .zip file, but before we do this, we need to firstly create a preview image of our theme called preview.png in the root of our theme directory and also create a descriptor file that includes who you are, what the theme is called etc. This is stored in a file called about.yml and is defined in YAML as follows:

1. title: ClockObj Theme
2. author: Jon Milet Baker
3. version: 1.0
4. homepage: http://www.gotripod.com
5. summary: THe theme for www.gotripod.com

This article has hopefully been a useful overview to creating your own Mephisto theme. There are lots of resources not only on Mephisto’s site but also on their Wiki

More Information

• Mephisto Blog
• Mephisto Wiki

1. @whois = %x[whois www.gotripod.com]

And what is important and not mentioned by Jay is the fact that you can pass parameters into %x[] as follows:

1. dom = ‘www.gotripod.com‘
2. @whois = %x[whois #\{dom\}]

Having asked if a custom Validator could be passed in the .Now() function Alec had the following to say:

In regards to passing a custom validation method into the .now method, it will not \’91create\’92 the validation method as such, but will accept one you have made, as long as your custom validation method takes a value as the first argument, and throws a Validate.Error exception when it fails (in order to pass on the failure message made easier by using Validate.fail), and true if it passes. For example:

1. Validate.Example = function(value, paramsObj)\{
3. // the following sets up default options and overides them with those passed in
4. var params = Object.extend(\{
5. failureMessage: “Default failre message goes in here!“
6. \}, paramsObj || \{\});
8. // here you would check the value you wish to validate (the one passed in), against some expected value
9. // if it fails then use the Validate.fail method will throw an exception containing the failure message
10. if(value != ‘My expected value‘) Validate.fail(params.failureMessage);
12. // if the script reaches this far then no exception has been thrown, so the validation passed
13. return true;
14. \}

Alec clarified: “…if you take a look at some of the included validation methods they contain calls to some of the other ones internally, as they will throw exceptions and halt proceedings if they fail, so act in much the same way as the simple one we have above. Validate.Email is a simple example of this and can be easily adapted to make a reusable postcode format validation for instance.”

Following Alec’s example above, you can easily then use the validator using the following:

1. Validate.now(Validate.Example(), value_to_validate, \{options\})

Using a custom validator opens up many possibilities such as making an AJAX call to the server to check the uniqueness of a username or password.

For more information:

Live Validation

Documentation for Validate.now()

LiveValidation in action

As I am currently reading the highly recommended Designing the Obvious: A Common Sense Approach to Web Application Design which discusses the use of Poka Yoke (Japanese for “mistake proofing”) devices on the web. One of which is the use of real-time validation to provide feedback to users as they make the error, rather than waiting to submit the form (which could extend beyond the screen) and finding that they cannot proceed. Sometimes searching for where they have made an error can be a challenge in itself! This client side validation library fits the bill nicely. Hoekman may argue that actually Alec is a little aggressive in his technique of pouncing on errors before the user has had a chance to get it right but I feel it is nice that the user can see as they type whether the field is valid.

Although this library seems clearly aimed at Rails developers (which I will elaborate on next) the library is fully cross platform/cross browser compatible, It has been tested across a large cross section of browsers on different platforms and can be used with any server side technology such as PHP, Ruby on Rails, ASP, Java, Python etc.

I mentioned the library is aimed at Rails developers and this is because the naming of validators for the JavaScript library closely match those built into the Rails Framework. There are the following validators build in:

1. Presence
2. Format (using Regular Expressions)
3. Numericality
4. Length
5. Inclusion
6. Exclusion
7. Acceptance
8. Confirmation
9. Email

It is not clear if you can validate against a custom function, for example allowing you to create a AJAX request to the server to check Uniqueness of user names or email addresses on a registration form [I will contact Alec to clarify]. Validations can be combined together on a single field, so for example you can check if a field is required or not. Another nice feature is that you can check whether the whole form has validated, allowing you to prevent submission to the form as suggested by Alec, or use this to only enable the submit button once the form is valid as advocated by Hoekman.

Setting up validation on a field is easy, for example to Validate presence you would need the following code:

1. var f1 = new LiveValidation(‘f1‘);
2. f1.add( Validate.Presence );

The script is available as a standalone version or for integration with Prototype and is released under the MIT licence.

For more information see: livevalidation.com

Tktit.com – The self service ticketing site.

This was my first full development outing into the realms of Ruby on Rails which has been an inspirational and educating experience and I will be posting several articles in the near future on some of the techniques I used such as using script.aculo.us to produce a similar color selector to the one I did in .Net/JQuery.

I have also used this opportunity to streamline the design of the site, there were a few things that didn’t work quite as they should on the old site and will have been improved along with a revamp of the colour scheme.

As I write this www.miletbaker.com still points to the old blog until all the content has been migrated and I have configured Apache to relay requests to my old urls to their new location. Once this is complete that will also be migrated across.

Also look out for the Jive (Javascript Input Validation Engine) for Prototype which I am currently working on with George which will feature real time inline validation as well as validation calls via Ajax and a Rails plug in. Check out Live Validation.