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.

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, FormBoss 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 field Name/Value token.

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

To process this field in our condition statement we need to append the proper index of the field used for checking the condition using PHP array index format. It may sound confusing, but it's quite simple when you see it:

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

In short, the non-array way would be to simply use:

#{email_condition} == 'Recipient A'

But because we need to check an array index (again, because PHP treats checkbox items as arrays), we simply add the [0] part before the closing brace (}).

How do we know which array index to use (the number part)? In our example the checkbox field has two values; array indexs start with 0, so the first field, Recipient A, is [0], where Recipient B would be [1].

This numbering simply climbs up by 1 for every checkbox item you add.

Request Method
Choose between GET or POST and the type of request:

GET via file_get_contents(): This request method requires the allow_url_fopen .ini directive to be set to true. In some cases, your web hosting company may disable this feature for security reasons. Use your own discretion with this request type.

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. FormBoss will use this header information to automatically detect errors. FormBoss will die() if the HTTP request returns anything other than 200 status.

cURL POST - 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.

cURL POST + Headers - Performs an HTTP POST request via the PHP_CURL extension that returns and evaluates HTTP headers. FormBoss 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 requestors 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 FormBoss editor, which are located at the very bottom of the HTTP Request field items. Also, SOAP parameters are prefixed with SOAP.

HTTP URL: (fully qualified)
This is the URL of the HTTP Request.

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 variables. FormBoss supports two types of variables: Form Elements and PHP Variables. In both cases we input a comma delimited list of these field names and PHP variables to include them in your HTTP request as a URL encoded string. Let's take a look at each in turn:

Form Elements

Form elements will be the most common variable type given, simply because we are most likely going to be interested in sending the values our form user has supplied more than anything thing else. To ease in development time, you can always 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 FormBoss 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

FormBoss 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 FormBoss automatically creates a URL Encoded string for you using the field name + dynamic values. For example:

http://www.example.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 runtime, 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 FormBoss 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.

Success Code
FormBoss uses the value of this field to validate the status of your HTTP request though a simple boolean comparison. The result of this comparison determines what action path is followed: On Success or On Fail.

Please note this is a required field for the cURL methods. This means even if you're 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
If you supply a value to the Success Code field and the result of your HTTP request is equal to that value, this field will be processed. It is important to note the value of this field must be PHP code. See Sample Code 1 for an example.

On Fail: $response != success code
If the comparison between the Success Code and the HTTP request fails, the code in this field is processed, as your request has 'failed'. It is important to note the value of this field must be PHP code. See Sample Code 1 for an example.

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
If you provide any value in this box, this text will be used as the 'logic code' for any HTTP request, in that after the request finishes and the value of the HTTP request is passed into the $response PHP variable, this code will be inserted into your page and run by PHP.

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.

SOAP Options

SOAP WSDL URL
This is the url of the WSDL file you intend to query against.

SOAP Method Name
All SOAP calls must call a method, this is the name of the method you are calling. You do not need to include any text other than the 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
This is the comma delimited list of parameters you wish to pass to the SOAP Request.

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 FormBoss form element being used as the driver for that parameter.

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

Custom SOAP Response Logic
New to Build 706, this feature lets us add custom processing code to manage the SOAP response. This will not always be needed, but if so, we have four convenience variables created for us:

$soap_response
This value represents the stdObject automatically created for us by the PHP soap client. This object will typically hold one string property which is the processed XML of the SOAP response. The name of this property (and this is important!) is defined by the WSDL file of the web service being called. That is, if the web service returns a value, it will be defined in the WSDL file by name.

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 FormBoss 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 variable represents an attempt to instantiate a new SimpleXMLElement against $client->__getLastResponse(). Unfortunately the validity of this call may not always be acceptable.

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
As described above, PHP's SOAP implementation does not always seem to process the raw XML return data properly from a call to:

$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
This variable is set via a direct call to: $client->__getLastResponse(). Thus, it represents the purest form of SOAP response, in that no processing has been performed on the data.

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.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetQuoteResponse xmlns="http://www.webserviceX.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.webserviceX.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.webserviceX.NET/');
// now use the b prefix to call Last	
$result = $soap_xml->xpath("//b:Last");
var_dump($result);

SOAP Debug: Show Functions
So long as you have a proper SOAP WSDL URL defined, you can toogle this field on to return a list of valid method names. You can then use that list to properly query against the service.

SOAP Debug: Show Returns
Toggle this on to view the raw XML returned from the Web Service call.

SOAP Debug: Show SOAP Method Call Errors
This feature, introduced in Build 706, allows us to catch any method call errors. This is handy when debugging an newly created web service call, or when nailing down the parameters we're passing to it from FormBoss.

Socket Timeout
This feature, also introduced in Build 706, allows us to lower the servers socket timeout value via a PHP ini_set call of:

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.