TagUI automates your actions by running flows, which are text files with .tag file extension.
You can run a flow in the :ref:`Command Prompt/Terminal<how-to-use-command-prompt>` like this:
tagui my_flow.tag
TagUI looks for my_flow.tag in your current working directory. You can also provide the full path:
tagui c:\tagui\samples\1_google.tag
You can also :ref:`run flows on a fixed schedule <run-on-schedule>`.
You can create a shortcut file with -deploy:
tagui my_flow.tag -deploy
or using the shortcut -d:
tagui my_flow.tag -d
This creates a shortcut (my_flow.cmd) to run your flow just by double clicking the shortcut. The shortcut is in the same folder as your flow, but you can move it to your desktop or anywhere else.
If you want to create the shortcut with options like -headless (-h), you can include them:
tagui my_flow.tag -h -d
Note
If you move your flow file to another folder, you will need to create a new shortcut file.
You can also run a flow directly from a URL:
tagui https://raw.githubusercontent.com/kelaberetiv/TagUI/master/flows/samples/1_google.tag
You can run web flows without showing web browser by running TagUI with -headless option.
tagui my_flow.tag -headless
or using the shortcut -h:
tagui my_flow.tag -h
This allows you to continue using your desktop normally while the flow is running, but it will not work if your flow uses visual automation, because it reads and clicks what is on your screen.
Flows are made out of steps. Below are some common steps.
You can see the full list of steps in the :ref:`steps reference <step-reference>`.
One of the most common steps is click. You can use it to click on a web element:
click Getting started
This command tells TagUI to try to click on any element which has “Getting started” as its “id”, “name”, “class” or “title” attributes (:ref:`How to find an element’s attributes <element_attributes>`), or as a last resort, has “Getting started” in its text.
This method usually works for targeting what you want, but you can be more explicit by providing an XPath. XPath is a powerful way to choose which web element you want to target. For example:
click //a[@class="icon icon-home"]
You can also click on a certain point on your screen:
click (500,300)
Here, 500 and 300 are x-y coordinates. This command clicks on a point which is 500 pixels from the left of your screen and 300 pixels from the top of your screen. A good way to discover which coordinates to input is to use the mouse_xy() :ref:`helper function <helper-functions>` in live mode.
Lastly, you can use visual automation to click where it matches a previously saved image. This command looks for button.png in the same folder as your flow, then looks for a similar image on your screen, and clicks it:
click button.png
It’s often a good idea to keep your flows and images organised. You can create a folder (eg. named images) for your images and use the image like this instead:
click image/button.png
You can visit a webpage simply by entering the url:
https://somewebsite.com
You can type into web inputs. This command finds the element “some-input” in the same way as for the click step and types “some-text” into it:
type some-input as some-text
You can use [clear] to clear the input and [enter] to hit the Enter key:
type some-input as [clear]some-text[enter]
You can also use an image as the target, just like with the click step:
type some-input.png as some-text
The read step allows you to save text from web elements or from the screen into a variable.
This command finds the element “some-element” and saves its value into a variable called “some-variable”:
read some-element to some-variable
read can also use visual automation and OCR to read text from a region of your screen. The output from this may not be completely accurate as it relies on OCR.
This command reads all the text in the rectangle formed between the points (300,400) and (500,550):
read (300,400)-(500,550) to some-variable
You can also use XPath to read some attribute values from web elements. This command reads the id attribute from the element:
read //some-element/@some-attribute to some-variable
You can assign values into variables. This makes them easier to reference and work with.
This example uses the count() :ref:`helper function <helper-functions>`, counts the number of elements found with id/name/text with ‘row’ in them and assigns it to a variable row_count for later use:
row_count = count('row')
You have probably noticed that different steps have different ways that they target elements, called identifiers. Let's look at the different types of identifiers.
Note
The DOM and XPath identifiers only work for Chrome/Edge. To automate other browsers, use the Point/Region and Image identifiers.
click Getting started
This matches an element in the DOM (Document Object Model) of the web page, matching either the :ref:`id, name, class attributes <element_attributes>` or the text of the element itself.
click //body/div[1]/nav/div/div[1]/a
This matches the :ref:`XPath <find-xpath>` of an element in the web page.
It is a more explicit and powerful way of targeting web elements.
Note
You can use CSS selectors too in place of XPath, but XPath is preferred.
click (200,500)
This matches the point on the screen 200 pixels from the left of the screen and 500 pixels from the top of the screen. This uses visual automation.
read (300,400)-(500,550) to some-variable
This matches the rectangle formed between the two points (300,400) and (500,550). See :ref:`Point <point>`. This uses visual automation.
click button.png
This matches any area on the screen that looks similar to an image file button.png (in the folder of the flow). You first need to take a screenshot of button.png. This uses visual automation.
click image/button.png
This allows you to look for button.png within the image folder.
We recommend using live mode when you want to write your own flows or try out some step. In :ref:`Command Prompt/Terminal <how-to-use-command-prompt>`:
tagui live
This starts up a live session, where you can run steps one line at a time and immediately see the output. Within a TagUI flow, you can also use live step to pause execution and enter live mode.
You may want your flow to do something different depending on some factors. You can use an if condition to do this.
For example, if the URL contains the word “success”, then we want to click some buttons:
if url() contains "success"
click button1.png
click button2.png
url() is a :ref:`helper function <helper-functions>` that gets the url of the current webpage. Note that the other lines are indented, ie. there are spaces (or tabs) in front of them. This means that they are in the if block. The steps in the if block will only be run if the condition is met, ie. the url contains the word “success”.
Note
Before v6, you need to use { and } to surround your if block.
From v6 onwards, the curly braces {} are optional.
Another common case is to check if some element exists. Here, we say that “if some-element doesn’t appear after waiting for the timeout, then visit this webpage”.
if !exist('some-element')
https://tagui.readthedocs.io/
The ! negates the condition and comes from JavaScript, which TagUI code eventually translates to.
In below example, we check if a variable row_count, which we assigned a value earlier, is equal to 5:
if row_count equals to 5
some steps
Here’s how we check if it is more than or less than 5:
if row_count more than 5
some steps
if row_count less than 5
some steps
You can use loops to do the same thing many times within the same flow. In order to run one flow many times with different variables, the standard way is to use :ref:`datatables <datatables>`.
In this example, we repeat the steps within the block for a total of 20 times:
for n from 1 to 20
some step to take
some other step
some more step
Helper functions are useful JavaScript functions which can get values to use in your steps.
Each helper function is followed by brackets (). Some helper functions take inputs within these brackets. You can see the full list of helper functions in the :ref:`helper functions reference <helper-functions-reference>`.
Turns some variables into csv text for writing to a csv file. It takes variables as its input, surrounded by square brackets [] (which is actually a JavaScript array).
read name_element to name
read price_element to price
read details_element to details
write `csv_row([name, price, details])` to product_list.csv
Gets text from the clipboard:
dclick pdf_document.png wait 3 seconds keyboard [ctrl]a keyboard [ctrl]c text_contents = clipboard()
You can also give it an input, which puts the input onto the clipboard instead. This can be useful for pasting large amounts of text directly, which is faster than using the type step:
long_text = "This is a very long text which takes a long time to type" clipboard(long_text) click text_input keyboard [ctrl]v keyboard [enter]
Gets the mouse's x or y coordinates.
This is useful for modifying x or y coordinates with numbers for using in steps like read and click. The example below clicks 200 pixels to the right of element.png:
hover element.png x = mouse_x() + 200 y = mouse_y() click (`x`,`y`)
In live mode, you can use find out the coordinates of your mouse using echo `mouse_xy()` so that you can use the coordinates in your flows:
echo `mouse_xy()`