QwkTrigger - Trigger Point Notification

QwkTrigger gives you the ability to define a variety of emails. These emails can contain various tokens that will be replaced with system data.

Tokens are a way to get dynamic data to be used in combination with static text under the control of the store administrator. You use tokens by placing the token string inside of percent signs. For example to display the value of a token named "test" you would type in %test%. There are five types of tokens: System Variable Tokens, Global Variable Tokens, Database Variable Tokens, Internal Tokens, and Command Tokens.

System Variable Tokens
These are tokens that have a name exactly the same as an existing Miva script system variable, and always start with "s." or "system.". These are usually values that are either generated on the server or sent by the user agent (usually a browser) in the HTTP request headers. For example to display the ip address of the person visiting the store you can use a token like %s.remote_addr%. Below are some examples of Miva script system variables but for a full list you should review the Miva script reference manual in the documentation section of Miva's website.

Global Variable Tokens
These are tokens that have a name exactly the same as an existing Miva script global variable, and always start with "g." or "global.". These are usually values that are passed in to Miva Merchant on the url or from a form post. This would include things like the product code added to the basket %g.product_code%, or it's quantity %g.quantity%. Or a special value you are passing to a new screen, or a value being set by another module, or a value being set internally in Miva Merchant such as the current cookie value. Here are some examples of global variables you can use as tokens.

Database Variable Tokens
These are tokens that have a name exactly the same as the name of a valid database variable name. These tokens start with the alias of the table then have a ".d." then the field name. The table must be opened at the moment the token is used, and have been opened by the alias you are referencing it by and the value you will get will be from the current record that the Miva engine is pointing to. These constraints make these tokens have a fairly limited use, but one example of a safe use is to call any data of the records for the current store in the stores table. For example to get the current store name you could simply do %stores.d.name%. Below is a list of all the valid database variables from the stores table. This table is always open and always pointed to the current store.

Internal Tokens
The most important tokens you can use though are the tokens that the software makes available to you. These are more complex than simple tokens because they are often lists of values, such as all the items in the current order, or all products in the store. These tokens don't always start with any particular value but are grouped into named groups and the format of these tokens is usually %group:token% where "group" is the name of a valid token and "token" is the name of a sub token of that token. For example you can use %basket:ship_zip% to get zip code the shopper has entered, if any. A full list of all internal tokens can be found in the section of this document titled Internal Tokens List.

Command Tokens
The power of Internal tokens becomes more obvious once you understand command tokens. Command tokens bound text and other tokens. Command tokens have a starting token and an ending token and everything inside the two is constrained in some way by the command token. The starting command token is prefixed with a "#" and the ending command token is prefixed with "#/". Thus a simple command token looks like this %#command%command area%#/command% where "command area" contains text and tokens that are affected by the command token. The only command token that can stand alone is the block command token, all other command tokens must be contained inside the command area of a block command. Here is a list of command tokens: block, head, foot, body, first, last, body_pre, body_post, and alt.

The block command token
The block command token is special among all command tokens in numerous ways. It is the only command token that accepts a parameter, it is the only command that can stand on its own without any other commands, and it is the only command that can contain any command token in it's command area and can be contained in the command area of any other command token's command area. That is, you can place a block in a block, an alt in a block, and a block in an alt, and all are meaningful, but placing an alt directly in a head, or a head directly in an alt is meaningless. The block command determines the data available to tokens inside it by reading a token name that is passed to it as a parameter. If the token has a value then the body of the command area is displayed, otherwise nothing is displayed, unless an alt command tag was used in the command area in which case the contents of the alt command token's command area is displayed. If that token happens to be a list of values, then the body of the command area gets displayed once per item in the list. Inside the command area for a block command the token that the block command read can be referenced as %:% and any sub tokens can be reference as %:subtoken%.

For example if you did %block basket:ship_zip%This is being shipped to the zip code %:%.%#/block%, if there was a value to the shipping zip code for the current shoppers basket the contents of the command area would be displayed, otherwise nothing would be displayed. Additionally you could have added an optional alt command token into your block command area and anything inside the alt command area will only be displayed if the body of the block command area is not displayed. Note that if the only command tokens used inside the command area are alt, head, foot, or another block, you don't have to place the body contents inside an actual body command token because the system will assume anything not nested in one of the other command tokens is part of the body. But if you are using body, first, last, body_pre, or body_post, the contents not inside a command token command area will be ignored.

Here is another example that demonstrates the use of the alt command.

%block basket:ship_state%
   This is being shipped to %basket:ship_city%, %:% %basket:ship_zip%.
   %#alt%
      We don't know where this will be shipped yet.
%#/alt%
%#/block%

Displaying Lists.
If the token past to the block command is a token that represents a list of values then the command area is used for each item in the list. Further you can use the head and foot command tokens to display something before and after the list if there is something in the list, first and last, to control display of the first item or last item in the list, body_pre, and body_post to control the display of something before and after each item in the list. Note: if you are using the first command the body_pre and body_post won't display for the that item, and if you are using the last command the body_pre and body_post won't display for the that item.

Here is an example of a token code that would display the full-size images for all products.

%block products%
   <img src="%:image%">
%#/block%

But what if some of the products don't have a full-size image? how do you stop it from displaying a broken image? You do that by using another block command inside the first block Like this.

%block products%
   %block :image%
      <img src="%:%">
   %#/block%
%#/block%

If you wanted to you could place an alt command token inside the inner block so that a default image was displayed if there was no image, or a bit of text could be displayed, or whatever you wanted.

Lists In Lists.
Some tokens that are lists will also contain sub tokens that are lists. a good example of this is the basket token which contains a token called item which is a list of items in the basket, and each item has a token called option that contains the options for the item. Here is a complex example of displaying the basket contents

%#block basket%
%#body%
   <table>
      <tr>
         <td>
            <b>Code</b>
         </td>
         <td>
            <b>Name</b>
         </td>
         <td align="right">
            <b>Price</b>
         </td>
         <td align="right">
            <b>X Price</b>
         </td>
         <td align="right">
            <b>Quantity</b>
         </td>
         <td align="right">
            <b>Total</b>
         </td>
      </tr>
      %#block :item%
         <tr>
            <td>
               %:code%
            </td>
            <td>
               %:name%
            </td>
            <td align="right">
               %:price%
            </td>
            <td align="right">
               %:item_price%
            </td>
            <td align="right">
               %:quantity%
            </td>
            <td align="right">
               %:line_price%
            </td>
         </tr>
         %#block :option%
            <tr>
               <td>
                   
               </td>
               <td>
                  %:data_long, :data, :opt_code, :attr_code%
               </td>
               <td align="right">
                  %:price%
               </td>
               <td>
                   
               </td>
               <td>
                   
               </td>
               <td>
                   
               </td>
            </tr>
         %#/block%
      %#/block%
      <tr>
         <td align="right" colspan="5">
            Sub Total:
         </td>
         <td align="right">
            %:subtotal%
         </td>
      </tr>
      %#block :charge%
         <tr>
            <td align="right" colspan="5">
               %:desc%:
            </td>
            <td align="right">
               %:disp_amt%
            </td>
         </tr>
      %#/block%
      <tr>
         <td align="right" colspan="5">
            Total:
         </td>
         <td align="right">
            %:total%
         </td>
      </tr>
   </table>
%#/body%
%#alt%
   Couldn't find session id %g.session_id%
%#/alt%
%#/block%

Remember %#alt%Data inside an alt only appears if there is no body data to display for the block%#/alt% and you can explicitly declare what should be in the body by wrapping it in a %#body%body command%#/body%, and if you use the body command you can then specify what is output in only certain cases such as %#body_pre%This will appear before each body is displayed, except the first/last one if you are using the first/last command.%#/body_pre% and %#body_post%This will appear after each body is displayed, except the first/last one if you are using the first/last command.%#/body_post%, and %#first%this will appear for the first record only%#/first%, and %#last%this will appear for the last record only%#/last%, and %#head%this appears before all the body data appears.%#/head%, and %#foot%this appears after all the body data appears%#/foot%.

Token blocks do not have to be on separate lines so if you want your final output to contain no line breaks or extra space you can run it all together with no gaps and the token parser will understand it just fine. For example if you were trying to dynamically generate a url that had a comma separated list of product codes ordered you could do it like this:

%#block invoice%http://www.4thebest.com/miva-script-examples/echo.mvc?order=%:id%&products=%#block :item%%#first%%:code%%#/first%%#body%,%:code%%#/body%%#/block%%#/block%

Here is a list of all available tokens.