Marty Haught

Yui4Rails leaving svn

Mon, 28 Jul 2008 22:05:00 GMT

I’ve beaten my head up against the git-svn wall for hopefully the last time. On the Yui4Rails plugin, I’ve been enjoying using github and managing the constant sea of change from new YUI library releases as well as enhancements from two of my projects as well as merging in changes from a couple others. All of this I’ve done on the git side of the house. I struggled to do this efficiently with svn before and once my fellow programmers started to use git, I checked it out.

Now, I’m hardly great with git. I’ve still much git fu to learn. However, I have noticed how easier many things are to do in git, even with my limited knowledge and experience. As most of you will know, I created the Yui4Rails project on Rubyforge as a svn repo. Git wasn’t an option on Rubyforge and I hadn’t tried git out as yet. So to allow me to use the ease of git I used git-svn to bridge the gap and for the most part it was good. I’ve only once before had a fairly challenging conflict and with some irc help, got through it. However, tonight I ran into such a merge trainwreck that I again questioned why am I maintaining a svn repo when I don’t use it? No one else is contributing through svn and the last patch came via a pull request on github. It’s only causing more work for me and I don’t need to do that. I’ve got so little extra time for Yui4Rails at the moment that anything that causes me to waste a couple hours of my free time better be worth it.

So I’ve decided to kick the svn habit for Yui4Rails. I’ve just submitted a request to convert the svn repo to git on Rubyforge. Given that everything else in Rails seems to be switching over to git, I’m not going to resist it. As I’ve mentioned before, if you want the truly up-to-date version go to the github repo. I will continue to maintain zip/tarballs of the plugin for each release on Rubyforge so that will remain. Ciao svn!

Page Event Extension Updated

Sat, 26 Jul 2008 21:01:00 GMT

There have been a few things that have changed with Page Event extension recently in the github repo. First, limited the calendar to showing only published events. I added an upcoming and next tag for events. I also moved from test:unit to rspecs. I haven’t completed the conversion but it’s well underway. Additionally, I added doc to all the tags so you can look up the details in the ‘available tags’ reference in the admin ui. Finally, I pulled some changes from Sean Santry’s fork that adds a format option to the event:date and event:time tags. Enjoy!

Yui4rails and YUI 2.5.2

Sun, 22 Jun 2008 21:30:00 GMT

I apologize for being so silent since RailsConf. It’s been quite busy for me at work and home. I will see if I can get the next official release pushed to svn in the coming weeks. I have not yet looked into the 2.5.2 YUI release but will make sure it’s part of the next release of Yui4Rails. On a side note, I have updated the README in the github repo to be more accurate. If you have any comments or suggestions, please email me.

Yui4Rails at RailsConf

Tue, 27 May 2008 17:27:00 GMT

Just a quick note to anyone interested in Yui4Rails at RailsConf 2008. I have scheduled a Birds of a Feather session for Yui4Rails on Friday night at 9pm. You’re all welcome to come hang out with us and talk about Yui4Rails and what we’re up to in person. Here’s the entry with all the details:

Yui4Rails BOF Session

Otherwise, I’m getting ready to head out to RailsConf. I’ll be there Thursday afternoon. If you want to meet up, please send me an email to coordinate.

Yui4Rails Component Tutorial

Fri, 23 May 2008 19:19:00 GMT

Building YUI components in Yui4Rails

I’m going to go over the process for adding a YUI component into YUI4Rails. The basic philosophy that I have been following is the end result should be a concise, easy to use api for the developer yet allow flexibility for the myriad options that the YUI components offer. Let’s explore this approach with the latest widget that I’ve added, the carousel.

Before we dive into the code, let’s look at how the developer would use the carousel widget on one of his pages.

Using the component

1) Add the yui_includes call to the HEAD section of your layout:

<%= yui_includes :reset, :fonts %>

In the above example, we’ve decided that we also want the reset and fonts css components added to all pages that use this layout. You can just call yui_includes with no arguments.

2) Add the yui_carousel call to the page’s template:

<% yui_carousel("featured_photos", @featured_photos, {:scrollInc => 1, :navMargin => 82, :numVisible => 4}) do %>
    <div class="carousel-prev">
        <div id="prev_arrow"><span class="access">&#171; Left</span></div>
    </div>
    <div class="carousel-next">
        <div id="next_arrow"><span class="access">Right &#187;</span></div>
    </div>

    <div class="carousel-clip-region">
            <ul class="carousel-list">
<%= render :partial => '/photos/featured_photo', :collection => @featured_photos %>
            </ul>
    </div>
<% end %>

Here, we have identified a carousel, featured_photos, that will display a set of four images at once with a scrolling increment of one per click. The first parameter is the id name of the carousel object that we want to use. It is followed by the collection of photos that will populate the carousel list. Next we set several options that differ from the component’s defaults. Finally, the yui_carousel method takes a block which contains the html that you wish to put inside the carousel. Since the carousel control expects very specific html elements to work, I’ve chosen to wrap it but allow the developer to tweak css and html specifics to meet their needs.

Those are the only two steps. Let’s look into what happens under the hood and follow the flow as a component author.

Authoring a component

1) Widget class

The first step for writing a component in Yui4Rails is to write a Widget class. We’ll look at /lib/yui4rails/widgets/carousel.rb as our example.

The intent of a widget class is to take in the required arguments as well as optional ones and output the required pieces of javascript and html that will be required to make the YUI component work.

You start off placing the class into the appropriate module space, Yui4Rails::Widgets::Carousel.

module Yui4Rails
    module Widgets
      class Carousel
        def initialize(carousel_id, collection, options = {})    
                @carousel_id = carousel_id
                @collection = collection
                @options = defaults.merge(options)
                @options[:size] = @collection.size
                render_head_script
        end
    ...

The class’s initialize method requires the carousel_id, collection and a hash of options. We merge the options with default values that are defined in the class as well as put the size of the collection into the options. Finally we call the render_head_script method.

render_head_script is simply a method that contains the script output that will go into the head section of the page.

    def render_head_script
        Yui4Rails::AssetManager.manager.add_script <<-PAGE
        YAHOO.util.Event.addListener(window, "load", function() 
        {
            new YAHOO.extension.Carousel("#{@carousel_id}", 
                {#{@options.keys.map{|key| optional_value(key)}.join(", ")}}
            );
        });
                                                                                                PAGE
    end

We leverage the Yui4Rails::AssetManager’s add_script method to add our script content. This will keep hold of all the head script until the layout is rendered which is handy as it allows us to construct many components before anything is outputted to the page. Also of note here is that AssetManager is a singleton that is referenced through the class method manager. The rest of the content here should be familiar to anyone using YUI components on their own.

The only other methods in the class are private. One is defaults which just contains all the default parameters that I, as a component author, have decided should be automatic in widget’s constructor.

    def defaults
        {
            :numVisible => 3,
            :animationSpeed => 0.5,
            :scrollInc => 3,
            :navMargin => 60,
            :prevElement => "prev_arrow",
            :nextElement => "next_arrow",
            :wrap => true
        }
    end

One note here is that I’ve decided that I want to make a app-wide override for these. So that if you want to use the carousel multiple times on your site and that there are one or more options that you always set you can do it in one place instead of each time.

The other private method is optional_value which will either output the javascript parameters as a hash if they’re present as a key and value in the options hash.

    def optional_value(option, carousel_key = nil)
        carousel_key ||= option
        if @options.has_key?(option) && !@options[option].nil? 
            %\#{carousel_key}: #{@options[option].is_a?(String) ? "'#{@options[option]}'" : @options[option] }\
        else
            "" 
        end    
    end

2) Asset Manager

The asset manager’s role is to give a convenient and unified interface to indicating what YUI resources you will need for your component. Furthermore as we have seen, it gives a place to add custom script that will be outputted into the head section after template processing is complete.

The main thing you’ll need to do here is to make sure the javascript and css includes are handled. The current implementation is ultra simple and will be enhanced in the near future. There are two methods that will look at to understand how to add to the asset manager as designed

    def process_components            
        @yui_stylesheets = []
        @yui_javascript = []

        @components.flatten!

        @yui_stylesheets << "reset/reset-min" if @components.include?(:reset)
        @yui_stylesheets << "fonts/fonts-min" if @components.include?(:fonts)
        add_container_includes if @components.include?(:container)
        add_datatable_includes if @components.include?(:datatable)
        add_charts_includes if @components.include?(:charts)
        add_carousel_includes if @components.include?(:carousel)

        @stylesheets = @yui_stylesheets.uniq
        @javascripts = @yui_javascript.uniq
    end

Process components is where all the javascript files and css files are collected into unique arrays. They are simple strings to the path of the resources as consumed by the stylesheet_link_tag and javascript_include_tag helpers. The path ”/yui/” will be prepended for all. Thus for the reset css file you can see it adds the string “reset/reset-min” into the yui_stylesheets array.

Most likely you will need something like what carousel uses. In this case I wrote a method, add_carousel_includes, to handle it for me. If the :carousel is passed in, it will invoke this method.

    def add_carousel_includes
        @yui_stylesheets << "carousel/assets/carousel" 
        @yui_javascript << "yahoo-dom-event/yahoo-dom-event" 
        @yui_javascript << "animation/animation-min" 
        @yui_javascript << "container/container-min" 
        @yui_javascript << "carousel/carousel_min"    
    end

As you can see here I add in each css and js file needed into their respective arrays. Since these arrays are uniq’d later on we don’t need to worry too much about duplication.

The eventual design will not require you to do anything in here. You will simply pass the resource names (as symbols) in and it will determine dependencies and include them, in the most optimal way. Thus for Drag n Drop you’d be able to pass in :dragdrop. This will be identical to what is defined in YUI Loader as the YUI module names. It would then make sure these dependencies are there: yahoo-dom-event.js, dragdrop-min.js. I will look to make sure it minifies and compresses based on site-wide preferences and such.

3) Helper method

The last important piece is writing a helper method to make it convenient for the developer to invoke. In this case I’ve added the carousel’s method to /lib/yui4rails/helpers_extension.rb.

    def yui_carousel(carousel_id, collection, options = {}, &block)
        asset_manager.add_components :carousel
        carousel = Yui4Rails::Widgets::Carousel.new(carousel_id, collection, options)

        concat(%{<div id="#{carousel_id}" class="carousel-component">}, block.binding)
        yield block
        concat("</div>", block.binding)            
    end

In this helper, you can see we take in the arguments that we first talked about. The first order of business is it calls asset_manager.add_components with the key name that AssetManager’s process_components is aware of. There is another helper module, include_extension.rb, that provide a convenience method to get the AssetManager’s instance via asset_manager. We use it here but you don’t have to. Additionally, you could call add_components from the initialize method of the Widget class.

The next thing I do is construct the widget class passing through the parameters it needs. One nice thing with helpers is you could provide multiple helpers that use the same widget class varying their parameters. Finally, I output the required div as a wrapper around the block that they specified.

4) Testing

In reality, I wouldn’t do testing as the last step in my workflow. However, I wanted to mention it after you have seen the different parts and how they fit together. Testing, or specs, in this plugin have not been as strong as I would have liked. Part of that is it’s challenging to test this sort of code. Javascript is not something you can 100% test in a framework like Rails with any confidence. Other scripts, browser differences and html will keep it from being so simple. That said, you can test some things. Let’s look at /spec/models/carousel_spec.rb to see an example of what I’ve done so far.

We’ll only look briefly at the render_head_script describe block.

    describe ".render_head_script" do
        before(:each) do
          @carousel = Yui4Rails::Widgets::Carousel.new(@carousel_id, @collection)
        end

        it "should register the code as an anonymous function on the page load event" do
            @carousel.render_head_script.should match(/YAHOO\.util\.Event\.addListener\(window, "load", function\(\)/)
        end

      it "should render a YAHOO.extension.Carousel with our carousel_id" do
        @carousel.render_head_script.should match(/new YAHOO\.extension\.Carousel\("#{@carousel_id}",/)
      end

        it "should set the collection size into the size option" do
            @carousel.render_head_script.should match(/size: #{@collection.size},/)
        end

        it "should include default options" do
            @carousel.render_head_script.should match(/numVisible: 3,/)
        end
    ...

You can see I’m listing several specifications that I expect for the output to be valid. I use regex matches to confirm parts of the script are there. Clearly, this will not guarantee that the script is valid javascript but it will catch is major, important pieces are missing and that’s good enough for me here. I would suggest you take a similar approach.

That is essentially it for the steps you will need to take as a component author. As this project has grown organically out of YUI integration that I’ve used on a couple of my projects, it’s likely that we’ll need to enhance things as we go forward. The AssetManager is a great example.

One last thing to note on AssetManager. There is a class method called reset that will nil out the class instance of the manager. This is automatically prepended to your before filters so you never have to worry about stale AssetManager state biting you. The main motivator for this behavior is to allow the AssetManager instance to be available to any object that wishes to call it whether it be a template helper method or isolated Yui4Rails class that has no reference to the template or its variables.

Hopefully, this walk through will give you more confidence on writing components. Go forth and add your favorite components as you will.

Yui4Rails trunk updates

Tue, 13 May 2008 22:09:00 GMT

I’ve just pushed up my latest changes for Yui4Rails to the subversion trunk from my git repository. There have been some major changes under the hood and it will break if you don’t make a simple code change and you get the latest from the trunk. The zip and tarball versions, found on Rubyforge, are not affected by these yet. We’ll look for more testing and some hardening before we roll this out as a new release.

So how do you start to use the latest changes, you ask? Well, go ahead and pull the latest from the subversion trunk::

svn://rubyforge.org/var/svn/yui4rails/trunk/

Two primary changes are needed to make it work, AFAIK. First, you will need to add one line in the head section of your layout/template:


<%= yui_includes %>

I would put it after any other javascript includes such as the Rails defaults.

Second, you most likely have include_yui includes that need to be updated such as this:


<%= include_yui :datatable, :charts %>

These no longer need to output anything so you can change them to this:


<% include_yui :datatable, :charts %>

Those changes should get you working on the trunk again. I will be posting a more complete tutorial on how to use the new features as well as approaches for developing new components in the plugin. For now I wanted to get this out there so you can start playing with it, without needing git.

Page Event Extension Released

Sat, 03 May 2008 22:46:00 GMT

The event extension (for RadiantCMS) that I have been talking about and working on for nearly half a year has finally been released. You can see it in action on Boulder Ruby’s calendar page. This extension has been on my list ever since I created the Boulder Ruby site in Radiant. I will also be using this on the website for my children’s school. Loren Johnson already had done an event calendar extension but it was tied to an iCal feed and this was not how I wanted to manage the events. So this event extension is all about tying one of your pages to some date and time.

I currently have the extension hosted on github. Being the first release it should be considered alpha. Over the next month I will be fixing any bugs and improving the UI. The README in the project has detailed notes on installation and usage but I’ll outline how to install and use it briefly.

Installation

NOTE: The extension is tested against 6.6 though it might work for some of the older 6 releases. I have no intention of adding support for any release prior to 6.6.

You’ll need both the Shards extension and the Calendar Date Select plugin before you can use Page Event.

You have two options for installing the extension:

1) Use git to clone the extension


git clone git://github.com/mghaught/radiant-page-event.git vendor/extensions/page_event

2) Click the download button on Github to get a tarball of the extension. At that point just expand the tarball into a vendor/extensions/page_event directory of your Radiant application.

Once you have the code installed you’ll need to run the migrations and update commands. Here’s an example of those commands for the production env:

  rake production radiant:extensions:page_event:migrate
  rake radiant:extensions:page_event:update

After a restart of your server you’ll be ready to rock, event-style.

Usage

The most visible feature of the extension is the monthly calendar which will display all events for the current month. You can get this by using the <r : calendar /> tag on whatever page you want. It currently takes no options so it’s stuck displaying a single month defaulting to the current month. It does include next and previous month navigation. It also displays the title of the page (with an event) that is a url to that page as well as the time. I’m sure eventually I’ll expose more flexibility on this.

Along with the main calendar tag there are two event specific tags for displaying formatted date and time strings:

  <r : event:date />
  <r : event:time />

On the admin side, you’ll notice that all pages now have an event date field with calendar select widget next to it. This is how you set the date and time for your event. If it’s blank, the page has no event. You do need to save the page to have it take effect. You’ll also get a new tab next to pages called Page Event. There you can view a month’s view of all events in your pages.

What’s Next

I have a short road map for upcoming features and enhancements. First, I plan to get more use out of the extension on two sites of mine. Up until now it’s just been in development mode on my laptop. I’ve already noticed something tonight that will need attention. Status is ignored in the calendar tag. This means that hidden or draft events will show links in the calendar. I’ll change that to only display published events in the calendar. Second, I plan to do some refactoring and making the page event tab more attractive. It’s functional but won’t win any UI awards. :) Further down the road, I’ll be extracting the event date concept into its own model so you can create a start and end time to your event and assign it to multiple pages. I’ll also be interested in getting any feedback from others who might find this extension useful.

Feel free to watch or fork the project on github. You can also email me or the Radiant list to discuss things about the extension. Enjoy!

Upgrading Rubygems

Fri, 02 May 2008 17:23:00 GMT

This week I’ve been spending much of my free time getting the release of my new Radiant extension wrapped up. I’m in the final stages of that right now so expect a post soon on those details. So as part of this process I wanted to install the new extension on an external facing Radiant system, such as Boulder Ruby. I’ll reference it so people can see it in action. In order to do this I need to upgrade several things. First, I need to upgrade BoulderRuby to Radiant 6.6. Radiant 6.6 is built on Rails 2.0 and also needs the newer version of Rubygems. No problem, right? Well it turned out not to be so!

So I tried to simply update the Radiant gem. I tried multiple times but it hung on me. More specifically it got to this line and just stayed there, forever (well, until I killed it).

Bulk updating Gem source index for: http://gems.rubyforge.org/

Usually, it might take 5-15 seconds or so for this line on my development system. I wasn’t sure what was happening so I decided to skip the gem install and just manually bring up a tarball of my local BoulderRuby radiant upgrade. Fine except I could run rake as it needed a newer version of Rubygems. Updating Rubygems also hung on the same command. wtf?!?

I then manually upgrade Rubygems as I wanted to be on the newest release after going through all the trouble of updating my system. Then moved on to upgrading Rails which Radiant needs. Then Rails was hanging on the bulk updating line. By this point Slicehost is emailing me telling my server has been going heavy into swap. After some googling it appears that my issue may be the 256 MB Ram limit my meager slice has. Yikes! I was able to install and update gems before, what’s the deal now?

So I got around this by manually pulling down the gem files and installing with this command:


sudo gem install --ignore-dependencies --local activeresource-2.0.2.gem

It took me several tries to get to this workable solution. Rubygems doc doesn’t really talk about how to use all the options available and several different combos still got stuck on the bulk updating line. I’m guessing that upgrading my slice’s memory to 512 might make the difference but that just seems wrong.

YUI4Rails release 0.1.1

Fri, 18 Apr 2008 21:16:31 GMT

I’ve just posted the newest release of YUI4Rails, 0.1.1. I’ve upgraded the plugin to YUI 2.5.1 and have applied Bryan Donovan’s datatable patch. Several of you have contacted me on how to take things forward. In effort to make things a bit easier I’ve made a git repository of the plugin that is cloned off the RubyForge svn repo. You can find it here: http://github.com/mghaught/yui4rails/tree/master

We’ve got some new components that we’ve been developing lately. Carousel, lightbox and tooltip are close to being ready. One thing that has come up from this is that we’ve got some limitations with the current approach of including dependencies. I’m working on a new prototype that would ease this pain and output much nicer html/script tags. I’ll be pushing it to the github repository either tonight or this weekend. It will be in its own branch for the time being.

The basic idea is that you would have one helper call in the head section of your layout. You could declare components that all pages would need such as reset or fonts. Then in each individual template you can invoke the widget helpers as needed. They would in turn call an AssetManager class to indicate what dependencies they have on YUI assets. Additionally, javascript code that belongs in the head section will be outputted there, even though you are invoking it throughout your templates or partials. The end result should be cleaner html and javascript with less hassle calling helper methods.

I have several other things on the horizon for the plugin. First, several other developers have contacted me about contributing to the plugin so look for those additions in the coming weeks on the github repository. As we get closer to a stable release we’ll push up to the Rubyforge svn repo and post new release files. Part of this process will involve more discussion on YUI4Rails’ mailing list on design philosophies so we can keep a cohesive plugin. I welcome your comments and suggestions so we can build the best possible plugin. Second, we’re going to start working on improving documentation, tutorials and an official YUI4Rails website with access to all of it. It’s time to make this plugin more user-friendly. The other important thing is to have this plugin well tested. While the nature of js based widgets makes testing incredibly difficult, I think we can provide some test coverage for how our helpers operate. I’ll try to expand on this in another email/blog post in the future. So enjoy this new release and don’t be afraid to join the mailing list or fork the github repo.

MountainWest RubyConf 2008 Reflections

Wed, 02 Apr 2008 22:20:37 GMT

It’s been almost a week since the MountainWest RubyConf 2008. I had a great time there and if I hadn’t been under the weather with a sore throat I would have had an awesome time. The talks were some of the best I’ve seen, especially for a conference only costing $100 for two days. I was going to post this earlier but I wanted to wait for some of the talks to be available via video.

So what were the highlights? First, there was several cameos of Darth Vader and his colorful sombrero. Then Rick Astley decided he should make several appearances. You can catch them yourselves in the videos of the presentations. Not many are up at this point but they’ll get there eventually.

Evan Phoenix got things started with his overview on Rubinius and the community. This was a cool talk and if nothing else presented some interesting ideas on how to organize an open source community around a project. It made me want to dive right into the Rubinius code and submit some patches! Ezra’s talk followed and covered Merb. I’ve been pondering using Merb in several cases and I was impressed to see how easy it could be to port some of our services to it (from Rails).

Now probably the coolest and most entertaining talk that totally came out of the blue was Giles talk on code generation. I was blown away. I definitely want to use Rubinius and Ruby2Ruby to do some cool jedi tricks now. Giles comments on the the self image of the Lisp community was just hilarious! If you only watch one video from this conference check this one out.

Several topics seem to run deep through the talks. Metaprogramming and more of an understanding of the dynamic nature of Ruby was explored several times. Patrick Farley’s talk on Ruby Internals was one such example that was very illuminating. On an interesting side note, I was reading Pro JavaScript Design Patterns by Harmes and Diaz on the the flight to and from the conference. The first several chapters of that book also cover the dynamic nature and internals of JavaScript and reminded me very much of Patrick’s talk. Exploring the prototype chain of a JavaScript object and how functions resolve based on how you construct/set those parent references. Very cool stuff indeed.

Another topic of interest was DSLs (which seemed to get mentioned in the metaprogramming talks too). Joe O’Brien’s talk focused on DSLs and I found enjoyable. Git was also mentioned a lot and it felt like a git lovefest. After seeing how people are using it, I now get it (ha ha). I was going to use git anyway but now I’m very excited about it. I’ll be converting my personal projects to use it now. I’m also tickled to see the git-svn library to allow me to use git with a subversion repo. Anyway, enough on that.

The other thing that I found interesting was a constant, but subtle, anti-rails sentiment. Don’t get me wrong, I think everyone’s appreciative of what Rails did and how many great ideas are baked in there. However, it seemed that people are recognizing that there are some alternatives out there that are superior. Sequel and DataMapper were both mentioned as alternatives to ActiveRecord. Merb and it’s focused, smaller footprint compared to Rails. I’m not going out and dumping all my Rails apps but I’m glad to see the Ruby ecosystem maturing with other alternatives that are still going and ripe with enthusiasm.

I think the other 160 people that attended also had a great time. What a bargain it was. I’m starting to think that regional ruby conferences are where it’s at. I’ll be attending RailsConf 2008 but I’m not quite as excited. It may simply be too big now, too corporate. We’ll see. At least most of my friends in the community will be there. RubyConf is probably still the best conference but I think if you haven’t considered the regional Ruby conferences you might want to look into one close to you. There are many of them now. Oh well, enough on all that. It’s late and I have a Radiant extension that needs some finishing touches.