Design Notes

These are notes you can input that help you and other production staff understand your confirmation elements logic and purpose. This text is never used in the live form in any way, it is only for internal development.

When using the Query module, you will most likely be talking to a database other than the one RackForms is installed on. Thus, the fields below are vitally important for making a connection to that external database.

Making this connection is the same as any other PHP->SQL interaction, in that you provide a DB Host, user name, password, etc. The only wrinkle is that RackForms offers a tiered connection model, with each tier providing a slightly different path to the final connection. This tier system ultimately speeds up and secures the development and deployment process, but you should take a few moments to understand how it works.

The RackForms Tiered Connection Model
The first tier is the default config.php file which is based in:
app/movefiles/config.php.

That means If you provide no values for the DB Connector file and DB Vendor, DB Host Name, DB Schema Name, DB User Name, and DB Password fields, then the config.php file in your job folder is used. However, this may not be what we need with an SQL+ job, as we may not always need to write to the RackForms database, which is what the config.php file connects to.

This is so because the connection values included in the 'default' config.php file originate from when you first installed RackForms on your server, that is, the connection information would be the same as your RackForms application.

This makes sense for the Simple SQL module, as the RackForms entry viewer runs on the same database as your RackForms application. However, with the SQL+ module you will have a much greater chance of needing to talk to a different database.

The second tier are the DB Vendor, DB Host Name, DB Schema Name, DB User Name, and DB Password boxes. If you place values in these fields the config.php is ignored and the values you set in those boxes used instead.

The third tier is the DB Connector File box. Placing a value in this box means we override the default config.php file, as well as any DB Vendor, DB Host Name, DB Schema Name, DB User Name, and DB Password settings. This is considered the 'safest' model, as we could effectively hide connection information from clients or less privileged production workers by restricting access to the connection file pointed to in this field.

To set up and use this method we must:

a) locate the "original" config.php file in app/movefiles/config.php
b) copy this file to the new location defined by the DB Connector File box
c) update the values in the config.php file to match the database being connected to.

Now when we run the job RackForms will consult the custom config.php file for database connection details. This can be especially handy as it means the user of the job in the RackForms editor doesn't need to know the database details, just the path to the config file.

To summarize: if you leave everything blank, RackForms will include and use the 'default' config.php file. If you place values in the DB Vendor, DB Host Name, DB Schema Name, DB User Name, and DB Password boxes, they will be used over the config.php file. Finally, if you include a value in the DB Connector File, the connection variables in that file will override all other values.

DB vendor

Choose the database vendor you will be connecting to for the dynamic query.

DB Host Name

The host of your SQL provider - could be 'localhost', an ip address, or a server/instance name.

DB Schema Name

The Database catalog you wish to query.

DB User Name

Database user name

DB Password

The password for this database connection.

DB Connector File

If you input a relative path in this box, RackForms will use that file for all database connection information for this query.This means you can 'secure' your forms by making sure access to important database information is limited to only those with access to this file.

To create your own DB Connector File, simply copy the contents of your existing config.php file from your /app/movefiles/ directory and paste it into a new file named what ever you like.

You will then need to change the values of the fields shown below to match the values of the datasource you wish to use:

$db_type = 'mysql';
$db_host = '127.0.0.1';
$mysql_socket = '';
$mysql_port = '';
$db_user = 'RackForms';
$db_pass = 'test';
$db_catalog = 'RackForms';

Now in the DB Connector File field place a path to the file you just created relative to your forms final destination. For example, by default all RackForms output is placed in:

RackForms/output/forms/

Which means if I placed my DB Connector file in:

RackForms/output/forms/config.php

My DB Connector File field would have:

../config.php

as this file would indeed be one directory up from my form, which if was called external_db, would be located at:

RackForms/output/forms/external_db

Now when we run the form RackForms will not use the config.php file located in the job folder (indeed, one will not even be created unless I have a File Upload module in my form that doesn't also have a DB Connector File specified), which means in principal, any users with access to the RackForms job folder will never see any database login info, and so long as they did not have access to the folder with the External DB Connector File, not see any DB information period.

Confirmation Condition PHP Code

This field allows you to specify a condition which must be met for the query field to be processed.

The logic takes the form of:

Variable 1 | Condition | Variable 2

For example, let's assume we have a radio item in our form with the Name/Value of opt_1. The radio item has two possible vales, 'Yes' and 'No'. If the value of opt_1 is 'Yes' we want to send an email, if no, we do not.

We would write the Confirmation/Query Conditional PHP Code as such:

#{opt_1} == 'Yes'

In other words, we use the token for our field variable like we would in other property boxes, that is, a pound sign (#) followed by the Name/Value of the field in braces. Recall that at run time this token evaluates to the value set by our forms users, which in this case will be the value of the radio button with the Name/Value of opt_1.

We then set the comparison, in this case out comparison is equal too, denoted with the double == sign. Finally, because we know our radio item is a string value that can be 'Yes' or 'No', we wrap the value we want to check for in single tick marks.

On the raw code side, RackForms wraps the token call in an isset() block, which is further wrapped in the proper PHP if() syntax:

if(isset($_SESSION['qs']["{$_SESSION['entry_key']}"]['opt_1']) && $_SESSION['qs']["{$_SESSION['entry_key']}"]['opt_1'] == 'Yes') { // condition code start

When run, if the users set value for the radio box was 'Yes', we would process this confirmation element.

Digital Signature Processing Enabled?

Defaults to Enabled, setting this to Disabled turns the module off.

Process This Signature Form Item...

Use this select item to choose the signature field we wish to process.

Enable Signature Simple Save Mode

This mode saves the contents of the signature field to a built-in database table. The idea here is using this method is similar to using Simple SQL. With no additional effort we save a complete signature.

Enable Custom SQL Save Mode

This mode is for users who wish to save the signature to a custom database table and location, possibly along side other data.

The key to this method is as described below in the Variables section, although we can save other fields the core signature data must be accessed via the variables:

entry_id, field_id, signator, signature, signature_image, sig_hash, ip, created

Of course we can call these variables anything we like, but the Variables field must use those names.

The good news is by default RackForms creates a fully functional INSERT block so you can see what a working example would look like.

Also key is by default RackForms always pulls the lastInsertID from this SQL call and saves it to a variable named the same as the field selected under Process This Signature Form Item.... This means we can pull this value out and use it in subsequent SQL+ logic, for example.

Custom Signature Save SQL

This is the SQL used to INSERT our signature.

Variables

As described above, key to using custom SQL is knowing that the filed's our signature is saved under must be accessed as:

entry_id, field_id, signator, signature, signature_image, sig_hash, ip, created

These are the only values that work for gathering our core signature data.

Of course because this field accepts other tokens as well, as can use any other tokens for non-signature data.

Working With Digital Signatures

So we have a digital signature we wish to capture and use for some document -- how do we incorporate a signature into a larger application?

The key point is deciding how we wish to use the signature. As far as the end-user is concerned this usually means showing them the digital signature module which allows them to sign a document. They do so and when they click submit, they have the implicit understanding that their signature is being used to tie them to the document.

But as a form creator we also have to do something with this signature for it to be of any use.

At the most basic level this can be to show the user thier signature via the SIG() token, which would usually be via one of the two compatible page PDF modules, DOMPDF or mPDF (please note as of this time TCPDF doesn't work with digital signatures), to show a printable version of the form to a user. In this instance then it's more about the user having a printed or archived copy of the signed document than us as form creators doing anything with the signature. To use this method we simply use the SIG token in a text field like so:

This is some text, and this is the signature image: SIG{sig1}

Where sig1 is the Name/ID of the signature field we wish to show.

Again, the key here is we're not saving or storing the signature, we're simply showing it to the user and then most likely, creating an automatic PDF of the page for easy printing.

While simple, this method has limited use for more complex scenarios. Thus, this method of using tokens comes up again in our second scenario, sending email.

Using Signatures With Email

When sending emails with signatures we have two main methods:

The first is to use a Simple Email module and checking the Include Digital Signature File Attachments? box to include any digital signatures as attachments to that email.

The second method is to once again use tokens, but this time in theEmail+ Email Message block. For example, we would use this to show the signature, inline, in the email:

Signature: SIG{sig1}

Again, this assumes the signature field we wish to show is named sig1.

What's great about this method is the signature is shown inline with the rest of the email body. This makes it very easy to create formal documents where the signature sits exactly where we want it to be.

Using Signatures With A Database

The second main way of capturing signarture data is with database tables. The advantage here of course is by saving signature data we can call up it at a later time as needed.

For SQL operations we once again have two opitons, though both use the Signature confirmaiton module:

The first is we use the Enable Signature Simple Save Mode option. Using this guy means a pre-installed database table called fb_digital_signatures will receive several columns worth of data. We save the signature image, hash, ip address, and many other fields.

The point being that for a signature to be legally acceptable we should capture all of the fields contained in the fb_digital_signatures table, and this method makes it very easy to do so.

This is brought up as the second main way of saving to a database is by checking the Enable Custom SQL Save Mode box. This guy allows us to save the signature fields to any database table we choose, and in any way.

Key here though is when we do so we must know the names of the fields we're actually capturing and are thus available for database operations. To help us in this task by default the Custom Signature Save SQL box contains all valid fields in a sample (though fully functional) INSERT code block. We can also click the Dynamic Variable Picker link under the Variables text area for a list as well. Their we'll see a subset of tokens under the Built-In Signature-Specific Variables: heading. All of these guys are available to us when saving signature data.

One very important point we have yet to cover though is how do we relate this signature data to a larger data structure?

Simple: Both SQL methods will attempt to return the lastInsertID of the signature INSERT operation. For Enable Signature Simple Save Mode this always works, as this table has an auto-increment Primary Key set by default.

For Enable Custom SQL Save Mode though we'll want to make sure the table we're sending the signature data to has one defined (a primary key that auto-increments).

So long as we have an auto-incrementing primary key defined RackForms will then return that lastInsertID value to a PHP variable named the same as the field being processed, which is itself defined by the Process This Signature Form Item... option.

Because we have a valid key value for the signature insert operation, we can now use that value as a foreign key for a subsequent INSERT operation via SQL+. We can see an example of this in the Digital Signatures > digital-signature sample job.