Finally: decent documentation for Rails developers

Last week Jeremy McAnally talked about the continuing decline in Rails blogging. Like many Rails developers I’ve learned a lot from blogs over the last couple of years: in the early days it was pretty much the only way to find out about how Rails worked as the official documentation was poor to say the least.

In my opinion though, the future for Rails documentation is not as bleak as Jeremy suggests. Less blogging could simply indicate a move towards better quality postings: I’d rather have a choice from a handful of really well written blogs than the hundreds of “OMG!!! Look how awesome Rails is…” style posts that I used to have to trawl through – less hype and more substance is definitely better.

The official documentation is, at last, being improved too: as announced in May there is now a docrails branch on Github and it has already seen a huge number of changes committed.

While I don’t particularly miss coding in PHP it came as quite a shock when I made the move to Rails to find that there wasn’t anything that came close to its documentation. Not only is there a language reference, full documentation for the standard extensions (and with the crazy lack of naming conventions or namespaces in PHP this is really useful!) there is also the invaluable comments section where other PHP developers can contribute extra documentation to each and every part of the language.

This is what Rails has needed for a long time. The great news is that thanks to the hard work of the guys at Nodeta it has finally arrived: behold Rails-doc! The site reached version 2.0 last week and now it has pretty much everything you could ask for:

  • Full documentation of the Rails API including different versions of the API.
  • User comments.
  • Easy to use search, as well as a Firefox search bar extension.
  • A simple, clear user interface that is far better to navigate than the official API documentation.

Now, perhaps more than ever before, we as a community can get involved to improve Rails documentation: we can of course continue with our blogs, but we can also submit patches to docrails and post comments to Rails-doc. These things combined should ensure that we don’t reach the point where, to quote Jeremy, Rails becomes an esoteric project doomed to eventual abandonment because everyone has to shell out $40 for a book to learn how to use it.

Discuss this entry

A tamper-proof cookie jar for Rails

When the default session store for Rails was changed to use cookies last year it caused quite a furore: "It’s not secret! It’s not safe!" The truth is it was never meant to be: in most circumstances you shouldn’t really be storing data in cookies that need to be protected so strongly. But I don’t really want to re-open that can of worms! Instead I want to look at a different cookie-related situation that arose during some optimisation work I’ve been doing on an existing Rails application.

No cookie monstersThe scenario is straightforward enough: the application stores a numeric record ID in a persistent cookie that, while perfectly safe to be seen by users, shouldn’t be changed by them. The solution currently used in the application is equally straightforward: the data is encrypted (using the EzCryto gem and AES encryption) before being written to the cookie, and then decrypted when the data is read back in.

In situations where cookie contents really shouldn’t be seen by users then encryption is the way to go (unless of course you can find a way of not using a cookie at all), however for a simple numeric ID where tampering is the only thing we need to protect against then it seems like overkill. A better solution is to take inspiration from the Rails cookie session store and use a HMAC.

Read more of this entry

The Wedding of the Year

In the week when TheWebFellas became famous for five minutes thanks to Ryan Bates, Antonio Cangiano and Gregg & Jason at Rails Envy, I was away enjoying a relaxing holiday in the beautiful Garfagnana region of Italy. But taking a break from the fast-paced world of Rails development wasn’t the only motivation for the trip: my brother and partner in crime at TheWebFellas was getting married to his girlfriend of many years Samantha.

Resisting offers from Hello magazine (although the wedding did feature in the equally popular Barga News) the highly exclusive ceremony was held in the Barga Commune with only 22 members of immediate family and close friends in attendance. The evening was spent in the grounds of the 18th Century “I Cedri” villa in nearby Albiano where we enjoyed a huge Tuscan feast that went on well into the night. I’ve put a few of my photos up on Flickr: incredibly the official photographer managed to take about 600 photos!

For the remainder of the week I was able to relax by the pool, drive on some of the greatest roads in Europe in my trusty Micra convertible and enjoy some excellent food in various restaurants and pasticcerias: if you ever find yourself in Barga you must visit Bar Lucchesi in the new part of town for some genuine Italian atmosphere, pastries and the best cappuccino ever.

Sadly while Chris and Sam are still enjoying a leisurely trip back through Europe I’m now back in the UK, working hard and missing my swimming pool with a view!

Discuss this entry

EC2 Persistent Storage for the Impatient?

As I previously posted Amazon have announced that persistent storage is on it's way for EC2. Sadly the public launch date has not yet been disclosed - it's "coming later in the year". In the meantime this leaves the question of what to do when you need data to persist?

There are a number of options, especially when you start to consider scalability and fault tolerance. I won't dare claim I've considered all the options out there - I've simply started to look at what the immediate options are for persistent storage.

Without further ado, then, on to the technology. I've found a number of choices - rather than this being a 'how to' then it is more about the solutions I have found so far and that are on my list for consideration. Hopefully, if one of the options fits my needs then I will provide a guide at a later date!

Read more of this entry

Rails 2.1: now with better integrated caching

Rails 2.1 has just been out a week and so far something that seems to have passed most people by is that it now includes much better caching capabilities, including built-in support for memcached.

Last week I reached the point with an application where I needed to cache some models in memory to get a performance boost and decided to check out the current status of plugins like cache_fu and CachedModel to make sure they’d work with Rails 2.1. It was completely by accident that I stumbled across this innocent looking commit by DHH from start of this year and realised that Rails already had everything I needed!

Read more of this entry

Unsigned integers for MySQL on Rails

Ok, so I’m starting a new Rails application, I’ve spent some time refining my database, I’ve considered storage requirements and performance when choosing the data types for my fields and now I’m ready to create some migrations to implement my design.

And then I’m reminded that, lovely though Rails migrations are, there are two things that really bug me about them: they create signed primary keys and they don’t allow me to easily create unsigned integer columns.

It’s been discussed before, dismissed as an ‘uncommon requirement’ (probably because MySQL is, as far as I know, the only database that uses unsigned integers) and, as far as I can tell, not a lot more has happened. So, while sat out in the garden, enjoying a sunny Saturday afternoon, I grabbed edge Rails from GitHub and decided I’d see if I could do something about it (how’s that for geekyness?!)

Read more of this entry

Another plugin for the toolbox

Following on from Rob's Rails plugin round-up a few months back then another plugin has repeatedly found it's way into our projects - sql_logging.

Read more of this entry

Error fields with a Hpricot twist

The default Rails behaviour for highlighting form fields with errors is to wrap them in a div, so:

<div>
  <%= f.label(:email) %>
  <%= f.text_field(:email, :size => '30') %>
</div>

Becomes:

<div>
  <div class="fieldWithErrors"><label for="user_email">Email</label></div>
  <div class="fieldWithErrors"><input id="user_email" name="user[email]" size="30" type="text" value="" /></div>
</div>

This is great when knocking together a quick prototype but as your site evolves you’ll probably want to customise it. This can be done very easily by using ActionView::Base.field_error_proc, assign a Proc to it either in your environment.rb or, if you’re a modern thinker, in an initializer and you’re good to go.

Read more of this entry

Persistent Storage for Amazon EC2 Is On It's Way..

Good news - persistent storage for EC2 is on it's way - it's already in private beta and will be 'publicly available later this year'.

Read more of this entry

Sponsoring Open Source - Crazy Ideas or a Fresh Way of Thinking?

About a month ago Gregory Brown created a buzz with his blog post about working on open source projects for money. Gregory opens with a "Here’s a crazy idea" - but then outlined an idea that was pretty fresh, and not crazy at all (in my book!). This evolved into a wiki around the subject - an interesting read.

As is usual, it created a lot of discussion on blog sites and also fed into talks of a similar nature that had been happening at TheWebFellas HQ.

Read more of this entry

Choosing a simple, lightweight WYSIWYG editor

So today I found myself in need of a WYSIWYG editor for the admin pages of the site I’m currently working on. I’ve used FCKEditor and Scott Rutherford’s Rails plugin before and Chris has recently been using TinyMCE for a few of our other projects but both of them seemed too heavy, especially when the project requirements only stated a need to apply simple formatting like bold, italic and headings.

Read more of this entry

OpenSolaris Starter Kit - Finally!

There's a few things on my to-do list that repeatedly get pushed to the bottom - one of which is to give OpenSolaris a try - I ordered a Starter Kit a while ago and it popped through the door this morning.

Read more of this entry

Yay! YouTube API Now Supports Upload!

We're currently working on a project where we handle a lot of images and videos. Rather than handle these ourselves, we wanted to make use of the heavyweight's infrastructure where possible - this meant Flickr for images and YouTube for video.. but there was one snag - we couldn't upload video via the API. There were 'hacks' available, but we don't like to build solutions on unsupported features.

Read more of this entry

Hackers love attachment_fu?

I’ve said it before and I’ll say it again: attachment_fu is great Rails plugin! If you’ve never used it before then Mike Clark’s tutorial is the place to start. However there is one problem with attachment_fu that has been bugging me lately and it relates to mass-assignment.

Read more of this entry

ImageScience on Windows without the pain

Back in December I posted about ImageScience and RubyInline on Windows. Turns out I wasn’t the only one trying to get this combination working: according to Google Analytics it has become our second most popular blog entry (for the naturally curious this is the most popular).

Read more of this entry

Archives

  1. July 2008
  2. June 2008
  3. May 2008
  4. April 2008
  5. March 2008
  6. February 2008
  7. January 2008
  8. December 2007
  9. November 2007

Tags

  1. actionview
  2. active messaging
  3. activesupport
  4. aes
  5. akismet
  6. amazon
  7. amazon sqs
  8. apache
  9. api
  10. apr
  11. apr-util
  12. async
  13. attachment_fu
  14. attr_accessible
  15. autotest
  16. availability
  17. aws
  18. backgroundrb
  19. beanstalkd
  20. bindings
  21. bj
  22. branding
  23. bug
  24. cache
  25. centos
  26. cloud
  27. clusters
  28. community
  29. company name
  30. compiler
  31. consultancy
  32. controller
  33. cookies
  34. css
  35. database
  36. defensio
  37. deployment
  38. design
  39. development
  40. dhtml
  41. docrails
  42. documentation
  43. donations
  44. drdb
  45. ec2
  46. encryption
  47. erb
  48. error
  49. events
  50. ezcrypto
  51. fckeditor
  52. feedburner
  53. feeds
  54. filter
  55. flickr
  56. fuse
  57. geekup
  58. geocode
  59. god
  60. growl
  61. hacker
  62. haml
  63. helper
  64. hmac
  65. holiday
  66. hosting
  67. hpricot
  68. html
  69. identity
  70. imagescience
  71. infiniteftp
  72. init.d
  73. italy
  74. javascript
  75. leeds media
  76. linux
  77. logo
  78. mac
  79. markaby
  80. mass-assignment
  81. memcached
  82. mephisto
  83. messaging
  84. migration
  85. model
  86. mod_rails
  87. mod_ruby
  88. mongrel
  89. mongrel_cluster
  90. monit
  91. monitoring
  92. mq
  93. mysql
  94. neon
  95. new site
  96. nginx
  97. observer
  98. open source
  99. opensolaris
  100. openssl
  101. optimisation
  102. passenger
  103. patch
  104. performance
  105. persistence
  106. persistent storage
  107. persistentfs
  108. php
  109. phusion
  110. plugin
  111. plugins
  112. prototype
  113. queues
  114. rails
  115. rails development
  116. rails patch
  117. rails plugin
  118. rails-doc
  119. refresh
  120. rich text editor
  121. rmagick
  122. ruby
  123. ruby on rails
  124. rubyinline
  125. rvideo
  126. s3
  127. s3fs. elasticdrive
  128. schema
  129. security
  130. services
  131. snarl
  132. social
  133. solaris
  134. spam filter
  135. sparrow
  136. sql
  137. sql_logging
  138. starling
  139. starter kit
  140. storage
  141. subversion
  142. svn
  143. swig
  144. sysadmin
  145. tamper
  146. templates
  147. the webfellas
  148. time zone
  149. tinymce
  150. to-done
  151. transcoding
  152. tzinfo
  153. uk
  154. uk rails
  155. unsigned
  156. validation
  157. video
  158. webfellas
  159. webfellows
  160. wedding
  161. welcome
  162. widgeditor
  163. win32
  164. windows
  165. wysiwyg
  166. xen
  167. xhtml
  168. xvm
  169. youtube
  170. zentest
  171. zfs

Projects

Flickr snaps