Macro Tags Available Everywhere

[xxx] Tags that are Available Anywhere

The following tags can be used in any template file that WebCatalog displays. Additionally, if you have defined a SUFFIX-MAPPING and ACTION for WebCatalog to process .tpl or .HTML pages, then simply using a web browser to link to any .tpl or .HTML page on your site is equivalent to performing a ShowPage using that file as a template.

Depending on the preference settings, you may have to include  at the top of your files to indicate that WebCatalog should interpret the [xxx] tags inside the file.

Note: These are not containers, so they should not be followed by a corresponding [/xxx] tag.

[AUTHENTICATE Some Text]

Putting [AUTHENTICATE] in your template will cause the remote browser to display the Username/Password dialog, with whatever text you specify. When the visitor types a username and password into their browser, your templates can get that information by including the [USERNAME] and [PASSWORD] tags. Normally you put [AUTHENTICATE] inside [ShowIf] or [HideIf] contexts that compare the username/password, otherwise the password dialog will keep popping up forever.

Note: [AUTHENTICATE] is a low-level tool that requires some sophisticated knowledge to use, so most people use the simpler [PROTECT] tag to password-protect a page. You can see an example of how [PROTECT] makes use of [AUTHENTICATE] by reading the WebDNA in the file "MultiGroupChecker" on your hard disk (in the WebCatalog folder).

[BROWSERNAME]

Putting [BROWSERNAME] in your template will display the name of the remote browser program running on the visitor's computer.

[CART]

Putting [CART] in your template will automatically create a unique shopping cart identifier that can be used in eCommerce commands such as Add, Remove, Purchase, etc. If no cart value is specified when you arrive at a page, then a new unique value is created. If you pass in a cart value in the URL or form (propagating the same value from page to page), then that same cart value is used throughout the page.

[CART] is also handy for times when you just need a guaranteed-unique value somewhere, such as a record identifier or even a product SKU. For this reason, [cart] works in Typhoon as well as WebCatalog.

[CLEARLINEITEMS cart=cartID]

Putting [CLEARLINEITEMS] in your template will remove all line items from the specified shopping cart. Normally carts are found insidethe ShoppingCarts folder, but you may specify a cart in any folder by using file=/folder/cartID instead of cart=cartID.

[CLOSEDATABASE FileName]

Putting [CLOSEDATABASE FileName] in your template will cause the specified database file (or full path) to be written and closed. This is only needed for special cases (usually before appending to a file) where you need to change a file that may be cached in RAM. WebCatalog automatically closes databases when it needs more memory, so you typically do not need to use this tag.

Typhoon Note: Typhoon will only allow a single database to be opened.

[COMMAND]

Putting [COMMAND] in your template will display the WebCatalog command that was used to get to this page. Some examples are ShowPage, Search, ShowCart, etc. These commands are often used in Form Actions, but can also be specified in an HREF hyperlink.

[COMMITDATABASE FileName]

Putting [COMMITDATABASE FileName] in your template will cause the specified database file (or full path) to be written but not closed (so it will remain in RAM). This is only needed for special cases where you want to be absolutely certain that a database has been written to disk.

[COPYFILE from=FromFile&to=ToFile]

Putting [COPYFILE from=fred&to=wilma] in your template will immediately copy the file called "fred" to another file called "wilma".

[CREATEFOLDER folderPath]

Putting [CREATEFOLDER StarShip/Troopers] in your template will immediately create a new folder with the name "Troopers" inside a folder called "StarShip" which is in the same folder as the template itself.

[DATE]

Putting [DATE] in your template will display the current date as defined by the clock on your web server. The format of the date is normally MM/DD/YYYY, but you can change the default format by changing the DateFormat preference. You can override the default date format preference on a case-by-case basis by specifying a format inside the tag, as in [DATE %m/%d/%Y]. See [Time].

Note: this [date] tag is sometimes confused with the [OrderFile]'s [date] tag, which is not the same thing. The [date] tag inside the context of an [OrderFile] represents the date the order was created, and does not have the ability to be formatted in special ways. If you want to display today's date inside of an [OrderFile], then you must first assign a text variable outside the OrderFile context, and use that text variable from then on:

[Text]todaysdate=[date][/Text]
[OrderFile cart=[cart]]
  Order Date: [date]
  Today: [todaysdate]
[/OrderFile]

Here are the valid date formats:

Format	Description
%a	Abbreviated weekday name "Wed" *
%A	Full weekday name "Wednesday" *
%b	Abbreviated month name "Feb" *
%B	Full month name "February" *
%c	Date and time in the form Wed Sep 19 18:24:21 1997 *
%d	Day of month 01-31
%H	Hour 00-23
%I	Hour 01-12
%j	Day of year 001-365
%m	Month 01-12
%M	Minute 00-59
%p	AM or PM
%S	Seconds 00-59
%U	Week # of year (Sunday is first day of first week) *
%w	Weekday 0 (Sunday) - 6 (Saturday)
%W	Week # of year (Monday is first day of first week) *
%x	Date as Sep 11 1997 *
%X	Time as 14:01:12
%y	Year without century 00-99
%Y	Year with century 1900-2199. Note: on Linux systems, years earlier than 999 will not display 4 digits for the year.
%Z	Time zone of server
%%	%
	* These items depend on the underlying operating system's Y2K-compliance. Windows NT, for instance, will not display correct day-of-week-name results for years past 2039. The workaround is to use %w (weekday as a number) and perform your own lookup in a small database for the textual name of the weekday.

[DELETE db=DatabasePath&eqNAMEdata=Fred]

Putting [DELETE db=DatabasePath&eqNAMEdata=Fred] in your template will open the database specified by DatabasePath, find all the records whose NAME field contains "Fred", and delete those records. Any valid search parameters are allowed, as defined in the Search command and [Search] context. Note: if the database has username and password fields, then the records will not be deleted unless the visitor's web browser username/password match the record's username/password.

Typhoon Note: Typhoon will only allow a single database to be opened.

SQL/ODBC Note: To delete records from an ODBC-compliant table, use the [SQL] context.

[DELETEFILE file=FilePath]

Putting [DELETEFILE file=fred] in your template will immediately delete the file called "fred" in the same folder as the template. Paths are relative to the template, so "somefolder/fred" will delete the file down inside a folder called "somefolder", and "../fred" will delete the file in the folder one level up from the template.

[DELETEFOLDER path=FolderPath]

Putting [DELETEFOLDER path=StarShip] in your template will immediately delete the folder called "StarShip" in the same folder as the template. Paths are relative to the template, so "somefolder/fred" will delete the folder down inside a folder called "somefolder", and "../fred" will delete the folder in the folder one level up from the template. All files inside the folder are deleted, and all subfolders are deleted, as though you had dragged the folder to the trashcan and emptied it immediately. This operation is not un-doable!

Note: if the parameter to [DeleteFolder] is an alias, then just the alias itself is deleted.

[ELAPSEDTIME]

Putting [ELAPSEDTIME] in your template will display the elapsed time (in 60ths of a second) since the beginning of processing this page. Put one at the top of a page, and another at the bottom to see how long the entire page takes to process (subtract the 2 numbers to get the answer).

[FLUSHDATABASES]

Putting [FLUSHDATABASES] in your template will cause all databases to be written and closed. This is only needed for special cases (usually before appending to a file) where you need to change a file that may be cached in RAM, and you don't know the exact name of the database. WebCatalog automatically closes databases when it needs more memory, so you typically do not need to use this tag.

Typhoon Note: Typhoon will only allow a single database to be opened.

[FREEMEMORY]

Putting [FREEMEMORY] in your template will display the amount of memory available to WebCatalog. This number is reduced whenever templates are cached, or databases are opened.

[GETCOOKIE cookieName]

Putting [GETCOOKIE fred] in your template will display the value of the cookie named "fred" that the remote browser has remembered. If no cookie of that name exists, then nothing is returned. Use [ListCookies] to see all the cookies your browser is sending.

[GETMIMEHEADER headerName]

Putting [GETMIMEHEADER Accept-Language] in your template will display the value of the MIME header called "Accept-Language", which is a code that represents the human language that the viewer is able to read. Use [ListMIMEHeaders] to see all the headers your browser is sending.

[INCLUDE file=FilePath]

Putting [INCLUDE FilePath] in your template replaces the [INCLUDE] tag with the contents of the specified file. The included file can use any [xxx] tags that will be substituted as though you had typed the entire contents of the file at that place in the template.

Note: normally all filepaths are relative to the local template, or if they begin with "/" they are relative to the web server's virtual host root. As of version 3.0, you may optionally put "^" in front of the filepath to indicate that the file can be found in a global root folder called "Globals" inside the WebCatalog folder. This global root folder is the same regardless of the virtual host.

Optional Parameters	Description
[INCLUDE file=FilePath&raw=T]	raw=T means the file should be included unchanged, without performing any [xxx] substitutions.
[INCLUDE file=FilePath&fromCache=F]	fromCache=F means a more-recent version of the file should be read from disk, instead of using the cached version in RAM.
[INCLUDE file=FilePath&var1=xx&var2=yy]	Passes any variable names (and their values) you choose into the included template, which can then use [var1] anywhere inside it.
[INCLUDE file=^test.inc]	test.inc is found inside WebCatalog/Globals/ folder

[IPADDRESS]

Putting [IPADDRESS] in your template will display the ip address of the remote computer that the visitor is using to view your site. All sections of the IP address are expanded to 3 digits, so that 207.67.2.14 will display as 207.067.002.014. This helps make comparisons inside [ShowIf] tags work properly.

[ISSECURECLIENT]

Putting [ISSECURECLIENT] in your template replaces the [ISSECURECLIENT] tag with "T" if the remote browser is capable of SSL (Secure Socket Layer) connections, and "F" if not. As new browsers are released, you can control which ones are reported as secure by changing the "Browser Info.txt" file to indicate what level of HTML it supports, and whether or not it supports SSL.

[LASTRANDOM]

Putting [LASTRANDOM] in your template will display the same value as the last [RANDOM] number displayed. See [RANDOM].

[LOOKUP db=databasePath&value=searchValue&lookInField=searchField&returnField=fieldName&notFound=TextIfNotFound]

Putting [LOOKUP] in your template will perform an extremely fast search through the specified database and return either the value of the returnField in the found record, or the literal text of the notFound value. The search is an exact match, case-sensitive, so "Grant" does not equal "grant". If you want more control over the search criteria, then use a [SEARCH] context instead.

Typhoon Note: Typhoon will only allow a single database to be opened.

[MOVEFILE from=FromFile&to=ToFile]

Putting [MOVEFILE from=fred&to=wilma] in your template will immediately move the file called "fred" to another file called "wilma", and delete the file "fred" after the move is complete. You may specify a different folder for the file to be moved to.

[PASSWORD]

Putting [PASSWORD] in your template will display the password entered into the remote browser's last Realm password dialog. See [USERNAME] and [AUTHENTICATE].

[PLATFORM]

Putting [PLATFORM] in your template will display the computer platform (Windows or Macintosh or Unix) that WebCatalog is running on.

[PROTECT group1,group2]

Putting [PROTECT Groups] in your template will cause the remote browser to display the Username/Password dialog until the visitor enters a username/password that belongs to one of the specified groups. The Users.db database provided with WebCatalog (and administered here) contains all the username/password/group information.

[PURCHASE cart=cartID]

Putting [PURCHASE cart=cartID] in your template will move the specified shopping cart file from the ShoppingCarts folder to the Orders folder, effectively the same as a Purchase command. If the cart file is not in a ShoppingCarts folder, you may use the alternate file=/folder/cartID instead of cart=cartID.

[RANDOM]

Putting [RANDOM] in your template will display a random number between 1-100. See [LASTRANDOM]

[REDIRECT URL]

Putting [REDIRECT http://isd.smithmicro.com/] in your template will force the remote browser to immediately 'jump' to the new location specified, rather than displaying whatever is in the template. Any other text in the template will be ignored.

[REFERRER] or [REFERER]

Putting [REFERRER] in your template will display the URL of the referring page that led to this one. This is a handy way to give visitors a "back up" button. Note: this will not work if the previous page was a FORM METHOD="POST".

[REMOVELINEITEM cart=cartID&index=3]

Putting [REMOVELINEITEM] in your template will immediately delete the specified line item from the specified shopping cart file. Alternately, you may use the Remove command. See also [AddLineItem] and Add. If the cart file is not in a ShoppingCarts folder, you may use the alternate form file=/folder/cartID instead of cart=cartID.

[SETCOOKIE name=cookieName&value=cookieValue&expires=expireDate&path=/&domain=www.yourdomain.com]

Putting a [SETCOOKIE] tag into a template causes the remote browser to create or replace a cookie of that name in its local list of cookies. You can use [GETCOOKIE] or [LISTCOOKIES] later to retrieve that value from the remote browser. The expiration date of the cookie must be of the form Wednesday, 09-Nov-1999 23:12:40 GMT. The domain must be the name of your web server, otherwise the browser will not provide the cookie information.

Example:

[SETCOOKIE name=Visits&value=12&expires=Wednesday, 09-Nov-1999 23:12:40 GMT&path=/&domain=isd.smithmicro.com]

or one that expires 7 days from today (the +05:00:00 handles the US East Coast time difference from GMT):

[SETCOOKIE name=cookieName&value=sample&expires=[format days_to_date %A, %d-%b-%Y][math]{[date]}+7[/math][/format] [math time]{[time]}+{05:00:00}[/math] GMT&path=/&domain=www.yourserver.com]

Note: if you do not specify an expires parameter, then the cookie will become a "session cookie" which expires automatically when the browser quits.

[SETMIMEHEADER name=headerName&value=headerValue]

Putting a [SETMIMEHEADER] tag into a template causes WebCatalog to add a new MIME header to the outgoing HTML text for that page. MIME headers are normally used to create redirect requests and cookies. WebCatalog already has special tags for generating redirects and cookies, but in the future you may need to create MIME headers for other purposes.

[THISFILE]

Putting [THISFILE] in your template will display the platform-specific filesystem full path of the current template page being displayed. The path separators are platform-specific, so the path will look different depending on what MacOS, Windows, or unix computer system is used.

[THISURL]

Putting [THISURL] in your template will display the URL of the current page being displayed as a relative path from the root of the server hierarchy.

[TIME]

Putting [TIME] in your template will display the current time set on your web server's clock. The format of the time is normally HH:MM:SS (24-hour clock), but you can change the default format by changing the TimeFormat preference. You can also override the default time format by specifying a format inside the tag, such as [TIME %H:%M:%S]. See [DATE] for details.

[USERNAME]

Putting [USERNAME] in your template will display the username entered into the remote browser's last Realm password dialog. See [PASSWORD] and [AUTHENTICATE]

[VALIDCARD accountNum=cardNumber&card=VISA+MC]

Putting [VALIDCARD] into a template will display T or F (True or False), depending on the value of the number in accountNum. If the accountNum is a reasonable credit card number for the specified bank network, then T indicates it is good. Conversely, F indicates it is bad. This does not call the bank to verify funds on the card -- it merely does a simple numeric checksum to verify the number is consistent with a credit card number.

Parameters	Description
accountNum	(Required) The credit card number. Any extra spaces or non-numeric characters will be ignored.
card	(Optional) Set card to the names of the credit cards that are allowed, separated by space or +. Possible values are ALL, IGNORE, VISA, MC, AMEX, DISC, JCB, DINER. If not specified, then ALL cards are allowed. IGNORE tells it to always validate the card regardless of its checksum.

[VERSION]

Putting [VERSION] in your template will display the version of the currently-running WebCatalog program or plugin.