Procedure for migrating to faster forms

The OpenSRP client uses a light weight version of enketo core to render forms (https://github.com/OpenSRP/enketo-opensrp), the bundle constitutes enketo core and ziggy (https://github.com/OpenSRP/ziggy) enketo core is in charge of xform rendering while ziggy does data binding and database level operations.

Since initial release OpenSRP uses enketo core as the engine to render xls authored forms this has worked well over year however there has been some performance related concerns hence the need to develop a faster form technology. The new form technology still uses enketo core to render the xforms since its crucial to still maintain xls form authoring, however unlike the previous approach the new approach uses static template of enketo core library. The library is loaded to android assets folder and accessed whenever loading the forms at runtime. The save logic is also moved outside the form such that the xml submission obtained from the form is first converted into a form submission then handed over to ziggy which in turn inserts the items to the respective tables based on the declared bind type.

The procedure for rendering the form reads the static html together with its javascript and css resources from the assets folder then injects the model and form string. e.g if we are rendering form1 then form1 model and form tag is injected to static template.

If you have already have an OpenSRP client implementation and you want to migrate to the new form technology the procedure for doing do is as follows:

SecuredActivity.java

public abstract class SecuredActivity extends ActionBarActivity {
	// class specific code here
}

The associated activity syle is also changed to be descendant of AppCompact theme e.g on the android manifest make the following changes:

AndroidManifest.xml

<activity
            android:name=".view.activity.NativeECSmartRegisterActivity"
            android:screenOrientation="landscape"
            android:theme="@style/AppThemeNoTitle" />

Where style/AppThemeNoTitle is defined under styles.xml file as:

styles.xml

<style name="AppThemeNoTitle" parent="Theme.AppCompat.Light.DarkActionBar">
        <!-- Customize your theme here. -->
        <item name="android:windowNoTitle">true</item>
        <item name="android:windowActionBar">false</item>
        <item name="android:windowFullscreen">false</item> <!-- this is useful to prevent the keyboard from covering up the input fields -->
        <item name="android:windowContentOverlay">@null</item>
</style>

The logic that is contained in the initial activity that loads the form is then moved to a fragment, the base fragment, the fragment should be as self sufficient as possible i.e only the functions that are handled better by activity rather than fragment are left, the rest are moved to the fragment.

see org.ei.opensrp.mcare.fragment.HouseHoldSmartRegisterFragment; most of the the code moved over from the initial activity i.e org.ei.opensrp.mcare.household.HouseHoldSmartRegisterActivity.

The other modification required by the activity goes to manifest file i.e since we are switching the activity orientation during runtime depending on the fragment on display, we need to prevent the activity from starting a fresh each time (would otherwise cause an exception)

AndroidManifest.xml

<activity
            android:name=".household.HouseHoldSmartRegisterActivity"
            android:configChanges="keyboardHidden|orientation|screenSize"
            android:theme="@style/AppThemeNoActionBarAndTitle" />

The default form launch functionality is also overridden such that we show the FormFragment instead of launching a new activity whenever a form is requested, the new form launch functionality accepts three parameters:

formName - the name of the form we want to launch
entityId - the id of the record we want to load to the form e.g if we are editing
meta data (fields overrides) - data structure that holds the fields we would like to override

xRegisterActivity.java

	@Override
    public void startFormActivity(String formName, String entityId, String metaData) {
        if (entityId != null){
            String data = FormUtils.getInstance(getApplicationContext()).generateXMLInputForFormWithEntityId(entityId, formName, null);
            DisplayFormFragment displayFormFragment = getDisplayFormFragment();
            if (displayFormFragment != null) {
                displayFormFragment.setFormData(data);
                displayFormFragment.loadFormData();
                displayFormFragment.setRecordId(entityId);
            }
        }

        mPager.setCurrentItem(1, false); //Don't animate the view on orientation change the view disapears
    }