Skip to content

Latest commit

 

History

History
168 lines (123 loc) · 4.88 KB

portalfx-blades-ui.md

File metadata and controls

168 lines (123 loc) · 4.88 KB
Raw

Blade UI

Controlling blade UI

Blades support a variety of APIs which make it easy to customize their behavior and experience.

Title & Icon

The title, subtitle, and icon of a blade can be customized with a View Model. This allows making real time changes to the title and icon based on the status of the asset. The View Model for a blade is a simple interface:

Client\Blades\Template\ViewModels\TemplateBladeViewModels.ts

export class TemplateBladesBladeViewModel extends MsPortalFx.ViewModels.Blade {

    constructor(container: MsPortalFx.ViewModels.ContainerContract, initialState: any, dataContext: BladesArea.DataContext) {
        super();
        this.title(ClientResources.templateBladesBladeTitle);
        this.subtitle(ClientResources.samples);
        this.icon(MsPortalFx.Base.Images.Polychromatic.Info());
    }
}

In this case, the information in the view model will be hard coded. Finally, you're ready to reference the view model from PDL:

<Blade Name="TemplateBladesBlade"
       ViewModel="TemplateBladesBladeViewModel">
  <Lens>
    ...
  </Lens>
</Blade>

Blade Content State

Blades have the ability to display a status at the top of the UI:

Blade Status

The follow states are currently available:

  • None
  • Success
  • Warning
  • Error

The content state and its label are both set in the blade view model. They can be set initially, and changed at runtime to reflect the current state of the blade. For an example of using blade content states, view the following file in the samples:

\Client\Blades\ContentState\ViewModels\ContentStateViewModels.ts

this.contentState(MsPortalFx.Parts.ContentState.Success);
this.contentStateDisplayText("Success!");

Locking

Locking a blade will prevent users from pinning its parts to the start board, moving parts around, or resizing parts. It's particularly useful when building a list control, an input form, or a create experience. If you need a locked blade you should use <TemplateBlade /> as opposed to the classic <Blade Locked="True" />. TemplateBlade has been designed to significantly simplify the locked blade programming model, specifically allows you to use:

  • a single TypeScript ViewModel for the entire blade and its content
  • a single PDL element that uses a html template
  • significant reduction in the amount of PDL
  • significant reduction in property binding complexity

For example to define a TemplateBlade with CommandBar in PDL use the following:

  <TemplateBlade Name="TemplateBladeWithCommandBar"
                 ViewModel="TemplateBladeWithCommandBarViewModel"
                 Template="{Html Source='..\Templates\SomeTemplate.html'}">
    <CommandBar />
  </TemplateBlade>

Contrast TemplateBlade with the classic <Blade Locked="true" approach:

<Blade Name="Samples" 
       Locked="True"
       ViewModel="SomeBladeVideModel">
  <Blade.Commands>
    <Command Text="{Resource saveText, Module=ClientResources}"
             ViewModel="SaveCommandViewModel">
    </Command>
  </Blade.Commands>
  <Lens Name="SomeLens">
    <CustomPart Name="SomeCustomPart"
                  Template="{Html Source='Templates\\SomeTemplate.html'}"
                  ViewModel="SomePartViewModel">
    </CustomPart>
  </Lens>
</Blade>

For complete examples of TemplateBlades see SamplesExtension Client\Blades\Template\Template.pdl

Width

When creating blades, you can choose from multiple widths. The default is 'Medium':

  • Small
  • Medium
  • Large
  • XLarge
  • Expandable

This is defined statically on the blade, and cannot be changed by the user. Small blades are useful for displaying lists of information. The Large and XLarge sizes are useful for blades with dense information which doesn't fit on a normal width blade (such as documentation).

\Client\Blades\BladeWidth\BladeWidth.pdl

<Blade Name="Samples"
       Width="Small">

    <Lens>
     ...
    </Lens>

</Blade>

Initial Display State

When the user opens a blade, you can choose to have it open in the normal state, or in a maximized state:

  • Maximized
  • Normal

Users may always choose to restore the blade to its normal supported width. This is useful for blades which contain large amounts of information.

<Blade Name="Samples"
       InitialDisplayState="Maximized">
    <Lens>
     ...
    </Lens>
</Blade>