CITguy

How I Start My Gems

2014-07-02T17:54:00-05:00

Introduction

I’ve built quite a few rubygems and I’d like to share how I begin my gems nowadays.

For the purposes of this article, assume that we want to build a gem called bad_math. This article will not cover how to build a gem, merely how to make it easier on the developer. If you’ve not built a gem before, I recommend watching Railscast #245: New Gem with Bundler.

Prerequisites

bundler

Generate Gem Template

Yes, I could build the gem directory/file structure manually, but that’s too slow, and bundler makes it hella easy. (I do recommend doing it manually at least once to appreciate what bundler does for you.)

Running bundle gem bad_math will output something similar to the following:

[~/workspace/gems] $ bundle gem bad_math
     create  bad_math/Gemfile
     create  bad_math/Rakefile
     create  bad_math/LICENSE.txt
     create  bad_math/README.md
     create  bad_math/.gitignore
     create  bad_math/bad_math.gemspec
     create  bad_math/lib/bad_math.rb
     create  bad_math/lib/bad_math/version.rb
Initializing git repo in ~/workspace/gems/bad_math

Look at that! I’ve got a template and all I have to do is fill in the blanks and start coding.

Modifying the gemspec

For additional reading, you can view the gem specification reference to see all of the various configuration options that are available to you within this file. For the sake of this article, I’m only concerned with adding yard and redcarpet to my development dependencies.

  spec.add_development_dependency "yard"
  spec.add_development_dependency "redcarpet"

These gems work together to provide a very straightforward way of documenting my gem as I build it. I’ve found that if I have the capability to document from the get go, I’m more likely to actually write documentation, because nobody likes an undocumented gem.

Rakefile Addition

1
2
3
4
5
6
7
task :console do
  require 'irb'
  require 'irb/completion'
  require 'bad_math'
  ARGV.clear
  IRB.start
end

After reading the short “7 Lines Every Gem’s Rakefile Should Have”, I’ve been adding this to my gems ever since. As Ernie states, nothing beats playing around in the console, and no you don’t need to use IRB. You can use the console of your choice. The point is to start it up a console and load your gem so you can play around with it.

Configurable From the Start

I’ve written gems that started off with what I thought would be rock solid functionality, but find out later down the road that it’s more flexible than I’d originally thought. This is the reason why the first functionality I add is a Configuration class. With configuration set up from the start, it’s easier to stay flexible with functionality. Believe me, it’s a pain in the ass to add configuration functionality after the fact that your logic has mostly been written.

lib/bad_math/configuration.rb

1
2
3
4
5
6
7
8
9
10
11
module BadMath
  class Configuration
    # These are our configuration options.
    attr_accessor :nonesuch

    def initialize
      # default the values here
      @nonesuch = nil
    end
  end
end

lib/bad_math.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require "bad_math/version"
require "bad_math/configuration"

module BadMath
  # Customize configuration for library
  # @yieldparam [Configuration] config
  def self.configure
    yield self.config if block_given?
  end

  # @return [Configuration]
  def self.config
    @@config ||= Configuration.new
  end
end

So now if I need to use a configurable ‘foobar’ option, I will:

Add the option to the Configuration class (if not already) (attr_accessor :foobar)
- I use attr_accessor because I want to be able to modify the value at any point.
- If I need to keep a value from changing, I’ll use attr_reader instead.
Set a default value (Configuration#initialize: @foobar = "")
Use it by calling BadMath.config.foobar
PROFIT!!!

User Configuration

1
2
3
4
BadMath.configure do |cfg|
  cfg.nonesuch = "I'm not here"
  cfg.foobar = "bizbang"
end

Summary

Boom! Bundler to flesh out the boring templating, yard/redcarpet for simple documentation, and a simple configuration setup.

Happy Coding!

How I Version APIs

2014-05-30T18:37:00-05:00

Sick of having API versioned paths in your rails app? Try using Action Pack Variants instead.

The following is a simple example on how to implement this functionality with a Rails 4.1 application.

Set up your routes

Configure your routes as you would for a JSON endpoint.

1
2
3
4
5
6
# config/routes.rb
Rails.application.routes.draw do
  scope(format: :json) do
    get :hello, controller: :sandbox
  end
end

Define your custom Vendor MIME type

Try to use a definition that has very little chance of interfering with other possible API services. Here, I use the java naming notation (com.mydomain.api) to associate the MIME type specifically with my domain.

1
2
3
# config/initializers/mime_types.rb
# Define a custom Vendor MIME type
Mime::Type.register "application/com.mydomain.api-v1+json", :v1json

request.variant

It is now a simple matter of setting the request.variant to the proper variant name for the new MIME format (lines 6-8).

1
2
3
4
5
6
7
8
9
10
11
# app/controllers/sandbox_controller.rb
class SandboxController < ApplicationController
  def hello
    respond_to do |format|
      format.json # hello.jbuilder
      format.v1json do
        request.variant = :v1 # hello+v1.jbuilder
      end
    end
  end
end

Define your variant views

Since we used :v1 as our variant name, we will need a hello+v1.jbuilder variant to go along with it.

1
2
3
4
5
# app/views/sandbox/hello.jbuilder
json.hello "from default json"

# app/views/sandbox/hello+v1.jbuilder
json.hello "from v1 json variant"

Setup your requests

Finally, your requests will need to send the proper Content-Type header to request the correct response variant.

1
2
3
4
5
// GET [Content-Type:"application/json"] /sandbox/hello
{ "hello":"from default json" }

// GET [Content-Type:"application/com.mydomain.api-v1+json"] /sandbox/hello
{ "hello":"from v1 json variant" }

Benefits

A huge benefit of doing this way would be the lack of needing to maintain multiple nested, versioned routes and their associated controllers and views. This reduces your code footprint as well as routing complexity. Simply modify your output based on the versioned MIME requested.

Happy Coding!

OMG! magicExcel

2010-09-22T07:00:00-05:00

Have you ever had trouble wading through the ColdFusion 9 documentation pertaining to the new CFSpreadsheet Functions? Have you ever gotten frustrated with generating Excel documents with ColdFusion? Are you tired of boring spreadsheets? Don’t you wish there was an easier way to do it all?

You’re in luck! A new RIAForge project called “magicExcel” makes all this super simple. Using a custom tag, all you have to do is write HTML.

Wait! What?

Yes, that’s right! All you need to create sleek spreadsheets is knowledge of HTML tables.

Don’t believe me, check it out for yourself at http://magicexcel.riaforge.org.

Happy Coding!

How I Create Custom CFML Tags

2010-09-13T07:00:00-05:00

While I was cleaning up some code in a portal of ours, I realized that I could condense some of the code by combining a variable assignment with a custom tag attribute assignment.

To make things simple, the tag I am trying to optimize creates a database record with a note assigned to it.

1
2
  <cfset notes="A ton of html code here.">
  <cf_my_tag notes="#notes#">

The issue is that this code wouldn’t necessarily add a note in the same manner, every time. There might be times where I have to build the notes in a loop before I run the tag. Then there are times where I want to run the tag and NOT add a note. Also, I might want to define the note directly in the tag contents.

So here are the requirements for my new custom tag:

The tag must be willing to accept an attribute named “notes”
The tag must be willing to run without defining “notes”
The tag must be willing to transform its contents into “notes”, if it is not empty.

With the above constraints in mind, here’s what I came up with.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<!--- Content of my_tag.cfm --->
<cfscript>
  param ATTRIBUTES.notes = "";
  if (ThisTag.hasEndTag) { // Closable Tag
    if (ThisTag.ExecutionMode EQ "start") {
      // ThisTag.GeneratedContent is not set yet.
    } else {
      // This is the best place to execute code
      // All possible 'ThisTag' variables are defined.
      if (ThisTag.GeneratedContent NEQ '') {
        // GeneratedContent takes priority over attribute
        ATTRIBUTES.notes = ThisTag.GeneratedContent;
      }
      engage();
    }
  } else {
    // Self-standing Custom Tag
    engage();
  }
</cfscript>

<cffunction name="engage">
  <cfscript>
    // Capture Generated Content
    // (if we need to refer to the original content)
    LOCAL.content = ThisTag.GeneratedContent;

    // Prevent browser display of GeneratedContent
    ThisTag.GeneratedContent = "";
  </cfscript>

  <!--- Do Stuff Here --->
</cffunction>

This setup fulfills all three requirements:

I can refer to the ATTRIBUTES.notes variable to insert my note.
I don’t need to define ATTRIBUTES.notes as it is param’ed at the top of the tag.
If I have a closing tag with a non-empty string for its GeneratedContent, the ATTRIBUTES.notes variable will be overwritten with the GeneratedContent. This works for self-closing tags as well.
It also allows me to place my logic into a single function rather than splitting it up in an if..else block.

So there you have it. A simple solution to create a custom tag with flexible closing tags.

Happy Coding!

Gotchas: cfsavecontent and cfoutput

2010-08-29T07:00:00-05:00

I was playing around with cfsavecontent to generate dynamic HTML variable values for use as an argument to a function when I came across an interesting behavior regarding the tag. The issue I ran was that Coldfusion was giving me an error that the variable saved by cfsavecontent was not defined when I was trying to output the value. Take a look at the code below:

This code will produce a “Variable not Defined” error in ColdFusion at line #5.

1
2
3
4
5
6
<cfoutput>
  <cfsavecontent variable="foo">
    Gozirra!
  </cfsavecontent>
  #MyFunction(foo)#
</cfoutput>

The reason for this is because the cfsavecontent isn’t set until the cfoutput block closes. Here’s the ugly fix.

1
2
3
4
5
6
7
8
<cfoutput>
  <cfsavecontent variable="foo">
    Gozirra!
  </cfsavecontent>
</cfoutput>
<cfoutput>
  #MyFunction(foo)#
</cfoutput>

Happy Coding!