Jump to: navigation, search

Difference between revisions of "UBIK Templates"

(→‎RootPage)
m
 
(37 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
The UI is controlled by several predefined XAML templates which are loaded into the App at startup. There is a set of default template deployed with the App at installation, however, each of them can be overridden by placing the respective file in the folder [AppInstallPath]\LocalState\XAML. <br>
+
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.
−
Here you can see which XAML which area defines, either the area is ''beige'' colored or it has a ''red border'' around it.  
+
  
−
=== General ===
+
= General knowledge =
−
* UBIKThemes.xaml
+
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:
−
Controls the overall styling and behavior of the App, like standard Brushes (Colors) and Fonts.
+
* 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?
  
−
==== AuthenticationPage ====
+
= UI controls =
−
* UBIKSplashArea.xaml
+
Controls are basic building blocks for constructing the UI. Several types of them are used in the client.
−
[[File:SplashAreaA.JPG|upright=0.35|thumb|left|alt=UBIKSplashArea|UBIKSplashArea.xaml]]
+
−
{{clear}}
+
−
* UBIKPageNavigation.xaml -> Deprecated and changed to UBIKHomePageButtons.xaml {{Version/WinXSince|3.0.0}}
+
−
[[File:HomePageButtonsA.JPG|upright=0.35|thumb|left|alt=UBIKHomePageButtons|UBIKHomePageButtons.xaml]]
+
−
{{clear}}
+
−
* UBIKProfileItem.xaml
+
−
[[File:after.png|upright=0.35|thumb|left|alt=UBIKProfileItem|UBIKProfileItem.xaml]]
+
−
{{clear}}
+
  
 +
== 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, [https://www.microsoft.com/en-us/p/xaml-controls-gallery/9msvh128x2zt?activetab=pivot:overviewtab 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.
  
−
=== Content Pages ===
+
= Template loading mechanism =
−
* UBIKObjectIcon.xaml
+
−
[[File:ObjectIconA.png|upright=0.35|thumb|left|alt=UBIKObjectIcon|UBIKObjectIcon.xaml]]
+
−
{{clear}}
+
−
* UBIKObjectIconSmall.xaml
+
−
* UBIKBottomLeft.xaml
+
−
[[File:BottomLeftA.JPG|upright=0.35|thumb|left|alt=UBIKBottomLeft|UBIKBottomLeft.xaml]]
+
−
{{clear}}
+
  
 +
== 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.
  
−
==== RootPage ====
+
== Templates with custom names ==
−
* UBIKMainLeftArea.xaml
+
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 [[SYSCLS_CHILDAREATEMPLATE|child area template classification]], [[SYSCLS_CHILDITEMTEMPLATE|child item template classification]] and [[SYSCLS_CHILDAREATEMPLATE|content area template classification]]{{Version/WinXSince|4.1}} 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.
−
[[File:MainLeftA.png|upright=0.35|thumb|left|alt=UBIKMainLeftArea|UBIKMainLeftArea.xaml]]
+
−
{{clear}}
+
−
* UBIKMainItem.xaml
+
−
[[File:MainItemA.JPG|upright=0.35|thumb|left|alt=UBIKMainItem|UBIKMainItem.xaml]]
+
−
{{clear}}
+
−
* UBIKMainItemSmall.xaml
+
−
[[File:MainItemSmallA.JPG|upright=0.35|thumb|left|alt=UBIKMainItemSmall|UBIKMainItemSmall.xaml]]
+
−
{{clear}}
+
−
*UBIKMainArea.xaml
+
−
[[File:MainAreaA.JPG|upright=0.35|thumb|left|alt=UBIKMainArea|UBIKMainArea.xaml]]
+
−
{{clear}}
+
−
*UBIKMainPageListHeader.xaml
+
−
[[File:MainPageListHeader.png|upright=0.35|thumb|left|alt=UBIKMainPageListHeader|UBIKMainPageListHeader.xaml]]
+
−
{{clear}}
+
  
−
[[Category:UBIK|UBIK Templates]]
+
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.
 +
 
 +
<syntaxhighlight lang="xml">
 +
...
 +
<Grid xmlns:tpl="using:UBIK.WinX.Templates">
 +
    <Grid.Resources>
 +
        <tpl:ChildAreaTemplateSelector x:Key="ChildAreaTemplateSelector" />
 +
    </Grid.Resources>
 +
    <ContentControl ContentTemplateSelector="{StaticResource ChildAreaTemplateSelector}" />
 +
</Grid>
 +
...
 +
</syntaxhighlight>
 +
 
 +
The child area template selector used in this example determines the child area template to use based on the following rules.
 +
* If an object defines a child area template name (see [[SYSCLS_CHILDAREATEMPLATE|child area template classification]]), return the custom template with that name;
 +
<div id="StrictTemplatePolicy"></div>
 +
* {{Version/WinXSince|3.6}} ('''Not yet available for Xamarin''') If not found and the "Strict Template Loading Policy" setting is turned on, returns an [[Developer_Mode#Errors|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.
 +
 
 +
{{Hint|It's possible to use a different syntax to refer to a custom named template, e.g. <br><nowiki><ContentControl ContentTemplate="{Binding TemplateService[UBIKChildArea_WorkPackage]}" /> </nowiki>.<br> However, since the client does not know which default template should be used, an [[Developer_Mode#Errors|error template]] will be used if the custom named one can not be found.}}
 +
 
 +
{{Hint|It's also possible to specify a Suffix for the template selector, e.g.<br><nowiki><tpl:ChildAreaTemplateSelector x:Key="ChildAreaTemplateSelector" Suffix="Small" /></nowiki>.<br>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 [[Developer_Mode#Errors|error template]] will be used.}}
 +
 
 +
= Template Selectors =
 +
 
 +
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) ===
 +
This returns a fitting template based on the given child item according to the following rules:
 +
* If the child item is classified with the [[SYSCLS_CHILDITEMTEMPLATE|child item template classification]] and carries a valid child item template name:
 +
** Returns that template.
 +
* Otherwise:
 +
** If the given item is a TaskViewModel (namely if the associated object is a [[MRO_Objects_(Client)#Task|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 [[MRO_Objects_(Client)#Task|Task]]) & the TaskItemTemplate is null, it returns a ''UBIKTaskItem'' template.
 +
** If the given MROViewModel contains ProjectData (namely if the associated object is a [[MRO_Objects_(Client)#MRO_objects_with_project_information_.28WinX_only.29|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_Objects_(Client)#MRO_objects_with_project_information_.28WinX_only.29|MRO object with project information]]) and the ProjectItemTemplate is null, it returns a ''UBIKProjectItem'' template.
 +
** 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'' template.
 +
 
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKChildItem'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 +
 
 +
 
 +
=== PropertyDirectItemTemplateSelector (UWP & Xamarin) ===
 +
This returns a fitting template based on the given property item according to the following rules:
 +
<tabs>
 +
<tab name="UWP">
 +
* Returns a non-direct edit template (namely ''UBIKPropertyDirectItemNotSupported''):
 +
** when the given PropertyViewModel is a [[Live_Values|live value]] item or
 +
** if the related property is read only or
 +
** if the object is locked or
 +
** when the property requires authentication.
 +
* Otherwise:
 +
** Returns a ''UBIKPropertyDirectItemList'' template if the MetaProperty of the given item has a [[UBIK_Client_Basics#Selective_List_Properties|SelectiveList]].
 +
** Returns a ''UBIKPropertyDirectItemMinMax'' template if the given Property is a [[Min_Max_Properties|Min Max Property]].
 +
** Returns a ''UBIKPropertyDirectItemBool'' template if the given Property is of type Bool.
 +
** Returns a ''UBIKPropertyDirectItemString'' template if the given Property is of type String.
 +
** Returns a ''UBIKPropertyDirectItemInt'' template if the given Property is of type Int.
 +
** Returns a ''UBIKPropertyDirectItemDouble'' template if the given Property is of type Double.
 +
** Returns a ''UBIKPropertyDirectItemDateTime'' template if the given Property is of type DateTime.
 +
** Returns a ''UBIKPropertyDirectItemGuid'' template if the given Property is of type Guid.
 +
** Returns a ''UBIKPropertyDirectItemGeoData'' template if the given Property is of type GeoData.
 +
** Returns a ''UBIKPropertyDirectItemNotSupported'' template if the given Property is none of the type above.
 +
</tab>
 +
<tab name="Xamarin">
 +
* Returns a non-direct edit template (namely ''UBIKPropertyItem''):
 +
** when the given PropertyViewModel is a [[Live_Values|live value]] item or
 +
** if the related property is read only or
 +
** if the object is locked or
 +
** when the property requires authentication.
 +
* Otherwise:
 +
** Returns a ''UBIKPropertyDirectItemList'' template if the MetaProperty of the given item has a [[UBIK_Client_Basics#Selective_List_Properties|SelectiveList]].
 +
** Returns a ''UBIKPropertyDirectItemMinMax'' template if the given Property is a [[Min_Max_Properties|Min Max Property]].
 +
** Returns a ''UBIKPropertyDirectItemBool'' template if the given Property is of type Bool.
 +
** Returns a ''UBIKPropertyDirectItemString'' template if the given Property is of type String.
 +
** Returns a ''UBIKPropertyDirectItemInt'' template if the given Property is of type Int.
 +
** Returns a ''UBIKPropertyDirectItemDouble'' template if the given Property is of type Double.
 +
** Returns a ''UBIKPropertyDirectItemGuid'' template if the given Property is of type Guid.
 +
** Returns a ''UBIKPropertyItem'' template if the given Property is none of the type above.
 +
</tab>
 +
</tabs>
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKPropertyItem'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 +
 
 +
 
 +
 
 +
 
 +
 
 +
=== TaskPropertyTemplateSelector (UWP & Xamarin) ===
 +
This returns a fitting template based on the given task property item according to the following rules:
 +
<tabs>
 +
<tab name="UWP">
 +
* Returns a non-direct edit template (''UBIKTaskProperty''):
 +
** when the PropertyViewModel of the given TaskViewModel (namely if the associated object is a [[MRO_Objects_(Client)#Task|Task]]) is a [[Live_Values|live value]] item or
 +
** if the related property is read only or
 +
** if the object is locked or
 +
** when the property requires authentication.
 +
* Otherwise:
 +
** Returns a ''UBIKTaskPropertyList'' template if the MetaProperty of the given item has a [[UBIK_Client_Basics#Selective_List_Properties|SelectiveList]].
 +
** Returns a ''UBIKTaskPropertyBool'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Bool.
 +
** Returns a ''UBIKTaskPropertyString'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type String.
 +
** Returns a ''UBIKTaskPropertyInt'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Int.
 +
** Returns a ''UBIKTaskPropertyDouble'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Double.
 +
** Returns a ''UBIKTaskPropertyDateTime'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type DateTime.
 +
** Returns a ''UBIKTaskPropertyGuid'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Guid.
 +
** Returns a ''UBIKTaskPropertyGeoData'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type GeoData.
 +
** Returns a ''UBIKTaskProperty'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value has none of the types above.
 +
</tab>
 +
<tab name="Xamarin">
 +
* Returns a non-direct edit template (''UBIKTaskProperty''):
 +
** when the PropertyViewModel of the given TaskViewModel (namely if the associated object is a [[MRO_Objects_(Client)#Task|Task]]) is a [[Live_Values|live value]] item or
 +
** if the related property is read only or
 +
** if the object is locked or
 +
** when the property requires authentication.
 +
* Otherwise:
 +
** Returns a ''UBIKTaskPropertyList'' template if the MetaProperty of the given item has a [[UBIK_Client_Basics#Selective_List_Properties|SelectiveList]].
 +
** Returns a ''UBIKTaskPropertyBool'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Bool.
 +
** Returns a ''UBIKTaskPropertyString'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type String.
 +
** Returns a ''UBIKTaskPropertyInt'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Int.
 +
** Returns a ''UBIKTaskPropertyDouble'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Double.
 +
** Returns a ''UBIKTaskPropertyGuid'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value is of type Guid.
 +
** Returns a ''UBIKTaskProperty'' template if the given TaskViewModels (namely the associated object is a [[MRO_Objects_(Client)#Task|Task]]) Value has none of the types above.
 +
</tab>
 +
</tabs>
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKTaskProperty'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 +
 
 +
 
 +
=== HotSpotTemplateSelector (UWP & Xamarin) ===
 +
This returns a fitting template based on the given [[HotSpotting#HotSpots|HotSpot]] item according to the following rules:
 +
* Returns a ''UBIKAngularLinkHotSpot'' template if the given [[HotSpotting#HotSpots|HotSpot]] is of type LinkHotSpot with HotSpotShape Angular & if the UBIKAngularLinkHotSpot template is not null.
 +
* Returns a ''UBIKRoundLinkHotSpot'' template if the given [[HotSpotting#HotSpots|HotSpot]] is of type LinkHotSpot with HotSpotShape Round & if the UBIKRoundLinkHotSpot template is not null.
 +
* Returns a ''UBIKSignatureHotSpot'' template if the given [[HotSpotting#HotSpots|HotSpot]] is of type [[HotSpotting#SignatureSpot|SignatureSpot]] & if the UBIKSignatureHotSpot template is not null.
 +
* Returns a ''UBIKObjectHotSpot'' template if the given [[HotSpotting#HotSpots|HotSpot]] is of type ObjectHotSpot & if the UBIKObjectHotSpot template is not null.
 +
* Returns a ''UBIKMediaHotSpot'' template if the given [[HotSpotting#HotSpots|HotSpot]] is of type [[HotSpotting#MediaSpot|MediaSpot]] & if the UBIKMediaHotSpot template is not null.
 +
* Returns a ''UBIKInputHotSpot'' template if the given [[HotSpotting#HotSpots|HotSpot]] is of type [[HotSpotting#InputSpot|InputHotSpot]] & if the UBIKInputHotSpot template is not null.
 +
* If nothing of the above fits, it returns a ''UBIKDefaultHotSpot'' template.
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKInputHotSpot'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 +
 
 +
 
 +
=== ProfileItemTemplateSelector (UWP) ===
 +
* This returns a ''UBIKProfileItem'' template if the given item is a Profile file.
 +
* If the given item is a folder, it returns a ''UBIKProfileFolder'' template.
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKProfileItem'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 +
 
 +
 
 +
=== RootItemTemplateSelector (UWP) ===
 +
This returns a fitting template based on the given root item according to the following rules:
 +
* If the root item is classified with the [[SYSCLS_CHILDITEMTEMPLATE|child item template classification]] and carries a valid root item template name:
 +
** Returns that template.
 +
* Otherwise:
 +
** If the given item is a TaskViewModel (namely if the associated object is a [[MRO_Objects_(Client)#Task|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 [[MRO_Objects_(Client)#Task|Task]]) & the TaskItemTemplate is null, it returns a ''UBIKTaskItem'' template.
 +
** If the given MROViewModel contains ProjectData (namely if the associated object is a [[MRO_Objects_(Client)#MRO_objects_with_project_information_.28WinX_only.29|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_Objects_(Client)#MRO_objects_with_project_information_.28WinX_only.29|MRO object with project information]]) and the ProjectItemTemplate is null, it returns a ''UBIKProjectItem'' template.
 +
** 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 ''UBIKMainItem'' template.
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKMainItem'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
 +
 
 +
 
 +
=== ComboBoxItemTemplateSelector (UWP) ===
 +
* This returns a ''DropDownItemTemplate'' for drop-down list items.
 +
* Otherwise, it returns a ''ComboBoxSectionItemTemplate'' (for the selected item when the drop-down list is closed).
 +
{{Hint|To get an overview of how a template (e.g. ''DropDownItemTemplate'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
  
−
==== ChildPage ====
 
−
* UBIKChildItem.xaml
 
−
[[File:ChildItemA.JPG|upright=0.35|thumb|left|alt=UBIKChildItem|UBIKChildItem.xaml]]
 
−
{{clear}}
 
−
* UBIKChildItemSmall.xaml
 
−
[[File:ChildItemSmallA.JPG|upright=0.35|thumb|left|alt=UBIKChildItemSmall|UBIKChildItemSmall.xaml]]
 
−
{{clear}}
 
−
* UBIKChildArea.xaml
 
−
[[File:ChildAreaA.JPG|upright=0.35|thumb|left|alt=UBIKChildArea|UBIKChildArea.xaml]]
 
−
{{clear}}
 
−
* UBIKChildAreaSmall.xaml
 
−
* UBIKChildAction.xaml
 
−
[[File:ChildActionA.png|upright=0.35|thumb|left|alt=UBIKChildAction|UBIKChildAction.xaml]]
 
−
{{clear}}
 
−
* UBIKPriorityPropertyItem.xaml
 
−
*UBIKChildPageAction.xaml
 
−
[[File:ChildPageActionA.JPG|upright=0.35|thumb|left|alt=UBIKChildPageAction|UBIKChildPageAction.xaml]]
 
−
{{clear}}
 
  
 +
=== ChildAreaTemplateSelector (UWP) / ChildAreaTemplateConverter (Xamarin) ===
 +
This returns a fitting template for a given context object according to the following rules:
 +
<tabs>
 +
<tab name="UWP">
 +
* If the context object is classified with the [[SYSCLS_CHILDAREATEMPLATE|ChildAreaTemplate Classification]] and carries a valid child area template name:
 +
** Tries to return a custom template with the name of CustomTemplateName + Suffix.
 +
* Otherwise:
 +
** Tries to return a custom template with the name ''UBIKChildArea'' + Suffix.
 +
</tab>
 +
<tab name="Xamarin">
 +
* If the context object is classified with the [[SYSCLS_CHILDAREATEMPLATE|ChildAreaTemplate Classification]] and carries a valid child area template name:
 +
** Tries to return a custom template with the name of CustomTemplateName.
 +
* Otherwise:
 +
** Tries to return a custom template with the name ''UBIKChildArea''.
 +
</tab>
 +
</tabs>
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKChildArea'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
  
  
−
==== DetailsPage ====
+
=== ContentAreaTemplateSelector (UWP) / ContentAreaTemplateConverter (Xamarin) ===
−
* UBIKDocumentItem.xaml
+
This returns a fitting template for a given context object according to the following rules:
−
[[File:DocumentItemA.JPG|upright=0.35|thumb|left|alt=UBIKDocumentItem|UBIKDocumentItem.xaml]]
+
<tabs>
−
{{clear}}
+
<tab name="UWP">
−
* UBIKDocumentItemSmall.xaml
+
* If the context object is classified with the [[SYSCLS_CONTENTAREATEMPLATE|ContentAreaTemplate Classification]] and carries a valid content area template name:
 +
** Tries to return a custom template with the name of CustomTemplateName + Suffix.
 +
* Otherwise:
 +
** Tries to return a custom template with the name of ''UBIKContentArea'' + Suffix.
 +
</tab>
 +
<tab name="Xamarin">
 +
* If the context object is classified with the [[SYSCLS_CONTENTAREATEMPLATE|ContentAreaTemplate Classification]] and carries a valid content area template name:
 +
** Tries to return a custom template with the name of CustomTemplateName.
 +
* Otherwise:
 +
** Tries to return a custom template with the name of ''UBIKContentArea''.
 +
</tab>
 +
</tabs>
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKContentArea'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
  
  
 +
=== PropertyEditorItemTemplateSelector (UWP) / EditTemplateConverter (Xamarin) ===
 +
This returns a fitting template for a given context property according to the following rules:
 +
<tabs>
 +
<tab name="UWP">
 +
* Returns a ''UBIKEditMinMax'' template if the given Property is a [[Min_Max_Properties|Min Max Property]].
 +
* 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.
 +
{{Hint|Even though {{UBIK}} has an editor for GeoData and FileReference types, 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 types, therefore the selector is not relevant for them.}}
  
−
===MapView===
+
</tab>
−
*UBIKCustomMapPin
+
<tab name="Xamarin">
−
[[File:CustomMapPinA.JPG|upright=0.35|thumb|left|alt=UBIKCustomMapPin|UBIKCustomMapPin.xaml]]
+
* Returns a ''UBIKEditMinMax'' template if the given Property is a [[Min_Max_Properties|Min Max Property]].
−
{{clear}}
+
* 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 a ''UBIKEditNotSupported'' template if the given Property is of type XML, ByteStream, Geography, FileReference, or Undefined.
 +
</tab>
 +
</tabs>
 +
{{Hint|To get an overview of how a template (e.g. ''UBIKEditBool'') is loaded, please refer to [[UBIK_Templates#Template_loading_mechanism|Template loading mechanism]].}}
  
 +
[[Category:Client|UBIK Templates]]
 
[[Category:UBIK|UBIK Templates]]
 
[[Category:UBIK|UBIK Templates]]
 +
[[Category:WinX|UBIK Templates]]
 +
[[Category:XAML|UBIK Templates]]

Latest revision as of 15:31, 15 May 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.

  • (Not yet available for Xamarin) 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

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)

This returns a fitting template based on the given child item according to the following rules:

  • If the child item is classified with the child item template classification and carries a valid child item template name:
    • Returns that template.
  • Otherwise:
    • 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 template.
    • 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 template.
    • 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 template.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKChildItem) is loaded, please refer to Template loading mechanism.


PropertyDirectItemTemplateSelector (UWP & Xamarin)

This returns a fitting template based on the given property item according to the following rules:

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 property requires authentication.
  • Otherwise:
    • Returns a UBIKPropertyDirectItemList template if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKPropertyDirectItemMinMax template if the given Property is a Min Max Property.
    • Returns a UBIKPropertyDirectItemBool template if the given Property is of type Bool.
    • Returns a UBIKPropertyDirectItemString template if the given Property is of type String.
    • Returns a UBIKPropertyDirectItemInt template if the given Property is of type Int.
    • Returns a UBIKPropertyDirectItemDouble template if the given Property is of type Double.
    • Returns a UBIKPropertyDirectItemDateTime template if the given Property is of type DateTime.
    • Returns a UBIKPropertyDirectItemGuid template if the given Property is of type Guid.
    • Returns a UBIKPropertyDirectItemGeoData template if the given Property is of type GeoData.
    • Returns a UBIKPropertyDirectItemNotSupported template if the given Property is none of the type above.

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 property requires authentication.
  • Otherwise:
    • Returns a UBIKPropertyDirectItemList template if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKPropertyDirectItemMinMax template if the given Property is a Min Max Property.
    • Returns a UBIKPropertyDirectItemBool template if the given Property is of type Bool.
    • Returns a UBIKPropertyDirectItemString template if the given Property is of type String.
    • Returns a UBIKPropertyDirectItemInt template if the given Property is of type Int.
    • Returns a UBIKPropertyDirectItemDouble template if the given Property is of type Double.
    • Returns a UBIKPropertyDirectItemGuid template if the given Property is of type Guid.
    • Returns a UBIKPropertyItem template if the given Property is none of the type above.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKPropertyItem) is loaded, please refer to Template loading mechanism.



TaskPropertyTemplateSelector (UWP & Xamarin)

This returns a fitting template based on the given task property item according to the following rules:

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 property requires authentication.
  • Otherwise:
    • Returns a UBIKTaskPropertyList template if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKTaskPropertyBool template if the given TaskViewModels (namely the associated object is a Task) Value is of type Bool.
    • Returns a UBIKTaskPropertyString template if the given TaskViewModels (namely the associated object is a Task) Value is of type String.
    • Returns a UBIKTaskPropertyInt template if the given TaskViewModels (namely the associated object is a Task) Value is of type Int.
    • Returns a UBIKTaskPropertyDouble template if the given TaskViewModels (namely the associated object is a Task) Value is of type Double.
    • Returns a UBIKTaskPropertyDateTime template if the given TaskViewModels (namely the associated object is a Task) Value is of type DateTime.
    • Returns a UBIKTaskPropertyGuid template if the given TaskViewModels (namely the associated object is a Task) Value is of type Guid.
    • Returns a UBIKTaskPropertyGeoData template if the given TaskViewModels (namely the associated object is a Task) Value is of type GeoData.
    • Returns a UBIKTaskProperty template if the given TaskViewModels (namely the associated object is a Task) Value has none of the types above.

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 property requires authentication.
  • Otherwise:
    • Returns a UBIKTaskPropertyList template if the MetaProperty of the given item has a SelectiveList.
    • Returns a UBIKTaskPropertyBool template if the given TaskViewModels (namely the associated object is a Task) Value is of type Bool.
    • Returns a UBIKTaskPropertyString template if the given TaskViewModels (namely the associated object is a Task) Value is of type String.
    • Returns a UBIKTaskPropertyInt template if the given TaskViewModels (namely the associated object is a Task) Value is of type Int.
    • Returns a UBIKTaskPropertyDouble template if the given TaskViewModels (namely the associated object is a Task) Value is of type Double.
    • Returns a UBIKTaskPropertyGuid template if the given TaskViewModels (namely the associated object is a Task) Value is of type Guid.
    • Returns a UBIKTaskProperty template if the given TaskViewModels (namely the associated object is a Task) Value has none of the types above.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKTaskProperty) is loaded, please refer to Template loading mechanism.


HotSpotTemplateSelector (UWP & Xamarin)

This returns a fitting template based on the given HotSpot item according to the following rules:

  • Returns a UBIKAngularLinkHotSpot template if the given HotSpot is of type LinkHotSpot with HotSpotShape Angular & if the UBIKAngularLinkHotSpot template is not null.
  • Returns a UBIKRoundLinkHotSpot template if the given HotSpot is of type LinkHotSpot with HotSpotShape Round & if the UBIKRoundLinkHotSpot template is not null.
  • Returns a UBIKSignatureHotSpot template if the given HotSpot is of type SignatureSpot & if the UBIKSignatureHotSpot template is not null.
  • Returns a UBIKObjectHotSpot template if the given HotSpot is of type ObjectHotSpot & if the UBIKObjectHotSpot template is not null.
  • Returns a UBIKMediaHotSpot template if the given HotSpot is of type MediaSpot & if the UBIKMediaHotSpot template is not null.
  • Returns a UBIKInputHotSpot template 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 template.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKInputHotSpot) is loaded, please refer to Template loading mechanism.


ProfileItemTemplateSelector (UWP)

  • This returns a UBIKProfileItem template if the given item is a Profile file.
  • If the given item is a folder, it returns a UBIKProfileFolder template.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKProfileItem) is loaded, please refer to Template loading mechanism.


RootItemTemplateSelector (UWP)

This returns a fitting template based on the given root item according to the following rules:

  • If the root item is classified with the child item template classification and carries a valid root item template name:
    • Returns that template.
  • Otherwise:
    • 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 template.
    • 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 template.
    • 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 UBIKMainItem template.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKMainItem) is loaded, please refer to Template loading mechanism.


ComboBoxItemTemplateSelector (UWP)

  • This returns a DropDownItemTemplate for drop-down list items.
  • Otherwise, it returns a ComboBoxSectionItemTemplate (for the selected item when the drop-down list is closed).
IC Hint square.pngTo get an overview of how a template (e.g. DropDownItemTemplate) is loaded, please refer to Template loading mechanism.


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.
  • Otherwise:
    • Tries to return a custom template with the name UBIKChildArea + Suffix.

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.
  • Otherwise:
    • Tries to return a custom template with the name UBIKChildArea.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKChildArea) is loaded, please refer to Template loading mechanism.


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.
  • Otherwise:
    • Tries to return a custom template with the name of UBIKContentArea + Suffix.

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.
  • Otherwise:
    • Tries to return a custom template with the name of UBIKContentArea.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKContentArea) is loaded, please refer to Template loading mechanism.


PropertyEditorItemTemplateSelector (UWP) / EditTemplateConverter (Xamarin)

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

UWP

  • Returns a UBIKEditMinMax template if the given Property is a Min Max Property.
  • 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 types, 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 types, therefore the selector is not relevant for them.

Xamarin

  • Returns a UBIKEditMinMax template if the given Property is a Min Max Property.
  • 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 a UBIKEditNotSupported template if the given Property is of type XML, ByteStream, Geography, FileReference, or Undefined.
IC Hint square.pngTo get an overview of how a template (e.g. UBIKEditBool) is loaded, please refer to Template loading mechanism.
Retrieved from "https://wiki.augmensys.com/index.php?title=UBIK_Templates&oldid=26653"