Clipboard functions
¶

As of version 5.8.9 Guriddo jqGrid JS support a set of clipboard functions where friendlily way is provided to exchange data between the jqGrid and other applications. Actually with a help of these functions is possible to interactively copy a set of data from the visible rows in the grid and paste it in other application and vice versa.

This require some special condition which will be described below.

Concepts and usage ¶

The content of the first three chapters is taken from here

The system clipboard is a data buffer belonging to the operating system hosting the browser, which is used for short-term data storage and/or data transfers between documents or applications. It is usually implemented as an anonymous, temporary data buffer, sometimes called the paste buffer, that can be accessed from most or all programs within the environment via defined programming interfaces.

The Clipboard API allows users to programmatic-ally read and write text and other kinds of data to and from the system clipboard in secure contexts, provided the user has met the criteria outlined in the Security considerations.

Events are fired as the result of cut, copy, and paste operations modifying the clipboard. The events have a default action, for example the copy action copies the current selection to the system clipboard by default. The default action can be overridden by the event handler — see each of the events for more information.

Interfaces ¶

Clipboard Secure context

Provides an interface for reading and writing text and data to or from the system clipboard. The specification refers to this as the 'Async Clipboard API'.

ClipboardEvent

Represents events providing information related to modification of the clipboard, that is cut, copy, and paste events. The specification refers to this as the 'Clipboard Event API'.

ClipboardItem Secure context

Represents a single item format, used when reading or writing data.

Security considerations ¶

The Clipboard API allows users to programmatically read and write text and other kinds of data to and from the system clipboard in secure contexts.

The specification requires that a user has recently interacted with the page in order to read from the clipboard (transient user activation is required). If the read operation is caused by user interaction with a browser or OS "paste element" (such as a context menu), the browser is expected to prompt the user for acknowledgement. For writing to the clipboard the specification expects that the page has been granted the Permissions API clipboard-write permission, and the browser may also require transient user activation. Browsers may place additional restrictions over use of the methods to access the clipboard.

Introduction¶

jqGrid uses Clipboard secure content to interact with other applications. Since the grid is a tabular data the approach used to copy and paste the data is CSV string. In common the string contain header and body data cells separated with separator. This is the format that we use to exchange data.

The simple way to start the clipboard functions is to call the method startClipboard:

$("#jqGrid").jqGrid('startClipboard');

where #jqGrid is the id of the already created grid.

To remove these functions and all related events use stopClipboard

$("#jqGrid").jqGrid('stopClipboard');

After starting the clipboard functions the user can select cells from the grid using mouse. This can be done if the left mouse button is clicked hold it and try to mark the desired cells. To stop the selection release the left button. To lunch any action related to clipboard it is needed to click right mouse button within the grid content. After click the button the following context menu appear like in the picture below:

Screenshot

As can be seen there are predefined actions. Any action can be enabled or disabled as we can see this below. Folow a short description of the action:

Copy Selected to the Clipboard - this action copies the selected cells to the clipboard in csv format configured with options (see below)

Paste Update From Clipboard - generally paste the content from the clipboard (csv formated data) from selected position in grid and overwrites the data; in case the pated rows are greater from the rows to be updated , the remaining rows are inserted. In case if the configuration is to paste the content using the colModel names (the source data should contain the names too), the paste is done from the selected row. If this is not enabled then the paste begin from the selected cell.

Paste Add From Clipboard - generally add the content from the clipboard (csv formated data) from the last row in grid. In case if the configuration is to paste the content using the colModel names, the paste is done from the last row. If this is not enabled then the paste begin from the selected cell in last row.

Repeat Row vertically - Repeat the selection of the first row to the end of the selectiion

Repeat Column Horizontally - Repeat the selection of the first column (from left) to the end of the selected columns.

Undo - this command restores the original data in case paste or repeat commands are executed.

Cancel - closes the context menu

Configuration¶

To configure the clipboard functions use the following syntax:

$("#gridID").jqGrid('startClipboard', options);

whare the gridID is the id of the grid and options is a object with the following default properties:

const  options  = {
    copy_delimiter : '\t',
    copy_newline: '\n',
    copy_header_included : true,
    copy_formated_data : true,
    show_info_after_copy: true,
    paste_delimiter : '\t',
    paste_newline : '\n',
    paste_autodetect_delim : true,
    paste_header_included : false,
    paste_skip_formatter : true,
    show_info_after_paste: true,
    beforeCopyData : null,
    afterCopyData :null,
    beforePasteData : null,
    afterPasteData : null,
    menuConfig : {
        copy : true,
        paste: true,
        paste_add : true,
        row_vertical : true,
        row_horizontal : true,
        undo : true,
        cancel : true
    },
    toastPosition : "top center",
    userMenus : []
}

As can be seen there are options related to copy action and options related to the paste action

Copy action options¶

The related options are:

copy_delimiter : '\t',
copy_newline: '\n',
copy_header_included : true,
copy_formated_data : true,
show_info_after_copy: true,
beforeCopyData : null,
afterCopyData :null,

copy_delimiter - string - the delimiter between cells when the data is copied to the clipboard. Default is Tab.
copy_newline - string - the line delimiter for the rows - Default '\n'
copy_header_included - boolean - determine if the names of the selected data (from colModel) should be put as first row in the data to the clipboard. - Default is true.
copy_formated_data - boolean - determine if the data copied to the clipboard should be as seen into the grid - i.e if formatter is applied. Default is true
show_info_after_copy - boolean - determine if the toast message should appear if the data is copied with success or not.
beforeCopyData - function - event which raises before the data is a copied to the clipboard. Parameters passed to this events are array which represent the data to be copied and the clipboard options.
afterCopyData - function event which raises after the data is a copied to the clipboard. Parameters passed to this events are array which represent the copied data and the clipboard options.

Paste actions¶

paste_delimiter : '\t',
paste_newline : '\n',
paste_autodetect_delim : true,
paste_header_included : false,
paste_skip_formatter : true,
show_info_after_paste: true,
beforePasteData : null,
afterPasteData : null

paste_delimiter - string - the delimiter between cells for the data in the clipboard. Default is Tab.
paste_newline - string - the line delimiter for the rows in the clipboard - Default '\n'
paste_autodetect_delim - boolean - is true the program try to auto-detect delimiter in clipboard from the one of the following - '\t', ',', ';', '|'. Default true.
paste_header_included - boolean - determine if the names in clipboard data are present as first row.. - Default is true.
paste_skip_formatter - boolean - If true the data is inserted into the grid as it is. If false the data is formatted according to the formatters defined in colModel. Default is true
show_info_after_paste - boolean -If set to true info dialog appear when the data is pastedt.
beforePasteData - function - event which raises before the data is inserted into the grid. Parameters passed to this events are string which represent the data to be inserted and the detected delimiter .
afterPasteData - function event which raises after the data is inserted into the grid. Parameters passed to this events are data array of objects which represent the inserted data and the header array if available.

Other options¶

menuConfig - object - describes the available default menu and determine which item in the menu can appear when the user click right mouse button
toastPosition - string determines the appearance of the toast when the data is copied in the clipboard. Default is "top center".
userMenus - array - with this array is possible to set user defined menus, which can appear when the right mouse button is clicked. These menus appear after the enabled main actions. The the elements in the array is a set of objects with the following properties.

element = {
  id : $.jgrid.randId(),
  icon : "",
  position : "last",
  cloaseoncall : true,
  divider : false,
  title : "",
  click : null
}

title - the text that will appear in the menu
icon - the icon associated with this menu. This should correspond to the used CSS framework name
click - function to be executed when the menu is selected. To this function is passed the event
position - the position of the item added. Can be "last" or "first"
closeoncall - closes the menu after selecting the item
divider - adds a divider in the menu. The click event and title do not have effect in this case
id - the id of the item when inserted into the menu. If this parameter is not set jqGrid creates internally it using the jqGrid rand function - $.jgrid.randId()

Clipboard functions¶

Concepts and usage¶

Interfaces¶

Security considerations¶