QMBForm

Create simple Android forms

Basic Usage

1. Create a "FromDescriptor" - It's the holder for the form

   FormDescriptor descriptor = FormDescriptor.newInstance();
   descriptor.setOnFormRowValueChangedListener(this); //Listen for changes
   

2. Create sections with "SectionDescriptor" and add rows - Sections can have titles and rows (Form Elements)

   SectionDescriptor sectionDescriptor = SectionDescriptor.newInstance("tag","Title");
   
   //Add rows - form elements
   sectionDescriptor.addRow( RowDescriptor.newInstance("text",RowDescriptor.FormRowDescriptorTypeText, "Text", new Value<String>("test")) );
   sectionDescriptor.addRow( RowDescriptor.newInstance("dateDialog",RowDescriptor.FormRowDescriptorTypeDate, "Date Dialog") );
   

3. To render your form, use the "FormManager" helper. You will need a ListView instance.

       FormManager formManager = new FormManager();
       formManager.setup(descriptor, mListView, getActivity());
       formManager.setOnFormRowClickListener(this);    
   

4. Attention! If you use EditText based form elements, make sure you set "windowSoftInputMode" to "adjustPan"

   Do it in your manifest:

   <activity
   		      android:windowSoftInputMode="adjustPan"/>
           
   

   Or programmatically in the onCreate method of your activity

   @Override
   protected void onCreate(Bundle savedInstanceState) {
   
       super.onCreate(savedInstanceState);
   
       getWindow().setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_PAN);
       
   }
   

5. Create elements with custom type identifier and a FormCell class. You can also submit configs to use objects in your cell

   String customType = "customRowIdentifier";
   CellViewFactory.getInstance().setRowTypeMap(customType, CustomFormCell.class);
   
   RowDescriptor customRow = RowDescriptor.newInstance("custom",customType, "title", new Value<String>("value"));
   HashMap<String, Object> cellConfig = new HashMap();
   cellConfig.put("config",configObject);
   customRow.setCellConfig(cellConfig);
   section.addRow(customRow);
   

Use annotations for models

1. You can create a form from a POJO by adding annotations to your model properties

   public class Entry {
   
       @FormElement(
               label = R.string.lb_title,
               rowDescriptorType = RowDescriptor.FormRowDescriptorTypeText,
               sortId = 1,
               section = R.string.section_general
       )
       public String title;
   
       @FormElement(
               label = R.string.lb_description,
               rowDescriptorType = RowDescriptor.FormRowDescriptorTypeTextView,
               sortId = 2,
               section = R.string.section_general
       )
       public String description;
   
       @FormElement(
               label = R.string.lb_date_dialog,
               rowDescriptorType = RowDescriptor.FormRowDescriptorTypeDate,
               sortId = 4,
               section = R.string.section_date
       )
       public Date date;
   
       @FormElement(
               label = R.string.lb_date_inline,
               rowDescriptorType = RowDescriptor.FormRowDescriptorTypeDateInline,
               tag = "customDateInlineTag",
               sortId = 3,
               section = R.string.section_date
       )
       public Date dateInline;
   
   }
   
   

2. Use "FormDescriptorAnnotationFactory" to create a FormDescriptor from your model

   FormDescriptorAnnotationFactory factory = new FormDescriptorAnnotationFactory(getActivity());
   FormDescriptor descriptor = factory.createFormDescriptorFromAnnotatedClass(entry);
   

Validation

1. Define custom validators by implementing FormValidator

   public class EmailValidator implements FormValidator {
       private static final String EMAIL_PATTERN =
               "^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]+)*@"
                       + "[A-Za-z0-9-]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$";
   
       @Override
       public RowValidationError validate(RowDescriptor descriptor) {
           Value value = descriptor.getValue();
           if (value.getValue() != null && value.getValue() instanceof String) {
               String val = (String) value.getValue();
               return (val.matches(EMAIL_PATTERN)) ? null : new RowValidationError(descriptor,  R.string.validation_invalid_email);
           }
           return new RowValidationError(descriptor, R.string.validation_invalid_email);
       }
   

} ```

2. With annotations Specify validator classes as an array of .class items

   @FormElement(
           label = R.string.email,
           rowDescriptorType = RowDescriptor.FormRowDescriptorTypeEmailInline,
           sortId = 2,
           validatorClasses = {EmailValidator.class, BlankStringValidator.class}
   )
   public String email;
   

3. Or add validators to rowdescriptors manually

   RowDescriptor rowDescriptor = RowDescriptor.newInstance("valid",
       RowDescriptor.FormRowDescriptorTypeEmail,
       "Email Test",
       new Value<String>("notavalidemail"));
   
   rowDescriptor.addValidator(new EmailValidator());
   

Installation

QMBForm is not available at the maven repository yet. But it's a gradly based android-library project.

1. Include the QMBFrom directory as a library module in your application
2. see sample application:

Add this to your build.gradle dependencies section

compile project(":lib:QMBForm")

Add this to your settings.gradle

include ':app', ':lib:QMBForm'

QMBForm has no dependencies to other third party libs (but compile 'com.android.support:appcompat-v7:19.+') is needed

Supported Form Elements

Most elements have an inline version (label on the same line as the displayed value) and a normal version (label on separate line above displayed value).

• Available elements:

    public static final String FormRowDescriptorTypeName = "name";
  
    public static final String FormRowDescriptorTypeText = "text";
    public static final String FormRowDescriptorTypeTextInline = "textInline";
    public static final String FormRowDescriptorTypeDetail = "detail";
    public static final String FormRowDescriptorTypeDetailInline = "detailInline";
    public static final String FormRowDescriptorTypeTextView = "textView";
    public static final String FormRowDescriptorTypeTextViewInline = "textViewInline";
    public static final String FormRowDescriptorTypeURL = "url";
    public static final String FormRowDescriptorTypeEmail = "email";
    public static final String FormRowDescriptorTypeEmailInline = "emailInline";
    public static final String FormRowDescriptorTypePassword = "password";
    public static final String FormRowDescriptorTypePasswordInline = "passwordInline";
    public static final String FormRowDescriptorTypeNumber = "number";
    public static final String FormRowDescriptorTypeNumberInline = "numberInline";
    public static final String FormRowDescriptorTypeCurrency = "currency";
    public static final String FormRowDescriptorTypePhone = "phone";
    
    public static final String FormRowDescriptorTypeInteger = "integer";
    public static final String FormRowDescriptorTypeIntegerInline = "integerInline";
   
    public static final String FormRowDescriptorTypeSelectorSpinner = "selectorSpinner";
    public static final String FormRowDescriptorTypeSelectorSpinnerInline = "selectorSpinnerInline";
    public static final String FormRowDescriptorTypeSelectorPickerDialog = "selectorPickerDialog";
    
    public static final String FormRowDescriptorTypeDateInline = "dateInline";
    public static final String FormRowDescriptorTypeTimeInline = "timeInline";
    public static final String FormRowDescriptorTypeDate = "date";
    public static final String FormRowDescriptorTypeTime = "time";
    
    public static final String FormRowDescriptorTypeBooleanCheck = "booleanCheck";
    public static final String FormRowDescriptorTypeBooleanSwitch = "booleanSwitch";
    
    public static final String FormRowDescriptorTypeButton = "button";
    public static final String FormRowDescriptorTypeButtonInline = "buttonInline";
  
    public static final String FormRowDescriptorTypeSelectorSegmentedControl = "selectorSegmentedControl";
    public static final String FormRowDescriptorTypeSelectorSegmentedControlInline = "selectorSegmentedControlInline";
    
  

• Coming elements: (Avaiable at XLForm)

    public static final String FormRowDescriptorTypeTwitter = "twitter";
    public static final String FormRowDescriptorTypeAccount = "account";
  
    public static final String FormRowDescriptorTypeSelectorPush = "selectorPush";
    public static final String FormRowDescriptorTypeSelectorActionSheet = "selectorActionSheet";
    public static final String FormRowDescriptorTypeSelectorAlertView = "selectorAlertView";
    public static final String FormRowDescriptorTypeSelectorPickerView = "selectorPickerView";
    public static final String FormRowDescriptorTypeSelectorPickerViewInline = "selectorPickerViewInline";
    
    public static final String FormRowDescriptorTypeMultipleSelector = "multipleSelector";
    public static final String FormRowDescriptorTypeSelectorLeftRight = "selectorLeftRight";
    
    public static final String FormRowDescriptorTypeDateTimeInline = "datetimeInline";
    public static final String FormRowDescriptorTypeDateTime = "datetime";
    
    public static final String FormRowDescriptorTypePicker = "picker";
    
    public static final String FormRowDescriptorTypeImage = "image";
    public static final String FormRowDescriptorTypeStepCounter = "stepCounter";
    
  

To do

• Simpler cell customisation
• More form elements
• Form model

Credits

QMBForm is based on the ideas of XLForm - the most flexible and powerful iOS library to create dynamic table-view forms.

Thanks guys!