Creating a driver pickup form
To demonstrate Crosslight Form Builder capabilities, we will create a simple taxi order form, which consists of two sections: Passenger Details and Taxi Choice. In Passenger Details, we’ll have two form fields: Name and Pickup Time whereas in Taxi Choice we’ll have Car Type and Airport choices. In overall, our form structure looks like this:
- Passenger Details
- Pickup Time
- Taxi Choice
- Car Type
Readying the project
Start off from the Blank project created using Crosslight Project Wizard and name this project as CrosslightFormBuilder.
Creating the form metadata
You need to create 2 sections, with 2 property each based on our from metadata. Create a new model file that will contain our model as well as the form metadata, named it Order.cs and place it under CrosslightFormBuilder.Core/Models folder.
The Order model derives from ModelBase that is shipped by default in project creation using Crosslight Project Wizard. This class contains the necessary implementations that automatically implements INotifyPropertyChanged, INotifyDataErrorInfo, as well as IDataValidation needed for binding and validation purposes.
All you need is to provide the necessary properties, as shown in the code above and don’t forget to trigger the OnPropertyChanged method in the property setter to reflect data changes to the UI. This is the standard MVVM-enabled property that is required for data binding to work properly.
Now create the form metadata definition. Still in the same file, first we need to create the sections. Simply prepare two classes that will act as the sections, we will name the sections as PassengerDetailsSection and TaxiChoiceSection.
It is recommended that fields definitions have the same name as your property to be able to perform binding automatically. There are many attributes that you can choose from to decorate each field. You can easily customize the appearance, layout, behavior, editor to use, interactivity, binding, and more. If you would like to explore them all, check out these articles:
Also, if you notice, we have defined an enum for the car type. Form Builder automatically supports the use of enums in the form, so you don’t have to create the picker for it. Simply define the editor as AutoDetect and it will create the appropriate editor automatically.
The CarType enum is defined inside the CrosslightFormBuilder.Core/Models folder and is simply defined as follows.
Now that you have both sections ready, simply create the form by using the following code, name it OrderFormMetadata.
The OrderFormMetadata class also contains the fields with the section class types we’ve previously defined. You can adjust the section header by decorating the fields with the SectionAttribute and fill out the Header property. You can also set the title of the form with any caption you like.
Creating the ViewModel
Create a new OrderViewModel class file inside the CrosslightFormBuilder.Core/ViewModels folder. The codes are as follows.
When using the Crosslight Form Builder, it’s highly recommended to use built-in EditorViewModelBase<TModel> as this ViewModel holds important data operations that can be done automatically at the background, such as performing save and validation.
In the ViewModel, override the FormMetadataType property. This will tell the Form Builder which class holds the FormAttribute that will act as the form.
In the next section, we’ve also overridden the ExecuteSave method. Inside the method, you’ll see that we’ve called the Validate method. This will validate the form with the conditions we’ve specified as our form validation. We’ll discuss the form validation in the next section. Next, if the form has no errors, then we can proceed with our business logic.
In this case, we are going to display the inputted data and display them using Crosslight Message Presenter. So when the Done button is pressed, the ExecuteSave method will be called.
Last but not least, we’ve also instantiated our Order model as new item for the Form Builder.
Enabling form validation
To enable form validation, there are several things to be done. First, open up the model file. In our Order model, override the Validate method.
Here, we set the error when the user did not enter their name in the form. The ClearAllErrors method should be called to reset the validation state. If any of the validation hits the condition, then SetError will be called, which in turn be displayed using Message Presenter that we’ve defined previously in ExecuteSave method.
Creating the Views
Right click on the ViewController folder in CrosslightFormBuilder.iOS project and choose Add, New File.
In the dialog that appears, choose Crosslight and select Crosslight iOS Form View Controller. Give it a name of OrderViewController .
In the newly created OrderViewController.cs file, simply specify the TViewModel as OrderViewModel that you've just created and remove this line.
The ImportBindingAttribute is used only when you want to add additional bindings to the form, which we're not going to use in this scenario.
In addition, the DetermineNavigationMode overload method and the preferred content size can be completely removed since our app is not targeting iPad.
Here's the final content of the OrderViewController.cs.
As seen above, it's really only a simple class definition remaining since all the heavy lifting is done by the UIFormViewController class itself.
You've finished the iOS views. Let's move on to Android.
Begin by right clicking on the Activities folder in the CrosslightFormBuilder.Android project. Select Add, New File.
In the preceding dialog, select Crosslight, then Crosslight Android Form Activity, give it a name of OrderActivity.
Similar to iOS, remove this line
And set the TViewModel to OrderViewModel. Since we'll not be using any binding providers for now. If you notice in the OrderActivity.cs file we have just created, we have these codes.
This means we need to provide the action bar options to be used with the Activity. This defines the actions that resides in the Action Bar of Android Activity, usually located on the top right hand corner of the screen. In this case, we want to set it as the Save button. To do that, right-click on the Resource/layout folder in the CrosslightFormBuilder.Android project. Click Add, New File .
From the dialog, select Android, Layout . Give it a name of actionbareditinglayout.
Use the following code.
On the 5th line, you'll see @string/Save. This corresponds to the key of the string value that's located inside the strings.xml file. You can find this file inside the Resources/values folder. Simply add this line as a child of the resources node.
Back to the OrderActivity.cs, we can now use the new layout that we've created as MenuLayoutId so that it'll appear on the ActionBar. Change it to
You're done with the views.
Setting the Root ViewModel
The last thing to do is tell the app which ViewModel to use as the root ViewModel. To do this, open up AppService.cs located inside CrosslightFormBuilder.Core/Infrastructure folder. In the OnStart method, change the root ViewModel to OrderViewModel.
You're now ready to run the project. Here's how it looks like when the user hit the Done button and no Name is entered.
Learning more about Form Builder