TAG

From iMacros
Revision as of 00:37, 11 December 2015 by Td (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The TAG command selects HTML elements from the current webpage. The identification of the element can be done by

  • the element's type, position, and attributes,
  • the XPATH to element, or
  • the CSS selector for the element.

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. If the selected element is part of an input form then the CONTENT parameter can be used to fill content into the selected field.

Syntax iMacros Browser IE Plug-in Firefox Chrome

TAG POS=n TYPE=type [FORM=form] ATTR=attr [CONTENT=some_content]

or

TAG XPATH="[xpath_expression]" [CONTENT=some_content]

or

TAG SELECTOR="[selector_expression]" [CONTENT=some_content]

Parameters

  • POS
    Specifies the number of the occurrence of the HTML element. By default the occurence is counted from the top of the page. By using "POS=Rx" the occurrence can also be relative to the previous TAG command (see Relative Positioning for more details on this concept.)
  • TYPE
    Specifies the HTML type of the element
  • FORM
    Specifies the name of the parent FORM element (only valid for FORM child elements).
  • ATTR
    Specifies the identifier for the selected element.
  • CONTENT
    Specifies the content to send to the selected element (only valid for FORM child elements).
    Replace blank spaces with <SP>, e.g. CONTENT=Hello<SP>world, or enclose the content in double-quotes: CONTENT="Hello World"
    Double curly brackets must be escaped with #NOVAR#, e.g. CONTENT=#NOVAR#{{somevalue}} will treat {{somevalue}} as a literal value and not a variable reference.
  • EXTRACT
    Specified the type of extraction to be carried out
  • XPATH
    An XPath expression to localize the element on the page
  • SELECTOR
    A CSS Selector expression identifying the element on the page

Remarks

For the TYPE, FORM and ATTR parameter sub-parameters are used. Sub-parameters are used in the form parameter=sub-parameter:value.

  • Especially in the ATTR parameter, extensive use of the wildcard character '*' can be made.
  • The TAG command also incorporates the EXTRACT functionality of iMacros, post Version 6.0. Giving an additional EXTRACT parameter to identify the type of extraction to perform.
  • For more background information on how TAG is related to the HTML source code, visit TAG parameters explained

Following links

To follow links the TYPE parameter of the TAG command is set to A. For text links the FORM parameter is not needed. Which link will be followed is solely determined by the POS and the ATTR parameter. Except for the number of the occurence on the page (determined by the POS parameter) a link is uniquely identified by its name and its URL. Therefore, the ATTR parameter offers two different sub-parameters: TXT and HREF. To select a link by its name use

ATTR=TXT:some_name, 

to select by its URL use

ATTR=HREF:some_url. 

Sometimes iMacros does not wait long enough for a TAG command to appear. This can be avoided by increasing the !TIMEOUT_STEP wait time.

How to avoid following links

If you want to use a link or button as a reference, you should tag it with TAG ... EXTRACT=TXT, to avoid following the link or "clicking" the button. In that case, do not forget to use SET !EXTRACT NULL, to clear the extract variable before the real extract.

Timeout

Sometimes text does not appear immediately after a page is loaded. Examples include ajaxy websites or intermediary pages that display some kind of "processing request" message.

So if you need to wait for some text to appear saying that a transaction is processed/completed, the good news is that he TAG command takes care of this automatically:

TAG waits !TIMEOUT_STEP seconds and checks every second to see if the text is here. The default wait time is 6 seconds.

Filling forms

On one webpage several forms can appear, therefore the FORM parameter determines which form to use by its NAME sub-parameter. The input type is selected using the TYPE parameter, if necessary with the sub-parameter INPUT.

Special TAG Commands for Drop Down Menus

The CONTENT parameter is used to specify which element of a drop down menu (generated by the HTML SELECT command) is selected.

 <select name="select1">
 <option value="">Select Fruits</option>
 <option value="AP 1">Apple</option>
 <option value="BN">Banana</option>
 <option value="Special">Kiwi</option>
 </select>

By default the CONTENT parameter of TYPE=SELECT stores the value of the option, if that is available. Otherwise, iMacros uses the the display name of the chosen option. The third possibility is the position in the list (also called index) of the selected value.

You can manually change this so that an entry is selected by its name, its index, or its value. The name of the menu item is the text which is displayed in the drop down menu. The value is the text that follows the VALUE= parameter in the OPTION tag. The index is the position of the option in the list of possible options, starting from 1.

To select an entry by its name add a $ before the name so that the command looks like

TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=$Apple 

To select an entry by its value use the percent symbol (%)

TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=%AP<SP>1 

To select an entry by its index use the # symbol

TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=#2

Spaces can be written as <SP>, or the content should be put inside double quotes (").

TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=$French<SP>Fries
TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=$"Bread & Butter"

The comparison in the latter two cases is case insensitive and wildcards (*) can be used.

In multiple selection menus multiple selection can be achieved by listing indices separated by a colon (:).

TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=$Apple:$*berry*:$Peach 
TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=#1:#3:#8 

To select all values of a selection use CONTENT=ALL. If you start the macro via iimPlay and select a value that is NOT in the selection then the iimPlay command returns an error code that is the maximum number of lines possible. For an example, please see this forum post: Number of Options in a Select tag.

iMacros for Firefox/Chrome Note:

When you use the $, % and # symbols with variables, the symbols must be outside the {{..}}, so that iMacros can see the variable type while parsing. This is just as in any other scripting language where you have to declare the type before usage:

This will not work in iMacros For Firefox or Chrome:

 'Example on how NOT to it
 SET !VAR1 $*apple*
 TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT={{!VAR1}}

This works:

 'Correct $,%,# usage
 SET !VAR1 *apple*
 TAG POS=1 TYPE=SELECT FORM=NAME:form1 ATTR=NAME:select1 CONTENT=${{!VAR1}}

Hidden Input

Hidden input fields are used in HTML to write information (like usernames are session IDs) in the HTML code so that the user does not have to type them in manually every time a new page is loaded. Since hidden fields are not displayed in the browser the TAG command for them cannot be generated during normal recording. But you can add TAG commands with TYPE=HIDDEN manually into the macro and iMacros will fill these hidden fields during replay. To do this record a TAG command for a visible field (e.g. the name input field) and you get:

TAG POS=1 TYPE=INPUT:TEXT FORM=NAME:TestForm ATTR=NAME:Name CONTENT=Peter 

To modify this for the hidden field we change the TYPE from INPUT:TEXT to INPUT:HIDDEN and the name from Name to abc:

TAG POS=1 TYPE=INPUT:HIDDEN FORM=NAME:TestForm ATTR=NAME:abc CONTENT=999999 

File Upload

Internet Explorer and other browsers do not allow direct filling of any fields with the type FILE. Typically these fields are used for uploading files. However, iMacros can fill these fields with the TAG command automatically. More details, including how to record such a command, can be found in Demo-Upload.

Related forum post: Automating a tricky file upload dialog

Triggering events

Sometimes it is required to fire certain events concerning a web site element characterized by the parameters in the TAG command. To fire an event set EVENT:event_name as the CONTENT parameter.

  • SAVEITEM
    This event can be used to save items, mostly images, from any web site. A command doing this is most easily compiled by using the Save Item Wizard or clicking on the elements during record and adding CONTENT=EVENT:SAVEITEM manually. To control the location and name of the downloaded file use the ONDOWNLOAD command.
  • SAVE_ELEMENT_SCREENSHOT
    Takes a "screenshot" of the tagged element and saves it as a PNG file cf. SAVE_ELEMENT_SCREENSHOT
  • SAVETARGETAS
    This event is named after the corresponding function in the Internet Explorer menu: "Save Target as". You can right-click on any web page element to see if the web page element supports this feature. To create such a command you have to click on the elements during record and add CONTENT=EVENT:SAVETARGETAS manually. To control the location and name of the downloaded file use the ONDOWNLOAD command. Example: Demo-SaveTargetAs
  • MOUSEOVER
    For the selected element a mouseover event is triggered. This is sometimes needed to change the state of an image.
    (currently not implemented in iMacros 7 and later, see workaround)
    Related forum posts: How to issue mouse events using Javascript, Trigger Javascript function
  • FAIL_IF_FOUND
    This event is an iMacros internal event as opposed to an HTML event. It is useful when doing keyword searches.
Example: download image
URL GOTO=http://www.iopus.com/imacros/demo/v6/images/bigbee.jpg
ONDOWNLOAD FOLDER=* FILE=*
'Download the picture by either of the following:
TAG POS=1 TYPE=IMG ATTR=HREF:http://*.jpg CONTENT=EVENT:SAVEITEM
'TAG POS=1 TYPE=IMG ATTR=HREF:http://*.jpg CONTENT=EVENT:SAVE_ELEMENT_SCREENSHOT

EXTRACT

Extracts data from websites. Use the attribute ATTR to determine which part is to be extracted. Normally this part is generated by the Extraction Wizard. The EXTRACT command searches the HTML source code of the website for the nth occurrence of ATTR and extracts it. The ATTR must always end with a wildcard *.

If several EXTRACT commands appear in one macro the results are separated by the string [EXTRACT]. This string is automatically translated into a line break when using the "SAVEAS TYPE=EXTRACT" command.

If a complete table was extracted then adjacent table cells are separated by the string #NEXT# and table rows are delimited by the string #NEWLINE#. These tags are automatically translated into commas and newlines when you use the "SAVEAS TYPE=EXTRACT" command, but the delimiters are retained when returning the data to a script via a call to iimGetLastExtract. If the table you are attempting to extract also contains nested tables, then the inner table data will also be delimited with #NEXT# and #NEWLINE# (to make the data easier to work with, only extract the innermost table that you need).

  • The following values may be specified in the EXTRACT parameter of a TAG command.
    • TXT
      Plain text extraction, all HTML tags are taken out.
      When used with a drop-down list (select element), it extracts the selected (visible) entry.
    • TXTALL
      For use with a drop-down list (select element). It extracts all entries of the list.
    • HTM
      The full HTML of the element the extraction anchor points to. Note: In the iMacros Browser and IE the HTML tags are always returned in caps. So <b>test</b> is extracted as <B>test</B>.
    • HREF
      The URL of the page element the extraction anchor points to.
    • ALT
      The alternative text of an image the extraction anchor points to.
    • TITLE
      The title attribute of an element, e.g. the tooltip text.
    • CHECKED
      Status of a checkbox or radiobutton. It returns "true" when the box is checked, otherwise "false" (Related forum post: [1])

Note: When extracting text from input boxes (TAG command contains "TYPE=INPUT"), there must not be a "CONTENT" parameter. Cf. the FAQ: How do I extract the content of an Input Box?

Extract Custom Attributes

Starting with iMacros 10.2, you can extract any attribute. If you want to know which attributes are available, record the TAG command in Expert Mode.

Example:

Normally, the tooltips are specified by the TITLE attribute of an element. You can extract the tooltip content with iMacros:

7.1.png



The qTip tooltip plugin for the jQuery JavaScript framework uses not the title attribute but a custom attribute named "data-qtip":

7.2.png



ComputerName=* is the initial immutable part of the tooltip content and is used to specify which tooltip should be extracted. Recording in Expert Mode will create a TAG command that consists of all attributes of the clicked HTML element.

Extract Data from a Dialog

Extracting web dialogs is covered here: !EXTRACTDIALOG

Examples

See any of the example demos in the Macros\ directory of your iMacros installation.

TAGs and HTML

A general information about the relation between the HTML source code and the TAGs that work on this code, can be found here: TAG parameters explained (older version: TAGs_and_HTML).

A test page is available at [2]. You can consider the content of the test page the specification of the TAG syntax for all pratical purposes.

Related Forum Posts

See Also

Fine Tune TAG Commands, TAG parameters explained, FRAME, TAB, EVENT, BACK, URL