Before we get started, please know that you can click on most of the images in the Documentation to get a better view! Click once to enlarge and once again to make it the original size!
Understanding Forms, Modes, Fields, Controls and Buttons
SnappyForge is understandably large, and to new users it can be quite a daunting system to wrap your head around. Before we dive in to all the how-to's and tutorials, we would first like to give you a brief overview of how the system works.
Forms are the most basic building block and the starting point for any user. A Form is a collection of data points which can include Text, Numbers, Dates and Times and more. You can think of a form as a complete table which represents data, kind of like a spreadsheet. Forms can be shared both publicly and privately, and they can also be brought into your website via our Widgets feature.
Forms are not just a table, however, as the complete Form in SnappyForge can also contain different Modes, or ways of accessing the data contained in the table. Each mode can have a different view of the data, allowing you to quickly create additional views and control who can see what!
You can even pull data from one Form into another form with a List Control (like a DropDownList), link multiple forms together to create an application, and also link forms together in a parent-child relationship!
Think of Modes as different views of your Form's data. When you create a Form, three Modes are automatically created for you. There is a List Mode, an Add Mode and an Edit Mode.
You are free to create as many Modes as you wish, and each Mode can display your data a bit differently. You could, for example, create a View Only Mode, and set the Controls to all be Labels. You could also create a Manager View, and have additional Fields which are hidden in the other Modes.
Your List View is special, and most of the properties which control how it is displayed are contained in the 'Edit Form' screen. You can control how many items to display in the list at a time, set a default column to sort on, and allow users to sort the list themselves.
Your default Add Mode and Edit Mode are responsible for inputting and updating data respectively.
Fields are the most basic portion of a Form. A Field defines a part of your table, so think of it as a column. Fields have many settings, but the two most important are Name and DataType. Name is what you would like to call it, and DataType is the type of data the column represents - like Text, Money, Numbers, or Dates. More DataTypes are being added as well as international formats for currency, dates, and phone numbers!
The settings for a Field apply across all Modes. That means that the name of the Field will be consistent in all Modes, and if you set a Field to Money, it will be displayed as currency in each Mode it's visible in.
A Control tells each Field how to collect data in each Mode in your Form (except for List Mode). Controls can be different from Mode to Mode - for example you can have a Text input in Add Mode but make it a Label in edit Mode. Another use of Controls would be to have a Hidden Control in Add Mode but display it as a DateTime in Edit Mode. Each Mode can be customized seperately, and this is probably the most important feature (and most difficult to fully understand if you're just getting started)!
There are a wide range of Controls which you can use in SnappyForge, and each was designed to provide a rich end-user experience while enforcing high quality data collection standards.
It's important to note, after you create a Form and start adding Controls, SnappyForge does two things. First, it creates the proper Field to hold the data for that control (DateTime Field for a DateTimePicker Control, or Money Field for a Money Control), and it also creates that Control in each Mode you have in your Form (except for List Mode, which we will talk about a little later). Because of this, it's usually best to create the entire Add Mode form first, dragging out the Controls you intend to use in every Mode you plan on having, then going back and setting Controls for a particular Mode to be Hidden or Labels.
As with Controls, Buttons are configured to display in a particular Mode. Buttons control how users interact with your Form, getting from List Mode to Edit Mode and vice-versa. Buttons can do quite a lot for you, but for now it's best to just understand that like Controls, they're configured on a per-Mode basis.
Creating a Form
Creating your Form is very simple! Once you're logged in and can see our Main Menu on the left side of your screen, just click the "New Form" button.
After clicking on "New Form" you will be presented with a floating dialog with some options for your Form. The only required Control is "Form Name", which must be a minimum of 5 characters long. Clicking on the Help Button () in the Main Menu will display some tooltip icons on the dialog which should help explain what each option does. You can hover your mouse over these to read about each option.
Note that this feature is universal everywhere in SnappyForge! If you're not sure what a particular option does, click the Help Button to make these tooltips appear and hover over the one you're not sure of for a brief explanation. You can even make your own Forms display these tooltips (the option is on by default, go into the Field's settings to add the tooltip text).
These settings can be changed later on as well, so don't worry too much how big the Page Size is, or whether or not you want to allow users to Sort the List Mode - you can always go and change them.
One thing that is fun to play with is the Style options, but for a Free account those options are limited!
So go ahead and give your new Form a Form Name, and you can leave the rest of the settings at their defaults. Scroll to the bottom of the window and click Save.
The window will disappear and you'll see a floating screen telling you that your Form is being created. Once complete (this usually only takes about 10 seconds or so), you'll be redirected to your new Form's List Mode!
Also note that a single Field was created for your new Form, and it is called "ID". ID is a special field, and should probably be left alone. You can hide it, and we'll show you how in a bit. For now, you should know that ID acts as an Identity Field, a special field which counts from 1 for each row in your underlying data table. Identity Fields are extremely important for databases, and will always be unique for each row in your table. There will never be duplicates, so you can also use ID as a reference number for your Form (e.g. "What's the status of Case #101?").
SnappyForge has many different Field types, and more will be added as we move forward. Fields are created for you automatically when you drag a Control to your Form.
You don't have to worry too much about which DataType a Field is, because if you drag a CheckBox to your Form a boolean (True/False) column and Field is created for you. SnappyForge always tries to create a Field with the appropriate data type for the Control you create - but know that you can change this later provided that the data in the column can be converted into the new data type!
When Editing your Form (which we'll get into in the next section), you will notice that Controls have an Edit Button (). Clicking on that brings up a few windows where you can modify settings, but it brings you to the settings for that Control. The Field settings (which are 'global' and not for that Control in that Mode) are in the window just above the Control settings. Let's move forward, as this will all become a lot clearer in the next section!
The first thing we will need to do is get into Form Editing Mode - a special mode only you have access to for your Form. To do this, make sure you're in your form. If you are not, go to your Dashboard, and then click on the Form you want to edit. Once you're on your form you should see something like this: OR like this: Before entering Form Edit Mode, you should probably click on the Add New Button on your Form if you are in List Mode, as you can't really edit anything in List Mode yet.
You should now be in your form's Add Mode. You'll notice that the Save button is greyed out. If you hover over the Save Button, it will tell you why - there are no Fields in your form! Let's fix that!
On the Main Menu on the left, hover over "This Form", then click on the "Add Controls" button.()
Your Main Menu and your Form in Add Mode now looks like this: You will notice that the Main Menu changes, the one Field you had (ID) now has a small grey line around it and two buttons on it, and a whole window opened up on the right side of the page.
This new window contains the Controls that you can drag onto your Form. Note that it will always tell you which Mode you are in - "Drag Controls to Add Mode". The rest of the Form Editing windows will also do this.
The next step is to actually pick a Control that will collect some piece of data you want to collect. For now, stay away from DropDownList, CheckBoxList, RadioButtonList, CodeFormula and RowCodeFormula. The List Controls have some special settings which can be used to tie Forms together - so you can create a Form for Status, and then create a Project Form and drag a DropDownList to it. You'd then be able to easily tie the Status Form's data into that new Project DropDownList. The CodeFormula Controls are covered later on, so leave them alone for now. Left click and hold a Control to drag it out onto your form. Try to place it under the ID Label Control. You should see it snap into place. After it snaps, let go of the mouse button to drop it in place. A popup dialog will appear asking you to Name your new Field (Controls all inherit the name of the Field they're tied to). If you are not happy with the order of the Controls, you can drag them around to re-order them. Note that the order of the Controls stays the same in all Modes, even List Mode. Once you're finished, click Save () on the Main Menu on the Left. You'll be out of Form Edit Mode and you'll be back on your List Mode screen.
If you were to click on the Add New Button, you'll see your updated Add Mode You'll notice that the Save Button is no longer greyed out! You may enter a value into the Control you just placed and click on the Save Button to create a record!
Now you can see there is an item in List Mode: You can click on the Edit Button for each item to bring you into Edit Mode:Note that our Add Mode had ID as 0, but now it is 1? This is a small bug that we'll get to (it doesn't affect any functionality), and you'll likely want to hide ID from Add Mode anyway. Let's move on and learn how to do that!
Changing Controls in Add Mode (but not Edit Mode)
Let's go back into Form Edit Mode. Again, to do this, hover over "This Form" and click either "Add Controls" () or "Edit Controls" buttons.(). Note that you can still Navigate between different Modes when Editing your Form, so get yourself to Add Mode to follow along. If you're in Edit Mode, click the Cancel Button to go back to List Mode. If you're in List Mode, click the Add New Button to get to Add Mode. You should see something like:
Now let us talk about the red buttons that are on top of the Controls. There is a Delete This Field Button () and an Edit This Field/Control Button ().
When you Delete the Field, SnappyForge removes the Field, it's Controls, and the underlying column and data from the table. Do not Delete Fields unless you're absolutely sure you want to do that! We even try to warn you about it:
Find ID and click on it's Edit This Field/Control Button (). You'll notice the right side of the page now contains several options windows, but only one is open.
From top to bottom, we have a section for Dragging out New Controls to the Form, Editing the Field, Editing the Control for this Mode, Adding Additional Options for this Control in this Mode, and Adding Validation to the Control in this Mode. We'll get to the Control Options and Validation later.
It just so happens that we want to edit the Control for the ID Field, so we're in the right place already.
The ID Field in Add Mode is currently set as a Label Control: Let's change it to a Hidden Control and click the Save Control button at the bottom of that window.Now your Form in Add Mode looks like this:Click the Save Changes Button () to Save and go back into List Mode.
If you click the Add New Button now, you'll see that ID is indeed hidden from view:
Remember, each Control you make changes to is specific to the Mode you are in!
Now, let's make one more change to the ID Field itself. Let's say we don't really want it showing in our List Mode. Go into Add or Edit Mode, and then launch into Form Edit Mode by hovering over "This Form" and then "Add Controls" or "Edit Controls". Then click on the Edit This Field/Control button on the ID Field. Once again, you'll see this on the right side of the page:
From here, click on the section heading that reads "ID Field Settings (Global)" to open the Field Settings window: Now look for the setting "Include In List", and un-check the CheckBox. Then scroll to the bottom of the window and click "Save Field". Now click the Save Changes Button on the Main Menu to save and go back to List Mode. Viola! ID is not shown in the List Mode anymore: It's still a Label in Edit Mode, but Hidden in Add Mode and not displayed in List Mode.
You are free to explore these settings (and we know, there are a lot of them) - but in reality you will only need to change a few of them most of the time. The others are for special circumstances, and will be covered elsewhere in our Documentation.
Additional Control Options
For the Field Settings and Control Settings windows, we include settings which are shared by ALL Fields and ALL Controls - but there are some Control types which have additional options that you can set. You do this from the Additional Control Options window.
To get to this window, go to the Mode you'd like to edit and get into Form Edit Mode. Then click the "Edit This Field/Control" button to open the settings windows:
Now click on the section header for "Additional Control Options for YOURFIELDNAME in YOURCURRENTMODE Mode". Here, we used our example from above, but clicked Edit on the TextBox we had created:
We should mention that some controls have more options than others, and some of those options may already be set for you (TextBox, TextArea and TextHtml are all the same TextBox control with different options - as are DateTimePicker, DatePicker and TimePicker).
For our TextBox, we will click the Add New button to see the additional options:
Our TextBox has a few available options, including Placeholder and Multiline. Let's set both of these!
First, we will set Multiline - choose "Multiline" from the Key DropDownList and then check the checkbox which appears in the Value:Click the Save Button underneath and you will be presented with the following dialog:
Like Controls and Buttons, Additional Control Options are Mode specific. You may want to have a placeholder for a TextBox for Add Mode but not want it in Edit Mode. We know that most of the time, you'll want to set everything the same way, so this popup dialog box provides you an easy way to do just that! Please note: If you Edit an Additional Control Option later, you WILL have to make those changes in ALL Modes!
You can go and click on "Yes Please" and have the setting copied to our Edit Mode as well.
Now, let's repeat the process for Placeholder. A placeholder is text that appears in a TextBox before a user puts text in it. It does not count toward Validation. Let's add one now for the TextBox. Since we're here already, just click on "Add New" again. This time, we'll just enter some text into the Value field to set the Placeholder, then click on Save at the bottom of the window!Once again, click on "Yes Please!" to copy the setting to our Edit Mode as well.
We can now see that we have two Control Options:
Now click on the Save Changes Button in the Main Menu. You'll be back at your List Mode again. Click your Add New button to see what the final result looks like in Add Mode!
Now, we know that you won't likely use the Additional Control Options all that much, but you will likely use this next topic quite often - Validation!
Validation occurs when certain Buttons are clicked - usually Save Buttons. When a user comes to add some data into your Form, you'll likely want them to enter certain information, and you'll likely want that information to be well formatted. This is where Control Validation comes in!
Just like with Additional Control Options, Control Validation is done on a per-mode basis. Perhaps a Field is required in Edit Mode but not in Add Mode. If you let SnappyForge copy the setting, and then want to change it, you'll have to change it in each Mode you have for your Form.
Let's add a couple of Validation Rules to our TextBox control we created earlier. We'll need to get to the Control Validation window to do this.
To get to this window, go to the Mode you'd like to edit and get into Form Edit Mode. Then click the "Edit This Field/Control" button to open the settings windows:
Now click on the section header for "Control Validation for YOURFIELDNAME in YOURCURRENTMODE Mode". You will see the following:
Each Control has different rules it can be given. Almost every Control can be set to Required, but TextBoxes can also have settings like minlength and maxlength. All Text Controls are automatically given a maxlength rule, so they do not exceed the size of the underlying database column.
We're going to set two rules for our TextBox, Required and MinLength. Let's click on the Add New Button and add Required first. Check the CheckBox under Value, then enter your custom message that will be displayed to users in the event they fail to enter text in the TextBox. Click Save at the bottom of this window to save the rule. You'll be asked to copy it to your other Modes, click on "Yes Please!".
Now let's set another one, minlength to 10 characters and add a message for that as well:Again, click on "Yes Please!" from the pop up dialog box. Your Control Validation window should now look like this:
Now click on the Save Changes Button in the Main Menu. You'll be back at your List Mode again. Click your Add New button to go into your Add Mode, then try clicking on your Save Button.You'll notice that the message we set is displayed under the Control in bright red, and the Save Button temporarily says "Please Review Your Submission for Errors!".
Now we'll enter some characters into the TextBox to make our Required message go away...And we see our second rule is in effect! The user cannot submit the form without entering at least 10 characters!
So far, we haven't really talked about what we call "Data Bound Controls". Data Bound Controls are controls which could get their data from other Forms, and when we save the user's selection behind the scenes we do not save the 'Text' but rather the 'ID' they chose. Examples of these controls are DropDownList, RadioButtonList and CheckBoxList. The first two controls are single selection, while the CheckBoxList offers Multiple Selection. All three of these controls could be linked to pull their data from other forms, which we will cover later.
Their available List Items also can be set up manually, and we're going to cover the process for doing this right now. There could be many reasons for wanting to manually control the List Items - perhaps you only have a few items and they don't change often. Or, your DropDownList is linked to another Form, but you want to put a generic "Select One..." option with no value, to force a user to choose. Well read on!
Just like Additional Control Options and Control Validation, List Items are displayed on a per-mode basis. You could have a List Item on a DropDownList in Add Mode that says "Select...", but then display the same value ("") as "User Did Not Make a Selection" in Edit Mode.
Lets get into it!
If you haven't already done so, go into Form Edit Mode and drag a Data Bound Control to the Form. We're going to work with a RadioButtonList for these examples. Note that after you drag the RadioButtonList and name it, you'll be shown a pop-up to "DataBind This Control?":Just click on "Manual Setup" for now (unless you've already set up a Form you want to pull data from!).
To get to the Static List Items window, go to the Mode you'd like to edit and get into Form Edit Mode. Then click the "Edit This Field/Control" button on a Data Bound Control to open the settings windows:
When you go to Edit a Data Bound Control, you'll see an extra window at the bottom called "Control Static List Items for YOURCURRENTMODE Mode". Go ahead and click on that window's header to open it.
For our example, we're going to add three List Items:
Keep in mind that SnappyForge will allow you to enter whatever you like for both Text and Value. This could lead to two problems, so take care when adding List Items! The first potential issue is that your Field's DataType is set to integer - but you enter a string of characters for Value. This will not work and will likely cause an error. The other potential issue is that you could enter two Texts with the same Value - so if a user selects one in Add Mode it may appear that they selected both when you go back to Edit Mode.
When you go to click Save, just click on the "Yes Please!" button to copy this List Item to your other Modes in your Form.Your Static List Items box should look like this:
Now click on the Save Changes Button in the Main Menu. You'll be back at your List Mode again. Click your Add New button to go into your Add Mode to see the new List Items displayed in the RadioButtonList!
Very often, web applications need to have multiple Forms that may be related - and SnappyForge Applications allow you to do this just as easily as creating your Forms! Applications are really just our way of creating a Menu for your Forms to tie everything together in a neat and consistent way.
Note that Permissions for Applications is a bit more complicated than permissions for Forms - because you'll need to set the permissions for both the Form and the Application Buttons! We will cover all of this in the next section: Permissions.
Applications are both created and accessed from your Dashboard. Click the Dashboard button in the Main Menu on the left side of the page to go to your Dashboard.
Your Dashboard probably looks a bit like this:
The top section is where Applications you own or have been given access to would be, and is likely empty. The second section is for Forms You Own - and the Form we built earlier on is there - with two buttons. One will take you to Add Mode and the other will take you to List Mode.
As you create Forms, they will appear in this section as well.
Creating an Application
To create an Application, simply click the "Add Application" button from the Main Menu on the left side of the page.
Now you'll notice a few changes to your screen. First, you'll see that an Application has been created under the Applications You Own section - and you'll also notice some extra buttons under Forms You Own.
The first thing you'll want to do is name your Application. To do this, click on the Title when the Application is in Edit Mode (which when you create one, it is!). So, click on the text that says "Click Here to Name Your App". When you do this, it changes to a TextBox. Enter your Application's name and press the Enter key on your keyboard to set it.Note that when your Application is in Edit Mode, you can click on the title any time to edit it!
We are now ready to create the Menu for our App: You can drag the buttons from the Forms You Own section up into the grey bar under the three buttons ("Edit Permissions & Settings", "Save Menu" and "Delete This Application").
Dragging Menu Items works similar to dragging Controls into your Form. You can also re-order them! Let's drag both our List and Add buttons for the Form we created earlier into the Application.You will notice that the buttons change into tabs, because we're using the SnappyForge default style here, but rest assured they will take on whatever style you picked when you created your Form.
You can also remove Menu Items by dragging them into the area with the red dotted line around it. These items would not be saved when we save the Menu.
You can click on the Tabs to re-name them. If you give them a custom name we will always use that to lead to the Form - but if you do not then we will always use the CURRENT name of your Form. This means that if you were to rename your Form the default Menu Item will automatically reflect that change.
Click on one of your Tabs - you'll see it changes into a TextBox. Enter a name or just press the Enter key to save it.
Now let's take a quick look at the "Edit Permissions & Settings" button. Clicking on it changes the Application we're editing to look like this:
Under your application's name and each tab we have added some settings. Under the Application Name we add the following:
Company Header: You'll be able to use this to select a Company Profile you create under the Manage Companies button () on the Main Menu. We will cover this in a later section, but if you have a graphic logo you'd like to display above your Application Menu and Forms, this is how you'd do it.
Allow Roles: Roles are how SnappyForge determines who is allowed to see your content, and in this case, the Roles are used to determine who gets to see the whole Menu. You'll also be able to set the Roles for each Menu Item as well.
Display Breadcrumb Trail: Breadcrumbs are a way to let users know where they currently are, and they're turned on by default. Here's what that looks like when you're using a standalone Form: And here is what it looks like when you are using the Breadcrumb with the Application Name:
Display Application Name in Breadcrumb: By default we display the Application Name in the breadcrumb trail, but you can turn that off and make it look like a standalone Form by un-checking this box.
Under each Tab you'll see the following options:
Allow Roles: In this case, this setting determines who can see this Tab, provided of course they have the rights to see the Menu at all. We will cover the topic of security and permissions a lot more in the next section!
Display as Popup: Popups are a great way to manage small Forms! Instead of taking the user to a new page to render your Form, popups will appear over whatever they are doing. For some tasks, this could work well, but for others it may not do what you want. You can always reach out to us for assistance!
Popups require an account with Widgets to work! That means you cannot use this feature with our Free and Basic plans!
Next Section: Permissions and Security
Go To Permissions & Security