# Add-VaultTab

Adding a new Tab for a specific entity type to the Vault Explorer with an Action that is called when the Tab is clicked or the selection changes in Vault.\
The cmdlet provides the possibility to define a user interface for the registered Tab.

## Syntax

```powershell
Add-VaultTab -Name <String> -EntityType <VaultTabEntityType> -Action <Scriptblock | String> [<CommonParameters>]
```

## Parameters

| Type                                      | Name       | Description                                                                                                                                                                                                                                                                                                                                                                      | Default Value | Optional |
|-------------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|----------|
| String                                    | Name       | Label of the Tab displayed in the Vault Explorer.                                                                                                                                                                                                                                                                                                                                |               | no       |
| [VaultTabEntityType](commandlets/add-vaulttab:vaulttabentitytype) | EntityType | The entity type for which the Tab should be displayed.                                                                                                                                                                                                                                                                                                                           |               | no       |
| Scriptblock / String                      | Action     | Script block or function that gets executed for the currently selected entity in the Vault Client (`$selectedEntity`) if the Tab is activated. </br> This can be used to define or update the Tab interface by simply returning a [WPF Control](https://learn.microsoft.com/en-us/dotnet/api/system.windows.controls.control?view=netframework-4.5) from the script block or function. |               | no       |

(commandlets/add-vaulttab:vaulttabentitytype)=
### VaultTabEntityType

**Enum values:**
| Name          | Description                          |
|---------------|--------------------------------------|
| File          | Tab gets displayed for Files.        |
| Item          | Tab gets displayed for Items.        |

## Return type
**empty**

## Remarks

The Cmdlet extends the Vault Client's user interface with a new tab with the specified **-Name** as its label.\
When multiple tabs with the same *-Name* for the same *-EntityType* are registered, only the latest registered tab is displayed.

The script block or the function name passed as **-Action** parameter is invoked with an [powerVault entity](<inv:powervault#code_reference/objects>) that represents the element that is selected in the Vault Client.\
If multiple entities are selected, the first selected entity will be used. Depending on the *[EntityType](commandlets/add-vaulttab:vaulttabentitytype)* of the Tab, the passed object can be either a [file](<inv:powervault#code_reference/objects/file>) or an [item](<inv:powervault#code_reference/objects/item>).\
The *Action* is executed every time the Vault user changes a selection while the Tab is visible, or when the Tab is activated by the user.

The tab content is **cleared** and the log provides information when:
  - unhandled terminating exceptions occur on the hosting applications (Vault Client) UI thread
  - the _Action_ returns an invalid [WPF Control](https://learn.microsoft.com/en-us/dotnet/api/system.windows.controls.control?view=netframework-4.5)

:::{note}

- The cmdlet can **only be used** when running directly in a **Vault Explorer** process.
- Created tabs remain available as long as this process exists and disappear again when the Vault Client is restarted.
- Only the use of the cmdlet in client customization [scripts](</client_customizations>) ensures that the tab is displayed in every Vault Client session.
- The Vault Client remembers activated Tabs (based on their position) even after a restart. In this case, the passed *-Action* gets invoked immediately after [LoginVault](</code_reference/objects/event_mappings/connection_events/loginvault>) event registrations.

:::

## Examples

**Adds a Tab for files displaying a DataGrid with their FileBom rows:**

```{image} /img/Add_VaultTab_SampleFileBOM.png
:align: right
:width: 40%
```

```powershell

Add-VaultTab -EntityType File -Name 'Sample File BOM' -Action {
    param($selectedFile)

    $fileBom = Get-VaultFileBOM -File $selectedFile._FullPath

    if(-not $fileBom) {
        return BuildFromXaml @'
            <StackPanel xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
                <Label Content="There are no rows to show in this view." HorizontalAlignment="Center" />
            </StackPanel>
'@
    }

    #Print BOM data as Table like in Inventor
    $bomrows_table = BuildFromXaml @'
        <DataGrid xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" AutoGenerateColumns="False" IsReadOnly="True">
                <DataGrid.Columns>
                    <DataGridTextColumn Header="Position" Binding="{Binding Bom_PositionNumber}" Width="60" />
                    <DataGridTextColumn Header="Number" Binding="{Binding Bom_Part Number}" Width="120"  />
                    <DataGridTextColumn Header="Description" Binding="{Binding Description}" Width="*" />
                    <DataGridTextColumn Header="Quantity" Binding="{Binding Bom_Quantity}" Width="60" />
                    <DataGridTextColumn Header="Unit of Measure" Binding="{Binding Bom_Unit}" Width="60"/>
                </DataGrid.Columns>
        </DataGrid>
'@
    $bomrows_table.ItemsSource = @($fileBom | sort-object {[int]$_.Bom_PositionNumber})
    return $bomrows_table
}

function BuildFromXaml([xml]$xaml){
    $xamlReader = New-Object System.Xml.XmlNodeReader $xaml
    return [Windows.Markup.XamlReader]::Load($xamlReader)
}
```

**Adds a Tab for items that displays their Thumbnail image:**

```powershell
Add-VaultTab -EntityType Item -Name 'Thumbnail' -Action 'DisplayItemThumbnail'

function DisplayItemThumbnail($selectedItem){
    $imageControl = New-Object System.Windows.Controls.Image
    $imageControl.Source = $selectedItem._Thumbnail.Image
    return $imageControl
}
```