Welcome to Android Forms documentation!¶
This library makes it easy to deal with views, especially if dealing with a large amount of views.
It provide a consistent and fluent way of setting, validating, retrieving and saving values from views.
With this library you not have to change or alter you layout in anyway, but you will be able to work with multiple forms on multiple fragments via FormCollection.
The library also comes an inbuilt Data populator to use when developing. This comes in handy when you want to prepopulate you form with sample data.
For validation the Validation is used.
install¶
using Maven.
<dependency>
<groupId>com.eddmash</groupId>
<artifactId>android-form</artifactId>
<version>1.0.7</version>
<type>pom</type>
</dependency>
Using gradle
compile 'com.eddmash:android-form:1.0.7'
Usage¶
To use this library is very easy
- Create
Form
class
private class BasicForm extends Form {
public BasicForm() {
super();
}
public BasicForm(ValidatorInterface validator) {
super(validator);
}
@Override
public void save() throws FormException {
// implement the saving logic, you have access to
// getValues() returns a map of where key is the name of the field and the values
}
}
- Create form object
BasicForm form = new BasicForm();
- Add
Field
toFormInterface
// get the views from the layout
Spinner genderSpinner = (Spinner) view.findViewById(R.id.gender);
EditText fName = (EditText) view.findViewById(R.id.firstname);
EditText phone_number = (EditText) view.findViewById(R.id.phone_number);
// add views to the form
form.addField("gender", genderSpinner);
form.addField("firstname", fName);
form.addField("phone_number", fName);
// add validation check
form.addCheck(new NotEmptyCheck(gender,"Gender cannot be blank"));
form.addCheck(new NotEmptyCheck(fName,"Firstname cannot be blank"));
- Run
validation
and get thevalues
.
if(form.isValid()){
form.getValues()// returns a map of where key is the name of the field and the values
}else{
LinearLayout errorSpace = (LinearLayout) findViewById(R.id.error_base);
errorSpace.removeAllViews();// clear space first
ErrorRenderer errorRenderer = new ErrorRenderer(this, form.getValidator());
errorRenderer.render(errorSpace);
}
if(form.isValid()){
try{
form.save() // save
} catch (FormException e) {
e.printStackTrace();
}
}else{
LinearLayout errorSpace = (LinearLayout) findViewById(R.id.error_base);
errorSpace.removeAllViews();// clear space first
ErrorRenderer errorRenderer = new ErrorRenderer(this, form.getValidator());
errorRenderer.render(errorSpace);
}
Form Collection¶
This library also supports dealing with multiple forms at once.
A FormCollection
class accepts InnerForm
This makes it possible:
- for forms to depend on each other
- that is a form A cannot be validated before form B is validated.
- that is a form A cannot be saved before form B is saved.
- multiple forms get validated together.
- multiple forms get saved together.
Usage¶
To use this library is very easy
- Create
InnerForm
class
In this example, the DependOnBasicForm requires the BasicForm to have been validated on the validation stage and be saved on saving stage.
private class BasicForm extends InnerForm {
public BasicForm() {
super();
}
public BasicForm(ValidatorInterface validator) {
super(validator);
}
@Override
public String getIdentifier() {
return "basic_form_id";
}
@Override
public void save() throws FormException {
// implement the saving logic, you have access to
// getValues() returns a map of where key is the name of the field and the values
}
}
private class DependOnBasicForm extends InnerForm {
public DependOnBasicForm() {
super();
}
public DependOnBasicForm(ValidatorInterface validator) {
super(validator);
}
@Override
public void save() throws FormException {
// implement the saving logic, you have access to
// getValues() returns a map of where key is the name of the field and the values
}
@Override
public String getIdentifier() {
return "depend_on_basic_form_id";
}
@Override
public String[] requires() {
return new String[]{"basic_form_id"}; // make this form depend on the basicform
}
}
- Create
FormCollectionInterface
object
FormCollection formCollection = new FormCollection();
- Add
InnerForm
toFormCollection
.
// create instance of inner form
BasicForm basicform = new BasicForm();
DependOnBasicForm dependOnBasicForm = new DependOnBasicForm();
// add inner form to collection
formCollection.addForm(basicform);
formCollection.addForm(dependOnBasicForm);
- Run
validation
and get thevalues
.
if(formCollection.isValid()){
formCollection.getValues()// returns a map of where key is the name of the field and the values
}else{
LinearLayout errorSpace = (LinearLayout) findViewById(R.id.error_base);
errorSpace.removeAllViews();// clear space first
ErrorRenderer errorRenderer = new ErrorRenderer(this, formCollection.getValidator());
errorRenderer.render(errorSpace);
}
if(formCollection.isValid()){
try{
formCollection.save() // save
} catch (FormException e) {
e.printStackTrace();
}
}else{
LinearLayout errorSpace = (LinearLayout) findViewById(R.id.error_base);
errorSpace.removeAllViews();// clear space first
ErrorRenderer errorRenderer = new ErrorRenderer(this, formCollection.getValidator());
errorRenderer.render(errorSpace);
}
Data Population¶
When developing, especially when working with form we need to prepopulate the form with sample data to ease up our development.
The faker
is meant to take care of this for us.
Lets populate our basic form form from earlier with sample data.
form // the basicform from earlier example
// create a populator object
DummyDataPopulator populator = new DummyDataPopulator();
// format how the data should look
// this will generate data with the format a mobile number of we use here in kenya
// +254 722 472 447
populator.setFieldPopulator("phone_number", new Telephone().setFormat("(+###) ### ### ###"));
// tell populator to populate the form.
// it will use the provider we set above for the phone number instead of the default one which
// would be a random set of numbers
populator.populate(form);
// you could also populate single field on its own
populator.populate(form.getField("gender"));
The kind of data that is generated depends on the type of view and the name of the field. e.g. if a view is edittext of with inputype of number then the populator will generated numbers for that particular view.
Javadoc¶
com.eddmash.form¶
Form¶
-
public abstract class
Form
implements FormInterface¶
Methods¶
-
public void
addField
(FieldInterface field)¶
-
public FieldInterface
getField
(String fieldName)¶
-
public Map<String, FieldInterface>
getFields
()¶
-
public void
removeField
(FieldInterface field)¶
FormAwareInterface¶
-
public interface
FormAwareInterface
¶ Any class the implements this interface gets the form passed to it via the
setForm(FormInterface)
.This class come in handy when creating validation checks that need to be away of the form, especially when performing form wide validations like on the
FormInterface.validate()
method.A good examples is the
Field
which implements this interface.The following examples how this interface can be used to create form wide check.
public class BasicForm extends Form { @Override public void validate() { try { addCheck(new PasswordCheck(password1Edittext, password2Edittext, "Password should match")); } catch (FormException e) { e.printStackTrace(); } } @Override public void save() throws FormException { } }
A sample check that uses the FormAwareInterface interface
class PasswordCheck extends CheckSingle implements FormAwareInterface { private final EditText view; private final String errorMsg; private FormInterface form; public PasswordCheck(EditText view, String errorMsg) { this.view = view; this.errorMsg = errorMsg; } @Override public boolean run() { try { Map val = form.getValues(); Object pass1 = val.get("password_1"); Object pass2 = val.get("password_2"); if (pass1.equals(pass2)) { return true; } } catch (FormException e) { e.printStackTrace(); } return false; } @Override public String getErrorMsg() { return errorMsg; } @Override protected TextView getView() { return view; } @Override public void setForm(FormInterface form) { this.form = form; } }
Methods¶
-
void
setForm
(FormInterface form)¶ The form that will hold this class is passed in.
Parameters: - form –
FormException¶
FormInterface¶
-
public interface
FormInterface
¶
Methods¶
-
void
addField
(FieldInterface field)¶
-
void
disableCheck
(CheckInterface check)¶ Disable a validation check
Parameters: - check –
-
FieldInterface
getField
(String fieldName)¶
-
Map<String, FieldInterface>
getFields
()¶
-
ValidatorInterface
getValidator
()¶ The validator this form will be using to validate the inner forms.
-
Map<String, Object>
getValues
()¶ Return the values of each field on the form.
The returned values depends on the
field
some fields the values is a string whilst others its a list of string.Consult the specific
field
to get the returned value.Throws: Returns: a map, where keys a field identifier used when adding field to form and values are the fields respective values.
-
boolean
isValid
()¶ This is the entry point for form validations.
It firsts invokes the
validate()
to get the form wide validation .It the tells the validator to run the validation check.
Returns: true only if the validation checks passed.
-
void
removeField
(FieldInterface field)¶
-
void
save
()¶ This is where you should put you saving logic.
throw FormException if validation fails.
Throws:
-
void
validate
()¶ This is the right place to perform form wide validations. That is validating fields against each other, also validate against parent form fields.
At this point you have access to the getValues() of both parent form and current form you can use this values to compare against.
The recommend approach is to a create check that implements FormAwareInterface and add it to the validator.
This method is invoked before the field specific validations have been run.
com.eddmash.form.collection¶
FormCollection¶
-
public class
FormCollection
implements FormCollectionInterface¶ Use this class when you want to deal on multiple forms all at once.
Constructors¶
Methods¶
-
public void
addForm
(InnerFormInterface form)¶
-
public InnerFormInterface
getForm
(String identifier)¶
-
public void
removeForm
(InnerFormInterface form)¶
FormCollectionInterface¶
-
public interface
FormCollectionInterface
¶ Use this class when you want to deal on multiple forms all at once.
Methods¶
-
void
addForm
(InnerFormInterface form)¶ Add a form into the collection.
Parameters: - form –
Throws:
-
InnerFormInterface
getForm
(String identifier)¶ Get a form in the collection by its identifier.
Parameters: - identifier –
Throws:
-
ValidatorInterface
getValidator
()¶ The validator this collection will be using to validate the inner forms.
This is basically a parent validator which calls the individual validators bound to each of the inner forms.
-
boolean
isValid
()¶ Entry point for validation of all the innerforms on this collection.
Runs validation for each of the inner forms.
-
void
removeForm
(InnerFormInterface form)¶ REmove a from the collection.
Parameters: - form –
InnerForm¶
-
public abstract class
InnerForm
extends Form implements InnerFormInterface¶ This is basically
form
that has the capability of being used with a form collection.
Fields¶
-
protected FormCollectionInterface
form
¶
Constructors¶
Methods¶
-
public FormCollectionInterface
getParent
()¶
-
public void
setParent
(FormCollectionInterface form)¶
InnerFormInterface¶
-
public interface
InnerFormInterface
extends FormInterface¶ This is basically
form
that has the capability of being used with a form collection.This form also has the added capability of depending on another form thats in the same collection as the one it belongs to.
Methods¶
-
FormCollectionInterface
getParent
()¶ The collection form in which this form belongs to.
com.eddmash.form.faker¶
DummyDataPopulator¶
-
public class
DummyDataPopulator
implements PopulatorInterface¶ This is a minimalistic go at data faker.
This intention is to populate the FormInterface and FieldInterfaces.
Methods¶
-
public void
populate
(FormInterface form)¶
-
public void
populate
(FieldInterface field)¶
-
public void
setFieldProvider
(String name, ProviderInterface provider)¶
FakerException¶
PopulatorInterface¶
-
public interface
PopulatorInterface
¶ Its responsible for populating the
FormInterface
orFieldInterface
provided.The populator uses
providers
to populate each field presented to the populator.
Methods¶
-
void
populate
(FormInterface form)¶ Tell the populator to start the population on the specified form.
Parameters: - form –
Throws:
-
void
populate
(FieldInterface field)¶ Tell the populator to start the population on the specified field.
Parameters: - field –
Throws:
-
void
setFieldProvider
(String name, ProviderInterface provider)¶ Set the provider to use the populator a specific field.
Parameters: - name – the name of the field that will use the provider given.
- provider – the provider to use instead of the default onces.
com.eddmash.form.faker.provider¶
Company¶
Coordinates¶
Methods¶
-
public ProviderInterface
getLatitude
()¶
-
public ProviderInterface
getLongitude
()¶
DateProvider¶
Fields¶
Methods¶
-
public ProviderInterface
getTime
()¶
-
public DateProvider
setDateFormat
(String dateFormat)¶
-
public DateProvider
setTimeFormat
(String timeFormat)¶
LoremProvider¶
Methods¶
-
public ProviderInterface
getWord
()¶
-
public ProviderInterface
getWords
()¶
-
public ProviderInterface
getWords
(int noOfWords)¶
Person¶
Fields¶
Methods¶
-
public ProviderInterface
getFirstName
()¶
-
public ProviderInterface
getFirstName
(String gender)¶
-
public ProviderInterface
getFullName
()¶
-
public ProviderInterface
getFullName
(String gender)¶
-
public ProviderInterface
getLastName
()¶
-
public ProviderInterface
getLastName
(String gender)¶
Provider¶
-
public abstract class
Provider
implements ProviderInterface¶
Fields¶
-
protected PopulatorInterface
populator
¶
Methods¶
-
public PopulatorInterface
getPopulator
()¶
-
public ProviderInterface
setPopulator
(PopulatorInterface populator)¶
ProviderInterface¶
-
public interface
ProviderInterface
¶ This class is responsible for generating data.
RandomNumberProvider¶
Methods¶
-
public ProviderInterface
getDecimal
()¶
-
public RandomNumberProvider
setMax
(int min)¶
-
public RandomNumberProvider
setMin
(int max)¶
com.eddmash.form.fields¶
BaseField¶
-
public abstract class
BaseField
<V, E> implements FieldInterface<V, E>¶
CollectionField¶
-
public class
CollectionField
extends BaseField<List<View>, Object> implements CollectionFieldInterface<List<View>, Object>¶ Field that manipulates multiple individual views together.
Its important to note that the specific fields don’t loose there individuality and the values return will be values for each single view.
Setting will be attempted on each single view if its value is found in the map of values passed in.
Constructors¶
Methods¶
-
public void
addField
(FieldInterface field)¶
-
public Map<String, FieldInterface>
getFields
()¶
CollectionFieldInterface¶
-
public interface
CollectionFieldInterface
<T, E> extends FieldInterface<T, E>¶ Field that manipulates multiple views together.
Its important to note that the specific fields don’t loose there individuality and the values return will be values for each single view.
Setting will be attempted on each single view if its value is found in the map of values passed in.
Methods¶
-
void
addField
(FieldInterface field)¶ Add field to the collection.
Parameters: - field – field to be added to the collection
-
Map<String, FieldInterface>
getFields
()¶ The fields that make up the collection
Returns: map of fields. that are the in the collection field.
FieldInterface¶
-
public interface
FieldInterface
<T, E> extends FormAwareInterface¶ This provides a consitent way of dealing with the different views provided by android.
Methods¶
-
FormInterface
getForm
()¶ The form instance this field is attached to.
Returns: form
-
T
getView
()¶ The actual view object(s) we are operating on.
Note this may return a list of view objects in case of CollectionField
Throws: - FormException – in case it not possible to retrieve the view object
Returns: a view instance
-
boolean
isEditable
()¶ Is the view editable, this tells the form not to set values for the view and also tells the populator not to populate it.
Returns: true if editable, false otherwise
MultiField¶
-
public class
MultiField
extends BaseField<List<View>, Map> implements MultiFieldInterface¶ This fields deals with multi fields but they are each treated as one.
This mean the values return are for those fields that have values, the setting also happens to those fields who data is provided.
Constructors¶
Methods¶
-
public FieldInterface
getField
(String id)¶
-
public List<FieldInterface>
getFields
()¶