Add a Push Pane with jQuery.scPush

Included in the SuiteCommerce Advanced source code are some little extras that we have included to make shoppers' user experience (and your life as a developer easier). I've mentioned before how you can add modals to your forms easily using included functionality, but another easy to use feature is provided by a proprietary jQuery plugin called jQuery.scPush.js. What it lets you do is 'push' content off the page to a side area; this is sometimes called 'off-canvas'.

Why is it important? On devices with small screens, such as tablets and especially mobiles, there is a need to optimize the page so that the most important elements are emphasized and real estate is used effectively. By pushing cumbersome content off the page — but making it easy to get to — is a good way to ease the user's experience of your site.

We use push panes typically for complimentary information or controls, but for in some circumstances we require the user to use them. For example, options for matrix items are pushed off the page on product detail pages. For more information on the design side of things, see Push Pane. You can also take a look at the code itself (including the comments) by looking for the module in Modules > suitecommerce > jQuery Extras.

Implementing Push Panes

So you're probably wondering how you can implement this functionality. The good news that it's actually rather easy, most of the hard work has been completed already. You just need to modify your template and view, and then add some Sass.

Modify the Template

First you have to find the template that contains the content you want to push. For the purposes of this tutorial, I've added some lorem ipsum to the template I created as part of the artists module tutorial, artist_list.tpl. It looks like this:

<button class="artist-list-extra-information-pusher" data-type="sc-pusher" data-target="extra-info">Read More<i></i></button>

<div class="artist-list-extra-information-container" data-action="pushable" data-id="extra-info">
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur mattis leo sit amet faucibus euismod. Sed a nunc mi. In at dui vel lectus pharetra tristique. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis a pharetra nibh.</p>
    <p>Pellentesque euismod nisi et interdum accumsan. Nulla lacinia, nisi sit amet vehicula sagittis, libero ligula molestie est, in vehicula lacus lectus ut tellus. Aenean dignissim eros augue, molestie porttitor ligula viverra vel. Quisque sed felis in leo pellentesque accumsan.</p>
    <p>Pellentesque a arcu eu dui dictum placerat. Nulla eu lorem vel ipsum blandit molestie. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Pellentesque porttitor convallis eros, pellentesque auctor diam interdum a. Phasellus at interdum lectus. Integer et felis at neque ultrices aliquam id non ex. Mauris sed libero in erat laoreet pulvinar vel non nunc.</p>
</div>

The class names are canonical to my template, so you'll need to modify those to match your template and your site's naming conventions. However, you'll note the data attributes, which have the following properties:

  • data-type="sc-pusher" — this must go, as is, on the button that the user will use to access the pushed content. It is used by jQuery.scPush to identify push pane buttons.
  • data-target="extra-info" — this also goes on the button but it can be named what you want, as long as it doesn't conflict with another attribute with the same value. This tells the button which content it will access. Note that this match the content's data-id attribute value.
  • data-action="pushable" — this must go, as is, on the content that will be pushed off the page.
  • data-id="extra-info" — as mentioned in data-target, it doesn't really matter what this is called as long as the two attributes' values match.

That's basically it, next you'll need to edit the view associated with the template.

Modify the View

So for my template, I have to edit Artist.List.View.js. Firstly, you have to include the plugin as a dependency. So add jQuery.scPush to the define statement.

You don't need to add it as a parameter to the function.

After that, you need to add the following functions to the return statement:

showContent: function() {
  var self = this;
  this.application.getLayout().showContent(this).done(function () {
      self.initPlugins();
  });
},

initPlugins: function()
  this.$el.find('[data-action="pushable"]').scPush();
}

In a nutshell, these two functions initialize the plugin and the elements in the template that relate to the functionality.

Testing and Styling

After saving those changes, you can run gulp local and spin up your local server to take a look at your site. If you squash down the browser to mobile proportions, you'll see the pusher button appear. If you click it, the push pane will expand and reveal its contents.

However, you'll notice a number of things that need to be fixed with styling, like how the button isn't styled and how the content isn't hidden on mobile devices. The good news, though, is that, like the JavaScript, some Sass is included with the plugin that you can extend in your stylesheet. You can, for example, check out the classes starting .push-button- in _buttons.scss for the base styles for the push buttons, but for now, you can include the following in the Sass for the sake of the tutorial:

.artist-list-extra-information-pusher {
    @extend .push-button-primary;
    margin: $sc-xlarge-margin 0 $sc-large-margin;
    font-weight: $sc-font-weight-semibold;
    position: relative;

    i {
        position: absolute;
        right: 15px;
        top: 50%;
        height: 26px;
        margin-top: -12px;
    }
}

.artist-list-extra-information-container {
    width: 100%;
}

Note the styling on the container, this is necessary for this particular template because of how it's built. But you'll notice that by default some styling will be applied to push pane buttons and containers, so, depending on how your template is built, you may have to make your own adjustments. Save and refresh your local site; it should look something like the following:

That's pretty much it, although there are some additional options that you can configure.

Configuration and Utilization

In the initPlugins function, you can pass it an option called target which accepts one of two values:

  • mobile — pushes content only on mobile devices. This is the default value.
  • tablet — pushes content on both mobile and tablet devices. For tablets, rather than filling the entire screen like on mobile devices, a fixed width push pane is used instead (472px).

The distinction of what is a mobile or tablet device is based on Bootstrap's screen width media queries breakpoints. Just as a code snippet, if you wanted to make it work for tablets your code would look something like:

this.$el.find('[data-action="pushable"]').scPush({ target: 'tablet' });

Finally, if you want ideas on how it's used in the reference application, you can take a look at the ItemDetails and Facets modules. Combined with looking at the source code and documentation, this should give you a good idea of how to use it on your site.

Further Reading