Did you know Geocortex Workflow allows you to create custom forms you can present to an end user?
Implementing a custom component in Geocortex Mobile gives you the highest degree of flexibility with what you can do. Components can display custom, dynamic UI, register operation implementations, store persistent data, and more. They are also one of the most complex ways of customizing your mobile app, so it might be worthwhile to review simpler options like Commands and Operations or Workflow first.
Geocortex Mobile uses Autofac to register, locate, and inject components, services and other classes.
Each component class is registered with the
Component assembly attribute
It's convention for the name of the component in the
layout to be lower case and kebab case, i.e.
Once a component has been registered, it can be used in a layout by referring it by name and namespace.
Geocortex Mobile is built on top of the Xamarin Platform. In general, XAML Views are used to define reactive component UI. Component Views in Geocortex Mobile are built with the Model-View-ViewModel (MVVM) pattern. The model for components is usually either app config or a service hosting shared application data.
Each instance of a component class directly correlates to a component in the layout. A component class extends
ComponentBase and renders visual elements. As seen in the example below, components can provide their UI inline, but it is recommended that components render an associated XAML view instead.
Components are instantiated by dependency injection when the layout is rendered. This means that a component can also list dependencies that have been registered with autofac, such as the
ILayoutModel<MapView> in its constructor, and have them be passed at runtime. This also means that if a class associated with a component has application dependencies, such as a reference to the
MapOperations for map interactions, then the component will either need to provide that dependency somehow.
The preferred way to provide sub-dependencies to classes associated with components is to instantiate those associated classes with dependency injection also. Check out managing sub-dependencies for an example.
XAML views and their respective "code-behind" are responsible for the presentation concerns of a component. Check out a complete example in the SDK samples.
Component view models are responsible for populating properties with data for the view to bind to. The data for the view model is usually provided by the component class, which can consume app config or other data from the application through dependency injection. View models can use commands and operations to interact with application services and other components.
Check out this example of a component with a view model.
Every component is bound to specific item type, and each item type is bound to a class registered as an
AppItem with autofac. This class instantiates itself with values from the app config in its constructor, acting as a configuration model. The component class then consumes this configuration model, and then passes the appropriate values to the view and view model.
- App Item Model
- App Config
Most components support the
config attribute in the layout, which links a component to configuration in the app config JSON. However, many configuration models have default values they can supply for initialization instead of relying on a value to exist in the config. Any
AppItem class can provide default values through the
CreateDefault method. This method should return an instance of the
AppItem which represents the default values.
This pattern is what allows you to place a map with no config in the layout and have it render a default map.
Components have an initialization method, which can be used to perform asynchronous startup logic, and a teardown method, which can be used to free resources when a component is removed from the layout.
base.Dispose(disposing) when overriding the
ComponentBase already implements
IDisposableTracker, so only override the
Dispose method if you have created new managed resources which need to be cleaned up.
When a Geocortex Mobile Application boots up, the set of components which are in the layout are created. Next, any components that are initially active, depending on the layout, will be activated and initialized. Components like the
Panel will only activate their first child.
Custom code can listen and react to a components activation or deactivation by subscribing to the
ui.deactivated event. The
ui.* events contain various events relating to the component lifecycle.
UIOperations class contains implements the commands
ui.deactivate which can be used to examine and manipulate the activation state of components.
Check out the relevant Geocortex Mobile SDK Samples:
Learn how to use Commands and Operations with Components
Learn how to run and implement commands and operations with custom components
Learn about Component Interactions
Learn about how components and services can interact with each other
Create a Component with a Complex UI
Follow along with a more in depth component example
Create a Component that Consumes App Config
Learn more about writing components that consume configuration values.