SpreadJS 13
SpreadJS Documentation / Developer's Guide / Features / Manage User Interface / Cell Buttons
In This Topic
    Cell Buttons
    In This Topic

    SpreadJS provides button capabilities within the cells to enhance the usability of spreadsheets.

    What are Cell Buttons?

    Cell buttons are a set of predefined buttons (like drop-down buttons, undo/redo buttons, enable/disable buttons, spin buttons etc.) that can be added to cell margins to configure additional functionalities in the cells of the worksheet. For instance- The dropdown cell buttons can launch a drop-down menu for accepting various data inputs from the user.

    Integrating buttons in cells allows users to enhance the functionality of the workbook. Moreover, users can code specific behavior for cell buttons to execute specific operations when a user clicks on it, edits a cell or hovers over a cell etc.

    Example - Users can create a button with color picker drop-down by defining a custom color-picker named style for the cell. Now, any cell can easily become a color picker (or date picker, ...) by applying a style.

    Adding a Cell Button

    Users can add the following types of cell buttons while working with spreadsheets in SpreadJS:

    Configuring Cell Buttons

    Users can configure cell buttons by using different properties available for cell buttons as described in the table shared below:

    Property Description
    ButtonPosition This property is of type ButtonPosition enumeration that specifies the position of the cell button. Users can set the position of the cell button to left or right and create a custom style for displaying these buttons depending upon their requirements using the following values:
    • left = 0; indicates cell button is at the left of the cell.
    • right =1; indicates the cell button appears at the right of the cell.
    CaptionAlignment This property is of type CaptionAlignment enumeration that specifies the position of the caption in the cell button. Users can configure the position of the caption to left or right as per their specific requirements using the following values:
    • left = 0; indicates the caption of the cell button is at the left of the cell.
    • right =1; indicates the caption of the cell button appears at the right of the cell.
    ButtonImageType This property is of type ButtonImageType enumeration that specifies the image type of the cell button. Users can configure the button image type as per their specific preferences using the following values:
    Value Description
    none = 0 Indicates the cell button image type is none.
    custom=1 Indicates the cell button image type is custom.
    clear=2 Indicates the cell button image type is clear
    cancel = 3 Indicates the cell button image type is cancel.
    Ok = 4 Indicates the cell button image type is Ok.
    Dropdown = 5 Indicates the cell button image type is dropdown.
    ellipsis = 6 Indicates the cell button image type is ellipsis.
    left =7 Indicates the cell button image type is left.
    right=8 Indicates the cell button image type is right.
    plus=9 Indicates the cell button image type is "plus".
    minus =10 Indicates the cell button image type is "minus".
    undo=11 Indicates the cell button image type is "undo".
    redo =12 Indicates the cell button image type is "redo".
    search =13 Indicates the cell button image type is search.
    separator =14 Indicates the cell button image type is separator.
    spinLeft=15 Indicates the cell button image type is spin left..
    spinRight=16 Indicates the cell button image type is spinRight.
    ButtonVisibility This property is of type ButtonVisibility enumeration that specifies the visibility of the cell button. Users can choose whether to show or hide the cell buttons on different cell states using the following values:
    • always =0; indicates the cell button is always visible.
    • onSelected =1; indicates that the cell button is visible only when the cell is in active state.
    • onEditing =2; indicates that the cell button is visible only when the cell enters in the edit mode.
    caption This property specifies the text of the button that will be displayed in the caption.
    position This property specifies the position of the button in the cell.
    enabled This property specifies whether the cell button will respond to the user actions. The default value is set to true.
    useButtonStyle This property specifies whether the cell button is a button style. The default value is false.
    width This property specifies the width of the button. If users set this property to "null" or "undefined" then the button fit will automatically adjust itself based on the caption and the size of the image.
    visibility This property specifies the visibility of the button. Three options are available ("always", "onselect" and "edit").
    imageType This property specifies the type of the image that users want to display in the button. The default value for this property is "custom".
    command This property allows users to execute a spread command or a callback when the cell button is clicked.
    imageSrc This property allows users to upload an image by providing the source of the image when the imageType is set to custom.
    captionAlign This property specifies the position of the image and the caption. The available options are "left" and "right".
    imageSize This property specifies the image size. The default value is 16px.

    Defining Button Commands

    After creating the cell button, users can specify different command actions to associate different functionalities to the buttons as per the options provided in the following table.

    Command Option Description
    openColorPicker This option can be used when users want to open a color picker on button click event.
    openDateTimePicker This option can be used when users want to open a date time picker on button click event.
    openTimePicker  This option can be used when users want to open a time picker on button click event.
    openMonthPicker This option can be used when users want to open a month picker on button click event.
    openSlider This option can be used when users want to open a slider control on button click event.
    openWorkflowList This option can be used when users want to open a workflow list on button click event.
    openCalculator This option can be used when users want to open a calculator on button click event.
    openList This option can be used when users want to open a list on button click event.

    Using Code

    Refer to the following example code for adding different types of cell buttons in the worksheet.

    JavaScript
    Copy Code
    $(document).ready(function ()
    {
       // Configure Workbook and Worksheet
       var spread = new GC.Spread.Sheets.Workbook($("#sampleDiv")[0]);
       var activeSheet = spread.getActiveSheet();
       activeSheet.setColumnWidth(3, 300);
       activeSheet.setColumnWidth(4, 200);
    
       // Add a basic button with caption
       var basicButttonStyle = new GC.Spread.Sheets.Style();
       basicButttonStyle.cellButtons = 
       [
         {
            caption: "Insert"
         }    
       ];
       
       activeSheet.setText(2, 3, "Basic button with caption");
       activeSheet.setStyle(2, 4, basicButttonStyle);
       
        /* Add button with different configuration settings such as 
        position, style, enabled/disabled */
        var customButtonStyle = new GC.Spread.Sheets.Style();
        customButtonStyle.cellButtons = 
        [
          {
            caption: "enable",
            useButtonStyle: true,
            enabled: true,
            position: GC.Spread.Sheets.ButtonPosition.left
          },
          {
            caption: "disabled",
            useButtonStyle: false,
            enabled: false,
            position: GC.Spread.Sheets.ButtonPosition.right
          }
          ];
         activeSheet.setText(4, 3, "enabled/disabled buttons");
         activeSheet.setStyle(4, 4, customButtonStyle);
        
        // Add button with built-in and custom image
        var ImageStyle = new GC.Spread.Sheets.Style();
        ImageStyle.cellButtons = 
        [
          {
            useButtonStyle: true,
            imageSize: {
            height: 8,
            width: 8
           },
           imageType: GC.Spread.Sheets.ButtonImageType.ellipsis
          },
          {
          useButtonStyle: true,
          imageType: GC.Spread.Sheets.ButtonImageType.custom,
          imageSrc:"data:image/bmp;base64,
          Qk1eAAAAAAAAAD4AAAAoAAAACAAAAAgAAAABAAEAAAAAACAAAADEDgAAxA4AAAAAAAAAAAAAAAAAAP///
          wB+AAAApQAAANsAAAClAAAApQAAANsAAAClAAAAfgAAAA=="
         }
         ];
         activeSheet.setText(6, 3, "Image Buttons");
         activeSheet.setStyle(6, 4, ImageStyle);
         
         // Add Dropdown button with command action
         var dropdownStylecommand = new GC.Spread.Sheets.Style();
         dropdownStylecommand.cellButtons = 
         [
           {
             imageType: GC.Spread.Sheets.ButtonImageType.dropdown,
             command: "openColorPicker"
           }
           ];
           activeSheet.setText(8, 3, "Dropdown button with command");
           activeSheet.setStyle(8, 4, dropdownStylecommand);
          
          // Add Dropdown button with command function
          var dropdownStylefunction = new GC.Spread.Sheets.Style();
          dropdownStylefunction.cellButtons = 
          [
            {
               imageType: GC.Spread.Sheets.ButtonImageType.search,
               command: (sheet, row, col, option) => 
                {
                  if (sheet.zoom() === 1) 
                   {
                      sheet.zoom(1.5);
                   } 
                  else 
                   {
                      sheet.zoom(1);
                   }
                 }
             }
           ];
           
         activeSheet.setText(10, 3, "Dropdown button with command function");
         activeSheet.setStyle(10, 4, dropdownStylefunction);
    });