Skip to end of metadata
Go to start of metadata

One of the most powerful features in Crosslight for iOS is the comprehensive support for building data form. Based on the form metadata defined in the shared application layer, Crosslight automatically creates a beautiful data form complete with the layout and editing controls. Crosslight for iOS includes support to all editor types defined in the Crosslight foundation – from basic editors such as text field, multiple text field, check box, date time picker to advanced editors like image picker, selection controls and range input controls.

This section explains the features and desired behaviors of the each editor type on the iOS platform. For more information about the basics of form metadata and the available editor types, see Building Rich Data Entry Form.

Introducing UIFormViewController

Creating gorgeous iOS data forms with Crosslight couldn’t be easier. With only a single line of class declaration, you can build data forms that feature pixel-perfect layout and rich editing controls. Introducing UIFormViewController, this class automatically reads the form metadata based on the provided ViewModel type specified in the generic class template.

On this page:

The following example shows the usage of UIFormViewController.

There are several properties that you can customize in UIFormViewController:

  • CancelButtonVisibility – set to Auto by default.
  • DoneButtonVisibility – set to Auto by default.
  • NoItemMessage

To make the editing work as seamless as possible, the form view controller exhibit default behaviors and performs certain tasks automatically, such as:

  • When set to Auto (default), the visibility of buttons such as cancel and done button are smartly decided based on the device kind. On iPhone, the Cancel button will not appear by default when there is Back button, while the Done button will be always visible. On iPad, when shown in pop over, both the Cancel and Done button will appear only when users made changes to the data. If the automatic behavior is not desired, you may set the CancelButtonVisiblity and DoneButtonVisibility to another value explicitly.
  • When the item is dirty – that is when users made any changes to the current item – pressing back automatically save the changes “whenever possible”. This behavior is according to the Apple design guidelines. “Whenever possible” means that the item has past validation which is raised before the saving process. If there’s validation error, the cancel command will be invoked instead. If you would like to customize this behavior, please override the SaveChangesOnViewDisappear method.
  • The Cancel button is automatically bound to the CancelCommand in the EditorViewModelBase. If not desired, you can specify another command in the Form metadata’s CancelCommand property.
  • The Done button is automatically bound to the SaveCommand in the similar way.

Crosslight iOS Form Builder Features

In general, the Crosslight Form Builder for iOS includes the following key features:

  • Versatile data editing form based on table view user interface pattern
  • Conforms to the iOS design standards and guidelines
  • Supports both plain and grouped style
  • Include pre-built layout such as left detail, right detail and row detail
  • Advanced composite section style rendered in pixel-perfect fashion, supports image and fields to be positioned side-by-side
  • Automatic rotation handling with super smooth animation when adjusting position and size during rotation. Certain editors such as date picker are automatically re-drawn according to the iOS design guidelines.
  • Thoughtfully-designed user experiences, for instance, opened picker will be re-opened after rotation – all in smooth animation
  • Includes an advanced multi-line text view featuring smoothly animated auto shrink and grow based on dynamic content size and specified min/max height
  • Includes a sophisticated image picker supporting take photo from camera, choose from existing library, image editing (move, scale and crop), as well as delete photo which binds directly to the model
  • High-performance and memory-efficient image processing allows you to obtain both full size image or thumbnail image in the ViewModel
  • Supports advanced image picker features that let you add your own custom commands and intercept the image results in the ViewModel
  • Picker control such as date picker supports light-dismissible popup with smooth animation
  • Supports runtime interactivity such as expanding/hiding and enabling/disabling certain controls based on certain conditions – all performed in smooth animation
  • Supports custom editing controls through custom XIB files or custom view builder class
  • When using custom XIB, view identifier is automatically registered based on the defined binding description. This results in true codeless way to leverage your own custom editors.


For details, see the illustrated features overview in the next page.

The following illustrations show the overview of the Crosslight Form Builder’s key features.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Keep in mind that the editors and their behaviors are not controlled in the iOS application layer. Instead, they are defined in the form metadata at the shared application layer which enable other platforms to consume the same metadata.

For more information about form metadata, see Form Builder Overview.

For more information about data validation, see Validating Data.

Customizing Editor Features Programmatically

In the previous sections, you have learnt about Crosslight Form Builder and how it enables you build beautiful, fully-functional data form in mere minutes with the form metadata attributes. The form metadata was designed for cross-platform compatibility in mind. In general, it doesn’t focus on the platform-specific features.

The best practices and most recommended guidelines to build cross-platform data form with Crosslight is to use the Form Builder to define the behaviors that work in all platforms. If platform-specific editor customization is needed, then perform additional customization only for the particular platform in its own layer.

Crosslight lets you elegantly customize the platform-specific features and behaviors for every editor generated by the Form Builder. In iOS, you can access the generated editor views from the Form property provided in the UIFormViewController., then invoke the GetProperties method to get all property definitions across all sections defined in the form definition.

The following code example shows how to access the View of the “Quantity” property definition, and then customize the background color of the content view. Note that the View conforms to IComponentView Interface, and in the case of iOS, you can safely cast it back to UITableViewCell.

The results of the example can be in the image below. Notice that the Quantity cell’s background has changed to Orange color.

Using Custom Editor

The pre-built editors that come with Crosslight are great, but sometimes you will find scenarios that require using your own custom controls, or possibly other third party iOS controls. Designed with extensibility in mind, Crosslight lets you use your own custom control in the form builder – or extend the existing editor with customized features.

The easiest way to implement your own custom editor is through the view resource. A view resource is comprised of a XIB file that represents the interface definition of the view, and a class that wraps the XIB file. The first step is specifying the custom control definition in the form metadata attribute, then create the counterpart in the iOS project. At runtime, Form Builder automatically resolve the specified custom editor and instantiate your class to be consumed in the generated form.

The following example shows how to create a custom control that shows a map and a progress bar that appear in the middle of the data form. The code below shows how to specify the custom control in the form metadata definition.

Pay attention on the CustomEditorIdentifier property in the above code. The value of the property refers to the custom view class that will be instantiated by the form builder at runtime. Consequently, the name of the class should match the value specified in the CustomEditorIdentifier property.
In the iOS project, create a class called CustomEditorView.cs and an interface definition called CustomEditorView.xib such as shown below.

 

The following image shows the custom editor view design in Xcode.


The controls in the custom view will be bound automatically in the similar way as in normal view. This enables true codeless approach to build rich presentation that is loosely coupled to the user interaction logic. In the above example, the progress bar is identified as ProgressBar1. Since the binding provider includes a definition that binds ProgressBar1 to a property in the model, the progress bar value will be synchronized according to the property value when the form is loaded.

The image below shows the results of the custom editor that contains a map and a bound progress bar. Notice that the layout, positioning and dimension are automatically taken care.

The possibility to use custom controls in the Form Builder opens up unlimited possibilities to achieve complex design and challenging scenarios – while at the same preserving the idea of cross-platform through shared form metadata and MVVM-style data binding.

Combined with the automatic data binding through view identifier, you can easily create rich design that dynamically driven based on data, which also smartly synchronize back the changed values to the model.

For more information about data binding concept in Crosslight, see Understanding Data Binding and MVVM Design Pattern.

For more information about built-in editors supported in Crosslight, see Supported Editor Types.