### Formula Overview

The pricing of an ad is determined through the formulas configured for packages and upsells. The Ad-Owl engine calculates the formulas for the chosen package and all chosen upsells independently, and then totals the results of those formulas together to get the final result.

A formula is an equation built from predefined variables and common mathematical operations.

All paid packages must have a price and a statement to return price.  Packages that will be free or have the possibility to be free (ex. free base price with only additional words or upsells having a cost), should have the corresponding cost type (free or conditionally free) set within the package.

• Commenting is allowed in the formula Text Area of a package or upsell.  Common CSS format allowed:  ex:  /* Your Comment Here */
• All statements in formulas end with (;)  Semi-Colon
• A \$variable (PHP variable) is allowed but NOT recommended.
BEST practice is to use reserved UTL variables (listed below)
• Filtering is allowed ex.  (lines/ 3 | roundup);
• If the formula includes a calculation using cents, ex. \$0.25.
25 cents must be written as 0.25 with a leading Zero (0) or the formula will break.

### Expressions

An expression is a single mathematical operation involving two numbers and an operator between them. A formula may be built up from multiple expressions chained together.

Almost every type of operator is available for use in a formula. The most common are addition (+), subtraction (-), multiplication (*), and division (/). Notice that the multiplication operator is an asterisk, formed using Shift-8 on your keyboard.

An expression is entered on a single line and is evaluated by the Ad-Owl engine from left to right. Nothing else is required outside the expression itself. Thus, for the expression of "three times five" you would enter:

3 * 5

... into the appropriate formula box in your configuration panel. Ad-Owl will evaluate it and get the expected result of 15.

You can chain together larger expressions by appending them to each other. Thus the expression:

3 * 5 + 4

... would result in 19.

Certain rules of precedence should be observed when chaining together large expressions. In particular, it should be realized that multiplication and division operations are evaluated before addition and subtraction evaluations. So the expression:

2 + 4 * 3

... has a result of 14. This is because the 4 * 3 is evaluated first to get 12, which is then added to the 2.

You may force a different sequence of evaluation through the use of parenthesis. Anything within a pair of parenthesis will be evaluated before anything outside those parenthesis. So if the previous expression is rewritten as:

( 2 + 4 ) * 3

... then the result is 18, because the 2 + 4 is evaluated first to get 6 which is then multiplied by 3.

#### Commonly Used Allowed Operators

 Terse Style English Style Examples || or 5 || 6               5  or 6 && and 5 && 6            5  and 6 ! not ! 5                    not 5 = assignment operator price = 2; == Is days   == 1                     days is 1 != Is not color  != ‘None’              color is not ‘None’ % mod num   % 2                     num  mod 2 > greater than words > 25 < less than lines < 12 >= greater than equal to days >= 4 <= less than equal to days   <= 5 - minus (subtraction) words - 25 + plus (addition) 5 + 5 * asterisk (multiplication) 5 * 5 / forward slash (division) 4 / 2

### Variables

Various key statistics about the user's ad order, such as number of lines and number of scheduled days, are available to formulas through the use of variables. Use of a variable in a mathematical expression will result in that variable being replaced with the appropriate value at the time the formula is calculated.

For example, if you have a package configured with the following formula:

lines * 3.50

... and the user has built an ad which has 6 lines of text in it, then when the formula is calculated the variable \$lines will be replaced with the number 6, which will result in the expression:

6 * 3.50

... which has a result of 21. Thus, the cost of the ad before adding in any potential upsells is \$21.00.

Notice that the 3.50 above does NOT have a dollar sign before it. The Ad-Owl engine automatically assumes use of a dollar sign where appropriate. In your formulas you should use just the plain numbers.

### Formula Variables

The following RESERVED UTL variables are available for use in formulas. Variables are case-sensitive, so all variables MUST be lower case.

#### Pricing

 price Used for setting and retuning the price of the Ad

 lines Number of lines contained within the ad words Number of words contained within the ad chars Number of characters contained within the ad cap_words Number of capitalized words contained within the ad (corresponding to a style) bold_words Number of bolded words contained within the ad (corresponding to a style)

#### Days Variables

 height Height of ad in px height_px Height of ad in px height_pt Height of ad in pt height_pc Height of ad in pc height_in Height of ad in inches height_mm Height of ad in millimeters height_cm Height of ad in centimeters

#### Miscellaneous

NOTE: Dot notation is utilized

 save.set('VARIABLE', VALUE) Set a variable that can then be used in formulas processed later (upsells or packages) save.add('VARIABLE',VALUE) Add to an already existing variable (numbers only) save.get('VARIABLE') Retrieve an already existing variable order.field_data.CUSTOM_FIELD Retrieve data from a custom field that has beenused to create a custom layout. order.rate_table('rates/TABLE_NAME',lines , days ) Retrieve a price from a rate table by passing the lines and days.

### Formula Syntax (Examples)

#### Price

Every package or upsell that has a cost value being charged will have to set a price and return the price.

NOTE:  A package and Upsell can both have the variable price and as the user progresses these amounts will be added together.

Example:

#### Words

Example:  A package that has an initial price of \$10 for the first 25 words and then the user is charged 25 cents for each additional word.

Example:

• The first statement sets the initial price:   price = 10;
• The second statement starts the "if" conditional:  if words > 25;
If the number of words in the ad is greater than 25 words then execute the next statement
• The third statement will dynamically calculate the new price based on the number of words minus 25 words, and then charge 25 cents per word
1. By putting words – 25 inside () parenthesis, this forces this calculation to be executed first.

2. By enclosing (words – 25) * 0.25 inside parenthesis, this forces the result of (words – 25) to multiplied by 0.25 as the second step:  Example:  a user submits an ad with 27 words...
(27 words – 25 words allowed with the initial price) = 2, so the two additional words would be multiplied by the \$0.25...  2 * 0.25 = 0.50

3. This is what determines the final price:
price (final price) = original price (10) + the cost associated from additional words (2 * 0.25)

price = 10 + 0.50

so the price returned is 10.50

#### Lines

Example:  A package that charges an initial rate of \$10 for 4 lines and \$1 for every extra line

#### Days

Example: A package for \$10 for one day and charge \$5 for every extra day

#### A more complex example

Example: A package that starts out for \$10 for 10 lines.   0.50 for each extra line and \$8 for each extra day.

#### A formula with a rate table

Example:  A site has chosen to use a rate table that has been filed in with variable rate prices based on a number of lines and a number of days

• The price is set by using the value from the Line 1 and Day 1.
• If no initial price is set the front end user sees  “Your Free Ad”