API Redesigns: The Past, Present and Future
Back in November, we announced the first of many API redesigns. In that post, we briefly stated our overall goals:
jQuery UI is undergoing an API redesign which will slim down the size of the API in order to provide a more stable codebase that is easier to learn and use. We’ll be posting the proposed changes over the next few weeks in order to gather feedback from the community. Our goal is to support the old (current) and new (proposed) APIs simultaneously in 1.9 and then remove support for the old APIs in 2.0.
Now it’s three months later and two things are clear: 1) it’s taking more than a few weeks to post all of the proposed changes; and 2) we didn’t give enough information about the planned changes and the reasoning behind them.
The Past
When jQuery UI was first created, it was a combination of new and existing plugins. Pulling in existing, popular plugins was beneficial for everyone involved: jQuery UI was released earlier and with more plugins, the original authors’ hard work was publicly recognized and supported by the jQuery Project and the existing user base gained official support for the code they were using. Unfortunately, there was a downside to this approach. Because the existing plugins were written by different authors with different design principles and different coding styles, there wasn’t much consistency within jQuery UI. Between the 1.0 and 1.8 releases there were a few attempts to standardize various parts of the API, but there was never a coordinated effort large enough to make the necessary changes.
In addition to the inconsistencies between plugins, other problems started to appear over the past three and a half years. As users requested more and more features, the number of options, methods and events continued to grow. Over time, this led to what we have today, where something as simple as a draggable element has almost 30 options. On one hand, it’s impressive that so many various use cases can be handled, often with the use of just one or two of these options. On the other hand, finding the right one or two options to use can be a daunting task, especially for new users.
The Present
Recognizing the existing problems, we approached the 1.8 release differently. We defined a new process for building plugins that focuses on simplified APIs that are easy to extend. With the success of the 1.8 release, especially the simplicity and flexibility of the Autocomplete widget, we were convinced that our new process was working. Having a new process and new standards, we decided to go back and redesign all of our existing plugins with the same design process. In October, the jQuery UI team got together in Boston to do a first pass at redesigning all of the existing plugins. A few weeks later we started posting the proposed changes to gather feedback from the community. We’re still working through some of the details for specific plugins.
Our goal is to have a completely refreshed project with the 2.0 release. We will have a much simpler API, better stability, full documentation and a full test suite for every plugin. However, getting there will require a lot of backward-incompatible changes. We’re aware of how painful that can be and we are doing everything we can to reduce the pain of upgrading. Specifically, we’re doing the following while implementing the new API:
- Ensuring we have a full test suite for the 2.0 API
- Creating a separate test suite for the 1.8 API
- Re-implementing any deprecated functionality on top of the new functionality
- Defaulting to the 1.8 API in cases where the old and new APIs cannot live side-by-side
This approach has several benefits, with one of the most important being that upgrading to 1.9 should not break any existing pages. In fact, the 1.9 release will have better support of the 1.8 API than any 1.8.x release. As plugins are refactored for 1.9, many bugs present in 1.8.x will be fixed and some of the fixes will not be easily ported to the 1.8 branch. Because the support for the 1.8 API in the 1.9 release is actually new code built on top of the 2.0 API, it benefits from these bug fixes. The addition of a full test suite for the 1.8 API ensures that these bugs are actually fixed in both APIs.
Defaulting to 100% support of the 1.8 API is great for upgrading to 1.9, but it doesn’t provide a way to determine if you’re ready to upgrade to only using the 2.0 API. In order to deal with this, we’ve added a new flag, jQuery.uiBackCompat. If you load jQuery, then set jQuery.uiBackCompat = false, then load jQuery UI, none of the 1.8 API will be loaded. This will result in only having the 2.0 API available and will allow you to test your pages for compatibility with the new API and provide confidence that you will be ready to upgrade to 2.0 when it is released.
The Future
When jQuery UI 2.0 is released, we will no longer support the 1.8 API. However, the 1.8 API compatibility layer from 1.9 should continue to work; it will just not be included in the 2.0 release and will no longer be officially supported. All new plugins will go through the new design process so large API changes like this should not occur again. Once the existing plugins have been updated to our new standards, we should be able to move the project forward much faster than we’ve previously been able to.
It’s worth mentioning that only widgets, utilities and effects are being refactored in 1.9. All interactions are going to be rewritten for 2.0 so they will be undergoing a different implementation process. As a user of jQuery UI, there shouldn’t be much perceived difference between the widget refactors and the interaction rewrites other than the release date.
We know that no one looks forward to refactoring existing code to work with API changes, and we’re working to make sure the transition process will be clear and simple. We hope that you, our users, understand that we need take this opportunity to refine jQuery UI to make it more robust, extensible, and maintainable in the long term.
This sounds like a great plan to move JQUI forward while still accomodating older versions. There should definitely be some log/error messages in 1.9/2.0 writing out that particular implementations are deprecated.
This plan sounds good to me. 1.9 allows me to start making changes towards the 2.0 release which will provide a sound future for jQuery UI. I hope to see great strides in the future of JUI. Thanks for all the hard work guys.
I would agree that this is the most sensible and sustainable approach long-term, but I would add that it would be great to have some good concrete examples for breaking changes or suggestions on what to look for in preparation for transitioning to the 2.0 API.
Phil: A list of breaking changes along with an upgrade path will be fully documented in with the 1.9 and 2.0 releases. Until then, you can use the individual API redesign posts to see what the changes will be.
Steve: I think adding warnings for the deprecated functionality would require quite a bit of extra code. If someone in the community is interested in building another layer to add in the warnings, that should be possible.
This all sounds good. Any bit of headache now is much better than bigger problems further down the road. Looking forward to 1.9 and 2.0 and thanks for all of the awesome work JUI team!
Very pleased to see more consistency with other widgets, plus the removal of a few bits. All good
This sounds outstanding. Consistency, across the board, is very critical. Is there posted roadmap somewhere? I know that including a grid is on your list, with backing from some major players, and I’m wondering what other new widgets may be in store. I know you don’t want to bloat the library (and the refactor will help with that), but seems there are still a few key pieces to really round things out (like the grid, and a tree, for example).
Steve: There’s a roadmap posted at http://wiki.jqueryui.com/Roadmap which outlines the high level goals for the upcoming releases. Note that the roadmap is subject to change, especially for releases further ahead than the next major release, but we try not to change directions too much.
Thanks for all the great work! I’m glad the steps toward consistency are being taken despite the pain.
This all sounds great, but I would rather see you guys spend your time adding new UI controls for now, instead of refactoring existing ones (which seem to function fine for people). The new ones could be made using the new techniques you described, then when you have covered the most-used types of UI controls, you could go back and make some of the first controls be more inline with the new ones. Not that I’m going to change your mind of course, but I doubt I am the only one with this thought. It seems like the new controls you’re working on have been in the works for so long now. Anyway, you all do great work, and I look forward to whatever comes next.
Michael: It is currently impossible for us to provide support for the majority of our existing plugins. There are currently almost 800 open tickets. The fact that there are so many open tickets combined with the fact that we don’t feel comfortable maintaining the existing codebase means that the existing plugins are in fact not working fine for people. Adding more plugins would make the situation worse because it would increase the amount of support needed, not decrease it. Fixing the problem now is the only viable solution.
I understand wanting to keep backwards compatibility for a bit, and ease the upgrading process, but PLEASE PLEASE PLEASE don’t take away from the capabilities of 2.0 just to make 1.8 users happy. I would rather have a 200% better library with 50% of the functionality (for now) then being held back by the consideration of compatibility.
~Ross
How about the CSS API (for want of a better word)?
The current situation is with jQuery 1.x and themes is that either everything has a theme applied to it, or nothing has and you have to style everything yourself. Getting around this requires you to write CSS more specific than the themeroller CSS to reset and restyle things you want to use styling other than a themeroller theme. This is really tedious and error-prone. Some kind of mechanism where you could selectively theme things and style the unthemed things yourself would be of great benefit.
The one we’ve run into most frequently is when you want to use a date picker or dialog on a page that uses an accordion or tabs. You want the date picker and dialogs to use the theme roller, but the accordion and tabs to use the page styling.
Ross: Do you have specific concerns? Our only concern when redesigning plugins and removing a feature is that it’s possible to build that feature again as an extension.
Gordon: All of our plugins only require the functional CSS to be loaded, e.g., jquery.ui.dialog.css. You can then style the plugins however you want. In addition, ThemeRoller already supports scoping the theme based on a selector (see the advanced options during download), so you can scope the widgets you want styled appropriately.
However, we do have updates planned for the CSS framework, ThemeRoller, and the styling capabilities within our widgets. We’re working on separating all style-related classes, e.g., ui-corner-all, from our widgets and adding options for which classes to apply to the widgets based on the functional classes. See http://bugs.jqueryui.com/ticket/7053 for more details.
Scott: No, I do not have any specific concerns. I have just experienced many projects that were fatally limited by their concern for backward compatibility. I understand the need, but that’s just not the mentality behind most revolutionary advancements in technology. A good example is HTML5, which does absolutely nothing to ensure compatibility with IE. If it did, the successes and advancements would be greatly limited.
I’m not completely sure what all you are changing, or how much. I just want to suggest that I (and presumably others as well…?) would much rather have new features (or at least the possibility of new features and future extension) than massive backwards compatibility.
Ross: Your general concern is certainly valid, but it’s good to know you don’t have any specific concerns. You’ll be glad to know that when redesigning the API for existing plugins we completely ignore how to maintain backward-compatibility. The only real impact the existing APIs have on the new APIs is that they serve as a set of use cases that we know we need to support. During the design process, we go through the existing API and ask “how should the functionality for this existing option/method/event be done in the new design?” We actually never consider the technical implementation of the back-compat layer during the design. This is why there is the possibility for areas where the 1.8 API and the 2.0 API conflict with each other. In those cases we’ll default to the 1.8 API by letting the back-compat layer overwrite the new functionality. But that doesn’t affect the 2.0 API or what is available if you set $.uiBackCompat to false in 1.9.
In summary, we completely agree with you. Mistakes in the past should not hold back advancement for the future. The amount of change between the 1.8 API and the 2.0 API is actually quite substantial, but we’re ensuring there’s an upgrade path for every change.
Looking forward to it.
It really takes time to do the right thing.
One more thing specific to the Datepicker. Would be great if the dates passed around in events such as onClose and onSelect would be JavaScript Date instances instead of strings. I realise that a Date instance can easily be constructed from the ‘inst’ data in these events, although it beats my why selectedDay is a String, while selectedMonth and selectedDay are Integers as the should.
Looks like my previous post didn’t show up… here’s what I had in mind as a request for jQUI 2.0.
Would be great if the events for a widget were fired on the element that a widget (e.g. Datepicker) is attached to, instead of having to send them in the options as functions. Would make for a cleaner way to attach events in a separate logical structure, making the use of MVC-type patterns (such as Backbone.js etc.) simpler and cleaner. jQuery Tools has this, which is neat.
jQUI feature set is still one of the largest compared to competition. So keep up the good work! Thanks!
Glen: What you’re asking for already exists (and has existed for a very long time). Perhaps you’re thinking specifically about datepicker, which is the only widget in jQuery UI that doesn’t use the widget factory and therefore doesn’t conform to our standards.
Mean while I’m still waiting for the SelectMenu widget to be officially supported.
Maybe i’ve missed: when jQUI 2.0 will release?
@scott Well it’s nice to know that that feature exists in themeroller, I wasn’t previously aware of it.
Perhaps you should make that part of the themeroller interface a bit more obvious?
Man these guy’s talk a Lot, JUI is the best thing I ever seen, nice and perfect. If it will have changes and lose compability, nice, and all the comunity have to accept it and contribute to make better.
JUI team, congratulation for the Great job. hope i can download it soon
I second the questions above about… do we have a target release date for 2.0?
There’s no set release date for 2.0, but it will probably be around 6 months from now.
On built-in support for cookies being removed from tabs.
I am not a coder (one of the reasons why jquery is so appealing), so I may be missing something, but the explanation for removing built-in cookie support, that “Cross-page state management should be easy, but not be built-in,” comes up short. Why “should” it not be built in? Currently, using cookies to remember a tab state is remarkably easy. Changing that is a step in the wrong direction from this user’s perspective. My perspective is that built-in cookie support for tabs “should” be built in. Why is my “should” less important than the “should” that explains the change?
I wonder, other than the “should” offered as an explanation, what the drawbacks are of maintaining built-in cookie support for tabs. The benefits are ease of use. What’s the downside?