Revision as of 15:11, 15 November 2019

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 and child item 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 an object defines a child area template name (see child area template classification), return the custom template with that name;
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.

It'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.

@@ 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]] and [[SYSCLS_CHILDITEMTEMPLATE|child item 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.
-[[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}}
+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>
-==== ChildPage ====
+The child area template selector used in this example determines the child area template to use based on the following rules.
-* UBIKChildItem.xaml
+* If an object defines a child area template name (see [[SYSCLS_CHILDAREATEMPLATE|child area template classification]]), return the custom template with that name;
-[[File:ChildItemA.JPG|upright=0.35|thumb|left|alt=UBIKChildItem|UBIKChildItem.xaml]]
+* {{Version/WinXSince|3.6}} 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.)
-{{clear}}
+* If not found, returns the default UBIKChildArea template.
-* 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}}
+{{Hint|It'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.}}
-==== DetailsPage ====
-* UBIKDocumentItem.xaml
-[[File:DocumentItemA.JPG|upright=0.35|thumb|left|alt=UBIKDocumentItem|UBIKDocumentItem.xaml]]
-{{clear}}
-* UBIKDocumentItemSmall.xaml
-===MapView===
-*UBIKCustomMapPin.xaml
-[[File:CustomMapPinA.JPG|upright=0.35|thumb|left|alt=UBIKCustomMapPin|UBIKCustomMapPin.xaml]]
-{{clear}}
-*UBIKMapPOI.xaml
-[[File:MapPOIA.JPG|upright=0.35|thumb|left|alt=UBIKMapPOI|UBIKMapPOI.xaml]]
-{{clear}}
-*UBIKPOIFlyout.xaml
-[[File:POIFlyoutA.JPG|upright=0.35|thumb|left|alt=UBIKPOIFlyout|UBIKPOIFlyout.xaml]]
-{{clear}}
-*UBIKUserPin.xaml
-[[File:UserPinA.JPG|upright=0.35|thumb|left|alt=UBIKUserPin|UBIKUserPin.xaml]]
-{{clear}}
-[[Category:UBIK|UBIK Templates]]
-===Global===
-*UBIKPageAction.xaml
-[[File:PageActionA.png|upright=0.35|thumb|left|alt=UBIKPageAction|UBIKPageAction.xaml]]
-{{clear}}
-*UBIKSearchResultDialogHeader.xaml
-[[File:SearchResultDIalogHeader.png|upright=0.35|thumb|left|alt=UBIKSearchResultDialogHeader|UBIKSearchResultDialogHeader.xaml]]
-{{clear}}
-*UBIKSearchResultItem.xaml
-[[File:SearchResultItem.png|upright=0.35|thumb|left|alt=UBIKSearchResultItem|UBIKSearchResultItem.xaml]]
-{{clear}}
-*UBIKTopLeft.xaml
-[[File:TopLeft.png|upright=0.35|thumb|left|alt=UBIKTopLeft|UBIKTopLeft.xaml]]
-{{clear}}
-*UbikTopCenter.xaml
-[[File:TopCenter.png|upright=0.35|thumb|left|alt=UBIKTopCenter|UBIKTopCenter.xaml]]
-{{clear}}
-*UbikTopRight.xaml
-[[File:TopRight.png|upright=0.35|thumb|left|alt=UBIKTopRight|UBIKTopRight.xaml]]
-{{clear}}
-*UBIKPropertyArea.xaml
-[[File:PropertyAreaA.JPG|upright=0.35|thumb|left|alt=UBIKPropertyArea|UBIKPorpertyArea.xaml]]
-{{clear}}
-*UBIKPropertyItem.xaml
-[[File:PropertyItemA.JPG|upright=0.35|thumb|left|alt=UBIKPropertyItem|UBIKPropertyItem.xaml]]
-{{clear}}
-*UBIKEdit.xaml
-[[File:UbikEditA.JPG|upright=0.35|thumb|left|alt=UBIKEdit|UBIKEdit.xaml]]
-{{clear}}
 [[Category:UBIK|UBIK Templates]]
+[[Category:Client|UBIK Templates]]
+[[Category:WinX|UBIK Templates]]

Difference between revisions of "UBIK Templates"