MacroPage is geared towards programmers and web developers who spend a good amount of time 'in the code'. This is not your warm fuzzy happy Frontpage or Dreamweaver world - it's the cold harsh stark reality of the DOS box and batch files, so if you aren't comfortable with those you should probably move along...
Summary:
| equation
| Required
| Equation to solve
|
target
| Optional
| Target for equation solution
|
With the IF command, you can use what are called 'conditional operations'. What this means is that could make a function or template for a forms question, for example, which has a field called 'Required'. Now you can use this in your html, and if you want the question to be required, all you would do is set Required="TRUE", then the IF statement tests to see if Required is TRUE, and if so, then it includes the special html related to making the question required.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="100">
<IF Equation="&FakeValue; < 10">
Did you know that &FakeValue; is less than 10? I did!
</IF>
|
|
Summary:
|
The ELSE command is only used in conjunction with the IF command. The ELSE command tells IF, that if the first statement is not TRUE, then it should skip it and do the ELSE. If the statement is TRUE, the IF continues processing, and skips the ELSE to /IF.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="100">
<IF Equation="&FakeValue; < 10">
Did you know that &FakeValue; is less than 10? I did!
<ELSE>
Did you know that &FakeValue; is greater than 10? I did!
</IF>
|
|
Summary:
| equation
| Required
| Equation to solve
|
target
| Optional
| Target for equation solution
|
The WHILE command is similar to the IF command, except for one distinct difference; as long as the equation is *NOT* FALSE (ie; 0), the loop will jump up to the beginning and run through again. This is handy when you need to display or do something that doesn't differ too much from each iteration. An example might be if you used this in conjunction with the READFIELD command, you could load all the fields from a database file and display them to a table.
|
|
Example:
|
<VARIABLE Name=IncrementValue Data="0">
<WHILE Equation="&IncrementValue; < 10">
We are on count &IncrementValue; out of 10
<SOLVE Target=IncrementValue Equation="&IncrementValue; + 1">
</WHILE>
|
|
VARIABLE
| name, data, scope
| Yes
|
Summary:
| name
| Required
| Name of variable to create or modify
|
data
| Optional
| Data that variable should contain
|
scope
| Optional
| Variable can be either local, global, or override
|
length
| Optional
| Maximum length (of data) to copy
|
Variables are similar to MACRO's, but they can be changes, combine, and manipulated throughout your HTML file. A variable can hold any type of data, from numbers to letters to words, and can be used anywhere, and is commonly used to store something that is likely to change in the future, like a color value or filename. To insert a variable into HTML, you simply type the '&' followed by the variable name, and finish with a ';'. If you want to access a portion of the variable, you can add a '+' and an offset in chars from the start. Similarly, you can add a '[' and an offset to return only 1 character from the variable (whichever one corresponds with the offset you select). You can also get the length of the string by simply adding an '!' before the semicolon. Finally, you can send a pointer to the variable by adding a '@' to the end, right before the ';'. Variables can be changed by calling them exactly the same way as you created them. Also note: Variables created inside of FUNCTIONs or TEMPLATEs will only be valid for the HTML inside the routine; this is what is referred to as 'local' scope. The scope type 'global' is used when you want to declare a variable inside of a function that will persist throughout the page. Scope can also be of type 'override', which is used when you want it to just past down exactly what the variable name is again. You might use 'override', when you're using another type of scripting that uses the same format as MacroPage does. Please note that the parameters may NOT be global in scope.
|
|
Example:
|
<VARIABLE Name=ExampleValue Data="42">
|
|
Usage:
|
Do you know what the ultimate answer is? Well, it's &ExampleValue;!
|
|
Summary:
| type
| Required
| Type of text filtering to take place (skip, normal)
|
Filter can be used for a variety of tasks, but the most common is to differenciate between a development section of a site and the release version. By setting one global variable to 'Skip', and then using that in areas describing unreleased products or sections of the website, the developers can work with the live content, while it can easily be turned off to update the main website.
|
|
VARIABLECOPY
| target, source, length
| N/A
|
Summary:
| target
| Required
| Target variable
|
source
| Required
| Source variable
|
wordclip
| Optional
| Clips to nearest word
|
length
| Optional
| Maximum length (in bytes) to copy
|
Copy the contents of one variable into another.
|
|
Example:
|
<VARIABLECOPY Target=ClippedString Source=OriginalString Length="10">
|
|
VARIABLEREPLACE
| name, search, replace, escape
| N/A
|
Summary:
| name
| Required
| Name of variable to modify
|
search
| Required
| String to search for inside of variable
|
replace
| Required
| String to replace matches with
|
escape
| Optional
| Escape special characters
|
Replace a specified search string with another value.
|
|
Example:
|
<VARIABLEREPLACE Name=VariableName Search="dog" Replace="cat">
|
|
Summary:
|
MACROs are simply like a cut and paste; you define a MACRO, and wherever it is used it will paste in what type defined. MACROs do not have parameters, so they are good for replacing small pieces of code you commonly use over and over. MACROs cannot be modified once they are created, so they are safe from being altered by another included file.
|
|
Example:
|
<MACRO indent=" ">
|
|
Usage:
|
<INDENT>Always indent at the beginning of a paragraph.
|
|
Summary:
|
A function is similar to an HTML code which doesn't require a close, such as META or IMG. Functions can contain parameters, which can alternately be set to some default value if the caller doesn't pass them in. One good example of what you might make a function for would be to set the titlebar on the browser. Since this is never multiline, the phrase you wish to set the title to could be passed as a parameter, automatically placing it between the title commands.
|
|
Example:
|
<FUNCTION TestFunction Message="TestMessage" Color="#FFFFFF">
<font face="Arial, Helvetica" Color=&Color;>
&Message;
</font>
</FUNCTION>
|
|
Usage:
|
<TestFunction Message="What? Me worry?">
|
|
Summary:
|
A Template is conceptually very similar to a function, but has a required close statement (such as FONT is the open, and /FONT is the close). Templates work exceedingly well at encapsulating commonly used open/close code into an easier to read condensed form. One use for the template command might be for a product listing on a website, where each product would use a template to simplify the inclusion of new products at a later date. If you are nesting multiple templates that are contained with other HTML elements, it's possible the tag analyser could report that something wasn't closed properly. If this happens, you can tag the inner templates (the names only) to be ignored in the analysis - to do this simply add the parameter 'BypassAnalysis' when defining the template.
|
|
Example:
|
<TEMPLATE TestTemplate PageTitle="TestTemplate">
<HTML>
<HEAD>
<TITLE>&PageTitle;</TITLE>
</HEAD>
<BODY bgColor="#000000" text="#FFFFFF">
<P>
<CONTENT>
</P>
<BODY>
</HTML>
</TEMPLATE>
|
|
Usage:
|
<TestTemplate PageTitle="The REAL test">
Put you content here...
</TestTemplate>
|
|
SOLVE
| target, equation, type
| N/A
|
Summary:
| target
| Required
| Target for equation solution
|
equation
| Required
| Equation to solve
|
type
| Optional
| Type of data to output
|
SOLVE allows you to perform complex mathematical calculations, and then output the results into a target variable. All of the common math functions, such as addition, subtraction, multiplication, and division, as well as higher math functions such as sin(), cos(), atan(), exp(), etc. Output can be set to any of the following formats: floating point (the default), integer, hex, or string.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="17.33">
<SOLVE Target=FakeValue Equation="(&FakeValue; * 100) / 3.5">
I can even do math for you! Like this: &FakeValue;
|
|
COMPARE
| string1, string2, checkcase
| N/A
|
Summary:
| string1
| Required
| Target for equation solution
|
string2
| Required
| Equation to solve
|
checkcase
| Optional
| Consider case when comparing (TRUE/FALSE)
|
In some instances, you might find it more convenient to do comparisons against strings, instead of values, in conditionals. COMPARE allows you to test whether two strings are identical, including or excluding case comparison. In most instances, you will want to wrap each string with quotes (as illustrated below, to ensure that all of the text you have entered is compared. COMPARE returns a 1 (true) is the strings are the same, or a 0 (false) if they are not. By default, COMPARE ignores case.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="this is a cat">
<IF Equation="<COMPARE string1=\"this is a dog\" string2=\"&FakeValue;\">">
<br/>Dog!<br/>
<ELSE>
<br/>Cat!<br/>
</IF>
|
|
Summary:
| file
| Required
| Output filename for operation
|
flags
| Optional
| Append, NoCompress
|
WRITE allows you to store any subsequent HTML generated into another file. One common use is for pages that contain several frames, where each points to a different HTML file. With WRITE, you can store the entire framed page source in just one file, and then generate the additional files at compile time. The output file is stored in the same directory as the source file, unless otherwise specified.
|
|
Example:
|
<WRITE file="output2.htm">
This message will go to output2.htm!
</WRITE>
|
|
ODBC
| database, username, password, query
| Yes
|
Summary:
| database
| Required
| ODBC database to connect to
|
username
| Optional
| Username for authentication
|
password
| Optional
| Password for username
|
query
| Required
| ODBC query to be performed
|
ODBC connects to a database using ODBC, allowing queries to be performed and the results to be used for further processing.
|
|
Example:
|
<VARIABLE name=RowNumber>
<VARIABLE name=TempVariable>
<ODBC database="GenericDatabase" query="SELECT TOP 10 * from [Users]">
<ODBCNEXTROW Target=RowNumber>
<WHILE Equation="&RowNumber; >= 0">
<ODBCCOLUMN Target=TempVariable Number="0">
&RowNumber; : &TempVariable;<br/>
<ODBCNEXTROW Target=RowNumber>
</WHILE>
</ODBC>
|
|
Summary:
| target
| Required
| Target for current row
|
ODBCNEXTROW reads in the next row from a given SQL query and returns the current row number. If the current row number is less than 0, then the query has been completed. In order for this command to function an ODBC session must first be opened using the ODBC command.
|
|
Example:
|
<VARIABLE name=RowNumber>
<ODBC database="GenericDatabase" query="SELECT * from [Records]">
<ODBCNEXTROW Target=RowNumber>
<IF Equation="&RowNumber; >= 0">
The query was successful!<br/>
</IF>
</ODBC>
|
|
ODBCCOLUMN
| target, name, number, escape
| N/A
|
Summary:
| target
| Required
| Target for field
|
name
| Optional
| Name of column to retrieve
|
number
| Optional
| Number of column to retrieve
|
escape
| Optional
| Escape special characters
|
ODBCCOLUMN is used to retrieve values from the current row from the SQL query. In order for this command to function an ODBC session must first be opened using the ODBC command, and at least one ODBCNEXTROW must be called to fill in the information.
|
|
Example:
|
<VARIABLE name=RowNumber>
<VARIABLE name=TempVariable>
<ODBC database="GenericDatabase" query="SELECT FirstName,LastName from [Users]">
<ODBCNEXTROW Target=RowNumber>
<IF Equation="&RowNumber; >= 0">
<ODBCCOLUMN target=TempVariable number=1>
And their last name was &TempVariable;.
</IF>
</ODBC>
|
|
Summary:
| target
| Required
| Target for count
|
ODBCCOLUMNCOUNT returns the number of columns in each row. In order for this command to function an ODBC session must first be opened using the ODBC command, and at least one ODBCNEXTROW must be called to fill in the information.
|
|
Example:
|
<VARIABLE name=RowNumber>
<VARIABLE name=TempVariable>
<ODBC database="GenericDatabase" query="SELECT FirstName,LastName from [Users]">
<ODBCNEXTROW Target=RowNumber>
<IF Equation="&RowNumber; >= 0">
<ODBCCOLUMNCOUNT target=TempVariable>
There are &TempVariable; columns!
</IF>
</ODBC>
|
|
ODBCCOLUMNNAME
| target, number
| N/A
|
Summary:
| target
| Required
| Target for column name
|
number
| Required
| Number of column name to retrieve
|
ODBCCOLUMNNAME returns the name of the specified column. In order for this command to function an ODBC session must first be opened using the ODBC command, and at least one ODBCNEXTROW must be called to fill in the information.
|
|
Example:
|
<VARIABLE name=RowNumber>
<VARIABLE name=TempVariable>
<ODBC database="GenericDatabase" query="SELECT FirstName,LastName from [Users]">
<ODBCNEXTROW Target=RowNumber>
<IF Equation="&RowNumber; >= 0">
<ODBCCOLUMNNAME target=TempVariable, number="0">
The first column's name is &TempVariable;!
</IF>
</ODBC>
|
|
ODBCCOLUMNTYPE
| target, number
| N/A
|
Summary:
| target
| Required
| Target for column type
|
number
| Required
| Number of column type to retrieve
|
ODBCCOLUMNTYPE returns the type of the specified column. In order for this command to function an ODBC session must first be opened using the ODBC command, and at least one ODBCNEXTROW must be called to fill in the information.
|
|
Example:
|
<VARIABLE name=RowNumber>
<VARIABLE name=TempVariable>
<ODBC database="GenericDatabase" query="SELECT FirstName,LastName from [Users]">
<ODBCNEXTROW Target=RowNumber>
<IF Equation="&RowNumber; >= 0">
<ODBCCOLUMNTYPE target=TempVariable, number="0">
The first column's type is &TempVariable;!
</IF>
</ODBC>
|
|
Summary:
| file
| Required
| Input filename for operation
|
delimiter
| Optional
| Used to separate fields
|
READ opens a file for use by any of the READ-family of functions (such as READLINECOUNT or READLINE). If the file contains delimited data, such as a database, separated by commas (ie, comma-delimited), it can be specified with the 'delimiter' parameter.
|
|
Example:
|
<VARIABLE name=TempVariable>
<READ file="database.dat" delimiter=",">
<READFIELDCOUNT Target=TempVariable>
This file contains &TempVariable; fields!!
</READ>
|
|
Summary:
| target
| Required
| Target for field count
|
READFIELDCOUNT returns the number of fields contained in a delimited file. This is primarily used when you are not sure if you might be adding fields to a database at a later time, and would like the webpage to automatically support the new data. In order for this command to function, a file must be opened first using the READ command.
|
|
Example:
|
<VARIABLE name=TempVariable>
<READ file="database.dat" delimiter=",">
<READFIELDCOUNT Target=TempVariable>
This file contains &TempVariable; fields!!
</READ>
|
|
READFIELD
| target, record, field, escape
| N/A
|
Summary:
| target
| Required
| Target for field
|
record
| Required
| Line (Record) number of fields
|
field
| Required
| Field number to retrieve
|
escape
| Optional
| Escape special characters
|
READFIELD is used to retrieve the actual contents of a field from any delimited file. In order for this command to function, a file must be opened first using the READ command.
|
|
Example:
|
<VARIABLE name=TempVariable>
<READ file="database.dat" delimiter=",">
<READFIELD Target=TempVariable Record="3" Field="7">
Did you know record 3, field 7 contains the text '&TempVariable;'?
</READ>
|
|
Summary:
| target
| Required
| Target for line count
|
READLINECOUNT returns the number of lines inside a file. In order for this command to function, a file must be opened first using the READ command.
|
|
Example:
|
<VARIABLE name=TempVariable>
<READ file="database.dat" delimiter=",">
<READLINECOUNT Target=TempVariable>
This file contains &TempVariable; lines!!
</READ>
|
|
Summary:
| target
| Required
| Target for line
|
line
| Required
| Line number to retrieve
|
READLINE is used to retrieve the actual contents of a line from inside a file. In order for this command to function, a file must be opened first using the READ command.
|
|
Example:
|
<VARIABLE name=TempVariable>
<READ file="database.dat" delimiter=",">
<READLINE Target=TempVariable Line="71">
Did you know line 71 is '&TempVariable;'?
</READ>
|
|
Summary:
| file
| Required
| Input filename for operation
|
The INCLUDE command allows you to 'include' another file into the current project. This might be a file that contains all of the functions and templates you normally use on your site, the colors that you use, javascript, or even additional HTML script. The included file is loaded from the same directory as the source file; if it cannot be found there, it will check the base path, and if the file is still not found, report an error. If an included file is changed, the DATE and TIME stamps for the source will not change.
|
|
Example:
|
<INCLUDE file="default.htm">
|
|
Summary:
|
| The NOCOMPRESS keyword lets MacroPage know that nothing inside the block should be compressed. The HTML tag >PRE< also has the same effect, since the output would be substancially changed if all formatting attributes were maintained. |
|
Example:
|
<NOCOMPRESS>
Anything in here won't be compressed, so a bunch of spaces will still survive the compress
as well as new lines, etc.
</NOCOMPRESS>
|
|
Summary:
|
The BYPASS keyword lets MacroPage know that it should ignore anything from the commands open, to the commands close. Keep in mind that this also means function, template, variables, etc will NOT work inside.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="3.1415">
<BYPASS>
Anything in here is ignored, so &FakeValue; won't work!
</BYPASS>
|
|
Summary:
|
The SCRIPT keyword is functionally very similar to BYPASS, but the big distinction is that SCRIPT will still allow the use of variables, so it's possible to combine Macropage output with another 3rd party scripting language.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="3.1415">
<SCRIPT>
Since this is a script, &FakeValue; will work!
</SCRIPT>
|
|
Summary:
|
The ASCII keyword is very similar to BYPASS, they both will not use any advanced processing on their contents. But there is one distinct difference; ASCII will convert any special HTML characters (like the " or the &) into their HTML facsimiles. This can be very helpful when writing something that uses these specials symbols extensively.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="6.28318">
&ASCII&
Anything in here is ignored, so &FakeValue; won't work, but
better yet, any formatting will be retained, and the text will
look the way it should.
&/ASCII&
|
|
Summary:
|
The comment command is much like the HTML comment, except that whatever is contained inside will NEVER be passed to the output HTML. This can be very convenient when you want to place titles at the top of template and functions to help remind you of what they do.
|
|
Example:
|
<VARIABLE Name=FakeValue Data="3.1415">
<COMMENT>
Dude, this is a comment, no one will every even know you tried
to call &FakeValue;, let alone that it didn't work!
</COMMENT>
|
|
Summary:
|
The PASSTHRU keyword is used when you do something called 'function overloading'. What this means is if you decide you want to make the FONT keyword use some different type of defaults, then you could create a template named FONT, and it would override the default HTML FONT call. But now that you've done that, you want to use the original FONT inside of your template named FONT. That's where PASSTHRU comes in; any HTML line you type in will be passed directly down to HTML, very much like BYPASS. But unlike BYPASS, you still can use variables inside the arguments.
|
|
Example:
|
<PASSTHRU FONT face=&FontFace; size=3>
|
|
Summary:
| message
| Optional
| Message to print as compiler message
|
Sometimes on larger projects, or in special circumstances, it is convenient to see exactly what is going on while compiling. With the COMPILER command, you can display any message, such as a variables value, the output of a function, or any other message. COMPILER messages are not stored in the output file, and are only seen when compiling.
|
|
Example:
|
<COMPILER message="Print this as a compiler message">
|
|
SYSTEM
| file, target, commandline
| No
|
Summary:
| file
| Required
| Filename of command to execute
|
target
| Optional
| Target for return value
|
commandline
| Optional
| Commandline passed to name
|
SYSTEM allows you to execute any commandline program. This is especially helpful when you may be including generated data, which needs to be rebuilt each time the page is updated. By using the system command, you can call the external executable automatically, ensuring that the information it uses is always up to date.
|
|
Example:
|
<SYSTEM file="dir" Commandline="> output.txt">
|
|
Summary:
| file
| Required
| Filename of check
|
target
| Required
| Target for return value
|
IMAGEWIDTH returns the width (in pixels) of the specified graphic file. Currently only JPEG and GIF images are supported.
|
|
Example:
|
<IMAGEWIDTH file="image.gif" Target="ImageWidth">
|
|
IMAGEHEIGHT
| file, target
| No
|
Summary:
| file
| Required
| Filename of check
|
target
| Required
| Target for return value
|
IMAGEWIDTH returns the height (in pixels) of the specified graphic file. Currently only JPEG and GIF images are supported.
|
|
Example:
|
<IMAGEHEIGHT file="image.gif" Target="ImageHeight">
|
|
Summary:
| file
| Required
| Filename of check
|
target
| Required
| Target for return value
|
FILEEXISTS allows you to check whether or not a file exists in the filesystem.
|
|
Example:
|
<FILEEXISTS file="filename.txt" Target="DoesExist">
|
|
Summary:
| file
| Required
| Filename of check
|
target
| Required
| Target for return value
|
FILESIZE returns the filesize (in bytes) of the specified file.
|
|
Example:
|
<FILESIZE file="filename.txt" Target="FileSize">
|
|
Summary:
|
Displays the full filename of the current file being compiled.
|
|
FILETIME
| file, target, usesource
| N/A
|
Summary:
| target
| Optional
| Target variable for result
|
usesource
| Optional
| Use the source directory
|
Displays the current file time, in the following format: Hour:Minute:Second TimeOfDay (ie; 06:44:40 PM).
|
|
Example:
|
<FILETIME target="ThisFileTime">
|
|
FILEDATE
| file, target, usesource
| N/A
|
Summary:
| target
| Optional
| Target variable for result
|
usesource
| Optional
| Use the source directory
|
Displays the current file date, in the following format: Month Day, Year (ie; April 10, 1999).
|
|
Example:
|
<FILEDATE file="test.exe">
|
|
FILEDAY
| file, target, usesource
| N/A
|
Summary:
| target
| Optional
| Target variable for result
|
usesource
| Optional
| Use the source directory
|
Displays the current file day, in the following format: Day (ie; Saturday).
|
|
Summary:
|
Displays the current time, in the following format: Hour:Minute:Second TimeOfDay (ie; 06:44:40 PM).
|
|
Summary:
|
Displays the current date, in the following format: Month Day, Year (ie; April 10, 1999).
|
|
Summary:
|
Displays the current day, in the following format: Day (ie; Saturday).
|
|
|