Basic Attributes

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.

Confirmation/Query Condition

Confirmation Condition PHP Code

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

Condition Wizard

If you're new to using conditions, or simply want to have RackForms generate the condition code for you, the wizard is a fast and easy way to do so. To create a confirmation condition, simply follow the wizard from top to bottom.

Start by mousing over the This Field: select item. All fields in your form will display, select the item you want to base the condition on.

Please note if we select a Checkbox field an additional select item will display, Having This Checkbox Value (optional):. This select item will display all possible values for that checkbox. Select which value you want to base the condition on. When you do, the condition process is complete.

For all other fields, the next step is to set the Must: field. This will take the value of Equal or Not Equal, and several others.

Finally, type into the This Value: box to set which value the form field we selected above will validate against.

If you want to add additional conditions, such as a name must be Equal to Steve and age less than 10, first select the Additional Condition button and start from the top of the wizard again.

Hand Coding Conditional Code

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 Condition 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.

Using Array Based Form Elements (Checkboxes)
PHP Treats checkbox items a little differently than other elements. The good news is the only element that needs this special attention is a checkbox field. The difference then, is that in order to use checkbox items we need to place an index indicator just after the form field name.

For example, lets say we have a checkbox field with the Name/Value: email_condition, and it has two elements: Recipient A and Recipient B

To process this field in our condition statement we append the proper index in the format of [index-number]. It's quite simple when you see it in practice:

#{email_condition[0]} == 'Recipient A'

#{email_condition[1]} == 'Recipient B'

Please note the [0] and [1]. These are the index positions of the field being checked. Compare this to a standard field token:

#{email_condition} == 'Recipient A'

A checkbox group has several items, the [0] and [1] bit tell RackForms which number item to grab.

How do we know which number to use? In our example the checkbox field has two values, and array indexs start with 0. Thus, the first field, Recipient A, is [0], and Recipient B is [1].

The rule then is our numbering simply adds 1 for every checkbox item in the group, and always starts at 0.

HTTP Request

Request Method

cURL GET - This request type uses the cURL library to perform GET request. Depending on your web hosting provider, you may need to use this method over the GET via file_get_contents()

cURL GET + Headers - This request type uses the cURL library to perform GET requests that return HTTP headers. RackForms will use this header information to automatically detect errors. RackForms will die() if the HTTP request returns anything other than 200 status.

cURL POST (Supports File Uploads < PHP v. 5.5) - Performs an HTTP POST request via the PHP_CURL extension. POST Requests are considered safer, more flexible, and a smart choice for communicating with Web Services over GET via file_get_contents() requests.

Please note that cURL post requests require that you supply a value to the Success Code box detailed below.

This method supports multi-part file uploads using PHP's CURLFile. When file items are present, they are sent to the endpoint via this API. Please note, however, this is only supported on versions of PHP that contain the CURLFile class, which means PHP 5.5 or higher.

cURL POST + Headers - Performs an HTTP POST request via the PHP_CURL extension that returns and evaluates HTTP headers. RackForms will die() if the HTTP request returns anything other than 200 status.

SOAP Request - Performs a SOAP HTTP request to the WSDL URL you specify. Form the requester side, SOAP requests are very good at taking an XML response and turning it into a native language Object, which can then be modified at will. From the Web Service creators side, SOAP requests can be tightly integrated into a structured programming environment. For example, you can take a PHP class and create a WSDL file based on that class.

Please note that SOAP requests use a different set of parameters in the RackForms editor, which are located at the very bottom of the HTTP Request field items. Also, SOAP parameters are prefixed with SOAP.

cURL + Raw XML & cURL + Raw JSON - These request are unique in that unlike many of the others, we send raw XML or JSON via an HTTP cURL request, along with the proper HTTP Header for each data type. This can be very useful for many types of processes such as payment processing.

One key item to note is if we're responsible for retrieving the content of such a request, we'll need to pull from PHP's input stream as:

$postXML = file_get_contents('php://input');

Or more verbosely and to the stout/console as:

syslog(LOG_NOTICE, stream_get_contents(fopen("php://input", 'r+' )));

We can then process the JSON or, in this case, XML, using classes like SimpleXML as:

$postXML = file_get_contents('php://input');

try{
    $xml = new SimpleXMLElement($postXML);
} catch (Exception $e){
    echo 'ACI Response Was Not Well Formed XML.';
    exit();
} 

Treat POST Method File Uploads As

This option determines how file upload data is processed when using one of the two POST Request Methods. The default is to treat file upload data as a simple POST field. This is a very common method, as it treats file data the same as any other field.

If we're running PHP 5.5 or higher, we can also use Multi-Part Data. This method uses PHP's CURLFile class to treat file upload fields as multi-part form data. This is how upload data is treated when we POST a form in the traditional sense, and may be required for some web service providers.

HTTP URL

The URL of the HTTP Request. For GET via file_get_contents this can be a file path path or fully qualified URL. For All other methods, this must be a full qualified URL.

Caution: If using GET via file_get_contents, if used with a local file path you'll return the raw file contents, not the processed file as a web server would return. This could be used to return sensitive information such as passwords and logins.

To use a raw PHP variable, define said variable before the HTTP Request module, then use the standard in-line syntax of:

http://dev/{$var}

Tokens are much the same, only instead of using the braces outside of the variable name, we wrap the variable in the type qualifier, braces, variable name. For example, if we had the same variable above named $var, the token would be:

http://dev/${var}

For other tokens we'd simply replace the $ with the token type. POST variables would use P, GET G, and so on.

Query String (Formerly Field Variables)

The HTTP Request you send will generally need variables to make it perform some work for you based on the run-time values of those items. RackForms supports two types of variables: Raw Query String and Comma Delimited List. Let's take a look at each in turn:

Raw Query String

A raw query string is simply a block of formatted text composed of one or more name / value pairs. The format of these pairs is field name, an equal sign, and a value. We "join" multiple name value pairs together with an ampersand (&):
&name=Matt&email=info@sample.com

Our job as a consumer of a web service is to create and pass this query string using the values and format understood to the service. The web service we're calling will contain this information, usually in the form of an API documentation page.

Of course a web service wouldn't be of much use if we didn't have control over the value component of the name / value pair. Thus, in RackForms we create the raw query string by using dynamic tokens. We use the tokens as replacements for any field component we wsh to be dynamic. For example, if we had a form fields called name, email and we wished to use those as field variables, we'd use the F{} token:

name=F{name}&email=F{email}

The main benefit of this method is we have 100% control over the query string. This is in contrast to the Comma Delimited List method, where the name component is created for you.

Comma Delimited List

The second method of providing values is with a Comma Delimited List. In this method we simply supply a list of PHP or Form Field tokens. The main difference between this and the Raw Query String method is in the Query string method you're responsible for creating the name value pairs in the correct format.

In this method we simply supply a list of field elements to pass to the query and RackForms builds the query string for you. It's key to note the output, as far as the web service is concerned, is the same -- a query string. The critical tradeoff however is the list method doesn't allow us to define the name part of the name value pair.

That is, RackForms will simply take the name of the field token and use that as the name element of the name value pair. For example, if we used: F{name}, the resulting string would be: name=F{Name}

To ease in development time use the Dynamic Variable Picker to display a valid list of field elements and their variable names for you.

Regardless of which method we use to populate the Field Variables box, as an example let's say in our RackForms form we have two text fields that have Name/Values of <name> and <age>. We would thus set the value of the Field Variables as:

name,age

RackForms will then process these variables at form submission time and send the result using the Request Method you specify. Of course to save you work RackForms automatically creates a URL Encoded string for you using the field name + dynamic values. For example:

http://www.rackforms.comexample.com?name=matt&age=31

PHP Variables

We can also supply the Field Variables list with local PHP variables. To do so we insert the PHP variable name without the dollar sign wrapped up in a token in the format of:

${php_variable_name}

For example, let's say I create a PHP variable like so and place it into the Page PHP Top Code text box: ** (please see note 1 just below)

<?php
$text1 = 'tester text 1';
?>

To retrieve this variable at run time, I would use the following text in my Field Variables text box:

${text1}

Notice we do not use a dollar sign in the variable name e.g., we use ${text1} not ${$text1}

Other Variables

Starting with Build 677, we can now use the full compliment of RackForms tokens to populate our variables list.

** Note 1 - Using the Page PHP Top Code box is very important when dealing with the HTTP Request module because by default, the PHP code you type into the other main PHP code box, Page PHP Head Code, is placed after the HTTP Request code. That means in order to use PHP variables with the HTTP Request module in the Field Variables list, that code must be placed into the Page PHP Top Code box.

$raw = file_get_contents('php://input'); // get raw input stream data
echo $raw; // print it out

// JSON To PHP Object
$obj = json_decode($raw);

if($obj != null){
  
  echo 'Raw value of RF_JSON Token';
  var_dump($obj);

  // Pull zip field from result
  echo 'Postal/Zip Code Field Value From RF_JSON' . $obj->postal_code;
  
} else {
  
  echo 'No RF_JSON Data Present, Skipping.'; 

}

Success Code

Please note this is a required field for the cURL methods. This means even if your HTTP Request does not return a value, you still need to supply one. A simple '1' (without quotes) will do as a dummy value.

On Success: $response = success code

On Fail: $response != success code

Sample Code 1
if($response == 1) {
  echo 'pass';
} else {
  echo 'fail';
}

In the example above, we can see that if the $response variable, which is the internal value of the GET or POST request response, is equal to 1, the script echo's 'pass' to the page, or 'fail', if not.

Custom Request Response Logic

For example, we could simply copy/paste the code example from above:

if($response == 1) {
  echo 'pass';
} else {
  echo 'fail';
}

Into our Custom Request Response Logic box and when run, this will be the code that is executed by PHP immediately after the HTTP request finishes.

Show Debug output

This option will show raw request information on the form page.

cURL: URL Encode cURL Variables/Request

This option will URLEncode your cURL request variables when using cURL GET or POST, and the entire request when using cURL + Raw JSON/XML. For raw requests this option is usually not needed, but could be helpful in some cases.

cURL: SSL Verify Peer

This security option may be needed when connecting to some hosts.

Custom cURL Options Code

This code block applies a cURL header to your request. The format of this code differs based on which Request Method we're using.

For all types except cURL + Raw XML and cURL + Raw JSON, we use curl_setopt calls in the form of:

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password'); // Your credentials here

In this example we're adding an authorization header as defined here. Note the use of the $ch variable. This is the main container RackForms uses for such calls, and must also be used in any custom header calls you create.

For cURL + Raw XML and cURL + Raw JSON we MUST start our code with a comma (,), followed by a comma-delimited list of string items. For example:

,
'Content-length: 0',
'Authorization: OAuth ' . $accesstoken

Be aware: these two methods send custom headers matching the data type they're sending, and thus may not work with custom headers like Authorization.

Also be aware that we cannot define variables in cURL + Raw XML and cURL + Raw JSON mode, we can only access them. Thus, in our example above we take it to mean $accesstoken has already been defined.

SOAP Options

SOAP WSDL URL

SOAP Method Name

If you're unsure of the method names the service defined in the SOAP WSDL URL supports, you can always toggle on SOAP Debug: Show Functions (see below) to echo out the list of functions this service returns. That said, we still need to place some text in this field, as if left empty it will cause a PHP error.

SOAP Parameters

Updated in Build 706, internally we now pass the name of the parameter as well as its value. This means the SOAP service MUST use named parameters, and those in turn MUST match the Name/Value property of the RackForms form element being used as the driver for that parameter.

For example, if your SOAP call requires a parameter of symbol, we must use that as the Name/Value property of the form field.

Custom SOAP Response Logic

$soap_response

These names generally follow the convention of using the same name as the SOAP method being called plus the word 'result'

So for example, in the SOAP demo in the Load Example Job menu of the RackForms editor, the method we call is:

GetQuote

Which means the XML string property we call for $soap_response is:

GetQuoteResult

Knowing this function name is the key to processing the XML result. If in doubt, check the WSDL file!

$soap_xml

This is because it appears PHP will not always properly parse the XML string being returned, which means any xpath calls will subsequently fail.

The problem seems to be the < > characters are not processed and instead set as non-entities. It is for this reason we have the $soap_xml_fixed variable, detailed below.

Regardless, if it's the raw value we need use $soap_raw or $soap_raw_fixed. If we want to use a SimpleXML object instead and we're sure it's been processed correctly by PHP, use this guy.

$soap_xml_fixed

$client->__getLastResponse()

The end result is xpath calls will not work, meaning we cannot access our return data.

This variable thus runs a str_replace() on the data before being run against SimpleXMLElement(). This should fix any of our string problems and return a fully-functional SimpleXML object.

We can then use this object to perform xpath queries against, or any other operation where we manipulate and read XML data.

$soap_raw

As such, this means it's also the most challenging to work with, as we'll need to call any needed registerXPathNamespace() functions on our own. The upshot of course is this may be needed for more complex result processing.

As an example of what's required for working with such raw data, lets assume the following XML return value:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.rackforms.comw3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.rackforms.comw3.org/2001/XMLSchema">
  <soap:Body>
    <GetQuoteResponse xmlns="http://www.rackforms.comwebserviceX.NET/">
      <GetQuoteResult>
        <StockQuotes>
          <Stock>
            <Symbol>IBM</Symbol>
            <Last>172.24</Last>
            <Date>5/12/2011</Date>
            <Time>4:02pm</Time>
            <Change>+2.74</Change>
            <Open>169.43</Open>
            <High>172.77</High>
            <Low>168.65</Low>
            <Volume>5142809</Volume>
            <MktCap>208.6B</MktCap>
            <PreviousClose>169.50</PreviousClose>
            <PercentageChange>+1.62%</PercentageChange>
            <AnnRange>120.61 - 173.54</AnnRange>
            <Earns>11.911</Earns>
            <P-E>14.23</P-E>
            <Name>International Bus</Name>
          </Stock>
        </StockQuotes>
      </GetQuoteResult>
    </GetQuoteResponse>
  </soap:Body>
</soap:Envelope>

The first thing to note is the use of namespaces in the XML file. This means we'll need to call registerXPathNameSpace() to create a link between the prefix and the namespace. Namespaces in SOAP responses are quite typical, and we'll need to have a good understanding of them as well as XPATH to make any headway in dealing with a raw response like the one above.

As a brief overview however, in this case, the proper entry point would be on the Default Namespace defined for GetQuoteResponse. We set the link to 'b', which means our xpath query becomes:

//b:Last

Which means: for the namespace b (which is an alias for http://www.rackforms.comwebserviceX.NET/), start at the current node and match at any point an element called Last. In this case, Last is the current stock price.

A typical PHP code block that performs this logic would be:

$fixed_xml = $client->__getLastResponse(); 
// fix the xml data  
$fixed_xml = str_replace('&lt;', '<', $fixed_xml);
$fixed_xml = str_replace('&gt;', '>', $fixed_xml);
// create the SimpleXML object...   
$soap_xml = new SimpleXMLElement($fixed_xml);
// register (alias) the namespace b to the GetQuoteResponse prefix
$soap_xml->registerXPathNamespace('b', 'http://www.rackforms.comwebserviceX.NET/');
// now use the b prefix to call Last  
$result = $soap_xml->xpath("//b:Last");
var_dump($result);

SOAP Debug: Show Functions

SOAP Debug: Show Returns

SOAP Debug: Show SOAP Method Call Errors

Socket Timeout

ini_set ( "default_socket_timeout", 60);

This is very important for debugging SOAP calls, in that in most default instances the server execution timeout limit will be reached before the socket_timeout, which means we never actually get errors returned from the SOAP Debug: Show SOAP Method Call Errors setting.

This is also a very handy way to speed up debugging of SOAP calls, as the default values of 30 or 60 for most servers are much longer than actually needed.

The default value for production forms should be 30 or 60, and a good debug value is 3. This value is in seconds.