Drag and Drop Apps Guide

Red Hat Mobile Application Platform Hosted 4

For Red Hat Mobile Application Platform Hosted 4

Red Hat Customer Content Services

Abstract

This document provides tutorials for creating and managing Forms-based apps in Red Hat Mobile Application Platform Hosted 4.

Chapter 1. Getting Started: Drag & Drop Apps

1.1. Overview

The Red Hat Mobile Application Platform Hosted (RHMAP) Studio provides you with all the tools you need to quickly create mobile apps for capturing data submissions using a powerful drag and drop UI. Throughout this guide, these apps will be referred to as "Drag & Drop Apps".

This Quickstart walks you through the steps from creating a simple form through building an app and finally viewing the data submitted by that form from a mobile device.

The summary steps are:

  • Create a form, including rules
  • Create a group of users who can work with that form in the Studio
  • Define who will be notified of data submissions
  • Create a theme for your Forms
  • Create an app for the form
  • Generate and install a binary of that app on your phone
  • Submit data from the app
  • View and print those submissions

1.2. Create a form

Forms are used to capture data from the end users of your solution. To create a new form:

  1. Click on the Forms Builder menu.
  2. Click New Form.
  3. Choose a template to bootstrap your development, or simply select the Blank Form template to create your own from scratch.
  4. The Form dashboard is displayed on the screen once the Form is created. Click Edit Form.
  5. Add a text field to the form by clicking the Text field.

    An untitled text field will be added to the form.

    Note

    Clicking a field will add it to the end of a form. Dragging allows you to position a field anywhere in the form.

  6. Click on the newly added field.

    A new menu will appear at the right hand side of the page. This menu allows us to further configure the selected field.

  7. Rename the textfield 'name', and ensure that the 'Required' check box is ticked.

    Having this box checked means that a user can not submit the form unless they have entered a value for this field.

    A preview of what the form looks like can be seen by clicking the Preview tab, located at the right hand side of the page. Here you can get a preview of what the current form looks like on a device.

    Forms can easily be created with multiple pages and fields can have specific validation rules associated to them.

    Advanced fields such as photo capture and signature capture are just as easy to use as simple fields and can also be repeated in a form as many times as you wish.

  8. Click Save. This will save the form in its current state and cause the browser to return to the Forms Screen.

Read More

1.3. Create rules

The powerful Rules section of a form enables you to create both field and page based rules. Field rules let you enable or disable the display of certain fields based on the contents of other fields. Page rules let you enable or disable the display of certain pages based on the contents of specific fields. In both cases, multiple rules and criteria can be created.

Read More

1.4. Define who will be notified of data submissions

E-mail notifications can be set on a per-form basis. Different users or sets of users can be notified of each new submission with the content of that submission attached as a PDF.

1.5. Create a Theme for your Forms

Themes are used to control the look and feel of your Drag and Drop App. You can just use the default theme if you wish to get started quickly. It’s unlikely that you’ll create many themes for your apps but at a minimum, you may just wish to set your logo.

  1. Go to Drag & Drop Apps > Forms Themes > New Theme
  2. Select a template
  3. Give your theme a name and a description
  4. Click Create Theme and you’ll be brought to the Edit Theme page
  5. Select your form in the preview window if it’s not already selected
  6. Make any changes you wish to colours, fonts, spacing or the main logo
  7. When you are finished making changes, click Save

Read More

1.6. Create an App for the Form

Whilst projects in the Studio can contain multiple apps, Forms projects generally only contain one. In order to create an app with your form, you must first create a project.

  1. Navigate to the Forms Projects sub-section of the Drag & Drop Apps area.
    You will see a list of the Apps that you have sufficient privileges to see.
  2. Click New Forms Project.
  3. Click Create New Project.
    You will be prompted to enter a name for the project.
  4. Click Next.
    This will cause Studio to start generating all the necessary code for your app. When the project has successfully been created, you will be prompted to pick a theme and pick the form(s) that should be included in the App. You can now choose the theme and form you created above.

    Note

    Multiple forms can be associated with a Project.

  5. Click Finish.

Read More

1.7. Generate and install a binary of the App on your phone

Building an application enables you to install it on a mobile device.

  1. In the specific Forms project area for your app, scroll down and click the Build this App button.
  2. In the resulting Build a Binary screen, pick your target mobile platform (for example, Android), pick Debug build type, and pick a Cloud App Connection.
    If you are building an Android Debug app, you don’t need any credentials. If you are building a Production Android App or any type of iOS App, you will be prompted to upload the various credentials needed.
  3. Click Build.

Once the App has been built you will be presented with a QR code, a short link and a download link.

1.8. Submit data from the app

Install the app on the device using the QR code or short-URL. Run the app and then start creating submissions in the forms that you included in your App.

1.9. View and print those submissions

Once submissions have been created, you can go to Drag & Drop Apps > Forms Projects > your project > Submissions (in left hand sidebar). You should be able to see all of the data you submitted from the app. Click on any one of them.

Each submission shows text fields, photos, signatures, and any other fields that have been submitted. Depending on your Group permissions you can download PDF, print, delete or edit each submission.

Read More

1.10. Further reading

You have now used all of the Core functionality around forms. There are many other advanced features you can use. Read More

Chapter 2. Create a Simple Form

Overview

This tutorial will cover how to:

  • Create a form
  • Add fields to a form

Requirements

  • App Studio Account

2.1. Tutorial

2.2. Step 1: Login

Log in to the Studio with your credentials.

2.3. Step 2: Creating a form

Click the 'Forms Builder' tab. You will now be presented with the Forms screen. If forms have already been created, they will be displayed here. If multiple forms have been created, the search box can be used to search for a form, or the listing format can be changed to a format that displays more forms at once. If no forms exist, or the user does not have sufficient priviliges to view the already created forms, a message saying 'No Forms Found' will be displayed.

Selecting a form will cause the Forms Dashboard to be displayed. Form the Dashboard, more information regarding the selected form can be accessed. This information includes:

  • Projects Using This Form
  • Submissions Today
  • Total Submissions
  • Pages
  • Subscribers

To create a new form, click the 'New Form' button.

The form creation window will now be displayed. Here you will be prompted to select a Form Template, and enter a Form Name. The inclusion of a Form Description is optional.

There are a number of Form Templates available for selection. Clicking on any of the templates will cause a preview of the form to be displayed. If you do not wish to use any of the pre-made forms, select the 'Blank Form' template.

Note

Selecting a template does not mean you have to use the form exactly as it is. Templates are used as a starting point for a form, and can be edited.

2.4. Step 3: Editing a form

To edit a form, first select the form from the list. After the form has been selected, a preview of the form will be displayed on screen along with the Form Menu.

Note

If a newly created form has been selected, the form preview will appear blank, showing only the title of the form. This is because fields have not yet been added to the form.

Select Edit Form from the sidebar. This displays the Edit Form screen. From here, fields can be added to a form. Fields can be added to a form in two ways, either via a drag and drop mechanism, or by simply clicking on the field you wish to add.

Note

When adding fields to a form, clicking the field will add it to the end of the form, whereas dragging and dropping a field allows you to position it wherever you want in the form. Fields can be moved via the drag and drop system after they have been added to a form.

Click on a field to add it to the form. The form preview is automatically updated when a field is added. When added to a form, all fields are automatically labeled 'Untitled' and the 'Required' value is applied.

Note

The required attribute determines whether or not a value must be entered in a field in order for it to be possible to submit a form. If the 'Required' attribute is added to a field, a value must be entered/selected for that field before the form can be successfully submitted.

Add a Number field to the form. After it has been added, click on the field in the preview. A new menu will now appear.

From here, various attributes relating to the selected field can be configured. These include the field name, additional instructions, limitations for maximum and minimum values that can be entered, and more.

Note

Each field has different configuration options specific to that field. For example, a text field will have a configuration option for the maximum set of characters that can be entered, whereas the photo upload field has a configuration option for the max file size that can be uploaded.

Set the attributes of the number field as the are listed below:

  • Name: Number field
  • Instructions: Please enter your mobile number

Now add a Text field by dragging it on to the form. Reposition the Text field so it’s above the Number field. To do this, drag the Text field and release it above the Number field.

Select the Text field and set its Name to "Name".

Now Save the form.

The form has now successfully been created, and can be associated with a project.

Chapter 3. Create a Forms Project

Overview

This tutorial will cover how to:

  • Create a Forms Project
  • Associate a Form with an existing Project

Requirements

  • App Studio Account

3.1. Create a Forms Project

There are two ways in which a Forms Project can be created using Drag & Drop Apps:

3.1.1. 1. Create a Forms Project via the Projects Section

  1. Click the Projects section to be brought to the Project creation area.
  2. Choose the New Project option.
    You will now be presented with a screen that allows you to both name your project, and select a template to base the project on. One of the selectable options is Forms Project.
  3. Select the Forms Project template.
  4. Click Create.
    Once the project has been created, you will be prompted to associate a theme and form(s) with it.
  5. Select a theme and a form to be associated with the Project.
  6. Click Save.

You have now successfully created a Forms Project via the Projects tab.

3.1.2. 2. Create a Forms Project via the Drag & Drop Apps Section

  1. Select Drag & Drop Apps from the menu bar.
  2. Select Forms Projects from the sub-navigation menu bar.
  3. Select the New Forms Project option.
    From here you have the option to either Create New Project or Use Existing Project.
  4. Select Create New Project.
    You will be prompted to enter a name for the project you are about to create.
  5. After you have entered a name, click the Next button.
    You will then be asked to associate a theme and form(s) with the Project.
  6. Select a theme and form(s) to be associated with the Project.
  7. Click Finish.

You have now successfully created a Forms project via the Drag & Drop Apps tab.

3.2. Associate a form with an Existing Project

There are two ways in which forms can be added to an existing project.

3.2.1. 1. Associate Forms with a Project via the Forms Projects Section

  1. Select a project from the Forms Projects section.
    After a project has been selected, the project subnav will be displayed. A Project Forms & Themes tab can be seen in this subnav.
  2. Select the Project Forms & Themes option from the subnav.
    The Forms section allows users associate themes and forms with a project. To add a theme, simply select a theme from the dropdown menu. To add a form, click in the forms field, and a list of available forms will appear.
  3. Select the form(s) you wish to associate with the project.
  4. Click Save.

The form has now been successfully associated with a project.

3.2.2. Associate Forms with a Project via the Forms Builder Section

  1. Select the Forms Builder section from the Menu bar.
  2. Select the New Forms Project option.
    You will now be given the option to either Create New Project or Use Existing Project.
  3. Select the option to Use Existing Project.
    You will now be prompted to associate a theme and form(s) with the Project.
  4. Select a theme and form(s) to be associated with the Project.
  5. Click Finish.

You have now successfully associated a form with a Project via the Forms Builder Section.

Chapter 4. Create a Form Theme

Overview

This tutorial will cover how to:

  • Create a Drag & Drop Apps theme

Themes allow designers to customize the visual appearance of a Form.

Requirements

  • App Studio Account

4.1. Tutorial

4.1.1. Create a theme from scratch

  1. Log in to the Studio using your credentials.
  2. Click on the Forms tab and select Themes from the sub-navigation.
    If no themes have been created, or the current user does not have sufficient priviliges to view the already created themes, the themes list will appear blank. If there are already themes created, then the themes list will be populated. Listed, is the name of the theme, the date it was last modified, the user that created the theme, and Projects currently using this theme.
  3. In order to create a new theme, click on the New Theme button.
    The theme creation screen will be displayed. The option to select a template will be presented. In order to create a theme from scratch, do not select any template.
  4. Enter the name of the theme.
    You can also enter a description for the theme, however this is not mandatory.
  5. Click Create.

    Note

    Leaving the name field blank will result in an error being displayed. All themes require a name.

  6. Select the newly created theme from the list.
    A preview of the theme will automatically load. This will show various aspects of the theme configuration, such as logos used, fonts, colours etc.

4.1.2. Create a theme from a template

When creating a theme, users can choose to create a theme from scratch, or choose a theme from an existing template. Using an existing theme can be useful for developers, as it is far less time consuming to modify an existing theme rather than create a theme from scratch.

  1. In order to use a template, click on the Forms tab, and select Themes from the sub-navigation.
  2. Select New Theme.
    This will display the theme creation screen. From here you can create a theme from scratch, or select a theme from a list of templates. Selecting a template will display a preview of the theme. Here, customization settings such as colour schemes, logos, typography etc. can be seen.
  3. Choose a template.
  4. Enter a theme name and a optionally a theme description.
  5. Select Create Theme.

The theme has now been successfully created based off of an existing template, and is ready to be associated with an App.

4.2. Editing a Theme

Select Edit from the sidebar. This will produce a similar screen, however you will now be able to change the values for the various sections of the theme.

Logo

Users can upload their own logo via the file upload option in the Logo section. Any image to be used as a logo must be in the .jpeg format.

Backgrounds

In the background section, users can change background colours for different sections of the theme. a colour can be changed by clicking the coloured circle above a section name, and then selecting a colour from the picker. The update will take place once the colour picker has been closed.

Typography

The Typography section allows for the customization of font size, type, and text decorations. The colour of a selected field can also be changed by clicking on the coloured square beside the section title. Clicking the coloured square displays a colour picker.

Borders

Here customizations can be made to the border sections of a theme. Users can make customizations based on colour, border type and border width.

Note

To get a preview of how changes made to the various sections affect the theme select a form from the dropdown menu and preview it in the simulator.

When you are happy with the customization of the theme, click the Save button at the bottom of the screen. This will save the theme and return you to the Themes page.

Chapter 5. Drag & Drop Apps Lifecycle Management

5.1. Overview of Lifecycle Management and Drag & Drop Apps

The basics of Lifecycle Management and Drag & Drop Apps are covered in the product features page. Essentially, Lifecycle Management allows users to clearly understand what versions of their applications are deployed to which environment. It also enables them to easily deploy and promote applications between those environments. Drag & Drop Apps allow users to easily define forms for collecting data via a Drag & Drop interface. These forms can then be used and integrated within Client Apps.

App Forms Relationship

5.1.1. How Does Lifecycle Management Work with Drag & Drop Apps

Drag & Drop Apps Lifecycle Management allows users to deploy and promote new and updated Drag & Drop Apps to individual environments as opposed to all at once. Drag & Drop Apps Lifecycle Management also enables users to clearly see which Drag & Drop Apps are available across each of their environments.

5.2. Lifecycle Management Interface

The Red Hat Mobile Application Platform Hosted (RHMAP) includes a simple interface that allows users to manage the full lifecycle of all Drag & Drop Apps as a whole as well as at the individual level.

To access the Lifecycle Management page for all Drag & Drop Apps:

  1. Navigate to the Platform and click on Drag & Drop Apps at the top of the screen.
  2. Click on Lifecycle in top navigation. This screen shows the status of every Drag & Drop App across every environment. All Lifecycle
  3. Click on the + button for any Drag & Drop App to reveal the details. Lifecycle Details

To access the Lifecycle Management page for a single Drag & Drop App:

  1. Navigate to the Platform and click on Drag & Drop Apps at the top of the screen.
  2. Click on Forms Builder in top navigation. Forms Builder
  3. Click on the desired Drag & Drop App from the list.
  4. Click on Lifecycle in left navigation. This screen shows the status of the chosen Drag & Drop App across every environment. Lifecycle Left Nav

Both pages offer the following functionality in the Drag & Drop App details:

  • Deploy Now
  • Preview
  • Live Edit
  • Promote
  • Submissions
  • Copy
  • Deploy

Operations

The typical flow of operations might be as follows: the user creates a form, saves it in the Core Platform and may perform subsequent edits safely before the form gets deployed to an environment. When the form is ready, it can be deployed to a Development environment, or even straight to Production. In case of any urgent issues found after deployment, live edits can be made to the form deployed in any of the environments. Live edits don’t automatically propagate to the Core Platform, the user needs to do that manually using the Copy function, which overwrites the master copy in the Core Platform.

Operation sequence

5.2.1. Deploy Now

Deploy Now appears in the Drag & Drop App details on the Lifecycle page and allows you to deploy a Drag & Drop App directly to a specific environment from the Core instance of the Drag & Drop App on the Platform.

Important

When associating projects with a Drag & Drop App, the project will only see and will only use the Drag & Drop Apps in the same environment. For instance, if a project is associated with a Drag & Drop App that is only deployed to Development, when that project is deployed to Production, it will be unable to see or use that Drag & Drop App. The same applies to updates made to a Drag & Drop App. If an update is deployed to a Drag & Drop App in Development but not to Production, associated projects will see the updated Drag & Drop App when they are in Development but will not see the update when they are in Production.

5.2.2. Preview

Preview brings up a live preview of the Drag & Drop App currently in that environment. Lifecycle Preview

5.2.3. Live Edit

The lifecycle for publishing a Drag & Drop App usually resembles:

  1. Create or make changes to the Core Drag & Drop App in the Platform.
  2. Deploy changes to a testing or staging environment.
  3. Once changes are approved, promote them to production.

In addition to this type of lifecycle, the Platform also enables users to do a Live Edit. Live Editing allows user with sufficient privileges to make changes to a form and save those changes directly in an environment without having to follow any promotion process.

For example, a user could make a change to a Drag & Drop App and deploy it only to a development or testing environment, leaving all other environments with the original version. Alternatively, a user could see a critical issue in Production and use the Live Edit functionality to make the change directly in Production to resolve the issue immediately. The user could then copy those edits back to the Core project and propagate that change to the rest of the environments.

To Live Edit a form:

  1. From the Lifecycle page, show the details of the desired Drag & Drop App by click on +.
  2. Click on Live Edit in the desired environment. Lifecycle Live Edit
  3. Make the desired edits and click Save and Deploy to save the changes to the environment.
Important

Clicking on Save and Deploy will save and deploy your changes to the current environment only and will do so immediately. To save these changes to the Core instance of the Drag & Drop App, Copy must also be used after you click Save and Deploy.

5.2.4. Promote

Promote allows you to replicate the deployed version of a Drag & Drop App from one environment to another. The main difference between doing a Promote versus doing a Deploy is that Promote does not involve the Core instance of a Drag & Drop App on the Platform. Meaning, Live Edits made to an environment can be Promoted to another environment without doing a Copy back to the Core instance of a Drag & Drop App on the Platform.

To Promote a form:

  1. From the Lifecycle page, show the details of the desired Drag & Drop App by click on +.
  2. Click on Promote in the desired environment and choose the destination environment. Lifecycle Promote

5.2.5. Submissions

Submissions allows you to see all submissions made to a Drag & Drop App for that specific environment.

5.2.6. Copy

Copy will copy any Live Edits made to an environment back to the Core instance of the Drag & Drop App on the Platform. This is useful for preserving changes made while doing Live Edits as well as deploying those changes out to other environments.

Important

Copy performs a rudimentary copy, not a merge, of the chosen environment back to the Core instance of the Drag & Drop App on the Platform. Meaning this has the potential to destroy changes that are not deployed to the environment that was live edited. Carefully review both the live edited environment as well as the Core instance of the Drag & Drop App prior to using Copy, to avoid losing changes made on the Core instance.

Important

Make sure you have used Copy to save any Live Edits you wish to save prior to using Undeploy or Redeploy.

5.2.7. Deploy

The Deploy menu provides two options: Redeploy and Undeploy.

Deploy Details

Redeploy allows you to deploy the Drag & Drop App from the Core instance to the chosen environment. This will overwrite any live edits made to that environment. Undeploy allows you to remove a Drag & Drop App from the chosen environment. Neither of these operations affect the other environments that Drag & Drop App is deployed to.

5.3. Permissions

All operations related to Drag & Drop Apps Lifecycle Management adhere to the existing permissions system of the Platform.

To Deploy and/or Live Edit a Drag & Drop App, the user must have:

  • Write access on the Deploy permission under forms
  • Write access on the form being deployed
  • Write access to the environment they are deploying the form to

To view a Drag & Drop App in the Lifecycle Management interface, a user must have:

  • Read access on the environment
  • Read access on the form being viewed

For example, a user with Read access on a form and Read access to all environments will be able to view all deployed forms, but not Live Edit those Drag & Drop Apps.

For more details on permissions in general, see the User Roles section of the Administration Guide.

5.4. Drag & Drop Apps Lifecycle Management and $fh.forms

The $fh.forms API allows you to call the Drag & Drop Apps API from javascript Client Apps. When making calls using $fh.forms, results will be filtered automatically depending on the current environment the application is running in. For example, an application may be associated with three Drag & Drop Apps, but if only one of them is deployed to the current environment, $fh.forms.getForms will only return that one.

For more details on using the $fh.forms API, consult the API documentation.

Legal Notice

Copyright © 2018 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.