jsPanel.exportPanels() added in version 2.4.0

jsPanel.exportPanels() allows to export/save the current layout of all jsPanels in the document that are not modals, hints or tooltips. This might be useful in an application where a user can arrange and configure a number of panels you want to restore when the user logs in again later or wants to use the same layout on a different machine.

What will be saved?

The method returns an array of objects where each object has data for a single jsPanel. The basic idea is to export/save panel data the user can influence like size, position, panelstatus plus a few more properties of an existing panel that might change. Saved data can than later be merged with predefined configs to restore the panels to the state when the layout was saved. The following properties are stored in the object for each jsPanel:

  • id: string with the id attribute of the jsPanel to identify the panel if needed
  • title: HTML string with the title of the panel
  • panelstatus: string with the panelstatus (maximized, minimized, ...) at the time of saving
  • size: object with width and height values in pixels
  • position: object with top and left values in pixels (values are relative to browser viewport)
  • offset: object with value 0 for both vertical and horizontal offset. Possible offsets are already incorporated in saved position.
  • content: string with the value of option.content. This might not be the actual content of a panel
  • load: object with the single property url if option.load is used
  • ajax: object with the single property url if option.ajax is used
  • iframe: object with the properties srcdoc and src if option.iframe is used
  • custom: your choice to save custom data you might need when restoring. Any custom data only gets exported when you stored the data in the jsPanel data property prior using jsPanel.exportPanels(). How to do this using jQuery:
    $("#panel_id").data("custom", "your_custom_data");

All other configuration data you possibly need to restore a jsPanel (like theme, callbacks, toolbars, ...) has to come from a "default config" you have to merge with the saved config before actually restoring the panel.

Where will be saved?

The method returns an array of objects where each object has data for a single jsPanel.

By default this array is processed with JSON.stringify() and the result is stored in window.localStorage.jspanels

If you have other needs it's up to you where to save the array jsPanel.exportPanels() returns.

Notes:

  • Modals, hints and tooltips are NOT exported

jsPanel.importPanels(predefinedConfigs) added in version 2.4.0

jsPanel.importPanels(predefinedConfigs) can be used to import and restore jsPanels previously exported using jsPanel.exportPanels().

Argument predefinedConfigs has to be an object with predefined panel configurations. Predefined panel configurations also have to be objects and will be merged with the saved configs when restoring panels. Which panel is used for merging depends on the setting of the specific panels data attribute "custom" (see example below). If predefinedConfigs contains a configuration with the identifier/key default: this config will be applied to all restored panels.


How to use a complete example

// object with predefined panel configurations is required
var predefinedConfigs = {
    // default config will be applied to all restored panels
    default: {
        theme:  "black",
        iframe: {
            style:  {'border': '10px solid transparent'},
            width:  "100%",
            height: "100%"
        }
    },
    // any number of further predefined configs
    configB: {
        theme: "primary",
        callback: function(panel) {
            panel.data("custom", {config: "configB"});
        }
    }
};

// create two example jsPanels
// PANEL 1
$.jsPanel({
    size:     {width: 800, height: 500},
    position: 'auto',
    theme:    'black',
    title:    'jsPanel.de <small>documentation</small>',
    iframe: {
        src:    'http://jspanel.de/documentation/',
        style:  {'border': '10px solid transparent'},
        width:  '100%',
        height: '100%'
    }
});
// PANEL 2
$.jsPanel({
    size:     {width: 800, height: 500},
    position: 'auto',
    theme:    'primary',
    title:    'foundation.zurb.com',
    iframe: {
        src:    'http://foundation.zurb.com/',
        style:  {'border': '10px solid transparent'},
        width:  '100%',
        height: '100%'
    },
    callback: function(panel) {
        // the data attr custom is used to pass the predefined config which
        // has to be merged with the saved config when restoring panels
        panel.data("custom", {config: "configB"});
        // if omitted the default config will be used when merging configs
    }
});

// now export and close all panels
jsPanel.exportPanels();
$(".jsPanel").remove();

// and finally restore exported jsPanels again
jsPanel.importPanels(predefinedConfigs);
create jsPanels and drag/resize panels if you like export and delete jsPanels restore jsPanels

Explanation:

First take a look at the code for PANEL 1. When you call jsPanel.exportPanels() following PANEL 1 data is exported/saved:

  • size: with actual values for css width and height in pixels. So when a user resizes a panel the new dimensions are exported/saved.
  • position: with actual values for css top and left in pixels. So when a user drags a panel the new position is exported/saved.
  • title: with the actual title text/html of the panel.
  • iframe.src: only src and/or srcdoc properties are exported/saved.

Then take a look at the variable predefinedConfigs. It's an object with predefined panel configurations including the jsPanel options that are not exported/saved. If predefinedConfigs contains a config with the identifier default: its options will be applied to all restored panels. Further predefinedConfigs may contain any number of configurations. Which of these further configurations has to be applied to a restored panel depends on the value of the panels data attribute custom. PANEL 1 doesn't have something stored in the data attribute.

So when restoring PANEL 1 theme, iframe.style, iframe.width and iframe.height values from predefinedConfigs.default are merged with size, position, title and iframe.src values from the exported/saved configuration.

Now take a look at the code for PANEL 2 and you'll see a callback that stores the object {config: "configB"} in the data attribute custom of the panel. The data attribute custom is also exported/saved. This tells the restoring method that predefinedConfigs.configB also has to be merged.

So when restoring PANEL 2 its configuration is the result of merging predefinedConfigs.default, predefinedConfigs.configB and the exported/saved configuration. Note that the value of option.theme from predefinedConfigs.default is overwritten by the value from predefinedConfigs.configB.