## 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. 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. **Kind**: global function | Param | Type | Description | | --- | --- | --- | | btn | `eLabSDK.GUI.Button` | An eLabSDK.GUI.Button instance configured with action, icon, and label | **Example** ```js // 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** ```js // 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. 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. **Kind**: global function | Param | Type | Description | | --- | --- | --- | | btn | `eLabSDK.GUI.Button` | An eLabSDK.GUI.Button instance to add to the browser toolbar | **Example** ```js // 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** ```js // 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. 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. **Kind**: global function | Param | Type | Description | | --- | --- | --- | | $btn | `eLabSDK.GUI.Button` | An eLabSDK.GUI.Button instance to add to the top page area | **Example** ```js // 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** ```js // 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. 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. **Kind**: global function **Returns**: `number` ⎮ `null` - The numeric parent sample ID, or null if no parent exists **Example** ```js // 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** ```js // 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** ```js // 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. 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. **Kind**: global function **Returns**: `number` ⎮ `null` - The numeric sample ID if on sample detail page, or null otherwise **Example** ```js // 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** ```js // 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** ```js // 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. 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. **Kind**: global function **Returns**: `number` ⎮ `null` - The numeric sample series ID if on series detail page, or null otherwise **Example** ```js // 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** ```js // 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** ```js // 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. 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. **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** ```js // 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: '

' + '

Field 1: ' + data.field1 + '

' + '

Field 2: ' + data.field2 + '

' + '

' }); }); } }); }); ``` **Example** ```js // 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: '

' + '' + '' + '' + '

Purity:	99.5%
Concentration:	10 mg/mL

' + '

' }); } }); }); ``` **Example** ```js // 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: '

' }); 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. 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. **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** ```js // 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: '

Low Quantity Alert: Only ' + sample.quantity + ' ' + sample.quantityUnit + ' remaining.

' }); } }); } }); }); ``` **Example** ```js // Add expiration warning eLabSDK.ready(function() { var samplePage = new eLabSDK.Page.Sample({ onSampleDetailReady: function() { samplePage.addTopNotice({ id: 'expirationNotice', icon: 'fas fa-clock', contents: '

Expiration Notice: This sample expires in 7 days.

' }); } }); }); ``` **Example** ```js // 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: '

' + 'Custom Workflow Required' + '

This sample requires special handling. ' + 'View Protocol

' + '

' }); } }); }); ``` ## .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** ```js // 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** ```js // 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** ```js // 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** ```js // 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** ```js // 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** ```js // 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'); } }); ``` [addSampleDetailButton(btn)]:#addsampledetailbuttonbtn [addButton(btn)]:#addbuttonbtn [addTopPageButton($btn)]:#addtoppagebuttonbtn [getParentSampleID()]:#getparentsampleid [getSampleID()]:#getsampleid [getSampleSeriesID()]:#getsampleseriesid [addSection(sectionToAdd)]:#addsectionsectiontoadd [addTopNotice(noticeToAdd)]:#addtopnoticenoticetoadd * * * © 2026 eLabNext