Formworks

Formworks is an Open-Source framework licensed under the MIT license developed with intention of facilitating the creation of forms on iOS application. Inspired by Server-driven UI, Formworks works by taking in JSONs describing all the components and characteristics of a form.

Formworks aims to be the simplest way to build usable forms.

1. Requirements
2. Installation
   • Installing using Xcode
   • Installing using Package.swift
3. Usage
   • Creating a Form
   • Receiving data from a Form
4. Form Input Format
   • JSON Input Example
   • Parameters
   • Output
5. Components
   • Parameters
6. Documentation
7. Contribuiting
8. Authors

Requirements

• Swift 5.0 or later
• iOS 13.0 or later
• Xcode 10.0 or later

Installation

Importing using Xcode

1. In a Xcode project, click on "File"
2. Click on "Swift Packages" and select "Add Package Dependency"
3. Paste the web url for this repository: https://github.com/MyFormworks/Formworks.git
4. Set Rules to Branch on "master"

After this, you can fetch the latest changes to the framework by selecting "Update to Latest Package Versions" in step 2.

Importing using Package.swift

If you don't already have a Package.swift file, create one and add the following .package URL.

import PackageDescription

let package = Package(
    ...
    dependencies: [
        .package(url: "https://github.com/myformworks/Formworks.git", "1.0.0")
    ],
    ...
)

Getting started

Import Formworks to your Project

import Formworks

Create a Form

let dataFromJSON: Data = // Fetch your JSON data.
let formConfiguration = FWConfiguration(json: dataFromJSON, style: .light)

let formViewController = FWFormViewController(configuration: formConfiguration)
// Present as desired

Receive data from a Form

To get the data from a Form, it is necessary to implement the procotol FWFormViewControllerDelegate. A form outputs a FWFormSnapshot.

extension ExampleClass: FWFormViewControllerDelegate {
  func didSubmit(_ answers: FWFormSnapshot) {
    // Handle answers
  }
}

Form Input Format

JSON Input Example

{
  "id": "87986E91-247F-4F36-A577-19DF6BD165D0",
  "responseFormat": "long",
  "title": "Formworks Title",
  "style": {
    "accent": "#F0F0F0FF",
    "background": "#CACACAFF",
    "componentBackground": "#F0F0F0FF",
    "componentTitle": "#212121FF",
    "componentDescription": "#212121FF",
    "componentInputText": "#212121FF",
    "componentInputBackground": "#FDFDFDFF",
    "componentRequired": "#FD5C5CFF",
    "componentCorrect": "#78C256FF"
  },
  "components": [{
    "text": {
      "id": "87986E91-247F-4F36-A577-19DF6BD165D0",
      "title": "What is your name?",
      "description": "Type your name.",
      "required": true,
      "placeholder": "Your name"
      }
    },
    {
    "email": {
      "id": "87986E91-247F-4F36-A577-19DF6BD165D0",
      "title": "What is your e-mail?",
      "description": "Type your e-mail.",
      "required": true,
      "placeholder": "youremail@example.org"
      }
    },
    {
    "text": {
      "id": "87986E91-247F-4F36-A577-19DF6BD165D0",
      "title": "Tell us a little bit about yourself",
      "description": "We want to know more about you."
      }
    },
    {
    "text": {
        "title": "What is your mother's name?"
      }
    }
  ]
}

Parameters

Parameter	Type	Description	Required	Default Value
id	String	Unique ID	Yes	-
responseFormat	String	Response format for the form's output. Can either be long or short	Yes	-
title	String	Form's title. It will be presented in the top of the form.	Yes	-
style	FWStyle	A form's visual style. Style provided in the JSON has priority over in-code selection.	Yes	-
components	[FWComponentModel]	An array that contains all the components that will be presented in the form.	Yes	-

Output

A form's output is a FWFormSnapshot, more information in the documentation.

Components

A form is composed of a series of components. In the JSON, the component's key determines what kind of component is being created. When a component has no default validation, a regex can be set in the JSON. If no regex rule is given and the componet is not required, any input is valid, even an empty string. If there is no regex but the component is required, the input is accepted if it is not empty.

Key	Description
text	Single line text inputs. No default validation.
multiline	Long text inputs with multiple lines. No default validation.
email	Text component for e-mail.
numerical	Text component for numerical.
phonenumber	Text component for phone numbers (Brazillian format).

Parameters

Parameter	Type	Description	Required	Default Value
id	String	Unique ID	No	Locally generated UUID as a String
title	String	Component's title.	Yes	-
description	String	Component's description.	No	""
required	Bool	Specifies if the field has to be filled or not.	No	false
regex	String	A regex validation rule. Exclusive to text and multiline	No	""

The default regex for each component can be found in the FWRegex enum in our documentation.

Documentation

Our documentation is hosted on GitHub Pages.

Formworks uses Jazzy to generate documentation based on our in-code comments/documentation.

Whenever new code is added to the master a GitHub Action generates the documentation using Jazzy and deploys it to GitHub Pages.

A sample project is provided as an example on how to use Formworks.

Contribuiting

Please see CONTRIBUTING.md.

Authors

This project was created by

Artur Carneiro

Cassia Barbosa

Edgar Sgroi

Rafael Galdino

Victor Falcetta