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:
... 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:
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:
... 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:
... 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:
... 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:
... 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 |
Ad Text
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
days | Total number of days the ad is scheduled to run. |
week_days | Number of week days in ad run. |
weekend_days | Number of weekend days in ad run. |
sundays | Number of Sundays in ad run. |
mondays | Number of Mondays in ad run |
tuesdays | Number of Tuesdays in ad run. |
wednesdays | Number of Wednesdays in ad run. |
thursdays | Number of Thursdays in ad run. |
fridays | Number of Fridays in ad run. |
saturdays | Number of Saturdays in ad run. |
not_sundays | Number of days the ad is running that are not Sundays |
not_mondays | Number of days the ad is running that are not Mondays |
not_tuesdays | Number of days the ad is running that are not Tuesdays |
not_wednesdays | Number of days the ad is running that are not Wednesdays |
not_thursdays | Number of days the ad is running that are not Thursdays |
not_fridays | Number of days the ad is running that are not Fridays |
not_saturdays | Number of days the ad is running that are not Saturdays |
Ad Height
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 been used 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.
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.
- 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
- By putting words – 25 inside () parenthesis, this forces this calculation to be executed first.
- 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
- 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”
