Happy new year!  I hope you’ve all had a great start to 2012 — and what better way to kick the year off than with a new version of Koala?

Goodbye, REST API, someday

Facebook has finally ported over the last of the REST API functions to the Graph API, meaning that anything you can do with Facebook you can do through the newer interface…and that it’s time for them to deprecate the REST API.  No need to rush — the older interface will still be around for a while and Koala of course will support it till the end — but you should start migrating over if you’re still using any REST API calls.

Documentation!

Koala is now completely documented; information on every public method and class is available on rubydoc.info.  I know everyone loves rummaging around in source code, but if ever you feel like you just want a concise, useful writeup of the methods available to you, check it out here.

Other improvements

Here are the biggest changes since the last release:

• New OAuth#url_for_dialog method creates URLs for Facebook dialog pages
• New API#set_app_restrictions handles JSON-encoding app restrictions
• New GraphCollection.parse_page_url now exposes useful functionality for non-Rails apps (see this issue)
• Utils.deprecate only prints each message once (no more spamming!)
• OAuth#url_for_access_token and #url_for_oauth_code now include any provided options as URL parameters
• OAuth#get_user_info_from_cookies returns nil rather than an error if the cookies are expired (thanks, herzio!)
• TestUsers#delete_all now uses the Batch API and is much faster
• Fixed bugs, reorganized file and class structure non-destructively, expanded/improved test coverage

The complete changelog is here, and the diff since 1.2.1 is here.

What’s next

Nothing much, actually.  Koala is stable and recent Facebook changes haven’t required any new code on our end (which we’re very excited about).  We’ll keep an eye on the FB developer blog and update Koala as the API changes; in the meanwhile, feel free to submit any pull requests if there’s code you want to add or improve.

Have a great 2012!

Alex
http://github.com/arsduo/koala

Fresh like a crepe off the pan comes Koala 1.3rc2 to fill your stomach and brighten your day. (The holidays really seem to bring out the food imagery, don’t they?)

Documentation!

Koala has always had a thorough wiki, but until now you’ve had to look at the source code to see what methods are available and what they do.  No more!  The library is now completely documented; information on every public method and class is available on rubydoc.info.  If you don’t feel like rummaging through the source code for the method signature of a particular method, you no longer have to.  (Not that there’s anyone here who doesn’t like digging through the code of their libraries, I’m sure.)

Winter cleaning

With the holidays approaching and the relatives coming over, it was to give Koala a long overdue housecleaning.  The lib/koala/ directory was getting a bit crowded, so I’ve reorganized, moving a number of files into the new the api/ and http_service/ subdirectories.  I’ve also updated the class structure largely to match, putting classes and modules in more logical places.

Don’t worry, though — for each move there’s an alias to ensure your existing code doesn’t break, and there’s even a legacy spec to really ensure all the old references work.  (If you’re directly referencing any of Koala’s more internal classes in your code — MultipartRequest,  Response, UploadableIO, BatchOperation, or GraphCollection — check out the legacy spec for more details.)

Other updates since 1.3rc1

• RealtimeUpdates#subscription_path and TestUsers#test_user_accounts_path are now public methods
• TestUsers and RealtimeUpdates methods now take http_options arguments
• All methods with http_options can now take :http_component => :response for the complete response object
• Fixed bugs in RealtimeUpdates and TestUsers

Installation

As always:

[sudo|rvm] gem install koala --pre

Or with Bundler:

gem "koala", "~> 1.3.0rc2"

What’s next

Assuming I don’t come up with any other projects like documentation and cleanup, I’ll release 1.3 soon.  After that, we’ll just kick back, enjoy the holidays, and update as needed to stay current with the Facebook API.

Have a great week,

Alex
http://github.com/arsduo/koala

wooo

I’m happy to announce the release of Koala 1.3.0rc1!

New Features

1.3.0rc1 provides support for several new Facebook features, a number of bug fixes, and other improvements:

• API#set_app_restrictions uses the new Graph API to set Facebook app restrictions
• OAuth#url_for_dialog builds the URLs for the various Facebook dialogs
• GraphCollection.parse_page_url now exposes useful functionality for non-Rails apps
• OAuth#url_for_access_token and #url_for_oauth_code now include any provided options as URL parameters, allowing you to specify display and other options
• API#fql now uses the Graph API FQL endpoint internally
• Utils.deprecate only prints each message once (no more spamming)
• Expanded/improved test coverage

The changelog is here, and the complete diff since 1.2.1 is here.

Mockfacebook

If you haven’t seen Ryan Barrett’s mockfacebook,  a standalone HTTP server that implements Facebook’s FQL and Graph API, check it out.  It’s a great tool for testing your application against a realistically-mocked subset of the Facebook API, and it’s really easy to use with Koala.

Koala’s on Facebook and Twitter!

Follow Koala on Facebook and Twitter for SDK updates and occasional news about Facebook API changes.

Installation

As always:

[sudo|rvm] gem install koala --pre

Or with Bundler:

gem "koala", "~> 1.3.0rc1"

What’s Next

We’ll be releasing 1.3 later this month, assuming no big bugs are discovered.  After that, we’ll continue updating Koala as the Facebook API continues to change and evolve.

As always, if you have any ideas, issues, or suggestions, feel free to let me know on Github!

Have a great week and happy coding!

Best,

Alex
http://github.com/arsduo/koala

wooo

Hey everyone,

I’m excited to announce the release of Koala 1.2!  This is a big update with a lot of cool features, plus support for Facebook’s upcoming authentication changes.

Read through this rather long announcement at your leisure and enjoy the new version

October 1st

Koala 1.2 supports all of Facebook’s new authentication schemes, which will be introduced on October 1, 2011; the old Javascript library and older authentication schemes will be deprecated at the same time.  If you have the appropriate calls to get_user_info_from_cookies (apps using the Javascript SDK) and/or parse_signed_params (for Canvas and tab apps), your application should work without a hitch.

To test your application ahead of time, upgrade to Koala 1.2 (see below) and configure your application according to Facebook’s OAuth 2.0 and HTTPS Migration guide.

Note: in their new secure cookie format, Facebook provides an OAuth code, which Koala automatically exchanges for an access token. Because this involves a call to Facebook’s servers, you should consider storing the user’s access token in their session and only calling get_user_info_from_cookies when necessary (access_token not present, you discover it’s expired, every 30 minutes, etc.). Otherwise, you’ll be calling out to Facebook each time the user loads a page, slowing down your site.

Faraday

With 1.2, Koala uses the Faraday library to make HTTP requests, replacing our homebrew Typhoeus and Net::HTTP adapters. This is a big change, so let’s go over it in detail.

What’s this about?

Faraday is a modular framework, patterned on Rack, which makes it easy to control how your app makes HTTP requests.  By switching to Faraday, we get Koala out of the business of choosing which libraries and features to support, giving you more choices and letting us focus on building the best Facebook library we can.

How does this affect me?

Good news! Based on the 1.2 betas, this change should be non-breaking for almost everyone. All the old settings are still supported, though you’ll see deprecation warnings. There’s now only a single Koala::HTTPService module, which handles all communication.

Almost everyone?

Since Faraday settings are global (affecting other gems that use it, like Twitter), Koala no longer uses Typhoeus by default.  To use that or any other supported library instead of Net::HTTP (the default), just set the default Faraday adapter:

# this could go in an initializer
Faraday.default_adapter = :typhoeus

Also, if you’re hooking directly into Koala’s HTTPService framework, you’ll probably have to make some changes; check out the Extensions wiki page to learn more about the new internals.

People like options, right?

Faraday gives you a huge range of options, which you can provide either per-request or globally by setting the new Koala::HTTPService.http_options hash. The format for the hash maps directly to what Faraday expects, so if you haven’t used Faraday, check out the Koala wiki for some examples.

We still support all the old individual options on Koala.http_service (proxy, timeout, etc.), which read from and write to the new hash.

Even more sweetly, with Faraday you can write your own middleware to really fine-tune how your requests are made.  (To take just one example, I recently wrote a module to log and analyze Facebook requests made through Koala — easy as pie.)  Koala provides a default middleware stack with everything you need, but you can specify your own using Koala::HTTPService.faraday_middleware.

Learn more

For more information and a complete list of how to migrate old settings, check out the HTTPService wiki page. If you have any questions, feel free to write to the Koala user’s group.

API

Koala::Facebook::API class is now the main API class, containing both Graph and REST API methods. Since the GraphAndRestAPI class showed it’s possible to offer all methods from one object, there’s no reason to force you to keep track of and instantiate three different classes to use the Facebook API. All three old classes are now aliased to API, and will remain available for the foreseeable future.

api = Koala::Facebook::API.new(my_token)
api.get_object("me")
api.fql_query("select first_name where uid = me()")
# you can even use the new Timeline API
# see https://developers.facebook.com/docs/beta/opengraph/tutorial/
@graph.put_connections("me", "namespace:action",  bject => object_url)

Other changes

• Koala is now on Travis, passing all tests under JRuby, Rubinius, and REE, as well as Ruby 1.8.7, 1.9.2, and 1.9.3!
  
• (My favorite update:) The live test suite now runs by default against test users, so you can run it as frequently as you want without having to update facebook_data.yml.
• To run it against a real user, add your OAuth token/session key/OAuth code to the YAML file.
• TestUsers#update lets you update the name or password of an existing test user
• API.get_page_access_token lets you easily fetch the access token for a page you manage
• API.put_picture now accepts URLs to images in addition to files
• GraphCollection use is smarter, fixing a problem with the Ads API

Check out the changelog for a complete list of changes. The diff since 1.1 is available here.

Thanks to…

Thanks to marcgg, johnbhall, and Will S. for their help with bugs and in keeping up with Facebook changes, and to Chris and everyone at Context Optional for their support, help, and feedback.

Installation

As always:

[sudo|rvm] gem install koala

Or with Bundler:

gem "koala", "~> 1.2" 

What’s Next

With 1.2 out we’ve completed most of the work we had planned for Koala; in the immediate future we’ll be working on a few remaining features, bug reports, and keeping up with Facebook (did we mention Koala already supports publishing to the Timeline?).

If you have any ideas, issues, or suggestions, feel free to let us know on Github.

Have a great week and happy coding!

Best,

Alex and the Koala team
http://github.com/arsduo/koala

Extreme Specificity

So, another project that I am working on has some specificity issues. Take a look at this selector:

.col-left div.topic-unit ol li div div.topic-unit-ol-image div

The stylesheet uses these types of selectors everywhere. The problem is that if someone comes in and tries to add a “div” as a child to the last “div”, they need to reuse the entire selector and add another bit to the end or there is a chance that their styles will be overriden by one of the previous “div” selectors.

Using element level selectors are good for certain situations but mainly for adding just a bit more specificity. A solution would to be to just use the classes from above to specify where you are at.

In my humble opinion, I find this to be a little excessive. This tells me that the page has some pretty specific and complicated CSS going on. More to the point, I feel pages that contain such selectors need some massive refactoring to simplify selectors.

Today’s wisdom: Keep it simple

Font-size and Inheritance

I’ve been working on this project recently and have had some problems with font-size inheriting. After a few minutes of investigation, it turns out that the following rule was being declared (unfortunately in a place where I can not touch it):

html, body, div, p, h2, h3, h4, ul, ol, span, a, form, img, li { font-size: 12px; }

I believe this was a desire for a CSS Reset. Unfortunately, this declaration forces all those elements to have a font-size of 12px. It is easily possible to override this style with more specificity. The overall problem, however, is the amount of overrides needed to change an entire area’s font-size.

For example,
Say you had that CSS and this HTML.

<div id="navigation_area">
<span class="title">Nav Title</span>
<p class="witty_title_description">I am witty</p>
<div id="navigation_area">
<a href="somepage.html" class="navigation_link">Some Nav Link</a>
</div>
</div>

My desire is to set the entire Navigation Area to have a font-size of 14px. When I apply the following style nothing happens

#navigation_area { font-size: 14px; }

Because each element has been assigned a value of 12px in that reset style, I would have to reapply a font-size specifically to each of them to override it. Like so:

#navigation_area div { font-size: 14px; }
#navigation_area span { font-size: 14px; }
#navigation_area p { font-size: 14px; }
#navigation_area a { font-size: 14px; }


Our canon decrees, for good reason, that font-size should inherit.

Today’s wisdom: Keep inheritance functioning in your stylesheet!

I have been wading deep, recently, in other people’s CSS and dealing with the little peeves that I have run across. I decided to make a trial run at series of quick entries entitled “My CSS Wishlist.” They will be titled as such and have a nugget of wisdom within.

Faraday

As of 1.2beta1, we use (and depend on) the Faraday library to make HTTP requests, replacing our homebrew Typhoeus and Net::HTTP adapters. This is a big change, so let’s go over it in detail.

What’s this about?

Faraday is a modular framework, patterned on Rack, which makes it easy to control and customize how Ruby makes HTTP requests; Koala allows you to take advantage of Faraday’s configuration options to tailor requests to your needs. By switching to Faraday, we get Koala out of the business of choosing which libraries and features to support, giving you more choices and letting us focus on building the best Facebook library we can.

How does this affect me?

Good news! This change should be non-breaking for almost everyone. All the old settings are still supported, though you’ll probably see a lot of deprecation warnings. There’s now only a single Koala::HTTPService module, which handles all communication.

Almost everyone?

Since Faraday settings are global (affecting other gems, like Twitter, which use it), Koala no longer tries to use Typhoeus by default.  To use that or any other supported library instead of Net::HTTP (the default), you just need to set the default Faraday adapter, which is really easy:

# this could go in an initializer
Faraday.default_adapter = :typhoeus

Also, if you’re hooking directly into Koala’s HTTPService framework, you’ll probably have to make some changes; check out the Extensions wiki page to learn more about the new internals.

People like options, right?

We’ve improved how we handled HTTP options by adding a global Koala::HTTPService.http_options hash. Any settings set here will be applied automatically to all requests (and can be overridden for individual requests).  The format for the hash maps directly to what Faraday expects, so if you haven’t used Faraday, check out the Koala wiki for some examples.

We still support all the old individual options on Koala.http_service (proxy, timeout, etc.), which read from and write to the new hash.

Also, not only does Koala provide a default middleware stack for Faraday (all you’ll need to use Koala as normal), we’ve added Koala::HTTPService.faraday_middleware, which lets you pass a block to build your own stack.

Learn more

For more information and a complete list of how to migrate old settings, check out the HTTPService wiki page . If you have any questions, feel free to drop me an email.

API

Koala::Facebook::API class is now the main API class, containing both Graph and REST API methods. Since the GraphAndRestAPI class showed it’s possible to offer all methods from one object, there’s no reason to force you to keep track of and instantiate three different classes to use the Facebook API. All three old classes are now aliased to API, and will remain available until at least 1.3.

api = Koala::Facebook::API.new(my_token)
api.get_object("me")
api.fql_query("select first_name where uid = me()")

Other changes

• Koala is now on Travis, passing all tests under JRuby, Rubinius, and REE, as well as Ruby 1.8.7, 1.9.2, and 1.9.3!
  
• The live test suite now runs by default against test users, so you can run it as frequently as you want without having to update facebook_data.yml.
• To run it against a real user, add your OAuth token/session key/OAuth code to the YAML file.
• TestUsers#update lets you update the name or password of an existing test user
• API.get_page_access_token lets you easily fetch the access token for a page you manage
• API.put_picture now accepts URLs to images in addition to files

Check out the changelog for a complete list of changes. The diff since 1.1 is available here.

Thanks to…

Thanks to marcgg for his help keeping up with Facebook changes, and to cbaclig, as always, for his help resolving some persistent issues with the test suite’s YAML file.  Credit also to everyone at Context Optional for their support and feedback.

Next steps

As you may have guessed from this being beta1, we expect to release at least one more beta to address some cookie changes Facebook has made, as well as incorporate any feedback we get from any of the changes in this release.

Installation

As always:

[sudo|rvm] gem install koala --pre

Or with Bundler:

gem "koala", "~> 1.2.0beta1" 

Enjoy! Looking forward to hearing your feedback.

Alex
http://github.com/arsduo/koala

Sunday morning #1!  We woke up at 6:30 AM, excited for our first day at Oktoberfest, scarfed a big breakfast, and left for the Wiesn.  Our lederhosen didn’t protect us much against the morning chill waiting in line, but by 9 AM we were safely within the cavernous Pschorr Bräurosl tent.  For the next six hours we drank, talked with our group, stood on benches, sang, drank, replaced our empty beer steins with full ones, ordered roasted chickens, took it all in, and drank some more.  Oktoberfest was amazing, full of life and noise and activity, all inside that one tent.  The afternoon rolled around many beers, chickens, and prosits later, and we left to get our visiting friend to his train.

We didn’t make it.  I spent the next few hours caring for a friend too sick to take a taxi, stuck in a plaza downtown until he felt well enough to rush home with me to make sure my unreachable husband hadn’t passed out face down in the bathtub.  The rest of the day was spent nursing two wasted men back to a (miserable) equilibrium.  The next day was miserable.

Intense?  Yes.  Memorable?  Definitely.  Good?  Not really.

In the meantime, two weeks went by.  We got better, we went back to Oktoberfest a few times, and then suddenly it was…

Sunday morning #2!  We woke up early, ate a quick breakfast, donned our lederhosen, and took our visiting guests to the Oktoberfestgrounds.  After waiting in line, we got into the cavernous Schottenhamel tent by 9 AM, and the beer started flowing.  We ate and drank as much and more, sang, danced, wandered outside, and came back to the tent to stay until it closed.  The day was great, and we had a blast.  The next day was a good one — we even came back for a sunny walk through the Wiesn.

Intense?  Yes.  Memorable?  Definitely.  Good?  Really.

If you’re coming to Munich this fall (and you should), this post’s for you.  I hope our experiences last year can help you have an awesome time like our second Sunday’s and avoid the mistakes we made the first time.  Oktoberfest is an amazing experience, and if done right you’ll love it.  If not…well, trust me: you don’t want to be the guy puking in the central station in front of a crowd of disgusted Germans.

Tips

Stick around: the longer you stay, the more you can see.  You can’t see all of Oktoberfest in one day; if your visit lasts three days instead of two, you can party the first day, relax, recover, and explore Munich the second, and head back the third (see also Get outside).  Had we just been in Munich for a weekend, as our friend was, we would have left Bavaria thinking the Fest was just a big frat party.

Get outside: we were surprised to discover how much more there is at the Oktoberfests than the beer tents that dominate media coverage and popular imagination.   You can ride roller coasters, watch horse races, eat at restaurants, play games, pet cows, and drink at outdoor biergartens — all in the sunlight and fresh air.  (Plus there are tents dedicated to wine and dessert.)  You can also climb the nearby church for a few Euros, which yields an amazing view at night.  Don’t confine yourself to the beer tents; even if there’s a line when you leave, you’ll get back in.  Over our five or six visits, we spent all but two outdoors.  (See also Pet some animals.)

Beers are big:  in everyday life we drink our beer in units — a pint glass, a bottle, a can, whatever.  Make a conscious effort to break that habit at Oktoberfest, because the beer comes in 1 liter steins (a Maß) — each unit roughly three American bottles or two pints.  Don’t try to drink it as you’d drink a beer back at home, or as fast as it seems like everyone else is.  If you’re still working on the same glass of beer an hour after you get it, congratulations!  You’re doing it the local way.  (See also Peer pressure and Beer is strong.)

Marvel: the Wiesn is a wonder of human triumph over complexity: 6,400,000 visitors drinking 6,600,000 liters of beer, eating hundreds of thousands of chickens, using the toilet, mingling, all in safety, (relative) cleanliness, and at a pretty fair price.  It’s amazing!  Be amazed.  Those tents you’re in, that are really full-on buildings?  They were built just for this, and they disappear afterward.  Those waitresses?  They really are carrying 8 heavy liter-sized glasses of beer at a time.  Those rides?  They won’t be there in November.  Those people?  Like you, they’re here from all over the world.  Lift your gaze up out of the beer occasionally and take it in.

Beer is strong: at Oktoberfest they brew the beer a few percentage points stronger, but it still tastes like regular beer.  Combined with the size and the constant drinking, it’s really challenging to know how much you’ve drunk (see Beers are big and Peer pressure).  Keep this in the back of your mind.

Be open: people are unusually friendly and open at Oktoberfest — take advantage of it!  We had more conversations with random Germans (and others) in those three weeks than in the months before or after, on the subway, at the Wiesn, even in the supermarket.  Be ready to make friends, and especially if you live in Munich, take a chance and ask if the people you meet want to get a beer later.

Pet some animals: last year we celebrated the 200th anniversary of the first Oktoberfest with an area reenacting the Oktoberfests of yore.  Bier brew’d in the olde styl, much showmanship of horses, a zoological exhibition in which one maye pett the animales (reflecting the festivals’ agricultural origins) — it was so popular that it’s back this year.  The Alte Wiesn is great complement to the more polished, commercial atmosphere elsewhere; sometimes it’s hard to get in, but the line is more than worth it — where else are you going to pet a horse and drink a beer at the same time? (See also Get outside.)

Peer pressure: look, you’re going to be in a tent with a thousand other people, some seasoned vets and some on their way to an experience like our first Sunday, all crammed side-to-side in every free space.  It’s tremendously fun and energizing, but it’s also intimidating.  Everywhere you look waitresses are rushing down the aisles delivering beer, and anytime you look around some of your co-revelers are swapping out empty glasses for new liters.  There’s nothing wrong with getting into the spirit — just remember you can’t pace yourself by the activity around you.  (See also Beer is strong and Beers are big.)

Preview tent life: despite all the pictures, my idea of what Oktoberfest is like was wide off the mark until by chance we picked up the movie Oktoberfest (sadly not available in the US).  It’s a decent ensemble movie and an excellent primer to the festival.  If you’ve never been, dig up some video (even if just the news) about what tent life is really like.

Eat: remember this if nothing else.  There’s some delicious food at the Oktoberfest, and at decent prices (unlike many American festivals).  Hendls (greasily delicious roasted half-chickens), crepes, currywurst, roasted almonds, kaiserschmarrn (German desert), and much, much more are all much tastier and fresher than you’d expect from such a big, packed festival.  Not only is the food worth enjoying, it’ll help you handle all the drink, so eat up!

Stay safe: Munich is an unbelievably safe city, and Oktoberfest is well organized.  Still, it’s a huge festival with hundreds of thousands of strangers passing through all the time.  Don’t worry too much, but do be smart.  Now that you know how to enjoy Oktoberfest, you should also read up on how to avoid problems while here.

Don’t eat Wiesn hearts: those famous gingerbread hearts are gifts, not food.  They’re all stale.  Always.  They last forever.  Bring a few home and put them up on your wall.

Wrapup

As you can tell, we’re very excited for the Wiesn this year — just six weeks away! — and we’re really looking forward to seeing everyone heading down here to Bavaria (especially all those coming for the Democrats Abroad weekend).  If you have any additional thoughts or ideas from your experiences at Oktoberfest (or plans to come), I’d love to hear them in the comments.

They're turning this....

...into this!

Batch API Support

me, koppel = @graph_api.batch do |batch_api|
  batch_api.get_object('me')
  batch_api.get_object('koppel')
end

[sudo|rvm] gem install koala

gem "koala"