Keep up to date with the Symphony Framework by subscribing to the mailing list.

Check out the new Symphony Framework Academy! It’s the home for information and tutorials to help you get the most from the Symphony Framework! Click on the Academy option below.

Symphony Framework Development

Symphony Framework Synergy Alpha Field Overview.


A Synergy Alpha field stores alpha-numeric data. The amount of storage available is determined by its size. From a user interface perspective you can define a display left less that the field length, thus providing a scrolling text entry box.

You should define a prompt value for your Alpha fields. Prompts are used in the UI to define field labels and report headings (you can also define a report heading, see below). Do not include special characters like > and <. If you need these in the prompt you must escape the character. The following table shows the escaped values:
Character Syntax Description


Using the Synergy Repository, Symphony Framework templates and CodeGen you can build powerful user interface styles, user controls and windows. All field entry controls utilise styles. A style defines how the user control will be rendered on the user interface. They also provide the ability to enable and display field/prompt entities, provide error state information and control input focus.

When you utilise the Synergy Repository and the CodeGen utility with the Symphony Framework templates to generate the styles for your user interface controls the templates utilise the fields and attributes defined in your repository. When processing a field there are a number of styles produced. The different styles allow you to accommodate a number of different scenarios in your Windows Presentation Foundation applications.

Alpha fields are exposed as a standard TextBox. This allows entry of any characters, up to the maximum size of the associated field. If an alpha field has a drill method assigned the base field type is defined as a SearchTextBox, which is a Symphony Framework type. This allows for the “lookup” of associated data. The following table defines the Synergy Repository field attributes that are recognised by the Symphony Framework CodeGen templates.

Attribute Comment
Size Will limit the number of character that can be entered into the field. This can be larger than the "display" width which limits the width of the input control
Exclude by Language Prevents the field being exposed through the Symphony Data Object. This is useful for hiding large/complex array and group elements. If you want the field available, but not exposed as a property then you should define the field with the token in the long description. See the long description tokens section below
Exclude by Toolkit Prevents the field from being included in any view or DataGrid. No style is created for the field. It will still be available as a property in the Data Object.
Exclude by Report Writer Will exclude the field from any criteria selection windows. This prevents the user from being able to see/use this field to select records in the data source. Fields will also not be available for inclusion by the user within DataGrid views. It will still be available as a property in the Data Object.
Prompt Used to propagate the fields associated Label style. As per the rules defined by CodeGen, if this attribute is not defined the field name will be used.
Report Heading Will populate the DataGrid column heading is specified. As per the rules defined by CodeGen, if this attribute is not defined the field prompt will be used.
View as
Field. Display the standard TextBox.
Checkbox. Will convert the field’s style to that of a CheckBox control. The values assigned to the field will be “Y” for checked, and “N” for unchecked.
Radio Button. Will create a radio button group. The values within the group will be the values of the Selection – List entries.
Uppercase Forces the entered text to be automatically uppercased.
Action-Default You can define a default value. When a Data Object is initialised, default values will be assigned to the associated fields..
Break Forces the entered data to update the data bound property as the data is changed, not when the field has lost focus. Note: Due to a current limitation in the Microsoft Framework 4.0 this setting is currently ignored and ALL fields are defined to update bound data when the property changes.
Required The field will be in error until at least one character is entered.
Selections
List. Assigns a Combo drop down list to the field’s style. The entries within the list are used to define the available dropdown list items. The field value for each items in the list will be determined by the folling:
Window. Assigns a Combo drop down list to the field’s style. The name of the selection window must be that of the repository structure that contains the value/description pairs. You can then code generate the code to load the selections from the file associated to the structure.
Drill Method If defined as the name of the related structure then the field’s style will be a SearchTextBox that provides a lookup capability.
Hyperlink Method Will display the fields associated label as a HyperLinkLabel that can be clicked by the user, and a new visual state presented.

Long Description tokens


There are a number of tokens that can be defined in the long description for a field that will alter the code generated. the following table lists all possible tokens and their associated actions. All tokens are defined within < and > characters.

Token Action
SYMPHONY_MAX_DISPLAY_LENGTH=value Limits the size of the input control. If the alpha field is larger than 50 characters the default action is to define it as a multiline edit control. Setting this token prevents this action and limites the physical width of the edit control based on the value specified.
SYMPHONY_ARRAY_FIELD This token identifys the field as an arrayed field which is to be excluded from the property list of the Data Object. When CodeGen encounteres an arrayed field it flattens the field and creates individual properties/fields for each element. This can cuase the creation of large Data Objects. Arrayed fields are very cumbersome to manage also. By setting this custom token you can prevent these arrayed field form being included as properties in Data Objects and from many other Symphony tempaltes.
SYMPHONY_SELWND_LENGTH=value When you assign a selection window to a field this token enables you to define the actual width of the resulting ComboBox control.
SYMPHONY_SEARCHBOX_COMMAND=string_value An alpha field with a drill method asigned will automatically be defined to use the SearchTextBox control. This control allows the user to enter a value or click the spy glass to perform a lookup-type function. The default action is to navigate to a state named as the drill method. You can alter this default behevior by specifying this token. The string_value should be the data bound commend to perform.

Selection List considerations


By default if you define a selection list and you do not enumerate it, the value of the selection is defined by the initial (length of the field) characters of the list item. for example, given an alpha field with a size of two:

List item Resulting storage value
On order On
Available AV
Allocated AL


You can alter this default behaviour by specifying the storage value in the item description. Enclose the storage value in < and > imediatly after the item description. For example:

List item Resulting storage value
On order< 1 > 1
Available< 6 > 6
Allocated<-1> -1


Examples


When you code genernate a style (using the Symphony_Style.tpl template) the generated XAML code defines the alpha field style based on the field attributed in the repository.

In this example we have defined a standard alpha text entry box. The code generated style defines the TextBox styling based on the attributes defined against the files.

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:symphonyConverters="clr-namespace:Symphony.Conductor.Converters;assembly=SymphonyConductor"
    xmlns:symphonyTriggers="clr-namespace:Symphony.Conductor.Triggers;assembly=SymphonyConductor"
    xmlns:symphonyUI="clr-namespace:Symphony.Crescendo.Presentation;assembly=SymphonyCrescendo"
    xmlns:symphonyControls="clr-namespace:Symphony.Conductor.Controls;assembly=SymphonyConductor"
    xmlns:i="clr-namespace:System.Windows.Interactivity;assembly=System.Windows.Interactivity">

    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Styles.xaml"/>
        <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Converters.xaml"/>
    </ResourceDictionary.MergedDictionaries>

    <Style x:Key="File_verify_File_name_style" TargetType="{x:Type symphonyControls:FieldControl}">
        <Setter Property="FocusVisualStyle" Value="{x:Null}"/>
        <Setter Property="Focusable" Value="False"></Setter>
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="{x:Type symphonyControls:FieldControl}">
                    <TextBox
                        Name="ctlFile_verify_File_name"
                        Text="{Binding Path=File_name, Converter={StaticResource alphaConverter}, UpdateSourceTrigger=PropertyChanged,
                                ValidatesOnDataErrors=True}"
                                Validation.ErrorTemplate="{StaticResource validationTemplate}"
                        MaxLength="255"
                        Width="300"
                        IsEnabled="{Binding Path=File_nameIsEnabled}"
                        IsReadOnly="{Binding Path=File_nameIsReadOnly}"
                        VerticalAlignment="Center"
                        HorizontalAlignment="Left"
                        ToolTip="{Binding RelativeSource={RelativeSource Self},Path=(Validation.Errors), Converter={StaticResource errorConveter}}">
                        <TextBox.Style>
                            <Style>
                                <Style.Triggers>
                                    <DataTrigger Binding="{Binding Path=File_nameIsFocused}" Value="true">
                                        <Setter Property="FocusManager.FocusedElement"
                                                Value="{Binding ElementName=ctlFile_verify_File_name}"></Setter>
                                    </DataTrigger>
                                </Style.Triggers>
                            </Style>
                        </TextBox.Style>
                    </TextBox>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>

</ResourceDictionary>


To utilise the generated style in you UserControl or Window you simply reference the FieldControl class in the Symphony Framework and style it with the required field style.

<UserControl x:Class="MyProject.View.File_verify_DataView"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
             xmlns:symphonyControls="clr-namespace:Symphony.Conductor.Controls;assembly=SymphonyConductor"
             mc:Ignorable="d"
             d:DesignHeight="600" d:DesignWidth="1100">

    <UserControl.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Styles.xaml"/>
                <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Converters.xaml"/>
                <ResourceDictionary Source="pack://application:,,,/MyProject;component/Resources/File_verify_style.CodeGen.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </UserControl.Resources>


    <Grid>
        <symphonyControls:FieldControl
                DataContext="{Binding Path=MasterData}"
                Style="{StaticResource File_verify_File_name_style}">
        </symphonyControls:FieldControl>
    </Grid>

</UserControl>

If the Alpha field has a Drill method assigned to it, then the style is created using the symphony Framework's SearchTextBox control. The token SYMPHONY_DRILL_COMMAND was assigned the value of DataContext.FileSearchCommand in the fields long description. This bindable command will be executed when the spy glass image is clicked.

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:symphonyConverters="clr-namespace:Symphony.Conductor.Converters;assembly=SymphonyConductor"
    xmlns:symphonyTriggers="clr-namespace:Symphony.Conductor.Triggers;assembly=SymphonyConductor"
    xmlns:symphonyUI="clr-namespace:Symphony.Crescendo.Presentation;assembly=SymphonyCrescendo"
    xmlns:symphonyControls="clr-namespace:Symphony.Conductor.Controls;assembly=SymphonyConductor"
    xmlns:i="clr-namespace:System.Windows.Interactivity;assembly=System.Windows.Interactivity">

    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Styles.xaml"/>
        <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Converters.xaml"/>
        <ResourceDictionary Source="pack://application:,,,/SymphonyFileUtils;component/Resources/File_verify_Content.CodeGen.xaml"/>
     </ResourceDictionary.MergedDictionaries>


    <Style x:Key="File_verify_File_name_style" TargetType="{x:Type symphonyControls:FieldControl}">
        <Setter Property="FocusVisualStyle" Value="{x:Null}"/>
        <Setter Property="Focusable" Value="False"></Setter>
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="{x:Type symphonyControls:FieldControl}">
                    <symphonyUI:SearchTextBox
                        HorizontalAlignment="Left"
                        Name="ctlFile_verify_File_name"
                        Text="{Binding Path=File_name, Converter={StaticResource alphaConverter}, UpdateSourceTrigger=PropertyChanged,
                                ValidatesOnDataErrors=True}"
                                Validation.ErrorTemplate="{StaticResource validationTemplate}"
                                SearchMode="Delayed"
                        Command="{Binding RelativeSource={RelativeSource AncestorType={x:Type UserControl}}, Path=DataContext.FileSearchCommand}"
                        CommandParameter="file_searchState"
                        MaxLength="255"
                        Width="300"
                        IsEnabled="{Binding Path=File_nameIsEnabled}"
                        IsReadOnly="{Binding Path=File_nameIsReadOnly}"
                        VerticalAlignment="Center"
                        ToolTip="{Binding RelativeSource={RelativeSource Self},Path=(Validation.Errors), Converter={StaticResource errorConveter}}">
                        <symphonyUI:SearchTextBox.Style>
                            <Style>
                                <Style.Triggers>
                                    <DataTrigger Binding="{Binding Path=File_nameIsFocused}" Value="true">
                                        <Setter Property="FocusManager.FocusedElement"
                                                Value="{Binding ElementName=ctlFile_verify_File_name}"></Setter>
                                    </DataTrigger>
                                </Style.Triggers>
                            </Style>
                        </symphonyUI:SearchTextBox.Style>
                    </symphonyUI:SearchTextBox>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>


The prompt is also defined within the style resource file.

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:symphonyConverters="clr-namespace:Symphony.Conductor.Converters;assembly=SymphonyConductor"
    xmlns:symphonyTriggers="clr-namespace:Symphony.Conductor.Triggers;assembly=SymphonyConductor"
    xmlns:symphonyUI="clr-namespace:Symphony.Crescendo.Presentation;assembly=SymphonyCrescendo"
    xmlns:symphonyControls="clr-namespace:Symphony.Conductor.Controls;assembly=SymphonyConductor"
    xmlns:i="clr-namespace:System.Windows.Interactivity;assembly=System.Windows.Interactivity">

    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Styles.xaml"/>
        <ResourceDictionary Source="pack://application:,,,/SymphonyConductor;component/Resources/Converters.xaml"/>
        <ResourceDictionary Source="pack://application:,,,/SymphonyFileUtils;component/Resources/File_verify_Content.CodeGen.xaml"/>
    </ResourceDictionary.MergedDictionaries>


    <Style x:Key="File_verify_File_name_prompt" TargetType="{x:Type Label}">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="{x:Type Label}">
                    <Label
                        Content="File(s) to verify"
                        IsEnabled="{Binding Path=File_nameIsEnabled}">
                    </Label>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>