View source

===Introduction===

Are you tired of filling out the same form over and over again? Then let iMacros help you. Simply put all data to be input into a very straightforward and easily understandable text file and iMacros can read the data from there and submit it to the web site - completely automatic, without your interaction! 

The data source can be in either of two different formats: a text file with a list of variables and their values of the form key=value or as a comma separated text file (CSV format). A text file in CSV format can be generated and edited by Microsoft Excel and many other applications. 

As a rule of thumb the "list of variables" format is recommend if you have many different variables but only one or a few value(s) for each variable (for example, your detailed address data that you use to fill out online forms). The CSV format is most appropriate for use with a few variables with many different values (for example, a long list of CD's that you want to submit to an auction web site). 

More advance users might connect directly to databases to retrieve the data. 

(Related example macros: Demo-Datasource, Demo-Loop-CSV-2Web)
(Related example script: Datasource-2-web.vbs, File-2-web.vbs, File-2-web-Method2.vbs, Database-2-web.vbs)

==Variables [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]==
(Related example macros: Demo-Datasource, Demo-Slideshow )

Variables are, as the name suggests, constructs that allow you to dynamically, usually during runtime, hold different values. This is very helpful when you are trying to follow links that contain changing words or when you want to use the same macro for entering different values into a search engine. 

The values (content) of all variables in iMacros are accessed by putting two curly brackets around the variable name. The values of !VAR1 is thus accessed by <nowiki>{{!VAR1}}</nowiki>. 

Variables can be part of anything inside the macro (except the commands themselves). For example, you can add them as part of the ATTR string in a TAG or EXTRACT command or as part of the URL statement: 

 <nowiki>URL GOTO=https://www.onlinestore.com/?shoppingcart={{!VAR1}}&item={{!VAR2}}</nowiki>

You can assign almost any value to a variable. However, when assigning a value to a variable with [[SET]] certain characters need to be escaped or substituted because they imply a certain behaviour to iMacros. When assigning values to variables all whitespaces in the value part must be substituted by <SP> and all newlines must be substituted by <nowiki><BR></nowiki>; double curly brackets must be escaped with #NOVAR# ie. #NOVAR#{{. Note this this only applies ''inside a macro'', e. g with the [[TAG]], [[SET]] or [[ADD]] commands. If you use the [[iimSet]] command of the Scripting Interface, it replaces " " with <SP> and newline with <nowiki><BR></nowiki> automatically.

There are two kinds of variables in iMacros: 

===Built-in variables [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]===
These variables are used to define certain properties of the macro's behavior, for example the macro timeout value: 

 SET !TIMEOUT 33 

There are three special built-in variables, !VAR1, !VAR2 and !VAR3. These variable can be set to anything you like. They are also defined with the SET command 

 SET !VAR1 hello<SP>world 

Alternatively, you can prompt the user to input a value: 

 PROMPT Please<SP>enter<SP>text !VAR1

===User-defined Variables [PRO and Scripting Edition] ===
These variables are created during runtime ("on the fly") by two different mechanisms. Either one uses the command line switch -var_MYVAR value like so: 

 imacros.exe -macro myMacro -var_ITEM 15 

creates the variable ITEM during replay of the macro myMacro and gives it the value 15. 

The second options is to use the iimSet function of the Scripting Interface. In a Visual Basic Script example this would look like: 

 iret = imacros.iimSet("-var_ITEM", "15")


Note that the user-defined variables '''should not have a prefixed "!"'''. Only the built-in ones do, like e.g. [[!LOOP]].

== Data Input ==

===Input from Comma Separated Data (CSV) File ===
<small>[http://wiki.imacros.net/CSV_input Short URL to this section]</small>
 
(Related example macros: Demo-ReadCSV) 
(Related example script: CSV-2-web.vbs, Database-2-web.vbs)

iMacros allows you to specify a text file with comma separated values ([[csv|CSV]]) to be used as input. Imagine, for example, that you want to submit a list of CD's to an online auction. Here is the list of the CD's in the comma separated format: 

 "ARTIST" , "ALBUM TITLE" , "PRICE" 
 "Beatles", "Abbey Road", "13.49" 
 "Beatles", "The Beatles 1,2,3" , "25.49" 
 "Mozart" , "Symphonies No.40 & 41", "9.98" 
 "Mozart", "Requiem", "7.50" 

Note: Quotation marks are optional in most cases. They are only required if the value itself contains a comma, or a new line. 

We now need to tell the iMacros macro where the data input file can be found. For that we use the built-in variable !DATASOURCE 

 SET !DATASOURCE OnlineAuction.csv 

If you do not use any path information (like C:\myPath\) in the !DATASOURCE value the file is assumed to lie in the standard datasources directory, which can be specified in the Paths tab of the Options dialog. The default directory is in the datasources\ directory of your iMacros installation (e.g. C:\Program Files\iMacros\datasources\). 

Since we want to insert all datasets into the form we need to loop over the macro, each time inserting the next CD. Therefore, we need to tell iMacros in which line of the datasource we currently are. We do this using the built-in variable !DATASOURCE_LINE. By cunningly using the built-in variable !LOOP we let iMacros take care of the counting. And since the first line is just the header, we would like to skip it and start counting from 2: 

 <nowiki> SET !LOOP 2</nowiki>
 <nowiki> SET !DATASOURCE_LINE {{!LOOP}}</nowiki> 

Now we can have the macro fill out the online form with the values from the current CD dataset. We use the built-in variables !COLn, where n represents the number of the columns to put into the form element. 

 <nowiki> TAG TYPE=INPUT:TEXT FORM=Listing ATTR=NAME:Name CONTENT={{!COL1}}  </nowiki> 
 <nowiki> TAG TYPE=INPUT:TEXT FORM=Listing ATTR=NAME:Album CONTENT={{!COL2}}  </nowiki> 
 <nowiki> TAG TYPE=INPUT:TEXT FORM=Listing ATTR=NAME:Price CONTENT={{!COL3}}</nowiki> 


During the execution of the macro the constants in parentheses <nowiki>{{..}}</nowiki> are replaced by the value specified in the data sources.


For reading huge files cf. [http://forum.iopus.com/viewtopic.php?f=15&t=1932 "Use scripting for accessing > 30 columns"]

===Input from List of Variables File [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] ===
(Related example macros: Demo-Datasource) 
(Related example script: Datasource-2-web.vbs)

Please note that '''this feature will be deprecated with iMacros V7'''. So if you start a new project, we highly recommend to [[Form_Filling#Input_from_Comma_Separated_Data_.28CSV.29_File|use the CSV input method]].

You can also use data from a list of variables input file. The information in this format is saved in the form of key-value pairs, like 

 key1=value1 
 key2=value2 

To use input in that format create a plain text file that contains the information you want to submit. The first line in this input file must be 

 [iOpus] 

In this example we create a file that contains the information on ordering "lunch". lunch.txt could look like this: 

 [iOpus]  
 name=Mr.<SP>Tester  
 main=2 
 drink=2  
 smallsizedrink=NO  
 myremarks=Deliver<SP>to<SP>home<SP>address:<BR>1629<SP>4th<SP>Avenue<BR>Thanks!<BR>Tom     

We now need to tell the iMacros macro where the data input file can be found. For that we use the built-in variable !DATASOURCE 

 SET !DATASOURCE lunch.txt 

If you do not use any path information (like C:\myPath\) in the !DATASOURCE value the file is assumed to lie in the standard datasources directory, which can be specified in the Paths tab of the Options dialog. The default directory is in the datasources\ directory of your iMacros installation (e.g. C:\Program Files\iMacros\datasources\). 

After we have specified the location of the input data it is ready to use! iMacros creates variables called after the key part of the key-value pairs. The value of this variable is the value of the key-value pair. You can now use these variable to fill the form: 

 <nowiki>TAG TYPE=INPUT:TEXT FORM=NAME:TestForm2 ATTR=NAME:Name CONTENT={{name}}</nowiki>   
 <nowiki>TAG TYPE=SELECT FORM=NAME:TestForm2 ATTR=NAME:main CONTENT={{main}} </nowiki> 
 <nowiki>TAG TYPE=SELECT FORM=NAME:TestForm2 ATTR=NAME:drink CONTENT={{drink}} </nowiki> 
 <nowiki>TAG TYPE=INPUT:CHECKBOX FORM=NAME:TestForm2 ATTR=NAME:C8&&VALUE:ON CONTENT={{smallsizedrink}} </nowiki> 
 <nowiki>TAG TYPE=TEXTAREA FORM=NAME:TestForm2 ATTR=NAME:Remarks CONTENT={{myremarks}}    </nowiki> 

During the execution of the macro the constants in parentheses {{..}} are replaced by the value specified in the data sources. 

Multiple Sets of Key-Value Pairs 
If you want iMacros to read different sets of key-value pairs for each loop add a number at the end of the key and add !LOOP to the end of the name inside the macro. The datasource input.txt could then look like this: 

 [iOpus]  
 name1=Tom<SP>Tester  
 name2=Ann<SP>Smith  
 name3=Nicole<SP>Frank  
 main1=2  
 main2=1  
 main3=3  

The complete macro would then look like this: 

 SET !DATASOURCE input.txt 
 <nowiki>TAG TYPE=INPUT:TEXT FORM=NAME:TestForm2 ATTR=NAME:Name CONTENT={{name!LOOP}}  </nowiki> 
 <nowiki>TAG TYPE=SELECT FORM=NAME:TestForm2 ATTR=NAME:main CONTENT={{main!LOOP}} </nowiki>

===Input from Database ===
(Related example macros: Wsh-Submit-2-Web)
(Related example script: File-2-web-Method2.vbs, Database-2-web.vbs)

This example only works with the Scripting Edition. 

iMacros can read data directly from any Windows database using the Scripting Interface and a few lines of code. 

This example code in Visual Basic Script connects to a Microsoft Access database: 

 ' open database 
 set rs = CreateObject("ADODB.Connection") 
 rs.Open("DRIVER={Microsoft Access Driver (*.mdb)}; DBQ=" _ 
 & mypath & "IIM-TEST-SUBMIT.MDB") 
 
 ' use SQL to select information 
 sql = "select * from table1" 
 set rs = rs.Execute(sql) 
 
 ' start iMacros 
 set iim1= CreateObject ("iMacros") 
 iret = iim1.iimInit 
 iret = iim1.iimDisplay("Submitting Data from MS ACCESS") 
 
 ' loop through result dataset 
 do until rs.eof 
    'Set the variable 
    iret = iim1.iimSet("FNAME", rs.fields(0)) 
    iret = iim1.iimSet("LNAME", rs.fields(1)) 
    iret = iim1.iimSet("ADDRESS", rs.fields(2)) 
    iret = iim1.iimSet("CITY", rs.fields(3)) 
    iret = iim1.iimSet("ZIP", rs.fields(4)) 
    iret = iim1.iimSet("STATE-ID", rs.fields(5)) 
    iret = iim1.iimSet("COUNTRY-ID", rs.fields(6)) 
    iret = iim1.iimSet("EMAIL", rs.fields(7)) 
    'Run the macro 
    'Note: This is the SAME macro, as in the FILE-2-WEB-METHOD2.VBS example script!!! 
    iret = iim1.iimPlay("wsh-submit-2-web") 
    If iret < 0 Then 
       MsgBox iim1.iimGetLastError() 
    End If 
   rs.movenext 
 loop 
 
 iret = iim1.iimDisplay("Done!") 
 iret = iim1.iimExit 
 WScript.Quit(0)

==Tabbed Browser [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ff-icon.png|Firefox]]==

 [[Image:Tabs.gif|frame|Using Tabs]]

(Related example macros: Demo-Tab )

The iMacros Browser [PRO and Scripting Edition only] includes a tabbed browsing interface that makes managing web sites with multiple open pages a snap. When a web page opens a new window iMacros automatically opens it in a new tab in the background. If the user changes to another tab a TAB command is automatically added during recording. 

You can close tabs while browsing by right-clicking on the tabs (not the browser window itself!). This will open up a context menu with the options to close the tabs. The following example shows the basic actions you can do with the TAB command 

 ' open a webpage in the first tab 
 URL GOTO=http://www.iopus.com 
 ' open a new tab 
 TAB OPEN 
 ' get new tab to foreground 
 TAB T=2 
 ' load another page 
 URL GOTO=http://www.google.com 
 ' close the second tab 
 TAB CLOSE 
 TAB T=1

==Frames  [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]==

 [[Image:Frame-dom-inspector-f6.png|150px|thumb|Frame in Object Tree]]

iMacros handles pages with frames automatically. It inserts FRAME statements that indicate to which frame the following TAG and/or EXTRACT command refers. Please note that TAG and/or EXTRACT will fail if they are not directed to the correct frame. To avoid this error please do the following: 

* EXTRACT command: if the object that needs to be extracted is on a framed page make sure that you use the correct FRAME statement. You generate such a FRAME statement by clicking on any element of any kind within the frame prior to performing the extraction.   

===Background information ===

The number n in the FRAME F=n command is the position of the frame in the object tree of website.

==Fine Tune TAG Commands  [[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]]==

Normally the TAG commands work the way they are recorded by iMacros, but sometimes you need to manually fine tune them. If an error occurs during replaying a TAG command it might be due to one of the following problems. 

===Wildcards ===
Some web sites are created dynamically from databases and the links contain unique numbers - the so-called session ID - each time you visit a page. While this technique helps the web site owner it poses a problem to iMacros. This is because during recording the session ID, which is often part of links, was written into the macro as part of the TAG command. During replay the session ID is different, thus iMacros does not find the exact link and produces an error. The solution is to replace the changing part of a link (or extraction) with the * symbol, which is read by iMacros as a wildcard. The wildcard causes iMacros to accept any character where the * is placed. 

====Example====
Tag line as recorded by iMacros: 

 TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:/kb/ki.dll/ke.kb.gz?kbb;532452&&2&&&&&nc ATTR=NAME:zipcode CONTENT=85250 

If you record the same macro a second time you will see that we get the same TAG line except one number - this is the session ID the website is using. 

 TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:/kb/ki.dll/ke.kb.gz?kbb;532244&&2&&&&&nc ATTR=NAME:zipcode CONTENT=85250 

Replace the session ID with *: 

 TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:/kb/ki.dll/ke.kb.gz?kbb;*&&2&&&&&nc ATTR=NAME:zipcode CONTENT=85250  

Actually, you could also remove most or all of the static parts of the FORM information as well. Exactly how much you can remove depends on the website. You still need enough information for iMacros to uniquely identify the page element. In our example, the result looks like: 

 TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:/kb/* ATTR=NAME:zipcode CONTENT=85250

or even

 TAG POS=1 TYPE=INPUT:TEXT FORM=ACTION:* ATTR=NAME:zipcode CONTENT=85250

'''Note:''' ''TXT:* is not the same as TXT: (without *).'' If only TXT: is used, this means you are looking for an element where the text attribute is "", if you are using TXT:* this means that the text attribute can have any value (= same as omitting the text attribute altogether). This applies to any attribute, not just TXT.