imacros-cheatsheet.js

// iMacro CheatSheet - Command Reference
// http://wiki.imacros.net/Command_Reference


// iMacros supports 3 types of variables:
// * The macro variables !VAR0 thru !VAR9. They can be used with the SET and ADD command inside a macro.
// * Built-in variables. They contain certain values set by iMacros.
// * User-defined variables. They are defined in-macro using the SET command.
 
 
// 1. iMacros Commands Reference.
 
 
"' comment"  // The single quote character ' indicates a comment. If a line starts with ' everything else on this line is ignored. Typically this is used for comments or to disable specific parts of a macro.
 
"ADD !VAR value"  // Add a value to a variable. You can also substract values by adding a negative value to the variable.
"BACK"            // Opens the previously visited website.
"CLEAR"           // Clears the browsers cache and all cookies.
"CLICK X=n Y=m"   // "Clicks" on the HTML element at the specified X/Y coordinates.
 
"SET !VAR1 EVAL('[javascript statements]')"  // This command allows you to evaluate values, and trigger macro errors if certain conditions are met.
"FILEDELETE NAME=file_name"                  // Deletes the file specified by Name. If no directory is specified in Name the file is assumed to lie in the iMacros Downloads subdirectory.
"FILTER TYPE=IMAGES STATUS=(ON|OFF)"         // Filtering is a feature that allows you to change data on the website before it reaches the browser. Currently only the TYPE=IMAGES filter is supported.
"FRAME (F=n|NAME=id)"                        // Directs all following TAG or EXTRACT commands to the specified frame. The frame tag and number is automatically generated by clicking into a framed web page.

"ONCERTIFICATEDIALOG C=n BUTTON=[OK|CANCEL]"                    // Selects the client side certificate at position C from the upcoming dialog.
"ONDIALOG POS=n BUTTON=(YES|NO|CANCEL) [CONTENT=some_content]"  // Handles upcoming Javascript dialogs. You can extract the text of a dialog by adding "SET !EXTRACTDIALOG YES" to your macro.
 
"ONDOWNLOAD FOLDER=folder_name FILE=file_name WAIT=[YES|NO] CHECKSUM=[MD5|SHA:hexadecimal_string]"  // iMacros automatically detects and intercepts downloads. With this command, which has to occur before the download starts, the location and name of the saved file is determined.
 
"ONERRORDIALOG BUTTON=(YES|NO) CONTINUE=(YES|NO)"         // If a page script error occurs on a webpage Internet Explorer opens an error dialog. This command handles such a dialog so your macros are not interrupted by script errors.
"ONLOGIN USER=username PASSWORD=password RETRY=[YES|NO]"  // Handles login dialogs. The ONLOGIN command must appear before the macro command that navigates to the site that brings up the login dialog.
"ONPRINT P=n BUTTON=(PRINT|CANCEL)"                       // Handles print dialogs. The ONPRINT command must appear before the PRINT command which triggers the printer dialog to come up.
"ONSECURITYDIALOG BUTTON=(YES|NO) CONTINUE=(YES|NO)"      // Command to handle security dialogs. If Continue=No is selected then the macro will stop if such a dialog appears.
"ONWEBPAGEDIALOG KEYS=some_keys|MACRO=macro_file"         // Web page dialogs are similar to Javascript dialogs except they display HTML content.

"PAUSE"  // Same as a manual click of the "Pause" button: Stops the execution of the macro. Waits for user to click "Continue" to continue.
"PRINT"  // Prints the current browser window on your default printer.

"PROMPT prompt_text variable_name [default_value]"  // Displays a popup to ask for a value. This value is stored in variable_name. This command can be used to change the variables !VAR1, !VAR2 or !VAR3, but not built-in variables like !DATASOURCE or dynamically generated variables.
"PROXY ADDRESS=proxy_URL:port [BYPASS=page_name]"   // Connect to a proxy server to run the current macro.

"REFRESH"   // Refreshes (Reloads) current browser window. Refresh includes sending a "pragma:nocache" header to the server (HTTP URLs only) which causes all elements of the website to be reloaded from the webserver.
"SAVEITEM"  // SAVEITEM saves the document that is currently displayed in the web browser, for example a PDF file.

"SAVEAS TYPE=(CPL|MHT|HTM|TXT|EXTRACT|BMP|PNG|JPEG) FOLDER=folder_name FILE=file_name"  // Saves information to a file. The SAVEAS command can save different information to a file.
"SCREENSHOT TYPE=(PAGE|BROWSER) FOLDER=folder_name FILE=file_name"                      // With this command, iMacros can take a screenshot of the Page/Browser that is being displayed.
"SEARCH SOURCE=(TXT|REGEXP) IGNORE_CASE=YES EXTRACT=$1"                                 // The SEARCH commands works with page source, instead of looking at the web page object model (DOM) that the TAG command uses.

"SET var value"  // Defines the value of a variable. The SET command supports the built-in variables, pre-defined user variables !VAR0 thru !VAR9, as well as user-defined macro variables.
"SIZE X=n Y=m"   // Resizes the browser window.

"TAB (T=n|OPEN|CLOSE|CLOSEALLOTHERS)"  // Sets focus on the tab with number n.
"STOPWATCH ID=id"                      // Measures the time in seconds between two STOPWATCH commands with the same identifier.

"TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=$Apple "  // The TAG command selects HTML elements from the current website. The identification of the element is given by providing the parameters POS, TYPE, FORM and ATTR. If the selected element is a link then the link is followed, i.e. the TAG command acts as if it clicks on the element.

"TRAY (HIDE|SHOW)"                     // Hides or shows the iMacros Browser during playback. A tray icon appears instead of the browser, just like with the command line switch -tray.
"URL GOTO=some_URL"                    // Navigates to a URL in the currently active tab.
"VERSION BUILD=<version number>"       // Specifies the version of iMacros that created this macro. Please note this command is required by all macros.
"WAIT SECONDS=(n|#DOWNLOADCOMPLETE#)"  // Waits for a specific time before continuing replay with the next command (timed delay).


// 2. iMacros Built-In Variables.


"!CLIPBOARD"             // Copy data from and to the clipboard.
"!COLn"                  // Specifies the column which is used for input. Set n to the column number you want to use.
"!DATASOURCE"            // Specifies the name and location of an input file for merging data with macro.
"!DATASOURCE_COLUMNS"    // Specifies the number of columns in the input datasource.
"!DATASOURCE_DELIMITER"  // Specifies the character used to delimit fields in your CSV input file.
"!DATASOURCE_LINE"       // Specifies the line in the datasource which is used for input.
"!ENCRYPTION"            // Specifies how to encrypt passwords you use in macros.
"!ENDOFPAGE"             // Uses the !TAGSOURCEINDEX variable to define the end of page for iMacros. A search for a TAG element does not go below this limit.
"!ERRORIGNORE"           // Tells iMacros to ignore errors. The replay of macros continues even if one or more commands fail.
"!EXTRACT"               // Contains the extraction results.
"!EXTRACT_TEST_POPUP"    // Toggles whether the extraction result in displayed during replay in a popup dialog.
"!EXTRACTDIALOG"         // Extract information from a dialog. The entire text of a website dialog is extracted.
"!FILE_LOG"              // Sets a specific log file name for the current macro. If no folder is supplied then the file will be written to the standard log file directory (V7.x) or the download directory (up to V6) of your iMacros installation.
"!FILE_STOPWATCH"        // Sets the file name for the file that contains the stopwatch measurement data. By default the file name is performance_macroname.csv and is located in the download directory of your iMacros installation.
"!FILE_PROFILER"         // Sets the file name for the file that contains the performance profile data and enables profiling. By default all performance output of a given day is stored in the file Profiler_yyyy-MM-dd.xml, located in the download directory of your iMacros installation.
"!FOLDER_DATASOURCE"     // Returns/sets the folder from which input files are read in by default. Setting this variable is valuable if several macros share an input file folder, or to separate the image files that each macro needs.
"!FOLDER_STOPWATCH"      // Sets the folder location for the file that contains the stopwatch measurement data.
"!IMAGEX"                // This value contains the X-coordinate of the last image found with the IMAGESEARCH or IMAGECLICK command. If the last image search did not find an image, then the value is -1.
"!IMAGEY"                // This value contains the Y-coordinate of the last image found with the IMAGESEARCH or IMAGECLICK command.
"!LOOP"                  // Counts the current loop number in loop mode. Especially useful together with the POS attribute of the TAG command. With SET !LOOP 3 you can set a start value for the loop counter (the default value is 1).
"!MARKOBJECT"            // Toggles whether a border should be drawn around the tagged element. The default value is YES.
"!NOW"                   // Contains the current time and date. In order to format the time and date you can use the following format codes, which you need to append to the variable after a colon.
"!POPUP_ALLOWED"         // Allow popups for a given URL during a macro run. Technically this is the same as white-listing the URL permanently. The advantages are that you can store this information in the macro and thus make it run everywhere, without the user having to manually white-list the URL.
"!REPLAYSPEED"           // Sets the replay speed to fast, medium or slow.
"!REGION_BOTTOM"         // Defines the bottom boundary of a subregion to restrict IMAGESEARCH. For very large pages this should reduce the time needed for IMAGESEARCH.
"!REGION_LEFT"           // Defines the left boundary of a subregion to restrict IMAGESEARCH. For very large pages this should reduce the time needed for IMAGESEARCH.
"!REGION_RIGHT"          // Defines the right boundary of a subregion to restrict IMAGESEARCH. For very large pages this should reduce the time needed for IMAGESEARCH.
"!REGION_TOP"            // Defines the top boundary of a subregion to restrict IMAGESEARCH. For very large pages this should reduce the time needed for IMAGESEARCH.
"!SINGLESTEP"            // Enables single-step debugging: iMacros stops after every command and waits for the user to click the "Continue" button.
"!STOPWATCHTIME"         // Contains the last measured response time value.
"!STOPWATCH_HEADER"      // If set to NO tells iMacros to omit the header in the output performance file.
"!TAGSOURCEINDEX"        // Retrieves the ordinal position of the object, in source order, as the object appears in the document's all collection.
"!TAGX"                  // This value contains the X-coordinate of the HTML element found with the TAG command. The !TAGX/!TAGY values are automatically set after each TAG command.
"!TAGY"                  // This value contains the Y-coordinate of the HTML element found with the last TAG command.
"!TIMEOUT_MACRO"         // Set the macro's global timeout in seconds.
"!TIMEOUT_PAGE"          // Set the page load timeout in seconds.
"!TIMEOUT_STEP"          // Sometimes text or images do not appear immediatly after a page is loaded.
"!URLCURRENT"            // Contains the current URL. This is the URL visible in the browser address bar at the time the variable is used.
"!USERAGENT"             // Change the default user agent of the web browser.
"!VAR0...!VAR9"          // Standard built-in variables for arbitrary use.
"!WAITPAGECOMPLETE"      // If this variable is set to YES iMacros will wait until the top frame is completely loaded.


// 3. Scripting Interface Commands.


ret_code = iimOpen(String commandLine [, boolean openNewBrowser] [, int timeout]);  // Initializes the Scripting Interface. It opens a new instance of the iMacros Browser, IE or Firefox, or connects to an existing instance (depending on the specified parameters). If the command fails for any reason it returns an error code.
ret_code = iimDisplay(String message [, int timeout]);                              // Displays a short message in the iMacros browser. A typical usage would be to distinguish several running iMacros Browsers or display information on the current position within the script.
ret_code = iimPlay(String macro [, int timeout]);                                   // Plays a macro. After the macro has played all options that have been set with the iimSet command are reset. Use iimGetLastExtract to get the extracted text.
ret_code = iimSet(String VARNAME, String VARVALUE);                                 // Defines variables for use inside the macro and assigns values to them.
ret_code = iimTakeBrowserScreenshot(String FILEPATH, int 0/1);                      // Takes a screenshot of the current browser content or the current website.
ret_code = iimClose([int timeout]);                                                 // Closes the iMacros browser.

ret = iimGetStopwatch(int index, string name, string value);  // Returns the data of the STOPWATCH command. If there is no STOPWATCH command in the macro then iimGetStopwatch returns only one value ("Total Runtime").
err_message = iimGetErrorText();                              // Returns the text associated with the last error.
extract = iimGetExtract([int index_of_extracted_text]);       // Returns the contents of the !EXTRACT variable.
macro_node = iimGetPerfomance();                              // Returns the XML fragment containing the performance data of the last macro run, if performance logging has been enabled.
version_number = iimGetInterfaceVersion();                    // It returns a number in LONG format such as 80066532. Note that the iMacros main version number (as shown by VERSION) and the Scripting Interface version number as shown by iimGetInterfaceVersion are not identical.