envelope

Since: Editor 1.0

Visually attach the form to an existing element on the page. Please note - this property requires the Editor extension for DataTables.

The full Editor reference documentation is available to registered users of Editor - the information shown below is a summary only. If you already have an Editor license please , alternatively an Editor license can be purchased on this site, or sign up for the free trial.

Description

Editor has two built in display controllers (lightbox and envelope). These display controllers provide the method for how the form is actually shown to the end user. Which option is used is controlled by the display option.

The envelope display controller will visually attach the form to an existing element in the document (usually a table row or the table header), making the form look like it slides out from underneath the attached element.

Unlike the lightbox display controller, the envelope display is not static in the viewport, and it will move with the page as it is scrolled. However, the background element it uses, to help increase focus on the form, is static and will not move with the document scrolling.

The envelope controller provides options to configure how it displays the Editor form through the properties in the object $.fn.dataTable.Editor.display.envelope.conf. The default options are (see before for a detailed explanation of each):

{
    "attach":        "row",
    "windowPadding": 50,
    "windowScroll":  true
}

Setting custom values

Setting a custom value for the envelope display controller can be done in one of two different ways. For setting a single option use:

$.fn.dataTable.Editor.display.envelope.conf.windowPadding = 50;

To set multiple items, it is more code efficient to use the jQuery.extend() method:

$.extend( $.fn.dataTable.Editor.display.envelope.conf, {
    windowPadding: 50,
    attach:        "head"
} );

Options

The envelope provides the following options:

attach

When Editor displays the form, the envelope display controller will attempt to visually attach the form to an existing element. This option controls what element the form is attached to. It can take one of two values:

  • row - Attach to the row on edit and remove actions. The thead will be used for the create action. This is the default option.
  • head - Always attach to the table's thead element

windowPadding

The Editor form is designed so it will visually fit inside the browser's viewport, with the fields scrolling and the header / footer always being visible (note this can be disabled using CSS if you wish). As such, the form has the height of the browser's window in which to show the form. By default the form does not touch the edge of the browser window when using the envelope display, but how far that padding distance is can be controlled by this parameter. It is an integer, with the size in pixels. 0 would indicate no padding if you want to make full use of the display area available.

windowScroll

By default when the envelope is displayed, the display controller will scroll the window's scrolling to bring the form fully into the viewport. That scroll can be disabled using this option, by simply setting it to false (true is the default).