Jump to: navigation, search

Difference between revisions of "UBIK Templates"

(→‎ContentAreaTemplateSelector (UWP) / ContentAreaTemplateConverter (Xamarin))
(→‎PropertyEditorItemTemplateSelector (UWP) / EditTemplateConverter (Xamarin))
Line 240: Line 240:
  
 
=== PropertyEditorItemTemplateSelector (UWP) / EditTemplateConverter (Xamarin) ===
 
=== PropertyEditorItemTemplateSelector (UWP) / EditTemplateConverter (Xamarin) ===
 +
This returns a fitting template for a given context property according to the following rules:
 
<tabs>
 
<tabs>
 
<tab name="UWP">
 
<tab name="UWP">
−
The PropertyEditorItemTemplateSelector dynamically selects a fitting DataTemplate based on the type of the given property.
+
* Returns a ''UBIKEditBool'' template if the given Property is of type Bool.
−
* Returns a ''UBIKEditBool'' template if the MetaProperty type of the given Property is of type Bool.
+
* Returns a ''UBIKEditString'' template if the given Property is of type String.
−
* Returns a ''UBIKEditString'' template if the MetaProperty type of the given Property is of type String.
+
* Returns a ''UBIKEditInt'' template if the given Property is of type Int.
−
* Returns a ''UBIKEditInt'' template if the MetaProperty type of the given Property is of type Int.
+
* Returns a ''UBIKEditDouble'' template if the given Property is of type Double.
−
* Returns a ''UBIKEditDouble'' template if the MetaProperty type of the given Property is of type Double.
+
* Returns a ''UBIKEditDateTime'' template if the given Property is of type DateTime.
−
* Returns a ''UBIKEditDateTime'' template if the MetaProperty type of the given Property is of type DateTime.
+
* Returns a ''UBIKEditGuid'' template if the given Property is of type Guid.
−
* Returns a ''UBIKEditGuid'' template if the MetaProperty type of the given Property is of type Guid.
+
* Returns a ''UBIKEditSignature'' template if the given Property is of type Signature.
−
* Returns a ''UBIKEditSignature'' template if the MetaProperty type of the given Property is of type Signature.
+
* Returns a ''UBIKEditChart'' template if the given Property is of type Chart.
−
* Returns a ''UBIKEditChart'' template if the MetaProperty type of the given Property is of type Chart.
+
{{Hint|Even though UBIK has an editor for GeoData and FileReference type, its UI is not customizable and therefore the selector is not relevant for them.}}
 +
{{Hint|UBIK doesn't show editors for XML, ByteStream, Geography, and Undefined type, therefore the selector is not relevant for them.}}
 +
 
 
</tab>
 
</tab>
 
<tab name="Xamarin">
 
<tab name="Xamarin">
−
The EditTemplateConverter returns a fitting EditTemplate from a Property item.
+
* Returns a ''UBIKEditBool'' template if the given Property is of type Bool.
−
* Returns null if the current editor’s PropertyViewModel instance is null.
+
* Returns a ''UBIKEditString'' template if the given Property is of type String.
−
* Returns a "UBIKEditBool" if the given PropertyItem is of type Bool.
+
* Returns a ''UBIKEditInt'' template if the given Property is of type Int.
−
* Returns a "UBIKEditString" if the given PropertyItem is of type String.
+
* Returns a ''UBIKEditDouble'' template if the given Property is of type Double.
−
* Returns a "UBIKEditInt" if the given PropertyItem is of type Int.
+
* Returns a ''UBIKEditDateTime'' template if the given Property is of type DateTime.
−
* Returns a "UBIKEditDouble" if the given PropertyItem is of type Double.
+
* Returns a ''UBIKEditGuid'' template if the given Property is of type Guid.
−
* Returns a "UBIKEditDateTime" if the given PropertyItem is of type DateTime.
+
* Returns a ''UBIKEditGeo'' template if the given Property is of type GeoData.
−
* Returns a "UBIKEditGuid" if the given PropertyItem is of type Guid.
+
* Returns a ''UBIKEditSignature'' template if the given Property is of type Signature.
−
* Returns a "UBIKEditGeo" if the given PropertyItem is of type GeoData.
+
* Returns an [[Developer_Mode#Errors|error template]] if the given Property is of type XML, ByteStream, Geography, FileReference, or Undefined.
−
* Returns a "UBIKEditSignature" if the given PropertyItem is of type Signature.
+
−
* Returns a "UBIKEditNotSupported" if the given PropertyItem is of type XML, ByteStream, Geography, Undefined or FileReference.
+
−
* Otherwise, it returns null if no specific template is found.
+
 
</tab>
 
</tab>
 
</tabs>
 
</tabs>
 +
{{Hint|To get an overview of how template selectors work, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 
{{UnderConstructionEnd}}
 
{{UnderConstructionEnd}}
  

Revision as of 06:48, 18 April 2024

The UI of UBIK® WinX/UWP client is highly customizable. Project engineers/customizers can tailor the UI for minor style changes or major redesigns according to their needs.


General knowledge

Due to the nature of customizing, it's impossible to cover all issues or questions that one might have during customizing. However, the fundamental ones should become self explanatory with the help of the Developer Mode feature. Such questions include and are not limited to:

  • Which parts of the UI are customizable?
  • How do I get the default XAML templates used in the clients?
  • What kind of data can I present in the custom UI?
  • Where should I deploy the custom template files?

UI controls

Controls are basic building blocks for constructing the UI. Several types of them are used in the client.

Standard controls

All standard Universal Windows Platform (UWP) controls can be used for our WinX/UWP client. There are online official documentations available for these controls. Some official or 3rd party apps showcasing these also exist and can be of great help. For example, XAML controls gallery presents a rich collection of examples/tutorials.

3rd party and UBIK controls

We also use a few 3rd party (e.g. Syncfusion) and UBIK® custom made controls in our client. There is currently no compiled lists of such controls. However, as a general rule, any such controls one finds in the default templates can be used in customizings.

Template loading mechanism

Templates with default names

As one can see in the Developer Mode, the default client UI consists of many parts and each of them is defined in an individual template with names such as UBIKChildArea. When a custom template file with the same name is deployed, that template is used by the client instead of the default one that comes with the client.

Templates with custom names

A common problem with customizing templates such as UBIKChildArea is that it alters the UI for all types of child objects. In order to use different templates depending on the objects, solutions such as child area template classification, child item template classification and content area template classification are provided. Custom template files with names such as UBIKChildArea_WorkPackage can be deployed so that only objects of that type display the custom content while the rest still uses the default UI.

Other than the necessary server side data configuration, a template selector is also needed to achieve this. For example, here's the code snippet in the default UBIKContentArea template.

...
<Grid xmlns:tpl="using:UBIK.WinX.Templates">
    <Grid.Resources>
        <tpl:ChildAreaTemplateSelector x:Key="ChildAreaTemplateSelector" />
    </Grid.Resources>
    <ContentControl ContentTemplateSelector="{StaticResource ChildAreaTemplateSelector}" />
</Grid>
...

The child area template selector used in this example determines the child area template to use based on the following rules.

  • If not found and the "Strict Template Loading Policy" setting is turned on, returns an error template; (This can be useful for checking if some templates are missing before the final deployment.)
  • If not found, returns the default UBIKChildArea template.
IC Hint square.pngIt's possible to use a different syntax to refer to a custom named template, e.g.
<ContentControl ContentTemplate="{Binding TemplateService[UBIKChildArea_WorkPackage]}" /> .
However, since the client does not know which default template should be used, an error template will be used if the custom named one can not be found.
IC Hint square.pngIt's also possible to specify a Suffix for the template selector, e.g.
<tpl:ChildAreaTemplateSelector x:Key="ChildAreaTemplateSelector" Suffix="Small" />.
Unlike the custom name template name lookup, the Suffix is no longer considered optional once specified. If such a template file cannot be found, an error template will be used.

Template Selectors

Wiki Under Construction Start.PNG

In general, Template Selectors return DataTemplates based on the given object. UBIK provides template selectors for different Items & Areas and their logic is explained in the following subsections.

ChildItemTemplateSelector (UWP & Xamarin)

The ChildItemTemplateSelector returns a fitting DataTemplate based on the given child item.

UWP

  • Returns a custom template if one is configured.
  • Otherwise, it returns a UBIKProjectItem if the given item is a MROViewModel and contains ProjectData (namely if the associated object is a MRO object with project information)
  • Otherwise, it returns a UBIKTaskItem if the given item is a TaskViewModel (namely if the associated object is a Task)
  • If nothing of the above fits, it returns a UBIKChildItem.

Xamarin

  • If the given ContentListItemViewModel is not null:
    • If the given item is a TaskViewModel (namely if the associated object is a Task) and the TaskItemTemplate is not null, it returns that TaskItemTemplate.
    • Otherwise, if the given item is a TaskViewModel (namely if the associated object is a Task) & the TaskItemTemplate is null, it returns a UBIKTaskItem.
    • If the given MROViewModel contains ProjectData (namely if the associated object is a MRO object with project information) and the ProjectItemTemplate is not null, it returns that ProjectItemTemplate.
    • Otherwise, if the given MROViewModel contains ProjectData (namely if the associated object is a MRO object with project information) and the ProjectItemTemplate is null, it returns a UBIKProjectItem.
    • If nothing of the above fits & the ChildItemTemplate is not null, it returns that ChildItemTemplate.
    • If nothing of the above fits & the ChildItemTemplate is null, it returns a UBIKChildItem.
  • Returns null if the given ContentListItemViewModel is null.

PropertyDirectItemTemplateSelector (UWP & Xamarin)

The PropertyDirectItemTemplateSelector returns a fitting DataTemplate based on the given property item.

UWP

  • Returns a non-direct edit template (namely UBIKPropertyDirectItemNotSupported):
    • when the given PropertyViewModel is a live value item or
    • if the related property is read only or
    • if the object is locked or
    • when the object requires authentication.
  • Otherwise:
    • Returns a UBIKPropertyDirectItemList if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKPropertyDirectItemBool if the given PropertyViewModel is of type Bool.
    • Returns a UBIKPropertyDirectItemString if the given PropertyViewModel is of type String.
    • Returns a UBIKPropertyDirectItemInt if the given PropertyViewModel is of type Int.
    • Returns a UBIKPropertyDirectItemDouble if the given PropertyViewModel is of type Double.
    • Returns a UBIKPropertyDirectItemDateTime if the given PropertyViewModel is of type DateTime.
    • Returns a UBIKPropertyDirectItemGuid if the given PropertyViewModel is of type Guid.
    • Returns a UBIKPropertyDirectItemGeoData if the givenPropertyViewModel is of type GeoData.

Xamarin

  • Returns a non-direct edit template (namely UBIKPropertyItem):
    • when the given PropertyViewModel is a live value item or
    • if the related property is read only or
    • if the object is locked or
    • when the object requires authentication.
  • Otherwise:
    • Returns a UBIKPropertyDirectItemList if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKPropertyDirectItemBool if the given PropertyViewModel is of type Bool.
    • Returns a UBIKPropertyDirectItemString if the given PropertyViewModel is of type String.
    • Returns a UBIKPropertyDirectItemInt if the given PropertyViewModel is of type Int.
    • Returns a UBIKPropertyDirectItemDouble if the given PropertyViewModel is of type Double.
    • Returns a UBIKPropertyDirectItemGuid if the given PropertyViewModel is of type Guid.

TaskPropertyTemplateSelector (UWP & Xamarin)

The TaskPropertyTemplateSelector returns a fitting DataTemplate based on the given task property item.

UWP

  • Returns a non-direct edit template (UBIKTaskProperty):
    • when the PropertyViewModel of the given TaskViewModel (namely if the associated object is a Task) is a live value item or
    • if the related property is read only or
    • if the object is locked or
    • when the objects requires authentication.
  • Otherwise:
    • Returns a UBIKTaskPropertyList if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKTaskPropertyBool if the given TaskViewModels (namely the associated object is a Task) Value is of type Bool.
    • Returns a UBIKTaskPropertyString if the given TaskViewModels (namely the associated object is a Task) Value is of type String.
    • Returns a UBIKTaskPropertyInt if the given TaskViewModels (namely the associated object is a Task) Value is of type Int.
    • Returns a UBIKTaskPropertyDouble if the given TaskViewModels (namely the associated object is a Task) Value is of type Double.
    • Returns a UBIKTaskPropertyDateTime if the given TaskViewModels (namely the associated object is a Task) Value is of type DateTime.
    • Returns a UBIKTaskPropertyGuid if the given TaskViewModels (namely the associated object is a Task) Value is of type Guid.
    • Returns a UBIKTaskPropertyGeoData if the given TaskViewModels (namely the associated object is a Task) Value is of type GeoData.

Xamarin

  • Returns a non-direct edit template (UBIKTaskProperty):
    • when the PropertyViewModel of the given TaskViewModel (namely if the associated object is a Task) is a live value item or
    • if the related property is read only or
    • if the object is locked or
    • when the objects requires authentication.
  • Otherwise:
    • Returns a UBIKTaskPropertyList if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKTaskPropertyBool if the given TaskViewModels (namely the associated object is a Task) Value is of type Bool.
    • Returns a UBIKTaskPropertyString if the given TaskViewModels (namely the associated object is a Task) Value is of type String.
    • Returns a UBIKTaskPropertyInt if the given TaskViewModels (namely the associated object is a Task) Value is of type Int.
    • Returns a UBIKTaskPropertyDouble if the given TaskViewModels (namely the associated object is a Task) Value is of type Double.
    • Returns a UBIKTaskPropertyGuid if the given TaskViewModels (namely the associated object is a Task) Value is of type Guid.

HotSpotTemplateSelector (UWP & Xamarin)

The HotSpotTemplateSelector returns a fitting DataTemplate based on the given HotSpot item.

UWP

  • Returns a UBIKAngularLinkHotSpot if the given HotSpot is of type LinkHotSpot with HotSpotShape Angular & if the UBIKAngularLinkHotSpot template is not null.
  • Returns a UBIKRoundLinkHotSpot if the given HotSpot is of type LinkHotSpot with HotSpotShape Round & if the UBIKRoundLinkHotSpot template is not null.
  • Returns a UBIKSignatureHotSpot if the given HotSpot is of type SignatureSpot & if the UBIKSignatureHotSpot template is not null.
  • Returns a UBIKObjectHotSpot'' if the given HotSpot is of type ObjectHotSpot & if the UBIKObjectHotSpot template is not null.
  • Returns a UBIKMediaHotSpot if the given HotSpot is of type MediaSpot & if the UBIKMediaHotSpot template is not null.
  • Returns a UBIKInputHotSpot if the given HotSpot is of type InputHotSpot & if the UBIKInputHotSpot template is not null.
  • If nothing of the above fits, it returns a UBIKDefaultHotSpot.

Xamarin

  • Returns a UBIKAngularLinkHotSpot if the given HotSpot is of type LinkHotSpot with HotSpotShape Angular & if the UBIKAngularLinkHotSpot template is not null.
  • Returns a UBIKRoundLinkHotSpot if the given HotSpot is of type LinkHotSpot with HotSpotShape Round & if the UBIKRoundLinkHotSpot template is not null.
  • Returns a UBIKSignatureHotSpot if the given HotSpot is of type SignatureSpot & if the UBIKSignatureHotSpot template is not null.
  • Returns a UBIKObjectHotSpot'' if the given HotSpot is of type ObjectHotSpot & if the UBIKObjectHotSpot template is not null.
  • Returns a UBIKMediaHotSpot if the given HotSpot is of type MediaSpot & if the UBIKMediaHotSpot template is not null.
  • Returns a UBIKInputHotSpot if the given HotSpot is of type InputHotSpot & if the UBIKInputHotSpot template is not null.
  • If nothing of the above fits, it returns a UBIKDefaultHotSpot.

ProfileItemTemplateSelector (UWP)

  • The ProfileItemTemplateSelector returns a UBIKProfileItem if the given item is a Profile file.
  • If the given item is a folder, it returns a UBIKProfileFolder.

RootItemTemplateSelector (UWP)

The RootItemTemplateSelector returns a fitting DataTemplate based on the given root item.

  • Returns a custom template if one is configured.
  • Otherwise:
    • It returns a UBIKProjectItem if the given item is a MROViewModel and contains ProjectData (namely if the associated object is a MRO object with project information).
    • It returns a UBIKTaskItem if the given item is a TaskViewModel (namely if the associated object is a Task).
  • If nothing of the above fits, it returns a UBIKMainItem.

ComboBoxItemTemplateSelector (UWP)

  • The ComboBoxItemTemplateSelector returns a DropDownItemTemplate for drop-down list items.
  • Otherwise, it returns a ComboBoxSectionItemTemplate (for the selected item when the drop-down list is closed).

ChildAreaTemplateSelector (UWP) / ChildAreaTemplateConverter (Xamarin)

This returns a fitting template for a given context object according to the following rules:

UWP

  • If the context object is classified with the ChildAreaTemplate Classification and carries a valid child area template name:
    • Tries to return a custom template with the name of CustomTemplateName + Suffix;
    • If not found, returns an error template (strict policy on) or goes to the next rule (strict policy off).
  • Otherwise:
    • Tries to return a custom template with the name UBIKChildArea + Suffix;
    • If not found, it will try to find the default template with the given name;
    • If that's not found, it returns an error template.

Xamarin

  • If the context object is classified with the ChildAreaTemplate Classification and carries a valid child area template name:
    • Tries to return a custom template with the name of CustomTemplateName;
    • If that's not found, it returns an error template.
  • Otherwise:
    • Tries to return a custom template with the name UBIKChildArea;
    • If not found, it will try to find the default template with the given name;
    • If that's not found, it returns an error template.

ContentAreaTemplateSelector (UWP) / ContentAreaTemplateConverter (Xamarin)

This returns a fitting template for a given context object according to the following rules:

UWP

  • If the context object is classified with the ContentAreaTemplate Classification and carries a valid content area template name:
    • Tries to return a custom template with the name of CustomTemplateName + Suffix;
    • If not found, returns an error template (strict policy on) or goes to rule 2 (strict policy off).
  • Otherwise:
    • Tries to return a custom template with the name of UBIKContentArea + Suffix;
    • If not found, it returns an error template.

Xamarin

  • If the context object is classified with the ContentAreaTemplate Classification and carries a valid content area template name:
    • Tries to return a custom template with the name of CustomTemplateName;
    • If not found, returns an error template.
  • Otherwise:
    • Tries to return a custom template with the name of UBIKContentArea;
    • If not found, it returns an error template.

PropertyEditorItemTemplateSelector (UWP) / EditTemplateConverter (Xamarin)

This returns a fitting template for a given context property according to the following rules:

UWP

  • Returns a UBIKEditBool template if the given Property is of type Bool.
  • Returns a UBIKEditString template if the given Property is of type String.
  • Returns a UBIKEditInt template if the given Property is of type Int.
  • Returns a UBIKEditDouble template if the given Property is of type Double.
  • Returns a UBIKEditDateTime template if the given Property is of type DateTime.
  • Returns a UBIKEditGuid template if the given Property is of type Guid.
  • Returns a UBIKEditSignature template if the given Property is of type Signature.
  • Returns a UBIKEditChart template if the given Property is of type Chart.
IC Hint square.pngEven though UBIK has an editor for GeoData and FileReference type, its UI is not customizable and therefore the selector is not relevant for them.
IC Hint square.pngUBIK doesn't show editors for XML, ByteStream, Geography, and Undefined type, therefore the selector is not relevant for them.

Xamarin

  • Returns a UBIKEditBool template if the given Property is of type Bool.
  • Returns a UBIKEditString template if the given Property is of type String.
  • Returns a UBIKEditInt template if the given Property is of type Int.
  • Returns a UBIKEditDouble template if the given Property is of type Double.
  • Returns a UBIKEditDateTime template if the given Property is of type DateTime.
  • Returns a UBIKEditGuid template if the given Property is of type Guid.
  • Returns a UBIKEditGeo template if the given Property is of type GeoData.
  • Returns a UBIKEditSignature template if the given Property is of type Signature.
  • Returns an error template if the given Property is of type XML, ByteStream, Geography, FileReference, or Undefined.
IC Hint square.pngTo get an overview of how template selectors work, please refer to Template loading mechanism.

Wiki Under Construction End.PNG

Retrieved from "https://wiki.augmensys.com/index.php?title=UBIK_Templates&oldid=26277"