Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Tip

Looking for a section on this page? Hover your cursor over the Table of Contents icon  to the right to quickly navigate this page.

...

The database connector maps between HTTP requests issued from frevvo forms to SQL queries executed against your database. The connector enables you to use the database of your choice to save and load your form data. You can create a new database or you can automatically generate forms that connect to your existing database tables to save and load data. The database connector contains working sample databases with some test data. The BIRT (ClassicModels) and myStore querySets are preloaded with in-memory Derby databases. We will use the in-memory databases to successfully complete this tutorial.

...

Download the Database Connector Tutorial project. This project contains all of the example forms used in this tutorial. This download is a frevvo project zip file that you can upload into your user account. See Project Home Page documentation for more information on uploading this project zip file.

...

The database connector maps between HTTP requests issued from and frevvo and SQL queries. It is important to understand how HTTP URLs map to SQL queries in the database connector. The above query returns a resultset that contains data as shown below:

frevvo forms work with XML or JSON data. You can test the above query using the URL: http://localhost:8082/database/BIRT/allCustomers. This should return an XML document with customerNumber and customerName for each customer as shown below. The DB connector has converted the SQL data into a format that is usable by   forms frevvo  forms.

Let's take a closer look at this URL.

...

The connector is also capable of returning JSON data. Try the URL: http://localhost:8082/database/BIRT/allCustomers?_mediaType=json the connector will return the same data as JSON. frevvo forms can use JSON data in business rules for dynamic behavior.

...

  1. if (form.load) - this implies that the rule will execute when the form first loads.
  2. eval ('x=' + http.get('http://localhost:8082/database/BIRT/allCustomers')) - this causes an HTTP GET to be issued to the indicated URL. When invoked in the context of a rule, the media type is automatically set to JSON. As we saw above, the database connector will return the list of customers as a JSON object.

    Info

    For the Standalone bundle with  Cloudwith frevvo Cloud, replace localhost:8082 with "app.frevvo.com" in the UR


  3. The rest of the rule is just JavaScript. We create an array of options in the format value=label (e.g. 242=Alpha Cognac) from the data returned in the JSON.
  4. Finally, we set the options of the dropdown to the array of options using the name we chose earlier (sc).

...

Since order details is a complex structure (product name, quantity, price etc.) we will use frevvo's built-in XML features to generate controls and populate them from the database. When an order is selected, the order line items will be displayed as shown below:

...

The database connector can generate an XML schema from any query's <retrieve> operation. This schema can then be used to generate a frevvo form.

  1. In a browser go to the URL: http://localhost:8082/database/BIRT/orderDetailsByOrder/schema?onum=10100 Save the resulting XML schema file to disk. Note that we need to pass in a known order number so that the query can successfully execute.
  2. Upload the schema to frevvo. See Data Sources for instructions.

...

  1. Make a copy of the form from Example 2 above and open it for editing.
  2. In the properties panel on the left, open the Data Sources pane by clicking on it.
  3. Click 'New from XSD'.
  4. You should see your schema in the resulting dialog box. Expand it and add the 'orderDetailsByOrder' element to the form by clicking the + icon next to it.
  5. Close the dialog box by clicking X in the top right corner.
  6. In the Data Sources pane, click the + icon next to the orderDetailsByOrder data source. frevvo will generate controls in the form.
  7. You can drag and drop to re-arrange as you wish.
  8. Change the label of the Section named 'row' to the string '{product}'. We'll explain this in more detail below.
  9. Collapse this Section.

This step generates controls that are bound to the orderDetailsByOrder data source by frevvo. You can render the controls as you wish but frevvo will always generate an XML document conforming to the XML schema above.

...

  1. Go to the Settings mode in the Guided Designer navigation bar.
  2. Select the Document Actions tab and the Send Data sub-tab.
  3. Select Manually set document URIs.
  4. You should see the Document name change to 'orderDetailsByOrder', which is the data source we are interested in.
  5. Set the URL to: http://localhost:8082/database/BIRT/orderDetailsByOrder?onum={so(for standalone bundle with  Cloudwith frevvo Cloud, replace <server:port> with app.frevvo.com.)
  6. Set the Read method to GET.
  7. Save the form.

This step indicates to frevvo that the 'orderDetailsByOrder' document is linked to the above URL via the READ method GET. frevvo will issue an HTTP GET request to the above URL and if an XML document conforming to the schema above is returned, frevvo will automatically initialize controls in the form using that document.

The URL itself is a dynamic URL and has a parameter indicated by {so}. Remember that we have a control in the form named 'so' (defined in this step Modifytheform. When the value of the control named 'so' changes (which will happen when the user selects a particular order),   will frevvo will automatically issue an HTTP GET to the above URL using the new order number and will dynamically update the order details including creating new line items, removing old ones etc. without refreshing the form as shown in the picture below.

...

Let's understand this query. We specify a <retrieve> operation (SELECT statement) in order to generate an XML schema/form controls. When the form is submitted, frevvo generates an XML document for those controls. The XML document is used to execute the <create> operation, which INSERTS the data. We have simply hard-coded a known order number for the example but you can use any query that generates a result set with the desired columns.

...

Code Block
<xsd:element name="row"> 
  • Upload the schema to frevvo. See Data Sources for instructions.

...

  1. Make a copy of the form from Example 1 and open it for editing.
  2. In the properties panel on the left, open the Data Sources pane by clicking on it.
  3. Click 'New from XSD'.
  4. You should see your schema in the resulting dialog box. Expand it and add the 'createOrder' element to the form by clicking the + icon next to it.
  5. Close the dialog box by clicking X in the top right corner.
  6. In the Data Sources pane, expand the createOrder data source by clicking on the + icon to the left.
  7. Click the + icon next to the row element. frevvo will generate controls in the form.
  8. You can drag and drop to re-arrange as you wish.
  9. Rename the Section named Row to Order Info.

This step generates controls that are bound to the createOrder data source by frevvo. You can render the controls as you wish but frevvo will always generate an XML document conforming to the XML schema above.

...

  1. Click the Rules mode in the Guided Designer navigation bar.
  2. Click to create a new rule. 
  3. Set the Name to 'Copy customer number and generate an order number'.
  4. Click Rule Code then click Edit Code to open the rule editor.
  5. In the Rule text area: copy and paste the following:

...

  1. Go to the Settings mode in the Guided Designer navigation bar.
  2. Select the Document Actions tab and the Send Data sub-tab.
  3. Select Manually set document URIs.
  4. You should see the Document name 'createOrder', which is the data source we are interested in.
  5. Set the URL to: http://localhost:8082/database/BIRT/createOrder (for standalone bundle with frevvo Cloud, replace <server:port> with app.frevvo.com.)
  6. Leave the Read method empty.
  7. Set the Write method to POST.
  8. Save the form.

This step indicates to frevvo that the 'createOrder' document is linked to the above URL via the WRITE method POST. When the form is submitted, frevvo will issue an HTTP POST request to the above URL sending the createOrder XML document in the payload. The database connector will map this to the <create> operation of the createOrder query that we defined above, will use the data in the XML document to resolve the query (replace {cnum} and {onum} with values from the XML) and perform the INSERT.

...

  • In your browser go to the URL: http://localhost:8082/database/BIRT/createOrderDetail/schema Save the resulting XML schema file to disk.
  • Upload the schema to frevvo. See Data Sources for instructions.

...

  1. Make a copy of the form from Example 4 above and open it for editing.
  2. We can hide the Order Info section since it does not contain information entered by the user. Select the section by clicking on its header and uncheck the Visible checkbox in the properties pane. The entire section should gray out.
  3. In the properties panel on the left, open the Data Sources pane by clicking on it.
  4. Click 'New from XSD'.
  5. You should see your schema in the resulting dialog box. Expand it and add the 'createOrderDetail' element to the form by clicking the + icon next to it.
  6. Close the dialog box by clicking X in the top right corner.
  7. In the Data Sources pane, expand the Create Order Detail data source by clicking on the + icon to the left.
  8. Click the + icon next to the row element. frevvo will generate controls in the form. Note that frevvo automatically generates a repeating element since a single Order can contain any number of line items.
  9. You can drag and drop to re-arrange as you wish.
  10. Rename the Section named Row to Order Line.
  11. Name the repeat control OrderLines. Take note of the "s" in the name.
  12. Select the Product Code input control. In the properties panel:
    1. Set the name to pc. 
    2. Select Dropdown from the Display As property list.
  13. Select the Onum control inside the Order Line section and in the properties pane set the name to olonum. Uncheck the Visible property.
  14. Select the Order Line Number control inside the Order Line section and in the properties pane set the name to oln. Uncheck the Visible property.
  15. Set default values in the Onum and Cnum controls inside the Order Info section and in the Onum and Order Line Number controls inside the Order Line section. You can set any values since we will be overriding them in a rule. We need to set a default value otherwise frevvo will gray out the Submit button and the form cannot be submitted.

This step generates controls that are bound to the createOrderDetail data source by frevvo. You can render the controls as you wish but frevvo will always generate an XML document conforming to the XML schema above. Here's what our form looks like:

...

When the form is submitted, frevvo will issue an HTTP POST request to the above URL sending the createOrderDetail XML document in the payload. The database connector will map this to the <create> operation of the createOrderDetail query that we defined above, will use the data in the XML document to resolve the query. Since there are multiple line items, the query will be executed once for each Order line item thereby inserting the multiple line items for an Order.

...

Code Block
<xsd:element name="row"> 
  • Upload the schema to frevvo. See Data Sources for instructions.

...

  1. Make a copy of the form from Example 1 and open it for editing.
  2. In the properties panel on the left, open the Data Sources pane by clicking on it.
  3. Click 'New from XSD'.
  4. You should see your schema in the resulting dialog box. Expand it and add the 'customerCreditLimit' element to the form by clicking the + icon next to it.
  5. Close the dialog box by clicking X in the top right corner.
  6. In the Data Sources pane, expand the customerCreditLimit data source by clicking on the + icon to the left and expand the row element.
  7. Click the + icon next to the cnum and creditLimit elements. frevvo will generate controls in the form.
  8. You can drag and drop to re-arrange as you wish.
  9. Hide the cnum element by unchecking the Visible checkbox in the properties pane.

...

  1. Go to the Settings mode in the Guided Designer navigation bar.
  2. Select the Document Actions tab and the Send Data sub-tab.
  3. Select Manually set document URIs.
  4. You should see the Document name 'customerCreditLimit', which is the data source we are interested in.
  5. Set the Read and Write URLs to: http://localhost:8082/database/BIRT/customerCreditLimit?cnum={sc}
  6. Set the Read method to GET.
  7. Set the Write method to PUT.
  8. Click Submit.

This step indicates to frevvo that the 'customerCreditLimit' document is linked to the above URL via the READ method GET and the WRITE METHOD PUT. frevvo will issue an HTTP GET request to the above URL and if an XML document conforming to the schema above is returned, frevvo will automatically initialize controls in the form using that document. The URL itself is a dynamic URL and has a parameter indicated by {sc}. When the value of the control named 'sc' changes (which will happen when the user selects a customer), frevvo will automatically issue an HTTP GET to the above URL using the new customer number and will dynamically update the values of the credit Limit and cnum controls without refreshing the form.

When the form is submitted, frevvo will issue an HTTP PUT request to the above URL sending the customerCreditLimit XML document in the payload. The database connector will map this to the <update> operation of the customerCreditLimit query that we defined above, will use the data in the XML document to resolve the query (replace {creditLimit} and {cnum} in the query with the actual values from the XML document) and perform the UPDATE.

...