Quick Start Guide
This is a brief introduction to using the ShinobiForms component. This quick start guide will walk you through a series of simple steps introducing the key features of the library; forms, sections, fields, and validation.
At the end of this guide you will have created the following form:
ShinobiForms ships with an installer to make it easier to get started. To run the installer, open the zipped file which you downloaded from ShinobiControls and run ‘install.pkg’. When it opens up, it should look as below.
The easiest way to install the ShinobiForms framework is to run the ‘install.pkg’ file. This will install the framework into Xcode for you, along with the framework documentation. This means you can add the framework to your project in the same way as you would any of the frameworks which are shipped with Xcode.
If you don’t want to run the installer, the framework is also contained within the ShinobiForms folder in the disk image. Regardless of whether you ran the installer, you should copy this folder onto your machine to save the samples and documentation. Drag the ShinobiForms folder onto the Desktop icon in the disk image. This will copy the folder onto your desktop.
The ‘ShinobiForms’ folder contains:
- A copy of the framework.
- A copy of the documentation for the framework.
- A set of samples to demonstrate getting started with ShinobiForms.
- An uninstall script for uninstalling the ShinobiForms framework & documentation from Xcode.
- A README file with setup steps.
- A change log stating the changes made in each release.
- A copy of the ShinobiForms Standard License.
- A text file containing the version number of the framework.
Creating a Simple Form
Start up Xcode and create a new project via File / New / Single View Application
Within your newly created project add a reference to the ShinobiForms framework. If you’ve installed ShinobiForms using our installer, you can add this in the same way as you would any of the standard Apple frameworks. Select your project target, and switch to the Build Phases tab. Open the Link Binary With Libraries section, click the Plus button, find the entry for ShinobiForms.framework, and click Add.
If you have just copied the framework onto your machine, the easiest way to add it to your project is to locate the ShinobiForms.framework and drag it directly into your project.
ShinobiForms makes use of a few other frameworks, so add the following as well:
- Security.framework (Trial Version only)
You can follow along with GettingStarted.xcodeproj in the Samples/ folder of your framework download. The first step is getting your view controller ready to be able to access the ShinobiForm classes. Open up the ViewController.m file and add the following import statement.
Further down the same file add a class extension and a property for the form.
@interface ViewController () @property (nonatomic, strong) ShinobiForm *form; @end
If you’ve downloaded a trial version of ShinobiForms you will have been issued with a trial license key. Add the key that was supplied to your
viewDidLoad method like so.
//Trial users: Add your license key here! //[ShinobiForms setLicenseKey:@""];
You’re now ready to start building your forms model. Now we’re going to create some field models with titles.
// Create some field models. SFormTextField *name = [[SFormTextField alloc] initWithTitle:@"Name"]; SFormDateField *birthDate = [[SFormDateField alloc] initWithTitle:@"Birth Date"]; SFormPickerField *pickerField = [[SFormPickerField alloc] initWithTitle:@"Picker"];
You’ll need to do some further set up for some field types. Let’s add some choices to the picker field.
pickerField.options = @[@[@"A", @"B", @"C"]];
Now we’ve created our fields, we need to create a section model to put them in.
// Create a section model. SFormSection *section = [[SFormSection alloc] initWithFields:@[name, birthDate, pickerField]]; section.title = @"My Form";
The next step is to create a form model to add the sections to.
// Create the form model. self.form = [ShinobiForm new]; self.form.sections = @[section];
Now we’ve got our model set up, we need to generate our view. You could do this yourself, but the easiest way is to use one of our view builders. Since we’re building the form, let’s use our form view builder.
// Build the views. SFormView *formView = [[SFormFormViewBuilder new] buildViewFromModel:self.form];
At this point we’ve now got our form view, section view, and field views. These have been automatically generated and sized for us. All you need to do now is position the form and add it to your view hierarchy!
formView.center = self.view.center; [self.view addSubview:formView];
If you run the sample application you should now see something like the image shown at the beginning of this quick start guide. As your users interact with your field views, your model objects will be updated to contain those values. If you modify your model object, your views will be updated to represent them – the model stays in sync with your views! (Note that the model will not update to programatic modification of your views.)
You’ve now learned how to set up a simple ShinobiForm, congratulations! If you got stuck at all, take a look at the corresponding sample – GettingStarted.xcodeproj.