Table of Contents

     Build User Interface
       Premium Resource: Custom Home Page Examples
       Page Admin Mode
       Add Web Parts
       Manage Web Parts
       Web Part Inventory
       Use Tabs
       Add Custom Menus
       Web Parts: Permissions Required to View

Build User Interface

The topics in this section help administrators learn how to create and configure user interface elements to form data dashboards and web portal pages. Flexible tools and design options let you customize user interfaces to suit a variety of needs
  • Page Admin Mode
  • Add Web Parts - Web parts are user interface panels that you can add to a folder/project page. Each type of web part provides some way for users to interact with your application and data. For example, the "Files" web part provides access to any files in your repository.
  • Manage Web Parts - Set properties and permissions for a web part
  • Web Part Inventory - Available web parts
  • Use Tabs - Bring together related functionality on a single tab to create data dashboards
  • Add Custom Menus - Provide quick pulldown access to commonly used tools and pages in your application.
  • Web Parts: Permissions Required to View
A sample folder page:

Related Topics

  • Projects and Folders - A project or folder provides the container for your application. You typically develop an application by adding web parts and other functionality to an empty folder or project.
  • JavaScript API - Use the JavaScript API for more flexibility and functionality.
  • Module-based apps - Modules let you build applications using JavaScript, Java, and more.

Premium Resource: Custom Home Page Examples

Related Topics

Page Admin Mode

Administrators can enter Page Admin Mode to expose the tools they need to make changes to the contents of a page, including web parts and wikis. These tools are hidden to non-admin users, and are also not visible to admins unless they are in this mode. Many web part menus also have additional options in Page Admin Mode that are otherwise hidden.

Page Admin Mode

Select > Page Admin Mode to enter it.

You will see an Exit Admin Mode button in the header bar when in this mode.

To exit this mode, click the button, or you can also select > Exit Admin Mode.

Web Parts

Add Web Parts

In page admin mode, you can add new web parts using the selectors at the bottom of the page. The main panel (wider) web parts can be added using the left hand selector. Narrow style web parts, such as table of contents, can be added using the selector on the right. Note that at narrow browser widths, the "narrow" web parts are displayed below (and as wide as) the main panel web parts.

Customize Web Parts

The (triangle) menu for a web part contains additional options in Page Admin Mode. Additional options:

  • Permissions: Control what permissions are required for a user to see this web part.
  • Move Up: Relocate the web part on the page.
  • Move Down: Relocate the web part on the page.
  • Remove From Page: Remove the web part; does not necessarily remove underlying content.
  • Hide Frame: Show this web part without its frame.

Frameless Web Parts

The outline, header bar, and menu can be removed from a web part by selecting Hide Frame from the (triangle) menu. Shown below are three views of the same small "Projects" web part: in admin mode both with and without the frame, then frameless as a non-admin user would see it.

Notice that frameless web parts still show the web part title and pulldown menu in page admin mode, but that these are removed outside of admin mode.

Frameless web parts make it possible to take advantage of bootstrap UI features such as jumbotrons and carousels.


When there is only one tab, it will not be shown in the header, since the user will always be "on" this tab.

When there are multiple tabs, they are displayed across the header bar with the current tab in a highlight color (may vary per color theme).

On narrower screens or browser windows, or when custom menus use more of the header bar, multiple tabs will be displayed on a pulldown menu from the current active tab. Click to navigate to another tab.

Tabs in Page Admin Mode

To see and edit tabs in any container, an administrator enters > Page Admin Mode.

To add a new tab, click the mini tab on the right. To edit a current tab, pulldown the (triangle) menu:

  • Hide: Do not display this tab in non-admin mode. It will still be shown in page admin mode. Hidden tabs are shown in page admin mode with a icon.
  • Delete: Delete this tab. Does not delete the underlying contents.
  • Move: The caret menu indicates you can click to select from a sub menu
  • Rename: Change the display name for the tab.

Related Topics

Add Web Parts

Once you've created a project or folder you can begin building dashboards from panels called Web Parts. Web Parts are the basic tools of the server -- they surface all of the functionality of the server including: analysis and search tools, windows onto your data, queries, any reports built on your data, etc. The list of web parts available depends on which modules are enabled in a given folder/project.

There are two display regions for web parts, each offering a different set. The main, wider panel on the left, where you are reading this wiki, and a narrower right-hand column (on this page containing search, feedback, and a table of contents). Some web parts, like Search can be added in either place.

Add a Web Part

  • Navigate to the location where you want the web part.
  • Enter Page Admin Mode to enable the page editing tools.
  • Scroll down to the bottom of the page.
  • Choose the desired web part from the <Select Web Part> drop down box and click Add.
  • Note: if both selectors are stacked on the right, make your browser slightly wider to show them on separate sides.
  • The web part you selected will be added below existing web parts. Use the (triangle) menu to move it up the page, or make other customizations.
  • Click Exit Admin Mode in the upper right to hide the editing tools and see how your page will look to users.

Note: If you want to add a web part that does not appear in the drop down box, choose (Admin) > Folder > Management > Folder Type to view or change the folder type and set of modules enabled.

Anchor Tags for Web Parts

You can create a URL or link to a specific web part by referencing its "anchor". The anchor is the name of the web part. For example, this page in the File Management Tutorial example has several web parts:

The following URL will navigate the user directly to the "Prelim Lab Results" query web part displayed at the bottom of the page. Notice that spaces in names are replaced with "%20" in the URL.

Related Topics

Manage Web Parts

Web Parts are user interface panels -- they surface all of the functionality of the server including: analysis and search tools, windows onto your data, queries, any reports built on your data, etc. This topic describes how page administrators can manage them.

Web Part Triangle Menu

Each web part has a (triangle) pulldown menu in the upper right.

An expanded set of options is available when the user is in page administrator mode. If the web part is frameless, the (triangle) menu is only available in page admin mode.

Web Part Controls

The particular control options available vary by type of web part, and visibility depends on the user's role and editing mode. For example, Wiki web parts have a set of options available to editors for quick access to wiki editing features:

When the user does not have any options for customizing a given web part, the menu is not shown.

Page Admin Mode Options

Administrators have additional menu options, including usually a Customize option for changing attributes of the web part itself, such as the name or in some cases selecting among small/medium/large display options.

To access more options for web parts, administrators select (Admin) > Page Admin Mode.

  • Permissions: Configure web parts to be displayed only when the user has some required role or permission. For details see Web Parts: Permissions Required to View.
  • Move Up/ Move Down: Adjust the location of the web part on the page.
  • Remove From Page: This option removes the web part from the page, but not the underlying data or other content.
  • Hide Frame: Hide the frame of the web part, including the title, header bar, and outline, when not in page admin mode. For details, see Frameless Web Parts

Related Topics

Web Part Inventory

The following tables list the available Web Parts, or user interface panels. There is a link to more documentation about each one. The set of web parts available depends on the modules installed on your server and enabled in your project or folder. Learn more about adding and managing web parts in this topic: Add Web Parts.

Left Side, Wide Web Parts

Web Part NameDescriptionDocumentation
Assay BatchesDisplays a list of batches for a specific assayWork with Assay Data
Assay ListProvides a list of available assay designs and options for managing assaysAssay List
Assay ResultsDisplays a list of results for a specific assayWork with Assay Data
Assay RunsDisplays a list of runs for a specific assayWork with Assay Data
Assay ScheduleDefine and track expectations of when and where particular assays will be runManage Assay Schedule
CDS ManagementManagement area for the Dataspace folder typeCollaborative DataSpace Case Study
Contacts / Project ContactsList of users in the current project (members of any project group)Contact Information
Custom Protein ListsShows protein lists that have been added to the current folderUsing Custom Protein Annotations
Data ClassesCapture capture complex lineage and derivation information, especially when those derivations include bio-engineering systems such as gene-transfected cells and expression systems.Data Classes
Data PipelineConfigure the data pipeline for access to data files and set up long running processesData Processing Pipeline
Data Transform JobsProvides a history of all executed ETL runsETL: User Interface
Data TransformsLists the available ETL jobs, and buttons for running themETL: User Interface
Data ViewsData browser for reports, charts, viewsData Views Browser
DatasetsDatasets included in the studyDatasets Web Part
Experiment RunsList of runs within an experimentExperiment Terminology
Feature Annotation SetsSets of feature/probe information used in expression matrix assaysExpression Matrix Assay Tutorial
FilesThe file repository panel. Upload files for sharing and import into the databaseFiles
Flow AnalysesList of flow analyses that have been performed in the current folderStep 4: View Results
Flow Experiment ManagementTracks setting up an experiment and analyzing FCS filesFlow Dashboard Overview
Flow ReportsCreate and view positivity and QC reports for Flow analysesFlow Reports
Flow ScriptsAnalysis scripts each holding the gating template, rules for the compensation matrix, and which statistics and graphs to generate for an analysisStep 1: Define a Compensation Calculation
Immunization ScheduleShow the schedule for treatments within a studyManage Study Products
Issue DefinitionsDefine properties of an issue tracking listIssue Tracker: Administration
Issues ListTrack issues for collaborative problem solvingIssue Tracker: Administration
Issues SummarySummary of issues in the current folder's issue trackerIssue Tracker: Administration
List - SingleDisplays the data in an individual listList Web Parts
ListsDisplays directory of all lists in the current folderList Web Parts
Mail RecordTest/development resource for email configuration.Test Email
Manage Peptide InventorySearch and pool peptides via this management interfacePeptide Search
Mass Spec Search (Tabbed)Combines "Protein Search" and "Peptide Search" for convenienceProtein Search
MessagesShow messages in this folderMessages Web Part
Messages ListShort list of messages without any detailsMessage List Web Part
MS2 RunsList of MS2 runsExplore the MS2 Dashboard
MS2 Runs BrowserFolder browser for MS2 runsView, Filter and Export All MS2 Runs
MS2 Runs with Peptide CountsAn MS2Extensions web part adding peptide counts with comparison and export filtersPeptide Search
MS2 Sample Preparation RunsList of sample preparation runsExplore the MS2 Dashboard
Peptide Freezer DiagramDiagram of peptides and their freezer locationsPeptide Search
Peptide SearchSearch for specific peptide identificationsPeptide Search
Pipeline FilesA management interface for files uploaded through the pipelineData Processing Pipeline
ProjectsProvides a list of projects on your siteProjects Web Part
Protein SearchDashboard for protein searches by name and minimum probabilityStep 6: Search for a Specific Protein
QueryShows results of a query as a gridQuery Web Part
ReportDisplay the contents of a report or viewReport Web Part: Display a Report or Chart
Run GroupsList of run groups within an analysis.Run Groups
Run TypesLinks to a list of experiment runs filtered by typeExperiment Terminology
Sample TypesCollections of samples that share columns and propertiesSamples
SearchText box to search wiki & other modules for a search stringSearch
Sequence RunsList of genotyping sequencing runs 
Study Data ToolsButton bar for common study analysis tasks. Buttons include, Create A New Graph, New Participant Report, etc.Step 1: Study Dashboards
Study ListDisplays basic study information (title, protocol, etc.) in top-down document fashion. 
Study OverviewManagement links for a study folder.Step 2: Study Reports
Study Protocol SummaryOverview of a Study Protocol (number of participants, etc).Study
Study ScheduleTracks data collection over the span of the study.Study Schedule
SubfoldersLists the subfolders of the current folder.Subfolders Web Part
Participant DetailsDashboard view for a particular study participant. 
Participant ListInteractive list of participants. Filter participants by group and cohort. 
Survey DesignsA list of available survey designs/templates to base surveys on.Tutorial: Survey Designer, Step 1
SurveysA list of survey results, completed by users.Tutorial: Survey Designer, Step 1
Vaccine DesignDefine immunogens, adjuvants, and antigens you will studyCreate a Vaccine Study Design
Vaccine Study ProtocolsList of current vaccine protocols (deprecated interface)Create a Vaccine Study Design
ViewsList of the data views in the study, including R views, charts, SQL queries, etc.Customize Grid Views
WikiDisplays a wiki page.Wiki Admin Guide
Workbooksmakecolumnwider Provides a light-weight container for managing smaller data files.Workbooks

Right Side, Narrow Web Parts

Web Part NameBrief DescriptionDocumentation
FilesLists a set of filesFiles
Flow SummaryCommon flow actions and configurationsStep 1: Customize Your Grid View
ListsDirectory of the lists in a folderLists
MS2 StatisticsStatistics on how many runs have been done on this server, etcMass Spectrometry
Protein SearchForm for finding protein informationMass Spectrometry
ProtocolsDisplays a list of protocolsExperiment Framework
Run GroupsList of run groupsRun Groups
Run TypesList of runs by typeRun Groups
Sample TypesCollections of samples that share properties and columnsSamples
SearchText box to search wiki & other modules for a search stringSearch
Study Data ToolsButton bar for common study analysis tasks. Buttons include, Create A New Graph, New Participant Report, etc.Step 1: Study Dashboards
Participant ListList of study participants 
ViewsList of views available in the folderCustomize Grid Views
WikiDisplays a narrow wiki pageWiki Admin Guide
Wiki Table of ContentsTable of Contents for wiki pagesWiki Admin Guide

Related Topics

Use Tabs

Using tabs within a project or folder can essentially give you new "pages" to help better organize the functionality you need. You can provide different web parts on different tabs to provide tools for specific roles and groups of activities. For an example of tabs in action, explore the interactive example study.

Some folder types, such as study, come with specific tabs already defined. Click the tab to activate it and show the content.

With administrative permissions, you can also enter page admin mode to add and modify tabs to suit your needs.

Tab Editing

Tabs are created and edited using > Page Admin Mode. When enabled, each tab will have a triangle pulldown menu for editing, and there will also be a + mini tab for adding new tabs.

  • Hide: Hide tabs from users who are not administrators. Administrators can still access the tab. In page admin mode, a hidden tab will show a icon. Hiding a tab does not delete or change any content. You could use this feature to develop a new dashboard before exposing it to your users.
  • Move: Click to open a sub menu with "Left" and "Right" options.
  • Rename: Change the display name of the tab.
  • Delete: Tabs you have added will show this option and may be deleted. You cannot delete tabs built in to the folder type.

Add a Tab

  • Enter > Page Admin Mode.
  • Click the mini tab on the right.
  • Provide a name and click OK.

Default Display Tab

As a general rule when multiple tabs are present, the leftmost tab is "active" and displayed in the foreground by default when a user first navigates to the folder. Exceptions to this rule are the "Overview" tab in a study folder and the single pre-configured tab created by default in most folder types, such as the "Start Page" in a collaboration folder. To override these behaviors:

  • "Overview" - When present, the Overview tab is always displayed first, regardless of its position in the tab series. To override this default behavior, an administrator can hide the "Overview" tab and place the intended default in the leftmost position.
  • "Start Page"/"Assay Dashboard" - Similar behavior is followed for this pre-configured tab that is created with each new folder, for example, "Start Page" for Collaboration folders and "Assay Dashboard" for Assay folders. If multiple tabs are defined, this single pre-configured tab, will always take display precedence over other tabs added regardless of its position left to right. To override this default behavior, hide the pre-configured tab and place whichever tab you want to be displayed by default in the leftmost position.
Note that if only the single preconfigured "Start Page" or "Assay Dashboard" tab is present, it will not be displayed at all, as the user is always "on" this tab.

Custom Tabbed Folders

Developers can create custom folder types, including tabbed folders. For more information, see Modules: Folder Types.

Add Custom Menus

An administrator can add custom menus to offer quick pulldown access to commonly used tools and pages from anywhere within a project. Custom menus will appear in the top bar of every page in the project, just to the right of the project and folder menus. For example, the LabKey Server Documentation is itself part of a project featuring custom menus:

Included in this topic:

Add a Custom Menu

  • From the project home page, select (Admin) > Folder > Project Settings.
  • Click the Menu Bar tab.

There are several types of menu web part available. Each web part you add to this page will be available on the header bar throughout the project, ordered left to right as they are listed top to bottom on this page.

The Custom Menu type offers two options, the simplest being to create a menu of folders.

Folders Menu

  • On the Create Custom Menu page, add a Custom Menu web part.
  • The default Title is "My Menu"; edit it to better reflect your content.
  • Select the radio button for Folders.
  • Elect whether to include descendents (subfolders) and whether to limit the choice of root folder to the current project. If you do not check this box, you can make a menu of folders available anywhere on the site.
  • Select the Root Folder. Children of that root will be listed as the menu. The root folder will not be presented on the menu itself, so you might choose to use it as the title of the menu.
  • The Folder Types pulldown allows you to limit the type of folder on the menu if desired. For example, you might want a menu of workbooks or of flow folders. Select [all] or leave the field blank to show all folders.
  • Click Submit to save your new menu.
  • You will now see it next to the project menu, and there will be a matching web part on the Menu Bar tab of Project Settings. The links navigate the user to the named subfolder.

Continue to add a web part on this page for each custom menu you would like. Click Refresh Menu Bar to apply changes without leaving this page.

List or Query Menu

The other option on the creation page for the Custom Menu web part is "Create from List or Query". You might want to offer a menu of labs or use a query returning newly published work during the past week.

  • On the Menu Bar page, add a Custom Menu web part.
  • The default Title is "My Menu"; edit it to better reflect your content.
  • Select Create from List or Query.
  • Use the pulldowns to select the following in order. Each selection will determine the options in the following selection.
    • Folder: The folder or project where the list or query can be found.
    • Schema: The appropriate schema for the query, or "lists" for a list.
    • Query: The query or list name.
    • View: If more than one view exists for the query or list, select the one you want.
    • Title Column: Choose what column to use for the menu display. In the "Labs" example shown here, perhaps "Principal Investigator" would be another display option.
  • Click Submit to create the menu.
  • Each item on the menu will link to the relevant list or query result.

Resource Menus

There are three built in custom menu types which will display links to all of the specific resources in the project. There are no customization options for these types.

Study List

If your project contains one or more studies, you can add a quick access menu for reaching the home page for any given study from the top bar.

  • Return to the Menu Bar tab.
  • Add a Study List web part. Available studies will be listed in a new menu named "Studies".

If no studies exist, the menu will contain the message "No studies found in project <Project_Name>."

Assay List

If your project contains Assays, you can add a menu listing them, along with a manage button, for easy access from anywhere in your project.

  • Return to the Menu Bar tab.
  • Add an AssayList2 web part. Available assays will be listed in a new menu named "Assays".

If no assays exist, the menu will only contain the Manage Assays button.

Samples Menu

The Samples Menu similarly offers the option of a menu giving quick access to all the sample types in the project - the menu shows who uploaded them and when, and clicking the link takes you directly to the sample type.

  • Return to the Menu Bar tab.
  • Add an Samples Menu web part. Available sample types will be listed in a new menu named "Samples".

If no samples exist, the menu will be empty.

Define a Menu in a Wiki

By creating a wiki page that is a series of links to other pages, folders, documents, or any destination you choose, you can customize a basic menu of common resources users can access from anywhere in the project.

  • Create a new Wiki web part somewhere in the project where it will become a menu.
  • Click Create a new wiki page in the new web part.
  • Give your new page a unique title (such as "menuTeamA").
  • Name your wiki as you want the menu title to appear "Team Links" in this example.
  • Add links to folders and documents you have already created, in the order you want them to appear on the menu. For example, the wiki might contain:

[Alpha Lab Home Page|http://localhost:8080/labkey/project/Andromeda/Alpha%020/begin.view?]

[Staff Phone Numbers|directory]
    • In this example, we include three menu links: the overview document, the home page for the Alpha Lab, and the staff phone list document in that order.
  • Save and Close the wiki, which will look something like this:

To add your wiki as a custom menu:

  • Return to (Admin) > Folder > Project Settings. Click the Menu Bar tab.
  • Select Wiki Menu from the <Add Web Part> pulldown and click Add. An empty wiki menu (named "Wiki") will be added.
  • In the new web part, select Customize from the (triangle) menu.
  • Select the location of your menu wiki from the pulldown for Folder containing the page to display. The "Page to display" pulldown will automatically populate with all wikis in that container.
  • Select the menu wiki you just created, "menuTeamA (Team Links)" from the pulldown for Page to display:
  • Click Submit to save.
  • If your menu does not immediately appear in the menu bar, click Refresh Menu Bar.
  • The team can now use your new menu anywhere in the Andromeda project to quickly access content.

Menu Visibility

By selecting the Permissions link from the pulldown on any menu web part on the Menu Bar tab, you can choose to show or hide the given menu based on the user's permission.

You must enter (Admin) > Page Admin Mode to see the "Permissions" option.

The Required Permission field is a pulldown of all the possible permission role levels. Check Permission On: allows you to specify where to check for that permission.

If the user does not have the required permission (or higher) on the specified location, they will not see that particular menu.

Define a New Menu Type in a Custom Module

If you have defined a web part type inside a custom module (for details of the example used here see Tutorial: Hello World Module), you can expose this web part as new type of custom menu to use by adding <location name="menu"> to the appropriate .webpart.xml file, for example:

<webpart xmlns="" 
title="Hello World Web Part">
<view name="begin"/>
<location name="menu"/>
<location name="body"/>

Your web part will now be available as a menu-type option:

The resulting menu will have the same title as defined in the view.xml file, and contain the contents. In the example from the Hello World Tutorial, the menu "Begin View" will show the text "Hello, World!"

Web Parts: Permissions Required to View

An administrator can restrict the visibility of a web part to only those users who have been granted a particular permission on a particular container. Use this feature to declutter a page, or target content for each user. For example, hiding links to protected resources that the user will not able to access. In some cases you may want to base the permissions check on what the user's permission is in a different container. For instance, you might display two sets of instructions for using a particular folder - one for users who can read the contents, another for users who can insert new content into it.

Note that web part permissions settings do not change the security settings already present in the current folder and cannot be used to grant access to the resource displayed in the web part that the user does not already have.

  • Enter > Page Admin Mode.
  • Open the (triangle) menu for the web part you want to configure and choose Permissions.
  • In the pop-up, select the Required Permission from the list of available permission levels (roles) a user may have.
    • Note that the listing is not alphabetical. Fundamental roles like Insert/Update are listed at the bottom.
  • Use the Check Permission On radio button to control whether the selected permission is required in the current container (the default) or another one.
  • If you select Choose Folder, browse to select the desired folder.
  • Click Save.

In the security user interface, administrators typically interact with "roles," which are named sets of permissions. The relationship between roles and permissions is described in detail in these topics:

These settings apply to individual web parts, so you could configure two web parts of the same type with different permission settings.

Related Topics