Tips and Tricks

Themes

Assigning a theme to use with wcDocker is as simple as calling a function.

myDocker.theme('shadow');

In this case, shadow is the name of a theme shadow.css found in the themes folder.


Using the Layout Table Item

the wcLayoutTable object makes it easy to organize the contents of your wcPanel. But, sometimes you need to make some style changes to the table cells themselves! wcLayoutTable.item() and wcLayoutTable.addItem() both return you a handy tableItem object which contains convenient methods for styling!

myPanel.addItem(domNode).css('text-align', 'right').css('border', '1px solid black').stretch('100%', '100%');

Here we are using the tableItem.css() and tableItem.stretch() functions, which can be chained! The first provides a way to add normal style attributes to the cell while the second provides a more reliable way to set your table cell sizes.


Event System

The event system is critical for communication between your panels. Often times you will need this to ensure all your panels integrate properly and intuitively.

For example: One panel may be dedicated to showing the properties of an object, while another panel may be responsible for displaying and allowing the user to select an object. If communication did not exist between the two panels, when an object is selected, the property panel would never know to show its properties.

First our property panel has to be listening for the event, in this case we have named one 'object selected' (It can be any string).

propertyPanel.on('object selected', function(object) {
  // Registered event handler for the 'object selected' event
  // Here, we do something to the object that was just selected.
  if (object) {
    showProperties(object);
  }
});

Once an object is selected in the other panel, it can trigger an event to notify any panels who care

otherPanel.trigger('object selected', selectedObject);

All events are broadcast to all panels (including itself and docker) who have registered for the named event and will receive it. See wcDocker.on() and wcDocker.trigger() for further details.


Storing User Configurations

Entire layout configurations can be saved and restored using wcDocker.save() and wcDocker.restore().

var savedLayout = myDocker.save();

// Any time you wish to restore a previously saved layout.
myDocker.restore(savedLayout);

The saved layout data is a serialized string that can be stored in cookies, or wherever you wish for later use!

Additionally, any panel can register events if they need to save and restore any custom attributes.

myPanel.on(wcDocker.EVENT.SAVE_LAYOUT, function(data) {
  // Save a custom attribute into the layout configuration data
  data.someValue = somePanelValueToSave;
});

myPanel.on(wcDocker.EVENT.RESTORE_LAYOUT, function(data) {
  // When a layout is being restored, you can retrieve those custom values if they exist.
  somePanelValueToRestore = data.someValue;
});

Batch Operations

Adding elements into the wcLayoutTable is not a problem in most cases, except when you need to add them in large quantities. Every time an item is added into the layout it causes the document to re-calculate and render. To improve performance, the layout can be put into a batch mode process, where it will queue all additions and add them all in a single operation.

myPanel.layout().startBatch();
for (var i = 0; i < 1000; ++i) {
  myPanel.layout().addItem($('div'), 0, i);
}
myPanel.layout().finishBatch();

Custom Panel Buttons

All panels can contain their own custom buttons which appear in the upper right corner of the frame (where the title bar and close button are).

To add a new button, use the wcPanel.addButton() function.

myPanel.addButton('Some ID Name', 'normalStateClass', 'B', 'Tooltip text', true, 'toggledStateClass');

Also, you can register an event to receive notifications whenever any custom button has been pressed.

myPanel.on(wcDocker.EVENT.BUTTON, function(button) {
  // In case we have multiple custom panel buttons, we can check the name of the activated button
  if (button.name === 'Some ID Name') {
    var toggled = button.isToggled;
    if (toggled) {
      // The button has been clicked, and its current state is depressed.
    } else {
      // The button has been clicked, and its current state is normal.
    }
  }
});

Popup or Modal Panels

Popup windows are a part of almost any application, and with wcDocker, it is a very simple process. In this case, any panel can become a popup by creating them and setting them to a floating (or detached) state.

myDocker.addPanel('popup', wcDocker.DOCK.FLOAT);

And if you want to block all other input until the user closes or acknowledges the panel, you can set it to a modal state instead.

myDocker.addPanel('popup', wcDocker.DOCK.MODAL);

Just be careful that all modal panels can be closed somehow, or else you will permenantly block the application.

Go back to the Getting Started tutorial.
Continue to the Widgets tutorial.


Panel Creation Elements

By default, wcDocker provides a right-click context menu that allows users to create new panels into their view. However, you may want to implement panel creation a different way. wcDocker provides an easy method for doing so, in the form of a CSS class. Simply create any HTML element, give it the CSS class "wcCreatePanel" and provide it with the panel type as the data attribute "panel", and wcDocker will instantly treat it as a panel creation element. The user can then drag-drop that element directly into their layout to add the new panel.

{@lang xml}<span class="wcCreatePanel" data-panel="My Custom Panel Type">Create My Custom Panel Type</span>

This element can be styled to looked exactly the way you want, whether it be a simple text element, or a fancy looking button!

Additionally, setting the data attribute "nofloating" to true will enforce that the user create this new panel docked within the layout rather than floating.

Here is the example used in our demo page for the Creation Panel:

myDocker.registerPanelType('Creation Panel', {
  faicon: 'plus-square',
  onCreate: function(myPanel) {
    // Retrieve a list of all panel types, that are not marked as private.
    var panelTypes = myDocker.panelTypes(false);
    for (var i = 0; i < panelTypes.length; ++i) {
      // Retrieve more detailed information about the panel.
      var info = myDocker.panelTypeInfo(panelTypes[i]);

      // We want to show the panel icon, if it exists.
      var $icon = $('<div class="wcMenuIcon" style="margin-right: 15px;">');
      if (info.icon) {
        $icon.addClass(info.icon);
      }
      if (info.faicon) {
        $icon.addClass('fa fa-menu fa-' + info.faicon + ' fa-lg fa-fw');
      }

      // Now create the item using our theme's button style, but add a few styles of our own.
      var $item = $('<div class="wcCreatePanel wcButton">');
      $item.css('padding', 5)
        .css('margin-top', 5)
        .css('margin-bottom', 5)
        .css('border', '2px solid black')
        .css('border-radius', '10px')
        .css('text-align', 'center');

      // Set our item content and insert the icon.
      $item.text(panelTypes[i]);
      $item.data('panel', panelTypes[i]);
      $item.prepend($icon);

      myPanel.layout().addItem($item, 0, i+1);
    }
    // Add a stretched element that will push everything to the top of the layout.
    myPanel.layout().addItem($('<div>'), 0, i+1).stretch(undefined, '100%');
  }
});

Loading Screens

Sometimes panel content needs time to load, for this wcDocker comes with a built in loading screen system.

The loading screen system comes in two forms, an individual panel loader and a full screen loader.

When an individual panel requires some loading time, you can use wcPanel.startLoading() and wcPanel.finishLoading() to display and hide the loading screen for it.

myPanel.startLoading();

// Perform some loading stuff...

myPanel.finishLoading(500);

Similarly, you can use wcDocker.startLoading() and wcDocker.finishLoading() to display a loading screen for the entire view. This is especially useful as an initial loading screen for the entire page.

myDocker.startLoading('Loading...');

// Initialize all panels for the view.

// Register our loaded event, this will be triggered after all panels have been initialized and all panel loading screens have been finished.
myDocker.on(wcDocker.EVENT.LOADED, function() {
  myDocker.finishLoading(500);
});

Note that while the full screen loading screen is active, all individual panel loading screens will be invisible, so it is perfectly ok to use them together!

Also note that the wcDocker.EVENT.LOADED event will only be triggered after all panels have finished their individual loading screens (if they are using it).