eLabSDK.Page.Sample

Functions

Name	Description
addSampleDetailButton(btn)	Add a custom action button to the sample detail page toolbar.

This adds a custom button to the action toolbar displayed on individual sample detail pages.
The button appears alongside standard actions like "Edit", "Delete", "Print Label", etc.
The button is rendered with an icon and label in the toolbar style. If a sample is already
loaded, the button is added immediately; otherwise it waits for the sample data to finish
loading. Prevents duplicate buttons by checking the actionID. Use this to add custom sample
operations accessible from the sample detail view.
addButton(btn) | Add a custom button to the sample browser/list page toolbar.

This adds a custom button to the main sample browser toolbar, positioning it before the
standard "Add Sample" button. The button is added immediately if samples are already loaded,
otherwise it waits for the sample table to finish loading data. Use this to add custom bulk
operations, specialized sample creation workflows, or other actions that apply to the sample
list view rather than individual samples.
addTopPageButton($btn) | Add a custom button to the top-right area of the sample page.

This adds a button to the optional actions area at the top-right of the sample browser or
detail pages. The button is added immediately if samples are already loaded, otherwise it
waits for the sample table to finish loading. This area is typically used for secondary or
optional actions that don't belong in the main toolbar. Use this for utility functions,
settings, or helper tools related to sample management.
getParentSampleID() | Get the parent sample ID of the currently displayed sample.

This retrieves the sample ID of the parent sample when viewing a child sample on the sample
detail page. Returns null if the current sample has no parent or if not on a sample detail
page. Parent samples are used in sample hierarchies where samples can be derived from or
linked to other samples. Use this to navigate to parent samples, display lineage information,
or implement inheritance-based functionality.
getSampleID() | Get the ID of the currently displayed sample.

This retrieves the sample ID when viewing a sample detail page. Returns null if not on a
sample detail page (e.g., on the sample list/browser). The function checks the URL hash to
determine if a sample is being viewed. Use this to reference the current sample in custom
actions, API calls, or when building URLs for sample-related operations.
getSampleSeriesID() | Get the ID of the currently displayed sample series.

This retrieves the sample series ID when viewing a sample series detail page. Returns null
if not on a series detail page. Sample series are collections of related samples (e.g.,
clones, replicates) that share common properties. The function checks the URL hash to
determine if a series is being viewed. Use this to reference the current series in custom
actions, API calls, or series-specific operations.
addSection(sectionToAdd) | Add a custom section to the sample detail page.

This inserts a new content section into the sample detail page layout, positioned relative
to an existing section (by default, before the "Storage Location" section). The section
includes a header and custom HTML content. Use this to add custom information displays,
forms, visualizations, or any additional content related to the sample being viewed. The
section can be positioned before or after any existing section.
addTopNotice(noticeToAdd) | Add a warning or informational notice to the top of the sample detail page.

This displays a prominent notice banner at the top of the sample detail page. The notice
can include an icon and custom HTML content, styled with warning colors to draw attention.
Useful for displaying important information, warnings, alerts, or contextual help related
to the specific sample being viewed. The notice is only added once (checked by ID) to
prevent duplicates.

addSampleDetailButton(btn)

Add a custom action button to the sample detail page toolbar.

Kind: global function

Param	Type	Description
btn	`eLabSDK.GUI.Button`	An eLabSDK.GUI.Button instance configured with action, icon, and label

Example

// Add custom export button to sample detail page
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var exportBtn = new eLabSDK.GUI.Button({
        actionID: 'customSampleExport',
        label: 'Export to System',
        icon: 'download',
        action: function() {
          var sampleID = samplePage.getSampleID();
          exportSampleToExternalSystem(sampleID);
        }
      });
      this.addSampleDetailButton(exportBtn);
    }
  });
});

Example

// Add button to send sample data via API
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var sendBtn = new eLabSDK.GUI.Button({
        actionID: 'sendToLIMS',
        label: 'Send to LIMS',
        icon: 'paper-plane',
        action: function() {
          var sampleID = samplePage.getSampleID();
          $.post('/api/lims/send', { sampleID: sampleID }, function() {
            alert('Sample sent to LIMS successfully');
          });
        }
      });
      this.addSampleDetailButton(sendBtn);
    }
  });
});

addButton(btn)

Add a custom button to the sample browser/list page toolbar.

Kind: global function

Param	Type	Description
btn	`eLabSDK.GUI.Button`	An eLabSDK.GUI.Button instance to add to the browser toolbar

Example

// Add bulk export button to sample browser
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample();
  
  var bulkExportBtn = new eLabSDK.GUI.Button({
    label: 'Bulk Export',
    icon: 'file-export',
    action: function() {
      var selectedSamples = getSelectedSampleIDs();
      exportSamples(selectedSamples);
    }
  });
  
  samplePage.addButton(bulkExportBtn);
});

Example

// Add custom sample creation button
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample();
  
  var createFromTemplateBtn = new eLabSDK.GUI.Button({
    label: 'Create from Template',
    icon: 'file',
    type: 'success',
    action: function() {
      openTemplateSelectionDialog();
    }
  });
  
  samplePage.addButton(createFromTemplateBtn);
});

addTopPageButton($btn)

Add a custom button to the top-right area of the sample page.

Kind: global function

Param	Type	Description
$btn	`eLabSDK.GUI.Button`	An eLabSDK.GUI.Button instance to add to the top page area

Example

// Add settings button to top of page
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample();
  
  var settingsBtn = new eLabSDK.GUI.Button({
    label: 'Settings',
    icon: 'cog',
    action: function() {
      openSettingsDialog();
    }
  });
  
  samplePage.addTopPageButton(settingsBtn);
});

Example

// Add help button
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample();
  
  var helpBtn = new eLabSDK.GUI.Button({
    label: 'Help',
    icon: 'question-circle',
    action: function() {
      window.open('/help/samples', '_blank');
    }
  });
  
  samplePage.addTopPageButton(helpBtn);
});

getParentSampleID()

Get the parent sample ID of the currently displayed sample.

Kind: global function
Returns: number ⎮ null - The numeric parent sample ID, or null if no parent exists
Example

// Check if sample has a parent
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var parentID = this.getParentSampleID();
      if (parentID) {
        console.log('This sample is derived from sample: ' + parentID);
        displayParentSampleLink(parentID);
      } else {
        console.log('This is a root sample with no parent');
      }
    }
  });
});

Example

// Navigate to parent sample
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var parentID = this.getParentSampleID();
      
      if (parentID) {
        var viewParentBtn = new eLabSDK.GUI.Button({
          actionID: 'viewParentSample',
          label: 'View Parent',
          icon: 'arrow-up',
          action: function() {
            window.location.hash = '#viewSample/' + parentID;
          }
        });
        samplePage.addSampleDetailButton(viewParentBtn);
      }
    }
  });
});

Example

// Load parent sample data
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var parentID = this.getParentSampleID();
      
      if (parentID) {
        eLabSDK.Inventory.Sample.load(parentID, function(parentData) {
          console.log('Parent sample name: ' + parentData.name);
          displayParentInfo(parentData);
        });
      }
    }
  });
});

getSampleID()

Get the ID of the currently displayed sample.

Kind: global function
Returns: number ⎮ null - The numeric sample ID if on sample detail page, or null otherwise
Example

// Get current sample ID and use in custom action
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var sampleID = this.getSampleID();
      console.log('Viewing sample: ' + sampleID);
      
      var customBtn = new eLabSDK.GUI.Button({
        actionID: 'customAction',
        label: 'Custom Action',
        icon: 'star',
        action: function() {
          processCustomAction(sampleID);
        }
      });
      this.addSampleDetailButton(customBtn);
    }
  });
});

Example

// Load additional sample metadata
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var sampleID = this.getSampleID();
      
      if (sampleID) {
        $.get('/api/v1/samples/' + sampleID + '/metadata', function(metadata) {
          displayCustomMetadata(metadata);
        });
      }
    }
  });
});

Example

// Conditional behavior based on sample context
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample();
  var sampleID = samplePage.getSampleID();
  
  if (sampleID) {
    console.log('On sample detail page - ID: ' + sampleID);
    enableSampleSpecificFeatures();
  } else {
    console.log('On sample browser/list page');
    enableBrowserFeatures();
  }
});

getSampleSeriesID()

Get the ID of the currently displayed sample series.

Kind: global function
Returns: number ⎮ null - The numeric sample series ID if on series detail page, or null otherwise
Example

// Get current series ID and add custom button
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var seriesID = this.getSampleSeriesID();
      
      if (seriesID) {
        console.log('Viewing sample series: ' + seriesID);
        
        var exportSeriesBtn = new eLabSDK.GUI.Button({
          actionID: 'exportSeries',
          label: 'Export Series',
          icon: 'download',
          action: function() {
            exportSampleSeries(seriesID);
          }
        });
        this.addSampleDetailButton(exportSeriesBtn);
      }
    }
  });
});

Example

// Load series members
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var seriesID = this.getSampleSeriesID();
      
      if (seriesID) {
        $.get('/api/v1/sampleseries/' + seriesID + '/members', function(members) {
          console.log('Series contains ' + members.length + ' samples');
          displaySeriesMembers(members);
        });
      }
    }
  });
});

Example

// Conditional behavior for series vs single sample
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var sampleID = this.getSampleID();
      var seriesID = this.getSampleSeriesID();
      
      if (seriesID) {
        console.log('Viewing series: ' + seriesID);
        enableSeriesFeatures();
      } else if (sampleID) {
        console.log('Viewing single sample: ' + sampleID);
        enableSingleSampleFeatures();
      }
    }
  });
});

addSection(sectionToAdd)

Add a custom section to the sample detail page.

Kind: global function
Returns: HTMLElement ⎮ null - The created section element, or null if linkedSection not found

Param	Type	Default	Description
sectionToAdd	`Object`		Configuration object for the section to add
[sectionToAdd.id]	`string`	`''newSection''`	Unique ID for the section element
[sectionToAdd.position]	`Object`		Positioning configuration relative to existing section
[sectionToAdd.position.linkedSection]	`string`	`''Storage Location''`	Name of the section to position relative to
[sectionToAdd.position.positioning]	`string`	`''before''`	Position relative to linked section: 'before' or 'after'
[sectionToAdd.header]	`Object`		Configuration for the section header
[sectionToAdd.header.contents]	`string`	`''New Section''`	HTML content for the header
[sectionToAdd.header.style]	`string`	`''padding-top:3px;''`	CSS styles for the header
sectionToAdd.contents	`string`		HTML content for the section body

Example

// Add custom metadata section
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var sampleID = this.getSampleID();
      
      $.get('/api/v1/samples/' + sampleID + '/custom-data', function(data) {
        samplePage.addSection({
          id: 'customMetadata',
          position: {
            linkedSection: 'Storage Location',
            positioning: 'before'
          },
          header: {
            contents: 'Custom Metadata',
            style: 'padding-top: 5px;'
          },
          contents: '<div style="padding: 10px;">' +
                    '<p><strong>Field 1:</strong> ' + data.field1 + '</p>' +
                    '<p><strong>Field 2:</strong> ' + data.field2 + '</p>' +
                    '</div>'
        });
      });
    }
  });
});

Example

// Add quality control section after sample info
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      samplePage.addSection({
        id: 'qualityControl',
        position: {
          linkedSection: 'Sample Information',
          positioning: 'after'
        },
        header: {
          contents: 'Quality Control Results'
        },
        contents: '<div class="qc-results">' +
                  '<table>' +
                  '<tr><td>Purity:</td><td>99.5%</td></tr>' +
                  '<tr><td>Concentration:</td><td>10 mg/mL</td></tr>' +
                  '</table>' +
                  '</div>'
      });
    }
  });
});

Example

// Add interactive chart section
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var chartDiv = samplePage.addSection({
        id: 'analyticsChart',
        header: {
          contents: 'Sample Analytics'
        },
        contents: '<div id="chartContainer" style="height: 300px;"></div>'
      });
      
      if (chartDiv) {
        // Initialize chart in the new section
        initializeChart('#chartContainer');
      }
    }
  });
});

addTopNotice(noticeToAdd)

Add a warning or informational notice to the top of the sample detail page.

Kind: global function

Param	Type	Description
noticeToAdd	`Object`	Configuration object for the notice to add
noticeToAdd.id	`string`	Unique identifier for the notice (prevents duplicates)
noticeToAdd.icon	`string`	FontAwesome icon class (e.g., 'fas fa-exclamation-circle', 'fas fa-info-circle')
noticeToAdd.contents	`string`	HTML content to display in the notice

Example

// Add warning notice for low quantity
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      var sampleID = this.getSampleID();
      
      eLabSDK.Inventory.Sample.load(sampleID, function(sample) {
        if (sample.quantity < 10) {
          samplePage.addTopNotice({
            id: 'lowQuantityWarning',
            icon: 'fas fa-exclamation-triangle',
            contents: '<p><strong>Low Quantity Alert:</strong> Only ' + 
                      sample.quantity + ' ' + sample.quantityUnit + ' remaining.</p>'
          });
        }
      });
    }
  });
});

Example

// Add expiration warning
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      samplePage.addTopNotice({
        id: 'expirationNotice',
        icon: 'fas fa-clock',
        contents: '<p><strong>Expiration Notice:</strong> This sample expires in 7 days.</p>'
      });
    }
  });
});

Example

// Add custom HTML notice with actions
eLabSDK.ready(function() {
  var samplePage = new eLabSDK.Page.Sample({
    onSampleDetailReady: function() {
      samplePage.addTopNotice({
        id: 'customNotice',
        icon: 'fas fa-info-circle',
        contents: '<div>' +
          '<strong>Custom Workflow Required</strong>' +
          '<p>This sample requires special handling. ' +
          '<a href="/protocols/special-handling">View Protocol</a></p>' +
          '</div>'
      });
    }
  });
});

.showStorageLayer(storageLayerID)

Open the storage layer compartment viewer for a specific storage layer.

This static method opens the visual compartment viewer interface for the specified storage
layer, allowing users to see the physical layout and contents of the storage location. After
opening the viewer, it automatically refreshes the sample table data to ensure the display
is up-to-date. Use this to programmatically navigate users to storage layer views, such as
from custom links or after sample operations.

Kind: static function

Param	Type	Description
storageLayerID	`number`	The numeric ID of the storage layer to display

Example

// Open storage layer viewer from custom button
var viewStorageBtn = new eLabSDK.GUI.Button({
  label: 'View Storage',
  icon: 'warehouse',
  action: function() {
    var storageLayerID = 456;
    eLabSDK.Page.Sample.showStorageLayer(storageLayerID);
  }
});

Example

// Navigate to sample's storage location
eLabSDK.Inventory.Sample.load(123, function(sample) {
  console.log('Sample stored in layer: ' + sample.storageLayerID);
  eLabSDK.Page.Sample.showStorageLayer(sample.storageLayerID);
});

Example

// Show storage layer after sample creation
eLabSDK.Inventory.Sample.create({
  name: 'New Sample',
  sampleTypeID: 789,
  storagelayerID: 101,
  fnWhenReady: function(config, sample) {
    alert('Sample created in storage layer ' + config.storagelayerID);
    eLabSDK.Page.Sample.showStorageLayer(config.storagelayerID);
  }
});

.refresh()

Refresh the sample table data to reflect current database state.

This static method reloads the sample table/browser to display the most current sample data.
Use this after performing operations that modify samples (create, update, delete, move) to
ensure the displayed list reflects the latest changes. The refresh is only executed if the
sample table component is available on the current page.

Kind: static function
Example

// Refresh after creating new sample
eLabSDK.Inventory.Sample.create({
  name: 'New Sample',
  sampleTypeID: 123,
  fnWhenReady: function(config, sample) {
    alert('Sample created with ID: ' + sample.sampleID);
    eLabSDK.Page.Sample.refresh();
  }
});

Example

// Refresh after bulk operation
function performBulkUpdate(sampleIDs) {
  var updatePromises = sampleIDs.map(function(id) {
    return $.post('/api/v1/samples/' + id, { status: 'archived' });
  });
  
  Promise.all(updatePromises).then(function() {
    console.log('Bulk update complete');
    eLabSDK.Page.Sample.refresh();
  });
}

Example

// Refresh button for manual updates
var refreshBtn = new eLabSDK.GUI.Button({
  label: 'Refresh',
  icon: 'sync',
  action: function() {
    eLabSDK.Page.Sample.refresh();
    console.log('Sample table refreshed');
  }
});