Chapter 6. Working With Forms Using FHC

6.1. Create a Forms Project using FHC

Overview

This tutorial will show you how to build an Forms Project using FHC. This project will consist of an Forms Client App, along with a Cloud App.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Project (View & Edit)
  • Drag & Drop Apps (View & Edit)

For more information on Permissions, see Teams & Collaborations.

6.1.1. Create a Forms project

First we must create an App Forms Project. This can be done by specifying which template to use when creating a project. This will create a project containing a Hybrid Forms App.

fhc projects create FormsProject forms_project

6.1.2. Add a form

Now that the Project containing the Forms App has been created, the next step is to associate a form with that App. We will do this by specifying the path to the form file we wish to use.

fhc forms create <form.json>

For example:

fhc forms create ~/Desktop/forms/smallForm.json

6.1.3. Associate a form with a project

Now that a form has been created on the Platform, we must now associate it with the app inside our project.

fhc forms apps update <project-id> <form-id>

For example:

fhc forms apps update 534572a3fb19a3983fd92c15 5579624572fb19ajsfig398c

Your App now has a form associated with it. Use the fhc preview command to view the current state of your form.

fhc preview <app-id>

This will load a preview of your app in the browser. You can see that the form has been successfully associated with the app, however it appears rather bare, as no theme has yet been assigned to make the form more visually appealing.

6.1.4. Create a theme

A theme is created in a similar way to that of a form. You create the theme.json file and then specify the path to that file using the fhc themes create command.

fhc themes create <theme.json>

For example:

fhc themes create ~/Desktop/themes/CustomTheme.json

6.1.5. Associate the theme with the app

Now that the theme has been added to the Platform, you must apply it to the project you created.

Note

Themes are associated with Projects, not individual Apps.

fhc themes app set <project-id> <theme-id>

For example:

fhc themes app set HQgUjokQi7jizH8T-7TD4SQQ 534578160663a687117a4bd1

At this stage you have a functioning Forms Project that contains a Client Forms App, and an Cloud App. The Client App has a form and a theme associated with it. Once again, you can preview using fhc preview <app-id>. You will notice that the form is a lot more visually appealing now that a theme has been associated with the project.

6.1.6. Add another Forms App

If you wanted to add a forms based app to a project, you would do as follows:

fhc apps create <project-id> <app-title> [<app-template-id>]

For the template-id you specify the 'appforms_client' template. This creates a Hybrid Forms App.

Note

To view all available App Templates, use the 'fhc templates apps' command.

So to add the Forms App to the project, enter the following into the terminal:

fhc apps create HQgUjokQi7jizH8T-7TD4SQQ Second_Form_App appforms_client

This has now successfully created another Form based App within your project. You can associate a form and theme with your app exactly as you did before.

6.2. Create a form using FHC

Overview

This tutorial explains how to create a form for use with an App Forms apps.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Drag & Drop Apps
  • Form (View & Edit)

For more information on Permissions, see Teams & Collaborations.

6.2.1. Create a form

Target your desired domain using fhc target.

fhc target exampleDomain.feedhenry.com

Then log in using the fhc login command.

fhc login testUser@example.com password

To list all forms on a domain, use the fhc forms command.

fhc forms

This command will list all forms that you have access to based on the Permissions assigned to the logged-in User.

6.2.2. Create a form

In order to create a form, you need to pass in a form.json object. Create a form.json object and take note of its path. The example form.json file used in this tutorial can be seen below.

{
   "description":"This is a test form",
   "name":"Test Form",
   "updatedBy":"testing-admin@example.com",
   "pageRules":[

   ],
   "fieldRules":[

   ],
   "pages":[
      {
         "name":"Page 1",
         "fields":[
            {
               "fieldOptions":{
                  "definition":{
                     "defaultValue":""
                  }
               },
               "required":false,
               "type":"text",
               "name":"Text",
               "helpText":"Text",
               "repeating":false
            },
            {
               "required":false,
               "type":"file",
               "name":"File",
               "helpText":"File",
               "repeating":false
            }
         ]
      },
      {
         "name":"Page 2",
         "fields":[
            {
               "required":false,
               "type":"text",
               "name":"Page 2 Text",
               "helpText":"Page 2 Text",
               "repeating":false
            }
         ]
      }
   ],
   "lastUpdated":"2014-01-22T16:51:53.725Z",
   "dateCreated":"2014-01-22T14:43:21.806Z",
   "pageRef":{
      "52dfd909a926eb2e3f000001":0,
      "52dff729e02b762d3f000004":1
   },
   "fieldRef":{
      "52dfd93ee02b762d3f000001":{
         "page":0,
         "field":0
      },
      "52dfd93ee02b762d3f000002":{
         "page":0,
         "field":1
      },
      "52dff729e02b762d3f000003":{
         "page":1,
         "field":0
      }
   },
   "lastUpdatedTimestamp":1390409513725,
   "appsUsingForm":123,
   "submissionsToday":1234,
   "submissionsTotal":124125
}

To create the form above using fhc, we use the fhc forms create command. The command operates as follows:

fhc forms create <form-file.json>

A JSON form object needs to be passed as a parameter for the command. The path of the file is to be specified.

fhc forms create ~/Desktop/forms/form.js

This will recreate the given form on the Platform. After the form has been created, use the fhc forms get command to display the form. Then copy and paste the code into your desired directory in case you want to edit the form in future. Alternatively, you could print the result of the fhc forms get command to file by issuing the following command:

fhc forms get <app-id> > ~/Desktop/formFile.txt

6.2.3. Update form

At some stage during development, you may want to update a form. To do this, edit whatever content you like in the file where you saved your form earlier. For example, you may wish to add another text field, or apply a rule to a page. You can then use the fhc forms update command to update an existing form.

fhc forms update <path_to_form>

For example:

fhc forms update ~/Desktop/formFiles/form
Note

If you pass in the path to the form file you used to create the form initially, the update command will actually duplicate the form, as that file has no id assigned to it. This means that instead of updating the form, a new instance will be created, and a new id will be assigned.

The new changes will now have taken effect.

To learn how to associate a form with a project, see the Associate a form with a project section of the Create an App Forms project tutorial.

6.3. Create a Form submission using FHC

Overview

This tutorial will inform you of how to list, retrieve, and generate form submissions.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Drag & Drop Apps
  • Form (View & Edit) — Submission (View & Edit)

For more information on Permissions, see Teams & Collaborations.

In order to complete this tutorial, you will have to already have created a form. See Form Creatation for a guide to creating a new form.

6.3.1. Listing submissions

In order to list submissions for a form, you can use either the fhc submissions or the fhc submissions list command.

fhc submissions list

This will return a list of all submissions for all forms you have access to.

6.3.2. Return a specific submission

The fhc submissions get command can be used to return a specific submission based on its id.

fhc submissions get <submission-id>

This will return that specific submission. You can also save the submission in .pdf form simply by appending a filename with the .pdf suffix.

fhc submissions get <submission-id> <filename>.pdf

For example:

fhc submissions get 534cf14de078a2c47291e5b3 savedSubmission.pdf

6.3.3. Submission status

You can check the status of a submission by using the fhc submissions status command in conjunction with a specific submission id.

fhc submissions status 5335bc00d4598fdb5cae04f7

6.3.4. Submitting a Submission

You can submit data for a submission by passing a submission.json file into the fhc submissions submitdata command.

fhc submissons submitdata <submission.json>

For example:

fhc submissions submitdata ~/Desktop/templateForSubmission.json

You can complete a submission by using the fhc submissions complete <submission-id> command to push mark the submission as finished.

fhc complete submissions complete 5335bc00d4598fdb5cae04f7

Just as you can save submissions as PDF’s, you can also save submissions as zip files. This can be useful if a particular project has a number of submissions.

fhc submissions export file=<zip-file> app=<project-id> || form=<form-id>

Note

The project parameter is passed into the app field app=<project-id>.

fhc submissions export file=submissions.zip app=H_DNbFNJWS9uZIt7LJOkut20

6.4. Create a form theme using FHC

Overview

This tutorial will teach you how to create a theme for a form using FHC.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Domain — Drag & Drop Apps
  • Theme (View & Edit)

For more information on Permissions, see Teams & Collaborations.

6.4.1. List all themes

Target your domain using the fhc target command, and log in using fhc login.

To list all themes on a domain, you can use the fhc themes command.

6.4.2. Create a theme

To create a theme, you must use the fhc themes create command. This command requires you to pass a json file as a paramter.

fhc themes create <theme-file.json>

For example:

fhc themes create ~/Desktop/themes/theme.json

This will create the specified theme on the Platform. It will also assign an id to the theme.

When the theme is successfully created, it will be output to the console.

Save the output to a file and take note of its path. This will be used to update a theme. To save the output to file

6.4.3. Associating a theme with an app

To add a theme to an app, you must first have first associated an app with a project. If you do not yet know how to add an app to a project, you can learn how to do so here.

Themes are associated with apps using the fhc themes app set command.

fhc themes app set <app-id> <theme-id>

For example:

fhc themes app set x5KmSy0gXPZOvpD_hHqCOwZe zRdUezAD3l11huedCk-WJswZ

6.4.4. Updating a theme

If you want to update a theme at any stage, you can do so via the fhc themes update command. Navigate to where you saved the theme after you created it. Make whatever changes you wish, and then save the file. You can now update the theme.

fhc themes update ~/Desktop/themes/theme.json

This will load in the changes you have made. The newly updated theme will once again be output to the console.