Action: FUNCTION

FUNCTION plays a vital role in the AVM action system. It is an entry point for defining logic. Using FUNCTION, an app writer can

  • Do data driven navigation - For example, show the login screen if last login is more than 3 days otherwise, show the home page
  • Change screen layout based on data - Show / Hide controls, change appearances. For example, if the price is negative the appearance is red, otherwise green.
  • Process data before displaying on the control.
  • Do custom validation before saving user inputs.
  • Do custom processing on the data received from server.
  • Add custom logic when the screen gets created, resumes, pauses or destroys.
  • Call functions defined in external libraries.
  • Call screens that are written in the native SDK.
  • Any functionality that is not provided in AVM and the app needs it.

FUNCTION can be triggered on any event (application state or user gesture generated).

In Android, the FUNCTION definition implements the interface CustomFunctionInterface. In iOS, the FUNCTION definition implements the protocol CustomFunctionInterface.

Attributes Value Mandatory
action_name FUNCTION Yes
event_list comma separated list of events, eg: TAP Yes
target name of the function Yes
input_parameter_list comma separated list of values to be passed to the function No
target_parameter_list comma separated list of parameters to be passed to the function No

How to add functions in the project?

FUNCTIONS are implemented in native SDK’s language. For Android, they are written in Java and for iOS they are written in Objective C. Because the native SDK’s work little bit differently, so are the steps to add them are different as well.

Android

The following steps show how to add new action FUNCTION.

  • Set the function_package_name for your functions in the yourprojectname/res/strings.xml. The property needs to reflect yourcompanyname and yourprojectname set in the AndroidManifest.xml. AndroidManifest.xml is present in the root folder of your project.

    <string name="function_package_name">com.yourcompanyname.yourprojectname.functions</string>
    
  • Add a package to <your project>/src folder.

    • Select the src folder
    • Select the menu File | New | Package
    • Add the package name com.yourcompanyname.yourprojectname.functions and click Ok
  • Add the class file to the functions package

    • Select the package
    • Select the menu File | New | Class
    • Enter a suitable class name. If your FUNCTION name is WelcomeFlow then the class name would be WelcomeFlow as well. It is case-sensitive.
    • Add the interface “CustomFunctionInterface”
    • Click Ok.
  • Copy the code below to the file. Remember to change the package name com.yourcompanyname.yourprojectname.functions and public class your function name before saving the file.

    package com.yourcompanyname.yourprojectname.functions;
    
    import android.content.Context;
    import android.os.Bundle;
    import android.view.View;
    
    import com.appemble.avm.Utilities;
    import com.appemble.avm.actions.CustomFunctionInterface;
    import com.appemble.avm.models.ActionModel;
    
    public class ``your function name`` implements CustomFunctionInterface {
    
        /**
         *
         * @param  context It represents more information about an <a href="http://developer.android.com/reference/android/content/Context.html">Activity"</a> (or screen) on which an event was received and this action is being invoked.
         * @param  view It is a UI component on which an event was received and this action got triggered. Good reading about <a href="http://developer.android.com/reference/android/view/View.html">View</a>
         * @param  parentView It is the container in which the control is created. For controls created under screen, title, CONTROL_GROUP this container is of type <a href="http://developer.android.com/reference/android/widget/RelativeLayout.html">Relative Layout</a>. A control can be part of a list item in which the container is the list box item of type CONTROL_GROUP.
         * @param  action It has the attributes defining the action itself.
         * @param  targetParameterValueList The parameter targetParameterValueList is a Bundle. It contains keys defined in the action's attribute input_parameter_list. Note: In case the target needs values with a different name of the key(s), you can define the attribute "target_parameter_list". The target_parameter_list must have the same number of field_name (comma separated) as in the input_parameter_list and MUST be in the same order.
    
         * @author your name
         * @return Object Boolean.valueOf(true) or Boolean.valueOf(false)
         */
    
        @Override
        public Object execute(Context context, View view, View parentView,
            ActionModel action, Bundle targetParameterValueList) {
    
    
            return Boolean.valueOf(true);
        }
    
    }
    
  • Now start writing the business logic inside the function execute(). If the function returns Boolean.value(false); then the cascading actions (if present) will not be executed. Happy coding!!!

Examples

Example 1

The tutorial How to add validation function shows how FUNCTION can do custom validation before saving user inputs or user gestures

Example 2

See the example Set Global Property to see how a global property can be set using a FUNCTION.

Example 3

Data driven screen navigation: In the example below, the user is directed to login screen if the last_login is more than 3 days.

public class WelcomeFlow implements CustomFunctionInterface {

//  Prerequisite - A table 'user' in the content database with column last_logged_in.
//  The column last_logged_in stores the datetime when the user last logged in. It is
//  updated every time the user makes a  successful login.
//  This action is called on the event BEFORE_ON_DESTROY of the welcome screen.
//  This action calls the action "NEXT_SCREEN" to go to the login screen or to the home screen.
//  The function returns Boolean.valueOf(true) indicating if there are cascading actions,
//  they are executed as well.
//
//  @param  context It represents more information about an <a href="http://developer.android.com/reference/android/content/Context.html">Activity"</a> (or screen) on which an event was received and this action is being invoked.
//  @param  view It is a UI component on which an event was received and this action got triggered. Good reading about <a href="http://developer.android.com/reference/android/view/View.html">View</a>
//  @param  parentView It is the container in which the control is created. For controls created under screen, title, CONTROL_GROUP this contains is of type <a href="http://developer.android.com/reference/android/widget/RelativeLayout.html">Relative Layout</a>. A control can be part of a list item in which the container is the list box item.
//  @param  action It has the attributes defining the action itself.
//  @param  targetParameterValueList The parameter targetParameterValueList is a HashMap. It contains keys defined in the action's attribute input_parameter. Note: In case the target needs values with a different name of the key(s), you can define the attribute "target_parameter". The target_parameter must have the same number of field_name (comma separated) as in the input_parameter and MUST be in the same order.
//
//  @return Object Boolean.valueOf(true)

//  @author Appemble mailto:support@appemble.com
//
    @Override
    public Object execute(Context context, View view, View parentView,
        ActionModel action, Bundle targetParameterValueList) {

         // User Input Validation

        boolean bNeedLogin = TableDao.getRowCount(action.sContentDbName, "user",
                "select count(*) from user where julianday(Date('now')) - julianday(last_logged_in) > 3") > 0;
        ActionModel nextScreen = new ActionModel(action.sSystemDbName, action.sContentDbName);
        nextScreen.setActionName("NEXT_SCREEN");
        nextScreen.sTarget = bNeedLogin ? "login" : "home";
        Action.callAction(context, view, parentView, nextScreen, targetParameterValueList);

        return Boolean.valueOf(true);
    }

}

iOS

TODO

Reference tutorial

This chapter uses source code from appemble-tutorial-validation-fn. If you have not downloaded tutorial source code, click on Download Source Code - Tutorials

Android - Right click on appemble-tutorial-validation-fn and click on Run as Android application.

iOS - Select scheme appemble-tutorial-validation-fn and iPhone x.x simulator. Click on Product -> Run.