Alfa Jango Blog Engineering, Software, and Entrepreneurship

Communication in Engineering, Software, and Open-source

Engineers and developers are not known for being the best communicators. Technical details? No problem. Explaining things in plain English? Err, that’s a different story. I’ve seen entire projects flounder from ineffective communication through my career as an engineer.

Since transitioning to the role of startup founder and open-source developer, communication has become an even larger part of my day. Below is an analysis, including my humble suggestions, for improving the state of your projects by improving your team’s ability to communicate.

A special thanks to Cory Flanigan (@seeflanigan), who gave a talk at Great Lakes Ruby Bash 2011 entitled, Communicating Effectively for Fun and Profit, which prompted me to write this, and also for providing feedback on this article.

Communication is about winning. Whenever you engage someone in communication, it is a competition. Who has the better story? Who can talk/write more? Who has the better code? And if you don’t win, you lose.

False.

Fact: if you win a conversation, then you also lose. This is especially true when your conversation must accomplish some achievable goal.

Actionable discussion

Let’s first define “actionable conversation” as that in which we are trying to achieve some explicit goal, whether to persuade someone of something or to find a solution to some problem.

Now, let’s divide actionable conversation topics as one of two types:

Opinion vs opinion

The majority of the time, there is no right or wrong, only opinion and differing opinion. To consider yourself right here is to disregard the differing opinion as decidedly wrong. Be careful, doing this makes it difficult to ever grow and learn.

Fact (true vs false)

Then there are topics for which there is a right and wrong. Let’s say you and I are arguing the solution to 1 + 1 = 2. You say it’s 2, but I say it’s 3. In a technical sense, you are right and I am wrong.

Read the rest of this entry »


jQuery EasyTabs v2.3 released – AJAX tabs and more

The jQuery EasyTabs plugin has recently hit v2.3 (well, v2.3.3 by the time I got this published). New for EasyTabs this release:

See demos for each new feature below

AJAX tab content

It’s been a long-time coming, and it’s finally here. EasyTabs now supports loading content into panels via ajax.

EasyTabs has always placed emphasis on semantic, meaningful markup. Traditionally, markup for a tab/panel pair would look something like this:

<a href="#panel-1" class="tabs">I'm a tab</a>
<div id="panel-1">Panel content</div>

Notice that in the above example, if JavaScript is disabled, we’re left with a normal anchor and anchor link in the page, which browsers understand by default.

Read the rest of this entry »


Remotipart 1.0 Released

Just 6 weeks after the announcement of v0.4, I’m pleased to announce the release of Remotipart v1.0. With this release, AJAX file uploads in Rails 3.0 and 3.1 (building off the standard jquery-ujs driver) are as easy as humanly conceivable. This was possible thanks to a large push from Adam Kerr.

The two major changes for v1.0 are:

  • New jQuery 1.6 iframe-transport instead of dependency on form.js
  • New rack middleware does away with configuration

With the release of v1.0, the new officially maintained repo for Remotipart has moved from here to the JangoSteve fork on Github.

There is also now a more robust test suite. Read more about that in the Remotipart docs.

New jQuery iframe-transport

Previously, the process of submitting files via an ad-hoc iframe element and inserting the response back into the page (described here) was done by the form.js. For those who aren’t familiar, form.js is an awesome plugin that does a lot of really useful things. However, we weren’t really doing it justice by requiring it as a dependency for only one small part of its capabilities.

Read the rest of this entry »


Rails 3 AJAX File Uploads with Remotipart

In my last article, we discussed the difficulties of file-uploads via AJAX, and how the iFrame method works around the issues to provide an AJAX-like interface for uploading files to the server.

So how does this relate to Rails?

Rails 3 uses Unobtrusive JavaScript for remote links and forms (and comes packaged with the jquery-ujs driver via the jquery-rails gem as of Rails 3.1!). However, because jquery-ujs relies on jQuery’s standard .ajax() function, it is incapable of doing AJAX file uploads.

The Remotipart gem

Remotipart to the rescue! The Remotipart gem does two things:

Read the rest of this entry »


AJAX File Uploads with the iFrame Method

AJAX file uploads, how do they work?! Well, they kinda don’t.

Browsers don’t allow file uploads via XMLHttpRequest (aka XHR) for security reasons. If we try to submit a form remotely via XHR, it will work, except with the file field stripped out of the request parameters. This sort of partial, silent failure can lead to unicorn black-eyes. (I punch unicorns in the face when I’m frustrated.)

This is how jQuery’s standard AJAX functions work, including .ajax().

In turn, the Rails 3 jQuery UJS driver uses jQuery’s standard AJAX functions internally. To prevent this sort of silent failure in Rails 3, we added the ajax:aborted:file event to abort the remote form submission if any non-blank file inputs are detected.

See New ajax:aborted Rails jQuery UJS Hooks.

Workarounds

So, there are a couple workarounds that give the impression of AJAX file uploads (and thus the same workflow and UI from the user’s perspective), without actually submitting the file via XHR.

Read the rest of this entry »


New ajax:aborted Rails jQuery UJS Hooks

In my last article, Rails jQuery UJS: Now Interactive, I talked about my push to make Rails jQuery UJS (aka jquery-ujs) more interactive and easier to customize and extend with third-party plugins. Along those same goals, let’s discuss another recent change: ajax:aborted hooks.

There are now two scenarios where remote forms will not be submitted, and the AJAX submission will instead be aborted. When this happens, jquery-ujs now publishes hooks, to which we can bind handler functions to gracefully handle these situations.

Let’s take a look at each of these scenarios and how we can utilize the event hooks.

Scenario Hook name
blank required fields ajax:aborted:required
non-blank file inputs ajax:aborted:file

Required fields

Read the rest of this entry »


Rails jQuery UJS: Now Interactive

The Rails jQuery UJS adapter (aka jquery-ujs) has undergone some major renovations over the past few weeks. This particular change is one I’m very excited about, as I’ve been wanting to do this for a while. Without further ado, jquery-ujs is now InteractiveTM.

What do I mean by “interactive”? Well, we can now plug into every facet of jquery-ujs, binding to custom events, and even customizing internal functions, without hacking or monkey-patching the rails.js file itself.

We’ll start with a brief explanation of the change and then dive into a few examples.

Feel free to bypass my blabbering and check out the the commit.

Closure style

Previously, rails.js was one big closure.

Before:

(function($) {
  ...
  function fire(obj, name, data) {
    var event = $.Event(name);
    obj.trigger(event, data);
    return event.result !== false;
  }
  ...
})( jQuery );

// cannot access fire() function here

This closure design had many advantages. However, the biggest advantage, in this case, happened to be the biggest disadvantage as well: everything inside was self-contained and inaccessible by the outside world.

So, what if we like most of what jquery-ujs does for us, but just want to modify one little function? Before, we’d have to open rails.js in our editor and start hacking away. But no more!

Object literal style

Read the rest of this entry »


jQuery EasyTabs Plugin v2.2

It’s only been a week since the last release, but I’m excited to present jQuery EasyTabs v2.2. New with this release:

Animated height transitions

In many cases, the tab panels (where the tabbed content lives) are not the same height. Now, EasyTabs automatically animates the height transition between panels of differing heights. The speed for the animation to scale panel heights depends on the animationSpeed option.

View the demo to see this new effect in action.

Animated transition options

As requested, EasyTabs now gives more control over the effects used to transition between panels. The default transitions are still fadeIn and fadeOut, respectively. But now, you can specify any other jQuery effect to use as well. The new options are:

transitionIn // effect for appearing target panel
transitionOut // effect for disappearing visible panel
transitionCollapse // effect for collapsing panel
transitionUncollapse // effect for uncollapsing panel

For example:

$('#tab-container').easytabs({
  transitionIn: 'slideDown',
  transitionOut: 'slideUp'
});

To see this in action, check out the demo.


jQuery EasyTabs Plugin v2.1.2

The jQuery EasyTabs plugin is now at version 2.1.0 2.1.2 (I managed to bump the version number twice before publishing this post). This release adds three four new features:

uiTabs option

Perhaps my favorite addition to the EasyTabs options, when uiTabs: true, EasyTabs will automatically add and use the same class names used by the jQuery UI tabs. This feature opens the doorway to making EasyTabs a drop-in replacement for jQuery UI tabs once you’ve outgrown UI’s out-of-the-box theming and structure.

If you are currently using UI tabs with this:

$('#tab-container').tabs();

Simply replace the above line with this:

$('#tab-container').easytabs({ uiTabs: true });

And your tabs will still look and function the same as before. Now you can start customizing the CSS and HTML markup with the flexibility of EasyTabs.

Read the rest of this entry »


Rails js.erb Remote Response not Executing

A common issue that comes up in the GitHub Issues for the Rails jQuery UJS and the Remotipart gem / jQuery plugin goes like this:

The JavaScript response from my js.erb is being interpreted as text and not being executed.

I usually point to this comment in GitHub Issues, which I posted the first time I came across this problem. But GitHub Issue comments are difficult to link to, and almost useless in search results due to all their ajaxy-ness. So, I’ll repost and explain here for future reference.

Read the rest of this entry »


Page 1 of 41234