==Starting iMacros ==
iMacros is distributed as a browser add-on for Firefox, Chrome, and Internet Explorer. Two of the commercial editions of iMacros (Standard Edition and Enterprise Edition) also include the standalone iMacros Browser, a [[FAQ#Q: What is the functional difference between Internet Explorer with iMacros turned on, and the iMacros browser?|derivative of IE]] with a [[Browser Automation#Command Line Interface and Batch Files|command-line interface]].
This article primarily covers interaction with the iMacros Browser, however, the concepts and interface are fairly consistent among all the different versions of iMacros. Throughout this Wiki, iMacros commands and functionality are are associated with browser icons ([[Image:IMacros-icon.png|iMacros Browser]] [[Image:Ie-icon.png|IE Plug-in]] [[Image:Ff-icon.png|Firefox]] [[Image:Cr-icon.png|Chrome]]) to designate their applicability to a particular browser.
===Internet Explorer Plug-in===
After installing the software, a new iMacros icon appears on the command bar of Internet Explorer (IE).
[[File:IE_Tools_Menu_Cut_Out.png|right|thumb|iMacros in the IE Tools menu]]Click this icon to start iMacros.
[[Image:IE_Command_Bar_Button.png]]
If you have already customized your IE command bar, you might need to manually add the icon or reposition it so it's visible. Please see this relevant [[FAQ_-_Frequently_Asked_Questions#Q:_What_if_the_iMacros_icon_does_not_appear_in_the_IE_toolbar?|FAQ]] for more on how to do this.
You can also start iMacros for IE by selecting 'iMacros Web Automation' from the IE Tools menu.
===The iMacros Browser (Standard and Enterprise Editions)===
To start the iMacros Browser, select the program from the Windows Start Menu, double-click the icon on your desktop, or navigate to the file "imacros.exe" (typically in C:\Program Files(x86)\Ipswitch\iMacros) and double-click it using Windows Explorer. In case,
To become familiar with iMacros run the "FillForm" demo macro that is automatically installed. This demonstrates the basic features of iMacros in a straightforward way. It navigates to a test form, fills the form and submits it, then returns to the iMacros Website.
==The iMacros Graphical User Interface ==
We have invested a lot of effort in making the Graphical User Interface of the iMacros Browser and the Internet Explorer add-on as intuitive as possible. This section explains the basic elements. <!--The minor differences between the iMacros Browser and the IE add-on will be pointed out as necessary.-->
===The Main Window ===
The main window consists of three parts: the menu and toolbar at the top, the iMacros sidebar on the left, and the browser window on the right. Web pages are displayed in the browser window using a tabbed interface just like other browsers. You control iMacros with the elements in the sidebar on the left.
[[File:iMacros_Browser.png|950px|center]]
<!--[[Image:Imacro_browser.gif|left|frame|iMacros browser]]--->
===The iMacros Sidebar===
The iMacros sidebar is divided into two parts. The top half displays a tree view of all your macros when iMacros is stopped, and the current macro code when you are playing or recording a macro. Only files with an .iim or .iimx (obfuscated macros) extension in the Macros folder are recognized by iMacros. The Macros folder is specified in the Path settings of the iMacros Options. The default macro folder is located in My Documents under iMacros\Macros.
The lower half of the sidebar consists of three tabs: Play, Record, and Edit. As the names suggest, the Play tab contains controls for playing macros, the Record tab contains controls for recording macros, and the Edit tab contains controls for editing macros, changing options, and getting help.
[[File:Sidebar_Pin.png|left]]'''Tip:''' [[Image:IMacros-icon.png|iMacros Browser]] You can auto-hide the sidebar by "un-pinning" it from the main window (just click on the thumb-pin icon to pin or unpin the sidebar), or you can move the sidebar outside the main window to a "floating" position, or dock it on the right, if you prefer. You can also hide the toolbar from the View menu. [[Image:Ie-icon.png|IE Plug-in]] The sidebar needs to be open in IE for iMacros to function.
<br>
==Recording Macros==
===What's a Click Mode?===
It is important to note that the primary way iMacros records your interaction with a web page is by recording your mouse clicks on the various web page elements. iMacros records these clicks as well as text entered into input fields on web forms and translates them into [[TAG]] commands. If you are entering and selecting values in a series of fields on a web form, you need to navigate to each field with the mouse and click into/on that field.
'''Note:''' Navigating through fields with the keyboard (i.e. using the TAB key) is not supported and will not be recorded.
Before recording, it is important to understand the different modes of recording that you can use. This is also known as the Click Mode. The three main click modes are Automatic, Expert (Use complete HTML tag), and [[DirectScreen]]. To select a click mode, use the ClickMode menu item or open the Click Mode Dialog from the main toolbar or Record tab.
[[File:Click_Mode_Dialog.png|right]]
====Automatic====
iMacros attempts to choose the best recording options (recommended in most cases for recording on HTML websites). In the automatic mode iMacros looks at the different attributes an element has (such as ID, NAME, Text, HREF, etc.) and selects the one attribute it thinks fits best (for details, please see the "[[Automatic Mode Details|For advanced users]]" description). Note that the automatic mode never switches to Expert or [[DirectScreen]] mode. If you need these recording modes, please select them manually.
====Expert====
This mode is for advanced users: iMacros does not select just ''one'' attribute as in the automatic mode, but instead creates a [[TAG]] command that consists of ''all'' attributes of the clicked HTML element. The purpose is to give the user a quick overview of all of the element's attributes. Typically the user will use such a [[TAG]] command as a starting point, and then delete the attributes that should not be used. Often this is more convenient than [[TAGs_and_HTML|building such a TAG command manually]].
====X/Y [[Image:Ff-icon.png|Firefox]]====
iMacros for Firefox provides this mode for identifying elements by their position on the web page. This can be useful if the name and URL of the item you want to click on changes dynamically from visit to visit. It should also be used if the web page element is embedded in JavaScript and iMacros can not find the recorded name during replay because it was created "on the fly" by JavaScript. For more information on this mode, see the [[CLICK]] command.
====DirectScreen====
This is the ultimate solution if everything else fails. It simulates standard mouse clicks and movement within the browser window. This feature works with all web pages. For non-html elements such as Flash or Silverlight, you must use the [[DirectScreen]] mode. DirectScreen is only available in the iMacros Browser and iMacros for IE commercial editions.
==== Image Validation ====
Image validation (the [[IMAGECLICK]] and [[IMAGESEARCH]] commands)''' combines the power of [[DirectScreen]] with computer vision'''. To use it, open the Image Validation Wizard. For more details please see [[Image Recognition]].
[[File:Image recognition wizard.png|thumb|center|400px|Image Validation Wizard: Use it to create the [[IMAGECLICK]] and [[IMAGESEARCH]] commands.]]
====Changing Modes====
[[File:Show_Click_Mode_Dialog_Button.png|none]]
In most cases you will record your macros using just one click mode, but you aren't limited to just one click mode per macro. In fact, you can mix the modes in a single macro by changing the click mode while you are recording! This is useful if you encounter problems while attempting to record one or more elements on a web page: simply switch to a different click mode and try clicking the element again.
You may also have to change click modes if you notice that your recorded commands are not playing back successfully. In this case try selecting a different click mode and re-record your macro.
===To record a macro===
[[File:Record_Button.png|none]]
To start recording a macro, select one of the following methods:
* Click the "Record" button on the Record tab of the iMacros sidebar
* Click the "Record" button on the toolbar.
* Press Ctrl+F5.
Now simply perform whatever tasks you wish to record, such as surfing to web sites, filling out forms, making a test order on your e-commerce site or any other task of your choosing.
After you have finished recording press "Stop". The current recording is automatically saved as a macro named "#Current". Press "Save Macro As..." to save it as a different name, or right-click the macro in the macro list and select "Rename".
===Hints for successful recording===
* Select elements to record by clicking them with the mouse (don't use the TAB key to navigate through fields).
* During recording do not use your browser's Back or Forward button or change the address line. Use the buttons supplied by iMacros instead (iMacros Browser and IE add-on only).
* Recording "Clicks". '''If a macro generates an error during replay you can experiment by selecting the link recording option (''Click Mode'') manually from the dialog after clicking ''Click Mode''.'''
* Because the iMacros recording language is [[Command_Reference#iMacros_Commands_Reference|fully documented]] it is easy to edit and "tweak" the macro manually after recording!
* The iMacros Standard and Enterprise Edition licenses include [http://imacros.net/support one year of expert technical support]. Our support team is ready to help you with your project and any recording issues that you might encounter.
Related animated tutorial: [[Tutorials#Recording_a_Macro|Recording a macro]]
==Playing Macros==
[[Image:Play_Toolbar_Button.png|none]]
To play a macro, first select the macro in the macro list and then choose one of the following methods:
* Click the "Play" button on the toolbar.
* Click the "Play" button or on the Play tab of the sidebar.
* Simply double-click the macro in the list.
* Press the F5 key.
During playback a blue frame shows you which parts of the web page are being manipulated. To play a recorded sequence multiple times, fill in the Max. number of times to repeat the macro and press the "Play (Loop)" button.[[Image:Play_Loop.png|frame]]
===Controlling playback speed===
There are two different options that affect the speed at which macros are replayed. These can be set in the General tab of the Options dialog as well as within the macro with the [[!REPLAYSPEED]] variable.
The first option is the replay speed, which can be set to three different values:
* FAST: the macro is replayed at maximum speed (Recommended in most cases).
* MEDIUM: iMacros waits for 0.25s between each command.
* SLOW: iMacros waits for 1s between each command.
The second option is to add timing information during recording ([[DirectScreen]] [[#What's a Click Mode?|click-mode]] only). If the "Add timing information" checkbox is checked in the Click Mode Dialog, then [[WAIT]] statements are automatically included in the macro. Thus, during replay these WAIT statements slow down the macro playback.
Of course, you can also always manually add [[WAIT]] statements to your macro to further control the speed.
===Errors during replay===
We work hard to make iMacros as "intelligent" as possible, but it still is not as smart as you. If an error occurs during replay it is mostly due to a "tricky" web page in which one of the automatic suggestions of the iMacros Recorder failed. In almost all cases re-recording the macro with different settings or manually editing the macro solves the problem. For recording tips please see the [[#Hints for successful recording|Recording]] section and for information on how to edit your macro go to the [[#Editing_Macros|Editing Macros]] section.
'''Related forum posts:'''
*[http://forum.imacros.net/viewtopic.php?f=15&t=5770 Editing a macro when automated recording fails]
*[http://forum.imacros.net/viewtopic.php?f=15&t=5744 Automating Google Maps]
'''See also:'''
* [[Browser Automation#Error Handling|Error Handling]]
'''Tip:''' If you want to prevent the blue frame from being drawn around tagged elements during playback, add the following statement to your macro:
SET [[!MARKOBJECT]] NO
==Editing Macros ==
[[Image:Edit_Macro_Button.png|none]]
(Related example macro: [[Demo-FillForm|FillForm]])
All recorded macros are stored as a plain text file with the an .iim extension in the folder specified by the "Folder Macros" setting on the Path tab of the Options dialog. The default macro folder is located in My Documents under iMacros\Macros.
You can manually edit and tweak the macros using any text editor you like, for example Notepad, which is shipped with the Windows operating system by default.
To open a macro, first select the macro in the macro list and then choose one of the following methods:
* Click the "Edit Macro" button on the toolbar.
* Click the "Edit Macro" button on the Edit tab of the sidebar.
* Right-click the macro in the list and select "Edit macro".
* Press the F9 key.
The editor specified by the "External editor" setting on the Path tab of the Options dialog ([[Editor|iMacrosEditor]] by default) will open and display the macro - in this example we chose the FillForm demo macro:
[[Image:iMacrosEditor.png]]
As a simple edit step, let's change the content of a form text field now. To change the Name below from "Tom Tester" to "Dr. A. Award" locate the TAG command that contains "Tom Tester" and change is as shown below:
Old:
TAG POS=1 TYPE=INPUT:TEXT FORM=NAME:f1 ATTR=NAME:n1 CONTENT="Tom Tester"
New:
TAG POS=1 TYPE=INPUT:TEXT FORM=NAME:f1 ATTR=NAME:n1 CONTENT="Dr. A. Award"
If the value of the [[TAG#Parameters|CONTENT]] parameter contains spaces, you must either:
* Enclose the value in double-quotes
* Replace all spaces in the text with <SP> and substitute all newlines with <nowiki><BR></nowiki>, e.g. CONTENT=Dr.<SP>A.<SP>Award. ([http://forum.imacros.net/viewtopic.php?f=2&t=4516 Related forum post]).
After you save the changes to the file, iMacros will immediately apply them during the next replay of the macro.
<!--'''Tip:''' We recommend [http://forum.imacros.net/viewtopic.php?f=2&t=4828 installing] and using the free Notepad++ editor. It not only has better features such as line numbering, but it also supports '''[http://forum.imacros.net/viewtopic.php?f=2&t=4828 iMacros syntax highlighting]'''.
[[Image:Notepad_plus_plus.png|thumb|center|800px|Notepad++ Editor with iMacros syntax highlighting for *.iim files]]
[[Image:IMacros-icon.png|iMacros Browser]] '''Coming soon!''' A built-in iMacros editor.
-->
==Next Steps==
* '''[[Tutorials|View some tutorials]]'''
* '''[[Password Security|Learn about protecting passwords in your macros ]]'''
* '''[[Browser Automation#Error Handling|Learn how to handle macro errors]]'''
* '''[[Form Filling#Variables|Learn about using variables in your macro]]'''
* Learn how to use a simple loop with a macro
* '''[[Form Filling#Wildcards|Learn about using wildcards for page elements with dynamic attributes and content]]'''
* '''[[Browser Automation#Dialog Manager|Learn how to handle browser dialogs]]'''
* '''[[Browser Automation#Saving Web Sites|Learn how to download files and page items, save complete pages, and take screenshots]]'''
* '''[[Form Filling|Learn about filling web forms]]'''
* '''[[Data Extraction|Learn how to extract data from web pages (web scraping)]]'''
* '''[[DirectScreen|Learn more about DirectScreen Technology]]'''
* '''[[Image Recognition|Learn how to use Image Recognition]]'''
* '''[[Web Testing|Learn how to use iMacros for Web Testing]]'''
* '''[[Web Scripting|Unleash the full power of iMacros with Web Scripting!]]'''
* '''[[Sample Code|Take a look at some macro and script examples]]'''
<!---
== Offline ==
If you work on a PC without Internet connection, it is recommended that you check the box "Work Offline" in the Options dialog. This avoids the Internet connection check at iMacros startup.
--->
