Skip to Main Content

Breadcrumb

Overview

The FOS - Splitter plug-in is a region that divides its 2 subregions into 2 panels, separated by a draggable splitter bar. The subregions can be split horizontally or vertically, with numerous other layout options.

This region must have exactly 2 subregions and it works best with a template without margins or padding, such as Blank With Attributes.

This plug-in leverages the Spitter widget that is used in Page Designer. We have included it in this plug-in, as it required a few minor tweaks to support splitters hidden behind tabs, collapsed regions etc.

*** Important ***

From APEX 21.1 onwards the "Always Render Layout" in the "Layout" section when editing the Page Template attribute is set to "Off" by default. This means that the wrapper elements we rely on for the splitter (such as div.row, div.col...) won't be rendered, and breaks the plug-in.

The fix is to perform one of the following:

  1. Edit the page template and under the "Layout" section set the "Always Render Layout" attribute to "On" (this is not possible if your theme is subscribed to a master)
  2. Alternatively add a dummy class name to either the "Row CSS Classes" or the "Column CSS Classes" attribute (on one of the direct child sub-regions of each splitter plug-in region)

Notes

  • A splitter region should always have exactly 2 subregions. If it doesn't, a Javascript error will be raised. If you want to have more than 2 regions separated by splitters, simply make one of the 2 subregions a splitter region, again with 2 subregions.
  • A splitter region must always have an exact height defined. This can be a static value like "500" pixels, or be based on a JavaScript expression that is reevaluated each time the window resizes. This might take a little more effort to set up, but it can help create very responsive layouts, similar to the Page Designer.
  • Splitters work best on a page or in a region without margins or padding. See the examples for more info.
  • A responsively positioned splitter e.g. centered 1/2, 1/3 etc. will not be repositioned on window resize if a user has adjusted the splitter position manually.
  • When using a splitter that is hidden behind a non active tab or in a collapsed region then please ensure that you check "Lazy Render" in the options.

Examples

Orientation

The Splitter region supports 2 orientations: Horizontal, where the subregions are side by side, and Vertical, where the subregions are stacked on top of eachother.

Example 1 - Horizontal Splitter

Subregion #1
Subregion #2

Example 1 - Vertical Splitter

Subregion #1
Subregion #2

Direction

The Direction dictates how the splitter will collapse on click of the button. The 2 options are To Start and To End.

For the Horizontal orientation, To Start will normally point to the left, but in case your application runs in Right To Left mode, it will point to the right.

Note that the Direction also has an impact on the initial position of the splitter. If the position of the splitter is 100px, the splitter will be positioned 100px away from the side that collapses. E.g. in the case of Vertical+To Start, the splitter will be positioned 100px under the top side of the region.

Example 2 - Horizontal - To Start

Subregion #1
Subregion #2

Example 2 - Horizontal - To End

Subregion #1
Subregion #2

Example 2 - Vertical - To Start

Subregion #1
Subregion #2

Example 2 - Vertical - To End

Subregion #1
Subregion #2

Initial Splitter Position

There are a number of options when it comes to the initial position of the splitter on page load.

Proportional

The simplest solution is to select one of the built-in proportional positions. These are: "0 (collapsed)", "1/4", "1/3", "1/2", "2/3" and "3/4". For example, when choosing "1/2", the splitter will be positioned at the very center of the region, no matter how wide or tall the region or the window is.

Based On a Javascript Expression

For more control, you can provide the starting position as a Javascript expression that evaluates to a number in pixels. While this sounds complex, it can be an arbitrary value like 300 or a more complex expression like $('#my-splitter-region').width() / 5

Example 3 - 300

The initial splitter position is 300px away from the collapsible side.

Example 3 - $('#my-splitter-region').width() / 5

The initial splitter position is a fifth of the region width away from the collapsible side.

Persist State

This widget also has the ability to "remember" the last position of the splitter. This preference can be stored either in the database as a User Preference, or in the user's browser under local storage.

Storing it as a User Preference means that an AJAX call will be made every time the splitter is moved. This preference is user specific and can even be carried accross multiple devices or browsers.

The second possibility is to store the position in the browser's Local Storage. This option does not need to communicate to the database, but it also means that the preference is not user specific and will not be carried to other devices or browsers.

The following splitter region has this option enabled and set to Local Storage. Move the splitter around and remember where you left it. Then refresh the page or create a new session. The last splitter position will be restored on page load.

If no previous preference was found or the splitter was never moved, the initial position will be defaulted to the above options, e.g. proportional value or based on a Javascript expression.

Example 3 - Persist State - Local Storage

Subregion #1
Subregion #2

Region Height

This plug-in requires an exact region height which must be provided as a Javascript expression.

It can be a static value, such as 500 or a more complex expression, such as $(window).height() - $('#t_Header').height(). This expression will be reevaluated and its result reapplied every time the screen size changes, ensuring a highly responsive and consistent layout.

Dynamic Height - Modal Dialog

In this example we want to split an entire modal dialog in half. To achieve this, we have to do the following:

  • Enable the "Remove Body Padding" option of the modal page
  • Give the modal dialog a static height, e.g 500
  • Set the template of the splitter region to "Blank with Attributes"
  • Set the height of the splitter region to: $(window).height()

Now open the modal dialog. You will see the splitter takes the whole height, even as you resize the dialog!

Dynamic Height - Regular Page

To achieve dynamic full page height on regular pages, do the following:

  • Standard pages in Universal Theme do not have a "Remove Body Padding" option, so we must add the following inline CSS to the page: .t-Body-contentInner{padding: 0;}
  • Set the template of the splitter region to "Blank with Attributes"
  • Set the height of the splitter region to: $(window).height() - $('#t_Header').height() to account for the height of the header.

You will notice that even as you resize the page or expand or collapse the navigation menu, the splitter region will take the entire size of the page and dynamically resize appropriately.

Nested Splitters

While a Splitter region must have exactly 2 subregions, 1 or both of these subregions can be Splitter regions themselves. This type of nesting allows for some very complex layouts.

When dealing with nested splitters, you often have to reference the height or the width of the parent panel or region. To aid with this, the children of a Splitter region with static ID my_region will be created with IDs my_region_splitter_first and my_region_splitter_second respectively.

Click the button to see how the following examples were constructed.

3 Panels

Subregion #1
Subregion #2
Subregion #3

Golden Splitter

1
2
5
6
4
3

Real World Examples

Interactive Grids

Tabs, Region Display Selectors, Collapsible Regions

This is an example showing you how the splitter will behave for non-active tabs & region display selectors & collapsible regions. When using these features you need to ensure you have checked "Lazy Render" in the Splitter options.

JET Charts

This is an example showing you how the splitter will behave when using JET Charts. The splitter can resize JET Charts to fit the size of the spliced region. You can enable this automatic resizing by checking the the "Resize Jet Charts to Fit Region" option.

Note: due to the internal behaviour of APEX resizing JET Charts you will see some slight jumping, since the inbuilt APEX resizing does not work as expected due to absolute positioning of splitter regions. The plug-in resizes after the APEX resizing, hence the slight visual jump.

Design

You can preview the plug-in setup as you would see it in page designer. You can either do this by clicking this button in the top right corner of each example, or you can see all the examples together in the region below.

Looking at the examples you'll see just how easy the plug-in is to use. Don't worry about changing any values as they aren't saved. We actually encourage you to change them, so you can see the behaviour of the attributes and their help text.

FAQ

  • How can I set the splitter position after initialization?

    You can change many splitter properties after initialization via Javascript. In this case you can run the following, with my-region being the region's static id:

    $('#my-region_splitter').splitter('option', 'position', 100);

    For the complete list of options and methods, see the widget.splitter.js file