You'll never guess which libraries are changing in the upcoming Sugar release

Or maybe you will.  Click-bait headlines are the worst.  Don't worry, I won't make you click through an ad-covered slideshow to find all of the library changes.

Anyway, we have a few library updates coming in our upcoming Fall '18 release, and we wanted to give you as much time as possible to begin preparing for the changes.  Without further ado, below is information on upgrades to Handlebars, Underscore, jQuery, jQuery Migrate, and jQuery UI.

Handlebars

The Handlebars library is a JavaScript library that lets Sugar create semantic templates.  Handlebars help render content for layouts, views, and fields for Sidecar.  You can learn more about Sugar's use of Handlebars in the Sugar Developer Guide.

Handlebars v4 included significant changes to depthed paths that would likely break many customizations and integrations (see the Handlebars 4.0.0 Release Notes for more details).  However, v4 also included improvements we wanted to get to you.  Below is information on our solution.

What is changing?

In order to get you the improvements without breaking your customizations and integrations, we have created a forked version of Handlebars v1.3.0 with a unique version number ("1.3.1-sugarcrm-temporary") that we intend to include in the Fall '18 release. 

What documentation should I reference?

What's coming in the future?

The forked version of Handlebars is intended to be a temporary solution that we intend to discontinue using and/or remove in a future version of Sugar.  Given the breaking changes to depthed paths in v4, we are exploring alternatives to reduce disruption to existing customizations and allow developers as much time as possible to adapt. Watch this blog for updates as we plan our path forward.

Underscore

Underscore is a Javscript library that Sugar uses to improve code readability and performance.  You can learn more about how you can use Underscore in your apps and customizations in Matt's blog post Using Underscore.js to improve Sugar 7 performance.

Underscore 1.9.0 includes big performance improvements that we want you to benefit from, so we will be upgrading it.

What was upgraded?

  • Underscore will be upgraded from 1.8.3 to 1.9.1.
  • In Ventana, Underscore was upgraded from 1.8.3 to 1.9.1.

What documentation should I reference?

What else should you know?

No functionality will be deprecated as part of this upgrade, so we expect the impact to be quite low.

jQuery, jQuery Migrate, and jQuery UI

We are upgrading jQuery, jQuery Migrate, and jQuery UI in the Fall '18 release.  jQuery is a Javascript library we use for tasks like traversing and manipulating the DOM and handling events.  jQuery Migrate is a Javascript library we use to help us migrate to newer versions of jQuery without our code breaking due to APIs being removed in the newer versions.  jQuery UI is a Javascript library we leverage for various interface interactions, effects, widgets, and themes.

Below are (hopefully) all of the answers to your questions related to the upgrades of these libraries.

What will be upgraded?

  • jQuery will be upgraded from 1.11.3 to 1.12.4 for both Sidecar and BWC. 
  • jQuery Migrate will be upgraded from 1.2.1 to 1.4.1 for both Sidecar and BWC.
  • jQuery UI will be upgraded from 1.11.4 to 1.12.1 for both Sidecar and BWC.
  • In Ventana, jQuery was upgraded from 1.11.3 to 1.12.4 and jQuery Migrate was upgraded from 1.2.1 to 1.4.1.

What will be removed or renamed?

  • The new versions of these libraries remove and deprecate various functions.  See the Changelogs and Release Notes in the Documentation section below for more details.  Two changes we think may affect many of you:

    • jQuery UI's .zIndex() function was removed.  You can consider using the .css() function instead.  For example, if you used .zIndex() to get the z-index of an element, you could use .css('zIndex')instead.  In cases where you set the z-index of an element by doing something like .zIndex(1), you could use .css('zIndex', 1)  instead.  Be sure to test your changes to ensure everything is behaving as you expect.  For other recommendations on how you could update existing code that uses the .zIndex() function, see the jQuery UI 1.12 Upgrade Guide
    • jQuery UI's CSS class name ui-icon-carat was renamed to ui-icon-caret.  We recommend searching and replacing all instances of ui-icon-carat with ui-icon-caret.
  • jQuery version 1.7.1 will be removed; portal/lib/jquery-ui/js/jquery-1.7.1.min.js will be removed.
  • An unused copy of jQuery 1.6.4 that was available at include/javascript/jquery.js will be removed.
  • The jQuery UI CSS component files will move to a components directory and be renamed to no longer begin with jquery.ui.  For example, the jQuery UI dialog was previously include/javascript/jquery/themes/base/jquery.ui.dialog.css and will be moved and renamed to include/javascript/jquery/themes/base/components/dialog.css.

What will not change?

For backwards compatibility, we will retain the file include/javascript/jquery/themes/base/jquery.ui.all.css and it will continue to work as before. Image files in include/javascript/jquery/themes/base/images will also be retained.

What documentation should I reference?

What's coming in the future?

Upgrading jQuery and jQuery Migrate to version 3.x is on the roadmap for an upcoming release, so we recommend beginning to look at how you will update your customizations and integrations to use a modern version of these libraries.

What else should you know?

A minified version of jquery.ui.all.css will be available at include/javascript/jquery/themes/base/jquery.ui.all.css.

If you are using jQuery plugins (see The jQuery Plugin Registry or The npm Package Search), you may need to upgrade those to newer versions that are compatible with jQuery 1.12.4 and jQuery UI 1.12.1.