Managing Forms in Vivaldi

Typical form design process


Previous:  General Vivaldi Settings


Example forms

We've created example table and detail forms you can use to learn how to apply many common form design techniques. Once in Vivaldi, select Administration>>Examples from the menu.

Creating forms

There are three types of forms available with Vivaldi:
Table - A tabular form that shows rows of records.  You can (optionally) specify a related Detail form that is used to add, edit, and view more details.  You can also (optionally) decide whether users can delete records from the table view, and export to PDF or Excel.  We recommend you begin by designing your Table form, then your Detail form.  When you've gotten your Table form into the desired shape, you can choose an option 'Copy items to Related Detail form' to speed up the design process.  You will then just need to adjust the layout of the Detail form as desired.

Detail - A single record detail view that is displayed in a responsive popup dialog.  The detail view can have more information than you would show in a table.  You can open Detail forms directly from a menu, but usually you will have a corresponding Table form where users search and locate the record they want to view/edit before opening the Detail form.

Master-Detail - A compound screen that displays a top-level tabular form ("master") along with up to three other forms below in tabs ("detail" or "child" forms).  The child forms all respond when a user clicks a row in the master form, and display related record(s) in the child forms.  More information about creating Master-Detail forms here.

  1. To create a new form, navigate to Forms > New Form Wizard in the menu.
  2. Enter the form name choose the base MySQL table, primary key, and what type of form you want to create.
  3. Vivaldi will create the basic form(s) for you, and you can navigate to the Form Designer once prompted.
On This Page

    Designing your form

    The Form Designer contains three left-hand panels.  The Properties, Items, and Permissions panels:
    Form Designer Panels
    The Properties panel contains the same options as the "Creating Forms" step, and is available as a convenience.

    At any time you can preview your form or expand it to full screen by selecting the options on the right-hand side of the screen:
    Form Designer Buttons

    Adding items to your form

    Vivaldi helps you add text boxes, dropdowns, buttons, and other elements to your Table and Detail forms.  When you have a paired Table and Detail form, you will want to make sure each form has a field defined that has the "Primary Key" set to yes (you can hide it if you want) that will represent a unique record.

    1. Select "New" in the Form Items panel.
    2. Select the corresponding form you are working with in the dropdown.
    3. Enter a caption for the field, and what column in your table/view the field should be bound to in the "Bound Field" field.
    4. If your form is a Table form, then use the "Table Display Order" to dictate the order of columns.  If your form is a Detail form, use the "Detail Row" and "Detail Column" to determine the order of display.  For example, row 1 might have 2 fields, row 2 might only have one, and row 3 might have 4.
    5. For Detail Forms, you can group controls in collapse panels by enter a text name in the Collapse Panel property (be sure all of the controls you want to group have the same panel name).
    6. For Table Forms, you can move some information to a collapse section by checking the "Show in row expand section?" checkbox.  This allows the additional information to hide until the user clicks the row "+" icon.
    7. Use the panels below to learn more about each Display Type and how to manage special options for them.
    Text boxes, numbers, checkboxes, dates, email, password, and range Display Types just need you to specify the Bound Field. They will write to your database "as-is" based on the user's entry. Click the 'Wizard' button next to the Display Format if you wan to format for dates and numbers.
    You can add the Custom CSS 'clearafteradd' to a field which will cause it to clear the values entered after the user has saved the record using the "Save and Add Another" button option.
    There are several types of dropdown lists you can create, described below. If you want your dropdown list to be easily searched by keyword, add the class 'chosen-select' to the "CSS Classes" property.
    • Yes/No - Users are presented with a Yes/No option, which maps back to numeric values 1 and 0 respectively.
    • True/False - Users are presented with a True/False option, which maps back to numeric values 1 and 0 respectively.
    • Table/Key/Text Lookup - Click the 'Wizard' button to help guide the selection of the lookup values. Or manually, you can specify a table, the key column, and text value column to use for the list values in the Lookup Source field in the item definition. For example, if you enter tblCustomers;CustomerID;Customer Name in the Lookup Source field, Vivaldi will look for unique values in tblCustomers and display the Customer Name, while the user's selection will be written to your database using the CustomerID value.
      List Source Example
      • Advanced Tip: You can add another semi-colon (;) and follow it with a SQL Where statement to further filter the results.
    • Key/Text - You can specify a list of key and text values in the Lookup Source field in the item definition. For example, if you enter 1;Florida;2;Georgia;3;Nova Scotia in the Lookup Source field, Vivaldi will display the options Florida, Georgia, Nova Scotia. When the record is edited/inserted, it will write 1, 2, or 3 to your table depending on which the user has chosen.
    • Function - You can enter one of several pre-built functions into the List Source field:
      • fGetCountryList - Displays a list of countries, and stores the 2-character country abbreviation code.
      • fGetStateList - Displays a list of US states, and stores the 2-character state abbreviation.
    Cascading Dropdowns
    Beginning with Vivaldi 2.4, you can define a dropdown field that is dependent upon the value of another field on your form. For example, if you have a dropdown for "Company" and then one for "Employee" and you want the employee dropdown to only show records related to the selected company. To do make your dropdown a child of another, select the parent field in the "Dropdown Parent" property for your child dropdown. Then, specify the field in your child dropdown "List Source" that must be filtered by entering that field name in the Child Filter column property.
    In the prior example, your child dropdown would indicate that the Customer is the Dropdown Parent, and the child filter field might be fk_customerid if that is the field in the employees table that ties employees to customers..
    Buttons can be placed on Table and Detail forms. Use the Click Event Wizard, or enter your own javascript in the Click Event property. You can also use the "Form Help" property to provide help tooltip text for users when they hover over the button.


    Detail Form Options

    Form Events

    Beginning with Vivaldi 2.4, you can specify what javascript function(s) to execute at the following points of the form lifecycle: after record fetch, after insert, after edit, after delete.  The javascript function(s) you specify in the Events tab of the Form Designer must end with a semi-colon (;) to avoid javascript errors that prevent further form processing. Form event options include:

    • Before Save - Occurs before a record is added/updated. Use javascript convention of 'return;' to halt the insert/edit operation if desired.
    • Before Delete - Occurs before a record is deleted. Use javascript convention of 'return;' to halt the delete operation if desired.
    • After Read - Occurs after the form data has been read from the server.
    • After Insert - Occurs after a new record has been inserted.
    • After Edit - Occurs after a record has been updated/saved.
    • After Delete - Occurs after a record has been deleted.
    Default values

    You can specify a default value for any field, or enter the following default keywords which are automatically populated at runtime.  Click the Wizard button for assistance, or enter the following text values (in bold) into the text box:

    • Current User - The username of the logged in user
    • Current Date - The current date in yyyy-mm-dd format
    • Current Datetime - The current date and time in yyyy-mm-dd hh:mm am/pm format

    Table Form Options

    Calculated fields

    You can add calculated fields to Table forms in the "Table-Specific Settings" panel.  The syntax you must use is: row.Fieldname and then any arithmetic you want to apply.  The fieldname should be the table field rather than the caption you use.  For example:  row.ItemPrice * row.Quantity will result in a multiplication of the fields ItemPrice and Quantity.  You can use common javascript notation for things like toFixed() to cast the results to the desired type and precision. You can also perform operations like concatenate on text. For example: '<a href="' + row.yoururl + '"'> + row.yourlinkdisplayname + '</a>' would concatenate the static text with a database field value to create a URL.

    Beginning with release 2.2, Vivaldi also supports if() {} statements in calculated fields.  For example: if(row.Quantity==4) {return 'Something';} else {return 'Another';}

    Inline Editing

    Beginning with version 3.3, Vivaldi supports the ability for users to edit values directly within your tables for text, number, and date values. To enable inline editing:

    1. Check the 'Inline Editing' option in the Form Properties.
    2. Set any text, number, or date fields you do not want to be editable to 'Read Only' in the Form Item properites.
    3. Ensure any editable fields are bound to a field in your Base Table form.
    4. Ensure that the 'Disable Scroller' is checked in the Form Properties 'Table Options' section (inline editing and the scroller feature are not compatible).
    Large Data Sets and Paging

    Vivaldi uses a feature that progressively renders data for large datasets. Beginning with version 3.3 this feature, Scroller, is enabled by default. In some cases, you may want to disable the feature, most specifically if you want text to wrap inside the table cells, or to enable inline editing within the table. The option is a checkbox in the Form Properties 'Table Options' section.

    Special Formatting Options

    There are several special CSS classes you can employee for Table Forms. Add special CSS classes in the Form Item properties.

    • tablelink - Displays the cell text as a hyperlink with underline and cursor hover.
    • truncate-sm - Truncates cell text after 15 characters. Text is still exported and visible when the user hovers
    • truncate - Truncates cell text after 30 characters. Text is still exported and visible when the user hovers
    • truncate-lg - Truncates cell text after 45 characters. Text is still exported and visible when the user hovers
    • truncate-xl - Truncates cell text after 150 characters. Text is still exported and visible when the user hovers
    • col-centered - Displays text centered in a column
    Export Buttons

    You can disable the ability to export data to Excel or PDF by unchecking the options in the Form Properties 'Table Options' collapse.

    Refresh Data

    You can enable the ability to refresh table data via a button at the top by checking the option in the Form Properties 'Table Options' collapse.

    Search by Keyword

    You can disable the ability to search by keyword by unchecking the options in the Form Properties 'Table Options' collapse.

    Granting Permissions

    In the Permissions panel, you can decide which Roles have access to your form, and whether they can insert/edit/duplicate/delete records.

    1. Select 'New' in the Permissions panel.
    2. Choose a role in the Permissions popup dialog.
    3. Choose the form you want to grant permissions to.
    4. Select whether the user has View, Insert, Edit, and/or Delete permissions.  Note that View is not inherited when a user can insert/edit/delete.  You will need to grant View for the user to see the form in the first place.

    Note:  If the form is not configured to allow an action, users cannot perform that action even if they have been granted permission for it.  For example, if you set "Delete Records" to "No" for the form, and a role has "Delete" set to "Yes," users won't be able to delete record unless you set the form to allow deletes.

    Copying Forms

    You can copy a form from within the Form Designer by selecting the "Copy form" option at the top-left of the screen below the form name.  When you copy a form, you specify the copy name as well as whether you want to include the related role permissions for the original form.

    Next:  Creating Master-Detail Forms