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

 

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. 

Example:

+6 
adowl_formula_price

 

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:

+6 
adowl_formula_words
  • 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
+6 
adowl_formula_wordsdiagram
  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

+6 
adowl_formula_lines

 

Days

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

+6 
adowl_formula_days

 

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.

+6 
adowl_formula_dayscomplex

 

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

+6 
adowl_formula_wratetable
  • 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”

Tags