Some people mistook my blog post last Friday as a condemnation of YUI, or of the YUI team. I’ve heard that the team is feeling some heat as a result, and this is unfair. I want to set the record straight, and I also want to apologize for my part in the negative tone this discussion has taken in some quarters, since that’s not helping anyone.

Credit where credit is due

First, I want to make it clear that the YUI team is fully aware of every problem I mentioned. Nothing I wrote in that post was news to the team, and they’ve been working on some of those problems for a while now. If the YUI team were to fix every single one of those problems tomorrow, it would be because they’ve been busting their asses for months, in some cases years, to solve them. It would not be because they read about them on my blog.

If I thought the YUI team were unaware, unwilling, or incapable of fixing these problems, I would fork the project and be done with it. I’m not doing that, because I believe in the team and its leadership, and because I know how resilient they can be in the face of seemingly unsurmountable obstacles. If I thought YUI couldn’t or wouldn’t change, I wouldn’t have wasted my time writing that blog post.

That said, YUI can’t succeed in overcoming these obstacles without the community’s help. And the community can’t begin to help until the YUI project becomes more transparent, less secretive; more of an open source project and less of a Yahoo! product.

The team is not entirely to blame for this. I’ve been in their shoes. I know exactly how easy it is to slip into the mindset of working on a product instead of on a community project, and how hard it is to remember what it means to work on an open source project when you’re being paid to spend eight hours a day in an office (even if, as in my case, it happens to be a virtual office most days).

It’s not the team’s fault that Yahoo! itself tends to see YUI as an internal product meant to serve the needs of internal customers. Nor is it really Yahoo!‘s fault. A publicly traded company can’t be expected to fund projects that don’t serve its bottom line, so YUI must serve Yahoo!‘s bottom line. YUI exists because Yahoo! needed a shared JavaScript and CSS library. It would be a waste of time and money for every Yahoo! product to build its own single-use framework. YUI is only public because the developers working on it, and the engineering managers who’ve led the team, wanted to give something back to the web and convinced the company to allow them this indulgence.

Yahoo! and YUI should be commended for this.

But what Yahoo! and the YUI team need to understand — and this is the source of my recent frustration and the reason for my blog post on Friday — is that, if they’ll let us, there’s a whole lot the web can give back to YUI, and to Yahoo! as well. In order for that to happen, Yahoo! and the YUI team need to change some of their ways of thinking and challenge some of the ways they’ve historically done things.

My blog post on Friday stemmed from my frustration at how it feels to be an outsider wanting to contribute to YUI — frustration that I probably wouldn’t feel so acutely if I hadn’t had the experience of contributing to YUI from the inside. I wanted to be frank, but I also wanted my criticism to be constructive, which is why I suggested solutions instead of just complaining.

It wasn’t my intent to be discouraging, and I think I probably should have waited a while and written that post from a place of less frustration. I stand by what I wrote, but I regret that it was couched in negative emotions. I owe the YUI team an apology for that.

Good news

Since Friday, I’ve heard a few encouraging things from individual members of the YUI team that I’d like to share.

• I’m told that the team is planning to be more proactive about managing and responding to pull requests. I’m already seeing increased activity and transparency on pull requests, which is awesome.

• YUI hopes to be able to provide commit access to trusted non-Yahoo! committers soon. This was already in the works, unbeknownst to me.

• Dav Glass has big plans for Gallery 2.0 — some of which are already in the works — and my complaints certainly weren’t news to him. In fact, the solution I proposed in Friday’s post was directly inspired by much of the work he’s already done on making the rest of YUI more npm-friendly and easier to build and maintain, so my proposal isn’t news to him either.

I haven’t heard much else yet, but I do get the sense that the team generally agrees with the need for more transparency and more community involvement.

I want to stress that these changes (and any other changes you see from the YUI team in the near future) aren’t my doing. All I’ve done, if anything, is provide a little bit of a window into the sausage factory.

On the awesomeness of YUI’s engineering managers

I’d like to take a moment here to kiss some asses, because frankly, these asses deserve to be kissed and don’t get nearly enough credit.

The YUI team currently has, and has always had, fantastic leadership. From Thomas Sha (who founded the team) to Eric Miraglia (who managed the team for over five years) to the team’s current manager Jenny Donnelly (herself a former YUI engineer), YUI has been led by the best engineering managers I’ve ever worked with.

I want to single out Jenny in particular, both because she’s the team’s current manager and because she keeps a pretty low profile and lets the kudos go to the engineers she manages, which prevents her from getting the credit she deserves. If you’ve been to YUIConf in the past few years, Jenny’s the person who made it happen, and she’s the one you saw running around making sure everything went smoothly — often (as luck would have it) while also extremely pregnant.

Jenny, like Eric and Thomas before her, is an engineering manager who gets it. Any engineer can tell you how truly rare and valuable this is.

If there’s one thing I regret about my blog post last week (and, let’s be honest, there are several things), it’s that Jenny will probably take heat for it, and she doesn’t deserve that. Jenny is as passionate about YUI and YUI’s community as anyone, and more so than most. She’s one of the best things YUI — and Yahoo! — has going for it.

I have full confidence that Jenny and the rest of the YUI team will, with the community’s help, overcome the challenges facing the project and that YUI will continue to be one of the best JavaScript libraries in the world. You should too.

On the awesomeness of YUI

Like any project worth caring about, YUI has problems. All software projects have problems. Particularly open source projects. The difference between an open source project with problems and any other project with problems is that an open source project’s problems ideally get discussed and dissected in the open.

Please don’t confuse my attempt to discuss YUI’s problems in the open for an attempt to convince people they shouldn’t use YUI. That’s the last thing I want, especially since I personally use YUI and want to see it thrive.

My personal decision to stop contributing to YUI until I feel my time is better respected doesn’t mean I’m going to stop using YUI, and it doesn’t even mean I’m going to stop working on YUI itself — it just means I don’t plan to contribute that work upstream until the process has been smoothed out.

If you currently use YUI, there’s no reason to stop. If you don’t yet use YUI, you should consider it. It’s a fantastic library, and it’s still my first choice.

Update, 2012-09-10: I’ve posted a followup to this post entitled Why I believe in YUI. Please read it.

When I quit my job at Yahoo! a few months ago, it didn’t feel like I was really quitting. I was leaving the company, sure, but I still planned to continue working on YUI, even though Yahoo! would no longer be paying me to do it. Getting paid to work on an open source project has many benefits, and one of them is that if you love your job, you can keep right on doing it even if you decide to leave the company.

I’m extra lucky that my new employer loves YUI, uses it extensively, and is more than happy to let me contribute the work I do back to YUI whenever it makes sense. Since I left Yahoo! I’ve sent ten pull requests to YUI. Some for minor bug fixes, enhancements, or performance improvements; others for brand new components like LazyModelList, Template.Micro, and node-scroll-info.

This has been one of the most frustrating experiences I’ve ever had contributing to an open source project.

Pull request graveyard

Even though I’m still in touch with the core team and talk to many of them on a daily basis, several of my pull requests sat in limbo alongside over 40 other open pull requests on the YUI 3 project (some dating back nearly a year). Compare this to jQuery, which — despite being more popular than YUI — currently has only 22 open pull requests, none older than two months.

Not all my pull requests were large. One was a minor change that fixed a critical performance bug in Y.Attribute#getAttrs(). Another was a minor change that improved the performance of Y.merge(), a core utility method used throughout the library. In both cases, the pull requests sat unreviewed as release windows passed them by, even though reviewing them would have taken minutes.

No external committers

Why send pull requests? Why not just commit these minor changes myself? Because there are no YUI committers who don’t work for Yahoo!. Despite having been a trusted senior member of the core team for over two years, I lost commit access to YUI the instant I stepped off the Yahoo! campus for the last time.

What many people don’t know about YUI is that the YUI GitHub repository is just a read-only mirror. YUI’s actual source-of-truth repo lives on a server inside the Yahoo! corporate firewall, and can only be accessed by Yahoo! employees. The reasons for this have to do primarily with typical Yahoo! bureaucracy and not with any desire on the part of the YUI team to exclude external developers, but nevertheless, that’s exactly the effect it has. YUI has many external contributors, but the only way to get commit access is to draw a Yahoo! salary.

The YUI team also has no actual set procedure or policy for dealing with pull requests. In theory, when budgeting time and making development estimates for each release cycle, team members are expected to budget time for handling pull requests, responding to community questions, etc. In practice, the team members who actually care about that stuff make time for it, and the ones who don’t care as much don’t make time for it. So some team members respond to pull requests, hang out on IRC, and drive YUI’s community engagement efforts, while others are completely invisible and unreachable to the YUI community.

Unfortunately, some of the team members who don’t care very much about engaging with the community outside Yahoo!‘s walls are also very senior members of the team who “own” many important parts of the library. Because they avoid spending time interacting with the community, they’re often out of touch with what YUI’s users need and care about, and tend to say “no” far more often than they say “yes”. They also tend to either ignore pull requests or excuse themselves from dealing with them by citing how busy they are.

As a result, some of the most important parts of YUI — Y.Node, Y.Event, Y.Base, Y.Attribute, and more — are also the most ignored, and the hardest for external developers to contribute to.

Long story short? Important changes and improvements to YUI are frequently blocked by people who rarely interact with the community and cannot be held to task by the community. These team members mean well, and they do what they do because they genuinely think it’s good for YUI. But it’s often not, and I’ve learned that fighting with them from the outside is far more difficult than fighting with them from the inside was.

The Template.Micro fiasco

A few weeks ago I opened a pull request for a new YUI component called Template.Micro. This is something I created for my own use, but I thought it would be a great addition to YUI. Some fantastic community discussion occurred on that pull request — lots of developers, including members of the core team, had excellent feedback, and we worked together to make Template.Micro awesome. Eric Ferraiuolo and I even chatted about Template.Micro in a public Google Hangouts on Air session and posted the recording on YUI Theater.

Once everyone who participated was happy with the pull request, Eric (who is a member of the core team) arranged to discuss Template.Micro at one of YUI’s weekly engineering meetings. These meetings are normally private, but the team occasionally invites external contributors to join in, and they invited me to talk about Template.Micro.

Every YUI team member in that room who had an opinion had already participated in the discussion on the pull request, except for — guess who? — the ones who rarely engage with the community. They hadn’t looked at it. Not even a glance. Naturally, they were the only ones who objected to merging it in. They objected strenuously and continuously for nearly two hours as I summarized and reiterated every discussion that had already taken place on the pull request or on IRC. Eventually, with the help of others on the team who had participated from day one, I managed to convince them it should be merged.

Then nothing happened, and nothing has continued to happen for over a week. Rumor has it that someone changed their mind (or just “doesn’t have time” to review the fiftyish lines of code, not counting comments) and has decided Template.Micro shouldn’t be merged after all. Code freeze for the next release approaches. I can’t actually get an answer on the pull request itself, so it sits unmerged, and I have no idea whether I or anyone else who wants to see this in the library will be able to use it in the next release.

I’m left feeling that I’ve wasted my time, and I no longer have any desire to contribute to YUI. It’s not worth it. This is just one of the battles I’ve had to fight recently, and fighting battles is not how I enjoy spending my free time, nor is it a good way for me to spend my employer’s time.

What needs to change

Problem #1: There’s no incentive for YUI core team members to review or merge pull requests.

Everyone on the core team is busy (usually incredibly busy) with their own tasks. No explicit time is ever set aside for managing external contributions, so the only time this happens is when someone takes the initiative to do it. There are people on the team who rarely take this initiative, and others who are often too busy to take this initiative. As a result, even small pull requests tend to sit around for a long time. This provides a significant disincentive for external developers to contribute minor fixes, and an incentive for them to simply bake monkeypatches into their own code, which YUI will never benefit from.

My recommendation: YUI should make it part of everyone’s job to triage and manage pull requests. They should strive for zero open pull requests at the end of every sprint — any pull request that shouldn’t go into the current sprint should either be denied or scheduled for a future sprint (and then should not be forgotten when that sprint rolls around).

Problem #2: There are no external contributors with commit access to YUI.

Obviously only highly trusted contributors should have commit access to YUI. The core team is highly trusted. Luke Smith (another recent former YUI team member who still contributes) and I were highly trusted when we were on the core team. As soon as we turned in our Yahoo! badges, we became just as untrusted as everyone else on the Internet. This is strange.

The weirdest thing about this? I’m now dogfooding YUI far more than I ever did when I was paid to work on it, so I’m naturally finding a lot of things I want to improve. I feel like I have a much better idea of YUI’s pain points and opportunities for improvement than I ever did before — but I also feel like there’s so much of a process barrier that the amount of effort required to get my changes back into YUI begins to approach the amount of effort required to simply fork YUI. That’s really scary to me, because it makes me wonder how many other YUI users and potential contributors have the same feeling.

My recommendation: Make GitHub YUI’s source of truth repo. Grant commit access to highly trusted external contributors, on the condition that non-trivial changes must be reviewed by the core team first. If an external contributor screws up, it’s not a big deal — revert the commit. If they screw up often, revoke their commit access.

Problem #3: There’s not much external visibility into YUI’s release planning and scheduling process.

I didn’t realize how frustrating this could be until I was on the other side. I want to contribute lots of stuff to YUI. Not just new stuff, but improvements and fixes. Naturally, I want to do this in a way that aligns with YUI’s own plans and schedules, but I also want to do it in such a way that I don’t have to babysit my contributions for months until they can be integrated into core.

Knowing YUI’s release plans and what the team is focusing on for an upcoming release would be a huge help in budgeting my time. I could look at the team’s plans and say, for example, “Hey, it looks like YUI is focusing on performance improvements for this release. I’ve got some of those on the back burner, so this would be a great time to contribute them.” Or “Well, I’ve cooked up this new widget, but it looks like the next YUI release will be a bug fix release, so I should roll this into a gallery module for now instead of letting it rot in my fork for three months.”

Efforts like YUI Open Hours and This Week in YUI help a little, but they don’t provide the nitty gritty insight into release planning and scheduling that are really needed, and Open Hours in particular requires a level of time commitment that people just can’t always make — it’s a lot harder to watch an hour-long screencast and try to extract meaningful info than it would be to read a blog post that simply says “here’s what we’ve got planned for the next release and here’s how you can help”. Even just knowing the dates for preview release windows would help contributors immensely in prioritizing our contributions.

My recommendation: Post the results of planning discussions and other non-confidential internal discussions on the blog (or on GitHub, with an announcement on the blog or Twitter) soon after they happen. A public document of some kind should be the end result of any non-confidential planning meeting or discussion. Consider inviting trusted external contributors to participate (via G+ Hangouts) in discussions that won’t involve confidential Yahoo! information.

Problem #4: Creating and maintaining gallery modules is far too much work.

The usual response to “it’s too hard to contribute to YUI core” or “YUI core doesn’t want my awesome new widget” is “well, just put your stuff in the gallery”. But it’s so painful to create, publish, and maintain a simple gallery module that I’d just rather not do it at all. It eats up far too much time that could be better spent writing code.

The main problem is how much manual labor there is, and how difficult it is to organize and maintain gallery modules as a result. Dav and others on the team are aware of my specific complaints in this regard, but until something is done, I think the team needs to stop using the gallery as a crutch to justify not solving problems 1 through 3 above.

My recommendation: Change the gallery to rely on the exact same build tools and procedures that YUI core uses. Remove the requirement for all CDN-hosted gallery modules to be maintained in a single yui3-gallery repo, so that gallery modules can use their own GitHub repos as their source of truth. Remove the manual form-filling required to create a gallery module on the website, and instead rely on the module’s own metadata and a simple tool that publishes gallery modules similar to how npm publishes npm modules.

If it were as easy to create a gallery module as it is to create an npm module, I’d have so many gallery modules people’s heads would explode. In a good way.

Problem #5: YUI can be a community project or a Yahoo! project. It can’t be both.

The primary mission of any good internal Yahoo! project is to further Yahoo!‘s corporate goals. The primary mission of any good open source project is to further the goals of its community. Since its inception, YUI has tried to do both. This isn’t working.

I can tell you from my time working at Yahoo! on both YUI and other projects that YUI is unlike any other project at Yahoo!. It sometimes doesn’t feel like it’s even part of the same company. And I can tell you from my time working on open source projects that YUI is unlike any other open source project, and in many ways doesn’t feel like an open source project. YUI tries to be a hybrid of both, and as such it tries to serve two masters — the corporation and the community.

This is why YUI is subject to Yahoo!‘s bureaucracy, it’s why some team members feel justified never engaging with the community, and it’s why contributing to YUI is a major pain in the ass. When I worked for Yahoo!, it was easy to assume that the external users (and non-users) who complained about this were just being too sensitive, too selfish, or too shortsighted. Now that I’m one of them, the shoe’s on the other foot and I’ve achieved enlightenment.

Despite the efforts and dedication of many members of the core team — seriously, YUI has an incredible group of core developers — YUI is not really an open source project. It’s a Yahoo! project whose source is public. The open source community has zero involvement in the management of the project. They have zero transparency into day-to-day happenings except for the mirrored source tree and whatever information leaks out via the blog, IRC, and Open Hours. There is no true sense of community ownership or responsibility for the project, and community members often feel frustrated at their inability to influence YUI’s direction.

My recommendation: Create a YUI foundation, separate from Yahoo!, and entrust the governance of the YUI project to it. Encourage Yahoo! and other companies that benefit from YUI to provide funding. This isn’t a new idea — it’s something that’s been discussed both inside and outside of Yahoo! for years, and is a structure embraced by many other open source projects — but it’s more and more apparent now that it’s crucial to YUI’s future.

I still love you, YUI

YUI has many flaws, whether we’re talking about the code itself or how the project is governed. But it’s also an amazing library with a vibrant, intelligent, devoted community. I plan to continue using it, and I hope to be able to contribute to it again at some point. But until some things improve, contributing to YUI just isn’t worth my time.

After five years, I will be leaving Yahoo! at the end of this month.

I’m not a fan of candy-coated, platitude-filled departure announcements that coyly avoid revealing actual opinions, so this is not one of those. I have many opinions about Yahoo!, and they have led to my decision to leave.

I’m not leaving to “explore new challenges” or “spend more time with my family”, and I’m not leaving because someone offered me a better job. I’m leaving because I no longer want to work for Yahoo!.

To be clear, I’m not leaving Yahoo! because I dislike my job, or my coworkers, or the projects I’ve been working on. I love my job. I love my coworkers. I love what I get to work on. For the past two years, I’ve had what is essentially my dream job working on YUI. Nothing I’ve ever done has been as much fun or as fulfilling as getting to wake up every morning and spend all day making one of the world’s awesomest open source JavaScript libraries a little bit awesomer.

What other job would pay me to write open source code, design, build, and perform sysadmin duties on a popular website, and even shoot and edit videos (one of my favorite hobbies)?

But as much as I love YUI, the team behind it, and the fantastic community of third-party contributors and users, I no longer believe in Yahoo! as a company. Yahoo!‘s corporate goals have taken some alarming turns recently, in particular with the reprehensible patent lawsuit against Facebook and the most recent round of senseless layoffs. Yahoo!’s actions violate my personal values and don’t reflect the values of the company I joined five years ago.

That said, my time at Yahoo! has been amazing, and I’m not exaggerating. When I joined Yahoo!, I thought I was hot shit. I wasn’t. I’ve learned and grown more as an engineer and as a person in the past five years than at any other time in my career. I’m grateful to have gotten to work on so many interesting projects with so many talented people. I don’t regret my time here.

Yahoo! has treated me well, both as an employee and as a human being. My managers and coworkers rewarded me and recognized me when I did great work and gave me honest criticism and guidance when I needed it.

When I told my manager in 2008 that living in the Bay Area wasn’t working out for me and Felicity and that I wanted to work remotely from Portland, Yahoo! was incredibly flexible and accommodating. They didn’t have to let me do that, but they did, and I’m very grateful.

When I’ve taken huge risks (like the time I developed and launched Yahoo! Search for iPhone — and announced it on my blog — without asking permission), Yahoo! has backed me up. Those gambles didn’t always pan out, and sometimes I got privately scolded, but I was never punished for pushing through the bureaucracy to do what I thought was the right thing, and in many cases I was rewarded. I respect Yahoo! for that, even though I wish it hadn’t been necessary.

I still think Yahoo! is a great place to work, and I mean that; the YUI team in particular (hint, hint). It’s just not the right place for me.

I don’t know what I’ll do next. I’m thinking about that now. If you’re looking for an awesome frontend engineer in the Portland area or are open to remote workers, get in touch.

Version 1.1.0 of Larch is now available.

Larch is a command line tool for copying email quickly and reliably from one IMAP server to another. It’s smart enough not to copy messages that already exist on the destination server, robust enough to pick up where it left off when interrupted, and also capable of more advanced operations like syncing message flags from the source server to the destination server. Larch is particularly well-suited for copying messages to, from, and between Gmail and Google Apps accounts.

Installing

Larch is a Ruby application and requires Ruby 1.8.6 or higher (1.9.2 is recommended). Once Ruby is installed, install or upgrade Larch via RubyGems:

gem install larch

What’s new

This release is the culmination of over a year of bug fixes and feature development. Larch is now faster and more reliable than ever. The most significant new features are:

This is only a partial list of changes. For the complete list, see the HISTORY file. For more details on how to use Larch’s new features, see the comprehensive README.

Try it out, report bugs

Please use Larch’s GitHub issue tracker to report bugs and request features. If you have questions or need help with Larch, the first thing you should do is read the very detailed documentation. If that fails, search the archives of the Larch mailing list on Google Groups. If you still can’t find an answer, send your question to the list.

Last week I gave an internal tech talk at Yahoo! entitled Achieving Performance Zen with YUI 3. The full video of the talk is now available on YUI Theater. The slides are available on SlideShare (or you can download the Keynote deck).

Synopsis: Following codified guidelines can help you build fast websites, but building applications that are clean, fast and extensible also involves taking a balanced approach to performance at every level of your F2E work. YUI 3 is designed to help you in this process, providing a right-sized abstraction layer with built-in performance magic and a variety of tools that make fast frontend code easy and fun to produce. In this session, we’ll explore the zen of performant JavaScript in the YUI 3 world and introduce you to some of the powerful tools YUI 3 puts at your disposal in every app you write.

I wasn’t at Yahoo! when Paul Graham was. He was there a long time ago. I can’t speak to whether his blog post accurately reflects what Yahoo! was like then. I can tell you that it doesn’t mesh at all with the experiences I’ve had at Yahoo! since I joined the company in early 2007.

The main point of Graham’s article is that Yahoo! didn’t have a hacker-centric culture. If there was a time when that was true, it must have been before I joined.

A company without a hacker-centric culture doesn’t encourage the kind of risk-taking and experimentation I saw when I was at Yahoo! Search. As an engineer, I had direct input into product features at every level, from ideation to design to implementation to launch. If I had a crazy idea, I was encouraged not just to tell people about it (up to and including executives), but to implement it and see if it tested well with users. I was able to add my own personal touch to parts of the product (sometimes big parts) without needing to ask permission or wade through excessive red tape.

This may not sound impressive to someone who’s used to the way things work at startups or small companies. But this was at one of the largest Internet companies in the world, on one of the most visited websites in the world. For Yahoo! to give me and other engineers the kind of freedom and power we had is not normal for a company or a product that operates at this scale.

Earlier this year, I transferred to the YUI team, where I get to work with some of the smartest frontend engineers on the planet on an open source JavaScript library that we develop not just for use by Yahoo!, but also by thousands of other developers around the world. The ideas and the work that I see coming from this team, and from the other teams we work with throughout Yahoo!, are amazing and often groundbreaking.

I have my gripes about Yahoo!, sure. It hasn’t been all kittens and rainbows. But the hacker-centric culture and the brilliant people Paul Graham seems to think don’t exist here are the reason I’ve been here for 3.5 years and counting, and they’re the reason I don’t plan on leaving anytime soon.

I originally wrote this as an answer to a question on Quora. I thought it was worth reposting here. My opinions, as always, are my own, and don’t necessarily reflect the views of my employer.

A little over three years ago, I opened a purple box containing a job offer and some boring forms to sign. It yodeled at me when I opened it. That’s when I knew I’d made the right choice in deciding to join Yahoo!.

Working on Yahoo! Search has been an incredible experience. I can now say that I’ve written code that’s used by hundreds of millions of people around the world. I can also say that I’ve broken code that’s used by hundreds of millions of people around the world (fortunately that only happened once). During my time there I did a little bit of everything, from writing build tools and pushing pixels around for bucket tests to leading frontend development on the September 2009 Search redesign—the biggest in the history of Yahoo! Search—which the team managed to pull off in only a matter of months.

At its best, working on Search was exciting and fulfilling in a way no other job has been for me; at its worst, it was stressful and relentlessly demanding. But whether it was exciting or stressful, fulfilling or demanding, I always learned something new every day, and I got to work with some of the smartest people in the business. As far as I’m concerned, that’s what makes a thing worth doing.

It’s in this spirit that I’m launching myself on a new journey. Not an altogether different one—I’ll still be at Yahoo!—but certainly one that I expect will be both incredibly challenging and a lot of fun. As a member of the YUI team, I’ll get to work on an awesome project that I love, with awesome people from whom I will doubtless learn truly epic amounts of stuff on a daily basis.

A little over three years ago, if someone had told me I’d be this lucky, I wouldn’t have believed them.

History Lite is a new YUI 3 Gallery module that provides an extremely lightweight (856 bytes minified and gzipped) and flexible Ajax browser history API. I originally wrote History Lite as a YUI 2 module for use on Yahoo! Search, and when the YUI 3 Gallery was announced recently, I jumped at the chance to port it to YUI 3 and release it publicly.

What’s it For?

Ajax applications often involve client-side interactions that change the contents or state of the page without performing a full page refresh. Unfortunately, browsers don’t record new history events for this kind of interaction, which means that the back/forward buttons cannot be used to navigate through the client-side changes. It also means that bookmarks and copied/pasted URLs will not return the user to the actual page state they might expect.

History Lite and other similar libraries provide APIs that Ajax applications can use to programmatically add state information to the browser’s history by manipulating the document’s location hash (the part of the URL after the # character), thus preserving the expected back/forward button behavior. This also results in copyable, bookmarkable URLs that allow an Ajax application to restore its state when it’s loaded.

YUI 2 and 3 already provide an excellent History utility written by my colleague Julien Lecomte. However, it has a few inconvenient requirements — an <iframe> must be added to the page, and all state parameters must be pre-registered before the module is initialized — which are necessary in order to provide full support for IE6 and IE7. This makes it a bit heavy for performance-sensitive use cases (especially since the <iframe> causes another HTTP request) and results in an API that can be difficult to share between multiple unrelated modules that coexist on a page.

History Lite provides only partial support for IE6 and IE7, which makes it possible to have a much smaller implementation and a more flexible API that doesn’t require any pre-existing markup or initialization. If supporting older versions of IE is critical for you, then you should use the YUI History utility. However, if you’re willing to do without legacy IE support, History Lite is a good alternative.

Usage

History Lite is hosted on the same Yahoo! CDN as YUI 3 itself, so you don’t even need to download anything to use it. Just tell YUI where to find it and it’ll be loaded automatically on demand:

<script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>
<script>
  YUI({modules: {
    'gallery-history-lite': {
      fullpath: 'http://yui.yahooapis.com/gallery-2009.12.15-22/build/gallery-history-lite/gallery-history-lite-min.js',
      requires: ['event-custom', 'event-custom-complex', 'node']
    }
  }}).use('gallery-history-lite', function (Y) {

    // Y.HistoryLite is now available to your code.

  });
</script>

History Lite doesn’t require any initialization, and the API consists of the add() and get() methods and the global history-lite:change event. Yep, that’s really the entire API!

Subscribe to the history-lite:change event to be notified when the history state changes. This occurs whenever a history parameter is added, modified, or removed. This example just logs stuff to the console to demonstrate how things work, but typically this is where you would implement any logic necessary to change the state of your application:

Y.on('history-lite:change', function (e) {
  // Properties on e.changed represent new or changed history parameters.
  Y.each(e.changed, function (value, name) {
    console.log(name + ' changed to "' + value + '"');
  });

  // Properties on e.removed represent history parameters that have been
  // removed.
  Y.each(e.removed, function (value, name) {
    console.log(name + ' was removed');
  });

  // The get() method returns the current value of the specified history
  // parameter. If you call get() without specifying a parameter name,
  // it'll return an object containing all current history parameters and
  // their values.
  console.log('current value of foo is ' + Y.HistoryLite.get('foo'));
});

In addition to listening for the history-lite:change event, it’s also a good idea to call get() when the page loads in order to restore state from a bookmarked or copied/pasted URL.

Use the add() method to add new entries to the browser history. Each call to add() will modify the document’s location hash, thus triggering the history-lite:change event:

// The add() method accepts an object containing key/value pairs of
// history parameter names and values. Each call to add() creates a new
// browser history entry.
Y.HistoryLite.add({foo: 'bar', baz: 'quux'});

// The add() method will also accept a query string.
Y.HistoryLite.add('foo=kittens&bar=puppies');

// A null or undefined value causes that parameter to be removed from
// the history state.
Y.HistoryLite.add({foo: null, baz: 'monkeys'});

Whenever you want your application to perform a state-changing action, use add() to trigger a change event and then perform the actual state change in the event handler (or in code called from the event handler). This enforces code modularity while also ensuring that state changes are explicitly tied to history events.

Supported Browsers

• Firefox 2+
• Google Chrome (all versions)
• Internet Explorer 8+
• Opera 9+
• Safari 3+
• Mobile Safari (all versions)

IE6 and IE7 are partially supported in that state changes and back/forward navigation within a single pageview will work, and bookmarked URLs will restore state. However, after navigating away from a page and then returning using the back/forward buttons, previous Ajax history from within that page will be lost.