Custom Button Bars: /home/

Custom Button Bars

The standard button bars for any query or table can be customized through XML or the JavaScript client API. You can add, replace, delete buttons or drop-down menus. You can also control the visibility of custom buttons based on a user's security permissions. Custom button bars can leverage the functionality supplied by default buttons.

This page covers:

LABKEY.QueryWebPart JavaScript API
XML metadata
Example of a button bar defined in custom XML metadata

LABKEY.QueryWebPart JavaScript API

The LABKEY.QueryWebPart's buttonBar parameter can be used to build custom button bars. For example:

var qwp1 = new LABKEY.QueryWebPart({
    renderTo: 'queryTestDiv1',
    title: 'My Query Web Part',
    schemaName: 'lists',
    queryName: 'People',
    buttonBar: {
        includeStandardButtons: true,
        items:[
          LABKEY.QueryWebPart.standardButtons.views,
          {text: 'Test', url: LABKEY.ActionURL.buildURL('project', 'begin')},
          {text: 'Test Script', onClick: "alert('Hello World!'); return false;"},
          {text: 'Test Handler', handler: onTestHandler},
          {text: 'Test Menu', items: [
            {text: 'Item 1', handler: onItem1Handler},
		    {text: 'Fly Out', items: [
              {text: 'Sub Item 1', handler: onItem1Handler}
            ]},
            '-', //separator
            {text: 'Item 2', handler: onItem2Handler}
          ]},
          LABKEY.QueryWebPart.standardButtons.exportRows
        ]
    }
});

Documentation:

Notes:

A custom button can get selected items from the current page of a grid view and perform a query using that info. Note that only the selected options from a single page can be manipulated using onClick handlers for custom buttons. Cross-page selections are not currently recognized.
The allowChooseQuery and allowChooseView configuration options for LABKEY.QueryWebPart effect the buttonBar parameter.

XML metadata

In addition to setting buttons from the API, an administrator can set additional buttons in the metadata of a table using XML syntax. When clicked, custom buttons can:

Navigate the user to a custom URL (see the "Google" button in the example below).
Execute an action using the onClick handler (see the "OnClickButton" below).
Invoke JavaScript functions (see the "View Chart" button in the next section's example). The JavaScript function is located in an included .js file.

Documentation:

buttonBarOptions element
ButtonBarOptions type
ButtonBarItem type
URL Actions. Also covers customized URL actions.

Notes:

Using the ButtonBarItem type, you can add new buttons to an existing button bar while including all of the standard buttons. You can use the insertBefore="<existing-button>" or insertAfter="<existing-button>" to place a button after another button. Alternatively, you can use insertPosition="3" to place a button absolutely or insertPosition="beginning" or insertPosition="end" to place the button at the beginning or end of the button bar. The insertBefore, insertAfter, and insertPosition attributes are not compatible with one another and cannot be combined.

Simple example:

<tables xmlns="http://labkey.org/data/xml"> 
  <table tableName="ListName" tableDbType="NOT_IN_DB"> 
    <columns></columns> 
    <buttonBarOptions position="top" includeStandardButtons="true" > 
      <item text="ButtonTitle"> 
        <item text="OnCLickButton"> 
          <onClick>alert('Hello');</onClick> 
        </item> 
        <item text="Google"> 
          <target>http://www.google.com</target> 
        </item> 
      </item> 
    </buttonBarOptions>   
  </table> 
</tables>

Example of a button bar defined in custom XML metadata

The example XML below creates a custom button bar that includes some standard buttons along with a custom button. It is excerpted below. Things to note:

The XML includes standard buttons by including a string that matches the standard button's caption ("originalText").
It also includes a custom "View Chart" button.
The onClick behavior for the custom button is defined in the button bar's included script ("studyButtons.js").

The full example can be found in the LabKey LabKey Open Source Project along this path: <LabKey_Root>\server\customModules\ehr\resources\queries\study\studyData.query.xml, where LabKey_Root is the root directory of your installation. Note that this module includes Java code, so its directory structure includes an extra level of hierarchy -- the "resources" directory. This directory is not found in Java-less modules.

<query xmlns="http://labkey.org/data/xml/query">
  <metadata>
        <tables xmlns="http://labkey.org/data/xml">
            <table tableName="StudyData" tableDbType="TABLE">                
                <columns>
                    <column columnName="Description">
                        <isHidden>false</isHidden>
                        <displayWidth>300</displayWidth>
                    </column>
                </columns>
                <buttonBarOptions position="both" includeStandardButtons="false">
                    <includeScript>/EHR_Reporting/studyButtons.js</includeScript>
                    <item text="Insert New">
                        <originalText>Insert New</originalText>
                    </item>
                    <item text="Views">
                        <originalText>Views</originalText>
                    </item>
                    <item text="Cohorts">
                        <originalText>Cohorts</originalText>
                    </item>
                    <item text="QC State">
                        <originalText>QC State</originalText>
                    </item>
                    <item requiresSelection="true" text="View Chart">
                        <onClick>
                            historyHandler(dataRegion, dataRegionName);
                        </onClick>
                    </item>
                </buttonBarOptions>
            </table>
        </tables>
    </metadata>
</query>

LabKey Support

LabKey Support