PoshBoard PowerShell Module
From PoshBoardWiki
Contents |
Module description
the PoshBoard PowerShell Module provides several cmdlets to create graphical components in PoshBoard. It also provides administrative cmdlets to interact with the PoshBoard database and designer.
A complete list of PoshBoard commands is available here.
PoshBoard UI cmdlets
In this section we'll study the general architecture of PoshBoard graphical cmdlets and related objects. Whatever control you're creating (Buttons, Charts, TextBox, Datagrid....), PoshBoard Module create a single type of object called PbElement. It eases the learning process and visibility, as every object keeps the same structure.
PbElement Object
A PbElement is a PowerShell object that can be translated to Graphic control on the website (Buttons, charts, datagrids, etc…) In PoshBoard each graphic control is defined with this single object type. Below is a summary of the properties and methods available
PbElement Properties
- AllowedChildrenTypes: types of PbElement allowed as Child (Example: a Chart only accept ChartSeries as children, a Grid accepts any kind of child element)
- Children: for Container control (Grid, ListBox, Combobox, etc…), this property shows the children object of the PbElement
- Name: Name of the control (mandatory). The name is automatically generated if not set.
- Type: the control type in the library
- GuiIdentity: the name of the library (xap file in Silverlight version) embedding the control
- Events: events declared for this control (Example : Click for a button). Event car trigger PowerShell script to update the end user GUI.
- Properties: contains the properties of the control (Width, Height, color, alignment, etc…)
- Methods: not used yet (will be used to define dynamic actions on controls)
Note: Children and AllowedChildrenTypes are not shown when a control isn’t a Container see button below
"Properties" property
When a developer create a new control for PoshBoard, he also create a PowerShell function to manage it. Every property is strongly typed in order to help end users define appropriate values.
PoshBoard UI cmdlet definition
In order to speed up UI integration in PoshBoard, we builded a specific model for UI PowerShell definition. Basically, UI Developers only define UI Parameters for the function, and the corresponding properties are dynamically created when users invoke the cmdlet.
As an example, here's the definition of the New-Button function
Function New-Button{ param( [Parameter(Position=0, Mandatory=$false)] [PBExclude()] [String] $Name = (Get-UniqueName("Button")), [Parameter(Position=1, Mandatory=$false)] [Int] $Column = 0, [Parameter(Position=2, Mandatory=$false)] [Int] $ColumnSpan = 0, [Parameter(Position=3, Mandatory=$false)] [Int] $Height = 0, [Parameter(Position=4, Mandatory=$false)] [HorizontalAlignment] $HorizontalAlignment = "Stretch", [Parameter(Position=5, Mandatory=$false)] [Int[]] $Margin = @(), [Parameter(Position=6, Mandatory=$false)] [Int] $MaxHeight = 0, [Parameter(Position=7, Mandatory=$false)] [Int] $MaxWidth = 0, [Parameter(Position=8, Mandatory=$false)] [Int] $MinHeight = 0, [Parameter(Position=9, Mandatory=$false)] [Int] $MinWidth = 0, [Parameter(Position=10, Mandatory=$false)] [Int] $Row = 0, [Parameter(Position=11, Mandatory=$false)] [Int] $RowSpan = 0, [Parameter(Position=12, Mandatory=$false)] [VerticalAlignment] $VerticalAlignment = "Stretch", [Parameter(Position=13, Mandatory=$false)] [Int] $Width = 0, [Parameter(Position=14, Mandatory=$false)] [Int] $FontSize = 0, [Parameter(Position=15, Mandatory=$false)] [String] $Text, [Parameter(Position=16, Mandatory=$false)] [HorizontalAlignment] $TextAlignment = "Center" ) process { if ( $DebugPreference -ne "SilentlyContinue") { Write-Debug ("Call : {0}" -F $MyInvocation.InvocationName) } $Events=@{ Click=@{ Description="Occurs when a Button is clicked." Script=[String]::Empty; References=[Object[]]@() }; } New-PBElement $Name "Button" -GuiLibrary "StandardControls" -AllowedChildType $AllowedTypeNone -EventsDefinition $Events if ( $DebugPreference -ne "SilentlyContinue") { Write-Debug ("End : {0}" -F $MyInvocation.InvocationName) } } } Export-ModuleMember New-Button
Properties are strongly typed by the type specified for the parameter, UI Developers can also specifiy specific text-based type with enums (more on this in the UI Dev specific section when PoshBoard final version will be released).
PbElement Methods
Below is the list of the common Methods associated to PbElements:
- ConvertToXml: convert the PowerShell object to a XML version validated by the xsd schema (PoshBoard use the XML version of the PbElement to generate the Graphic control on the webserver side)
- ConvertToXmlDoc: same as above, but convert the PowerShell object to a XML Document version
- Clone: create a copy of a control with another name (useful when you want to use identical controls in your widget)
- AddChild (available for Container object only): add a child object to the PbElement
- RemoveChild (available for container object only): remove a child object from the PbElement
PbElement Events
An event on a PbElement is similar to any event on GUI controls: it's an action triggered by an user action, like clicking on a button, selecting an item in a list, etc...
In PoshBoard, Control designers can maps UI event to a PowerShell PbElement. That's the case for instance on the New-Button cmdlet. the Button object was defined with the "Click" event, matching the Click event on the Silverlight Button. In the current Beta only Button Click, ListBox/ComboBox SelectionChanged are available, but every event can be exposed to PowerShell by the Control Designers.
PS C:\> $a = New-Button PS C:\> $a.Events Click ----- @{Description=Occurs when a Button is clicked.} PS C:\> $a.Events.Click References Script Description ---------- ------ ----------- {} Occurs when a Button is ... PS C:\>
An event is defined by 3 elements:
Event References
Event Script
PoshBoard Cmdlets
This chapter present available functions in the PoshBoard module.
When you load the PoshBoard module, it will load every function available in the “Scripts” subfolder.
How to list available commands
You can list the available commands with this one-liner:
(get-module -Name poshboard).ExportedCommands
Connectivity
These commands manage Host to Designer connection. The designer is a section of PoshBoard website where administrators can render live PowerShell stream on a PoshBoard Silverlight page.
