Nerds Publishing Monstrosities

    datatables-contextual-actions

    1.2.1 • Public • Published

    datatables-contextual-actions

    👉View Example👈

    A DataTables JS extension for adding contextual options to one or many selected rows. Ideal if you want synchronized buttons and context-menu actions defined in a single place.

    Context Menu

    Button List

    Button List Icon Only

    This will alter your DataTables table in the following ways:

    • Your actions will be rendered as a row of buttons above your table
    • Right-clicking a row will select it and present the user with a context menu of your actions

    Both can be individually enabled/disabled.

    Dependencies:

    • DataTables, the world's most comprehensive jQuery-based table component

    Getting Started:

    • Use DataTables in your project
    • Include the javascript and css in your project:
    <!-- For example, use a CDN: -->
    <link rel="stylesheet" href="https://unpkg.com/datatables-contextual-actions@latest/dist/dataTables.contextualActions.min.css"/>
    <script src="https://unpkg.com/datatables-contextual-actions@latest/dist/dataTables.contextualActions.min.js"></script>
    • Initialize with a configuration (see the Configuration section below)
    $(document).ready(function () {
    	// Set up our table in standard DataTables fashion (with selection enabled)
    	var myTable = $('#dt').DataTable({
    		select: {
    			style: 'os',
    			selector: 'td:first-child',
    		},
    	});
    
    	// And initialize our plugin.
    	myTable.contextualActions({
    		// Configuration options as described above
    	});
    });

    Configuration:

    options

    Property Type Description Default
    classes string[] CSS classes to apply to both the dropdown-menu and the button container []
    iconPrefix string CSS class that icons will all start with.
    For example, providing 'fas' will default an icon to
    <i class="fas"></i>

    ...before it's assigned its actual icon class.
    ''
    contextMenu contextMenu (see below) required
    showConfirmationMethod function(confirmation) A function taking in a confirmation object (see the documentation on item's confirmation attribute) that handles how to render and show the confirmation to the user. By default this uses the super basic window.confirm but the incoming confirmation parameter matches the config of BootBox, a plugin for showing confirmations using Bootstrap's modals. If using Bootbox, replace with function(confirmation){bootbox.confirm(confirmation)} function(confirmation){ confirmation.callback( window.confirm( confirmation.message)); }
    buttonList buttonList (see below) required
    items item[] (see below) An array of item objects that represent the options that will be both rendered as buttons, and as options in a context menu. required
    deselectAfterAction bool Whether or not to deselect all table rows after an item's action takes place. Note: if your action's code clears and redraws the table anyway, the selection state will be lost regardless of this option. Modify row data in the table itself using the DataTables API if you don't want to accidentally lose the selection state. true

    options.contextMenu

    Property Type Description Default
    enabled bool Whether or not to display a context menu when the user right-clicks a row true
    isMulti bool If true, multiple rows can be selected and then acted upon by right-clicking. If false, right-clicking will de-select all other rows before showing the context menu (default behaviour) false
    xoffset int The horizontal distance away, in pixels, to render the drop-down context menu from the mouse -10
    yoffset int The vertical distance away, in pixels, to render the drop-down context menu from the mouse -10
    showSpeed string A CSS duration describing how quickly the context menu should displayed '0.30s'
    headerRenderer string
    or
    function(rows)
    What to display as the context menu's header.

    Can be a static string or a function of the
    rows selected.
    ''
    showStaticOptions bool Whether or not to display static items in the context menu false

    options.buttonList

    Property Type Description Default
    enabled bool Whether or not to render the options out into an external container as a series of button groups true
    containerSelector string The CSS selector of the container element that the buttons will be rendered into.

    For example, '#my-button-bar'
    required
    iconOnly bool Whether or not to only display icons in the buttons.

    If true, buttons will only contain icons, and the option titles are turned into tooltips.
    true
    disabledOpacity decimal The opacity of a disabled button or context menu icon 0.5
    dividerSpacing int The number of pixels between divided groups of buttons 10
    groupClass string The class to give to the groups of buttons in the button list. Groups are the groupings of buttons separated with divider typed items. For example, with bootstrap, use btn-group ``

    options.item[]

    Property Type Description Default
    type string
    Items can be of the following types:


    • option is the standard type. It means the option is row-scoped and relies on row data to determine its action.


    • static means its action will not receive any data, and it mimics a DataTables button in that it is always visible and is table-scoped, not row-scoped.


    • divider acts simply as a divider item that splits up the above types when being rendered.

    required
    multi bool Whether or not to enable this button when more than 1 rows are selected false
    title string
    What the option is named.
    The title is rendered as:

    • In buttons: the button text

    • In buttons when iconOnly is true: the button's tooltip


    • In context menus: the dropdown option's text


      ''
      multiTitle string The title (above) to render when more than 1 rows are selected ''
      iconClass string The class of the <i></i> styled icon to render.
      For example, if iconPrefix is 'fa fa-fw' and iconClass is 'fa-eye', then <i class="fa fa-fw fa-eye"></i> is rendered.

      Leave blank to render no icon.
      ''
      classes string[] An array of CSS classes to add onto the rendered item (either the button or the
      dropdown option)
      []
      contextMenuClasses string[] An array of CSS classes to add onto the rendered item (ONLY the
      dropdown version)
      []
      buttonClasses string[] An array of CSS classes to add onto the rendered item (ONLY the button version) []
      id string Optionally you may assign an id to the item's rendered element if you wish to target it with any custom code later on ''
      confirmation object
      or
      function(rows)
      The confirmation configuration object.

      Include a title and a message that will appear in the default browser confirm dialogue

      OR you may provide a confirmation object that matches that of Bootbox.js, and then override the default confirmation behavior by passing bootbox.confirm to options.showConfirmationMethod

      Example (default behavior):

      {
      title:'Foo',
      message:'Are you sure you want to Bar?'
      }


      Example (if using Bootbox):

      {
      title: 'Delete Item(s)',
      message: 'Do you want to delete the item(s)?',
      buttons: {
      cancel: {
      className: 'btn-link',
      label: 'Cancel'
      },
      confirm: {
      className: 'btn-danger',
      label: 'Delete'
      }
      }
      {}
      action function(rows) The action to execute against the 1 or more rows selected when the action was executed required
      isDisabled bool
      or
      function(row)
      Whether or not to totally disable the option.

      If a function of row is provided, this becomes a test to run against every selected row.
      If ANY of the rows pass this test, the option will be disabled

      For example, to disable the button for "John" rows:
      (row) => row.FirstName === 'John'
      {}
      isDisabledStrictMode bool Modifies the behavior of isDisabled (see above). If specified and is true, then rather than allowing a multi-enabled button to be clicked when ANY selected row is enabled/applicable, ONLY enable the option if ALL selected rows are enabled/applicable.

      isDisabledStrictMode ensures that ALL selected rows fail the isDisabled check (in other words, are ALL enabled) before allowing an action to be confirmed or executed
      false
      isHidden bool
      or
      function(row)
      Similar to the above isDisabled but renders an option hidden/invisible instead of just being disabled (greyed out) {}

      Please see the example page referred to above for a demo of how to use all these options together.

      Refreshing:

      If you change underlying data that some renderers rely on (isDisabled on a static-typed action, for example), and want to update the controls without having the user manually select/deselect rows, you can force-update contextualActions like so:

      $(document).ready(function () {
      	var myTable = $('#dt').DataTable({
      		// ...
      	});
      
      	// And initialize our plugin.
      	var myContextActions = myTable.contextualActions({
      		// ...
      	});
      
      	// Manually refresh the control and force all actions to be re-evaluated
      	myContextActions.update();
      });

      Building:

      If you wish to examine the full source and/or make changes, clone the repo locally, make your changes, and run

      npm i
      npm run build

      to build the minified .js and .css files.

      Install

      npm i datatables-contextual-actions

      DownloadsWeekly Downloads

      56

      Version

      1.2.1

      License

      ISC

      Unpacked Size

      109 kB

      Total Files

      13

      Last publish

      Collaborators

      • parx