PhraseExpress v14 for Windows - Macro Functions

Table of Contents

Introduction

Macro functions extend static phrases with additional features, such as dynamically linking external file contents, prompting for text input or adding current time & date stamp.

Macro functions can also launch programs, open documents, or websites, display message dialogs or notifications or create input forms, link phrases, calculate math expressions and so much more…

PhraseExpress automates repetitive tasks by emulating key press sequences and with the help of string operations, program loops, variables and conditional statements.

Native support of the macro software Macro Recorder turns PhraseExpress into a full-fledged automation solution.

PhraseExpress for Mac, iPhone/iPad and Android "support a selection of macro functions with an adapted feature set.

How it works

Macro functions are place holders which are replaced with dynamic contents into the static phrase at the time of execution.

Example

The current date is CurrentDate. The current time is CurrentTime.

PhraseExpress processes macro functions sequentially (with the only exception of form macros) and replaces the macro placeholder with the current date:

The current date is 09/19/2018. The current time is 09:45am.

If you trigger the same phrase on a later day, the corresponding date and time would be inserted.

Adding a macro

To add a macro function to a phrase:
  1. Click in the phrase text, where you wish to add a macro.
  2. Select the desired macro function from the Ribbon main menu.
  3. Configure the parameters in the macro configuration dialog.

To edit an existing macro function, double-click the macro place holder token.

Macro configuration dialog

A typical macro configuration dialog includes input fields to enter the macro function name and several macro parameters which are explained in the following chapters.

If ticking the option "Global", the macro contents will not be stored within the phrase contents but in the a global variable manager.

You can also specify additional processing steps in each macro input dialog.

Macro name

The macro name is the text label of the macro token/placeholder:

Macro name

Choose a short and descriptive name.

Example: For a macro, that outputs a the current date plus 14 days for a payment reminder phrase, you may want to name it "Date+14d" or "PaymentReminderDate".

Without a name, macro code is shown in the phrase instead of the beautiful macro token. The code view may be interesting for users only, who like taking a peek under the hood.

You can toggle between code vs token view at any time by defining a macro name or removing it.

To learn more about the classic code syntax, visit the legacy macro documentation.

Macro parameters

Most macro functions have parameters and options which are explained in this documentation.

The awesome part: Macro parameters may contain macro functions themselves!

Example applications:
To achieve the latter example:
  • Create a phrase and click where you wish to add the macro function.
  • Select macro "User input » Manual input".
  • Click the icon in the input field "Default".
  • Select macro function "Time/Date" and configure that macro in its own macro configuration dialog.
  • By clicking OK , the date/time macro token is inserted in the input field "Default".
  • By clicking OK in the "Manual Input" macro dialog, the entire nested macro function is inserted into the phrase.

Done!

Additional processing

The output of a macro can be processed by a queue of additional macro functions:

Additional processing

 

To add processing steps, click the button "Additional processing" at the bottom of a macro input dialog and add processing steps as required. All processing steps will be daisy chained and executed from top to bottom.

Example: To create a prompt for a text input which is then changed to upper case and finally placed into the clipboard:

  1. Add a "Manual Input " macro.
  2. In that macro input dialog, click the button "Additional processing" at the bottom.
  3. In the subsequent window, click "Add processing" and select "Set to upper case" from the list of actions.
  4. Add a second processing step and select "Set clipboard content".
  5. Confirm all dialogs with OK

Done!

For experienced PhraseExpress users: Each processing step in the processing queue encloses the current macro onion-like (like nested macros in previous PhraseExpress versions).

Global variables

To reuse macros in multiple phrases, you can optionally store them in a global macro repository. Such global variables are managed in the Variables Manager.

To show/hide the variables manager, click the icon in the main menu:

The Variables Manager is located next to the phrase contents, allowing you to easily drag & drop variables into the phrase contents box.

If you use multiple phrase sources, e.g. a local phrase file and a SQL server connection, each source uses its own independent and isolated depository of global variables.

Converting macros into global variables

You can turn any macro in any phrase into a global variable to make it reusable for multiple phrases.

To turn a macro into a global variable:
  1. Open the macro dialog of any macro function in any phrase.
  2. Check the option "Global" next to the macro name input box:
  3. Confirm with OK.

Or alternatively:

  1. Make sure, that the variables manager is visible (if not, click the variables manager icon in the main menu).
  2. Drag the macro located from a phrase contents into the free area of the variable manager.
  3. Confirm the confirmation dialog.

When converting the macro into a global variable, the macro contents will be moved out of the phrase contents into the global variables repository. The placeholder in the phrase will then link to the global variable. You can reuse the global variable in any other phrase of the same phrase file/database.

To unlink a variable in a phrase from the global variable, double-click the placeholder in the phrase and uncheck the "Global" option. PhraseExpress will then create a copy of the global variable within the phrase and unlink that copy from the global variable.

Important: Global variables of one phrase file cannot be used in phrases of another phrase file.

Creating global variables

You can also create a global variable from scratch.

To create a new global variable:
  1. Make sure, that the variables manager is visible (if not, click the variables manager icon in the main menu).
  2. Right-click into the free space of the global variables manager, and select "New" (or press hokey CTRL+N):
    Context menu
  3. Enter the desired content (any text and/or macro functions).

Custom global variables allow you to optionally enter text only, e.g. a term, that you need in multiple other phrases. This could be a specific text, you use throughout your phrase library and which can you can centrally change in the global variables manager. You can also generate a global variable with a macro function.

Inserting global variables

To insert a global variable into a phrase:
  1. Make sure, that the variables manager is visible (if not, click the variables manager icon in the main menu).
  2. Drag the global variable token from the variables manager into the desired position of the phrase contents.

Done. It's that easy and you can repeat this simple drag & drop operation for multiple phrases as needed.

Editing global variables

To edit a global variable:
  1. Double-click the global variable token, either in any phrase or in the global variables manager.
  2. Make the desired changes in the dialog window and confirm with OK.

Done! The change will immediately take effect for all phrases using the global variable throughout the library.

There are no access restrictions on global variables. All users can edit global variables.

Deleting global variables

To delete a global variable:
  1. Make sure, that the variables manager is visible (if not, click the variables manager icon in the main menu).
  2. Right-click the global variable, you wish to delete, and select "Delete.":
    Context menu
  3. Confirm the warning dialog with OK.

Done! The global variable is now removed from the variable depository.

You can only delete abandoned global variables, that are not used by any phrase. To perform a search for all phrases using the global variable, right-click the global variable and select "Show all phrases using this variable":
Context menu
Then remove the global variable from the contents of all phrases to be able to delete that global variable.

You can't delete global variables, that are used in phrases you do not have access rights to.

Deleted variables will not be deleted from any backup.

Macro Functions

Date/Time

This macro function outputs the time and/or date in specific format and with an optional time shift.

Applications:
  • Output the current time or date in specified format and language.
  • Output specific parts of a date or time, e.g. the current month's name or the day of the week.
  • Output of a shifted date or time, e.g. next month, the current time plus three hours or any given date plus 14 (work) days. This may be versatile for invoice reminder boilerplate templates or out-of-office notifications.
  • Output of the rounded time, e.g. "11:45am" instead of "11:39am".
Format

Pick one of the presets on the left or define the desired formatting by entering one or more of following shortcuts in the input field "Format":

Unit Meaning
d Day without a leading zero (1-31)
dd Day including a leading zero (01-31)
ddd Abbreviated weekday (Sun-Sat)
dddd Weekday (Sunday-Saturday)
dddddd Date in standard format
m Month without a leading zero (1-12). If the following parameter is h or hh, then the minute is being displayed instead of the month
mm Month including a leading zero (01-12). If the following parameter is h or hh, then the minute is being displayed instead of the month
mmm Abbreviated month (Jan-Dec)
mmmm Month (January-December)
yy Year with two digits (00-99)
yyyy Year with four digits (0000-9999)
h Hour without a leading zero (0-23)
hh Hour including a leading zero (00-23)
n Minute without a leading zero (0-59)
nn Minute including a leading zero (00-59)
s Second without a leading zero (0-59)
ss Second including a leading zero (00-59)
am/pm 12-hour time prefix am or pm
Region

PhraseExpress uses the language as configured in the Windows OS regional settings to output date information such as "Monday" or "July".

The macro parameter "Region" allows you to specify another language:

Datum in verschiedenen Sprachen

Time shift

A date and/or time shift can be added to the current time and date, for example to output a payment term (current date plus 14 days).

Rounding

Time stamps can be rounded to the quarter, half and full hour.

Value

A date can be passed via parameter "Value" to perform date-/time-shift calculations.

Date calculations

This macro function calculates the number of days, workdays, weekdays, weeks, months, or years between two dates, specified in the format of the current Windows regional settings.

Example for the US: 01/16/2019

Example for Europe: 16.01.2019

If no date is specified, the current date is used.

Each months has 30.4375 days. Months are rounded in whole numbers.

User Input

PhraseExpress can prompt the user to enter information before or while it inserts a phrase:

The user input then replaces the macro placeholders in the phrase or it can be processed by other macro functions.

Manual text input

This macro function prompts the user to enter text:

Input

The input box can be a single-line or multi-line input.

The user input can be checked for specific syntax to prevent typing errors. In case of a syntax error, a notification is shown. Experienced users can enforce user input of a specific format defined with a (Perl) "Regular Expression".

RegEx Examples:
Desired Input Regular Expression
Text of specific length (2-5 chars): [\s\w\d]{2,5}
Number of specific min and max value (1-99): ^([1-9]|[1-9][0-9])$
Hexadecimal values: [0-9A-F]
Hexadecimal values of specific length (6 chars): [0-9A-F]{6}

Perl RegEx documentation and additional examples

Input form

Forms collect multiple input before a phrase is inserted.

Before a phrase is inserted, PhraseExpress scans it for any form macro and dynamically generates an input form.

After the form is filled, PhraseExpress replaces the form macro placeholders with the corresponding input throughout the phrase and inserts the whole text.

This phrase opens a form to prompt for user input:

Form example

After filling the form, PhraseExpress replaces the form macro functions with the user input and outputs the phrase:

Customer Name: Michael

The customer is an existing customer.

The customer is using version 14.

Macro functions are processed recursively by default, starting with inner nested macros to outer macros. Form macros are an exception as they are sequentially processed. Macro functions nested within a form macro are processed recursively.

If the same input is required at multiple positions throughout a phrase, use the identical label for all related form macros. Only one instance of the objects that have the same label will be shown in the form.

How to create a form:
  1. Start with the text phrase foundation, that shall include a form.
  2. In your phrase, put the cursor where user input shall be inserted and add a form macro function. This place holder will be replaced by the user input when the phrase is being executed.
  3. Repeat step 2 for all user input.

Form input

The form input provides multiple different types of input controls.

Input type

Parameter "Type" allows you to choose from a variety of input types.

Dynamic form elements

Form input elements can be shown depending on the input of another form input of the same form.

To control, visibility of a form input element, check option "Visible only on input in…" and select the user input, that shall control the visibility.

Numeric input

This macro function adds a numeric input box to a form:

Number input

Group

This macro function groups a set of form elements and outputs the user input by customizable enumerators:

Form group

The example creates a group of 3 form elements. Their output will be separated by ", ". The last checked item will be separated by " and ".

Number Slider

This macro function adds a slider for number input:

Slider

Appearance

This macro function specifies the form window title text and width.

This macro must be placed in the very beginning of the phrase.

Text label

This macro function adds a text label to the form:

Form label

Separator

This macro function inserts a horizontal line to visually separate form contents:

Separator

WYSIWYG Forms

WYSIWYG forms allow you to place text input boxes, dropdowns, phrase selection dropdowns, checkboxes and date selection within a formatted phrase. Any form input is inserted the actual position of the input control.

If nesting with other macro functions is required, we recommend that you use the form functions described above.

Document Generator

The Document Generator allows users to create a document by selecting multiple phrases in an easy-to-use front end.

Please check the Document Generator manual for details.

Open File dialog

This macro function opens the Windows dialog to select a file and outputs returns the selected file path:

Open file dialog

This macro useful to feed other macro functions for advanced macro programming.

Save File dialog

This macro function opens the Windows dialog to select a file to save:

File save dialog

The macro returns the selected file path that can be used with other macro functions.

External Data

MS Outlook Add-In

PhraseExpress can extract data from incoming emails in Microsoft Outlook.

Please check the Outlook Add-In manual for details.

Embed external file

This macro function inserts the contents of the specified file into the phrase.

Supported file types:
File Type File Extension
Text files .TXT, .RTF, .HTM, .HTML, .DOC, .DOCX

Bitmap files

.BMP, .JPG, .PNG

Microsoft Word files are supported in the Pro Edition (or higher) only and require a Microsoft Word installation.

Insert external file

This macro function copies the contents of the specified file into the clipboard and pastes the clipboard into the target application. For Microsoft Word files, see above.

{#INSERTFILE …} replaces/combines earlier macro functions {#IMGFILE …} and {#TEXTFILE …}.

CSV file values

This macro function inserts a specified values of a CSV file ("comma separated values).

You can define a range of values by their start and end row/column coordinates. Multiple cells can optionally be separated with a separator text.

MS Excel cell contents

Video tutorial

This macro function inserts a specified range of cells of a Microsoft Excel spreadsheet.

You can define a range of cells by their start and end row/column coordinates. Multiple cells can optionally be separated with a separator text.

PhraseExpress uses column numbers instead of letter coordinates (so called "R1C1 reference style") to allow you to calculate cell coordinates with the calculation macro function.

To insert the whole spreadsheet instead of a range of cells, use this macro function.

Find MS Excel column

This macro function returns the column coordinate (beginning with 1) of the specified Microsoft Excel spreadsheet, that contains the specified search string.

This macro function requires a Microsoft Excel installation.

Find MS Excel row

This macro function returns the row coordinate (beginning with 1) of the specified Microsoft Excel spreadsheet, that contains the specified search string.

This macro function requires a Microsoft Excel installation.

XML value

This macro function inserts a XML file value, addressed by its xpath value (see Wikipedia).

This macro function can be used as a data bridge to external databases which can create an XML file.

PhraseExpress accepts files and URLs of XML files stored on a web server.

Windows environment variable

This macro function inserts the specified Windows environment variable (see Wikipedia).

ActiveDirectory variable

This macro function inserts the specified LDAP variable into the phrase.

This macro is useful e.g. for email signatures which are dynamically filled by the ActiveDirectory variables.

Output

Simulate key press

PhraseExpress can simulate keystroke combinations, e.g. to automate programs:

For advanced automation tasks also check the Macro Recorder.

Application Example

jondoeTABpasswordENTER

Above example outputs "jondoe", followed by the TAB-key, the text "password" and the ENTER-key. This is useful to automate the login procedure at website logins.

Keyword list:

CTRL, ALT, SHIFT, SPACE, BKSP, TAB, BREAK, DEL, LEFT, RIGHT, UP, DOWN, ENTER, ESC, NUMPAD0, NUMPAD1, NUMPAD2, NUMPAD3, NUMPAD4, NUMPAD5, NUMPAD6, NUMPAD7, NUMPAD8, NUMPAD9, MULTIPLY, ADD, SEPARATOR, SUBTRACT, DECIMAL, DIVIDE, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, INS, HOME, END, PGDN, PGUP, PRTSC, SCROLLLOCK, NUMLOCK, CAPSLOCK, LWIN, RWIN, NONE

Random text

This macro function inserts one of the specified texts by random:

Random text

The items can also include macro functions.

Output to file

This macro function saves the specified text contents into a file.

This macro function requires a Microsoft Word installation.

PhraseExpress must have file write permissions for the defined storage location.

E-Mail attachment

This macro function pastes the specified file to the target application by using the Windows clipboard.

This is useful to attach a file to an open email message window.

You may need to add a delay to give Outlook some time to process the data.

Mail program "Thunderbird" doesn't seem to accept file attachments provided by the clipboard.

Message window

This macro function opens a windows with the specified text and configured OK/Cancel or Yes/No buttons:

Message box

Notification

This macro function shows a click-able notification with the specified text near the Windows system tray:

Notification

 

The notification feature must be enabled for PhraseExpress in the Windows 10 settings under "System » Notifications & Actions".

ASCII char

This macro function pastes the special character with the three-digit character code just as you would when using the ALT-key while entering the three-digit character code on the extended number block.

Example: The copyright-symbol © can be pasted by using the macro with the code 169.

The MS Windows utility Charmap provides an overview of the special characters including their code.

Random number

This macro function pastes a random number between 0 and the specified maximum value.

Set cursor position

This macro function places the cursor to the macro position within a phrase after insertion of that phrase.

Example

The cursor will be here: CURSOR and not at the end of the phrase.

This macro only works for phrases without text formatting that are pasted using the key-by-key paste method. The cursor position can be affected by other macros as they can alter the offset from the beginning of the phrase contents.

Automation

Macro Recorder Automation

This macro function launches the separate software "Macro Recorder" and playback the macro automation which has been created in Macro Recorder through PhraseExpress.

The automation data is stored in the macro (i.e. the phrase file/database).

Double-Click the macro to edit the automation in Macro Recorder.

Automation playback and editing requires an installed Macro Recorder.

Create email

This macro function creates a new email with your default email client.

Strange characters in the mail body may be caused by email programs with UTF-8 character encoding (e.g. Microsoft Outlook ). In such a case, please enable UTF-8 support in the PhraseExpress expert settings.

Multiple file attachments can be separated by a vertical line ("pipe char").

If the attachment file names contain space characters, you must enclose the path in "".

The email macro offers additional features if using Microsoft Outlook, such as definition of a file attachment and unlimited body text length. On the other hand, email sent using the mailto: system command only offers a limited body text length. Reduce the amount of text if an error message occurs.

Open a web page

This macro function opens the specified web page in the default internet browser.

The wait switch pauses the phrase execution until the web page is fully loaded (IE only) or after the optional timeout (in seconds).

Open File Explorer

This macro function opens the specified file folder in Windows Explorer.

Launch program

This macro function launches the specified program.

If the desired application is not registered in Windows, you need to enter the full program path.

If you wish to automate any further action in the application launched by the macro function, you need to set the input focus to that application. Otherwise, further macro functions will be executed in the app, from where you triggered the phrase.

Open a file

This macro function opens the specified file with the default application associated with the file type.

If the desired application is not registered in Windows, you need to enter the full program path.

If the macro opens another program and if you wish to execute further macro functions in that application, you need to set the input focus to that application with the macro function {#FOCUS …}. Otherwise, further macro functions will be executed in the app, from where you triggered the phrase.

Set focus

This macro function switches focus to the specified Windows application based on its windows title (e.g. "calculator"). The function is ignored if the specified application is not running.

You can also use a wildcard * within the windows title definition.

Loop Function

This macro function repeats the specified contents x-times.

Programming

Link phrases

This macro function inserts the contents of another phrase:

Insert phrase

 

You can also drag & drop phrases from the phrase tree directly into the phrase contents field to link it to the phrase you are currently editing. PhraseExpress automatically create the macro at the position where you drop the phrase.

Benefits of using nested phrases
  • Nested phrases work like a template system. Footer text changes automatically take effect on all phrases which refer to it and you do not need to enter the phrases individually. This is nice if, e.g. only the phone number in a footer needs to be updated or if you would like to add a temporary special offer advertisement to your footer.
  • You save storage space as you only need to add the reference to the nested phrase rather than typing its contents into each individual phrase.

Conditional statement

This macro function checks the specified text/value against multiple text/numbers with a comparator. If the condition is met, the defined text/value is output.

Multiple comparisons are combined with an "OR"-logic.

List of Comparators
Comparator Meaning
== equals
.= begins with
=. ends with
=.= contains
!= not equal
!.= does not begin with
!=. does not end with
!=.= does not contain
-> Text longer than
<- Text shorter than
> Value higher than
< Value lower than
>= Value equal or higher than
<= Value lower or equal than

Calculate expression

This macro function outputs the result of a math expression.

Supported functions and operators: +, -, *, /, ^, ln(x), sin(x), cos(x), tan(x), ctg(x), abs(x), sqrt(x), modulo (x % y), round(x), floor(x), trunc(x), frac(x)

Set phrase contents

This macro function creates/updates/deletes a phrase as specified. If content is empty, the phrase will be deleted.

The phrase file is stored after each execution of a phrase which contains this macro. If you use a PhraseExpress Server, then all clients are updated in this case. Unless you want to share the generated phrase with others, you might want to store it in a separate, local phrase file.

Variables

Variables store any text or numeric data for re-use in one or multiple phrases. If content is empty, the temporary variable is not deleted but emptied to allow you checking this state with the conditional statement macro.

Variables are flushed on exiting the PhraseExpress program.

Set variable contents

This macro function sets the variable contents as specified. If empty, the variable will be cleared.

The variable contents can be optionally output directly after defining its contents.

If you opt to save the variable contents to the phrase database/file, the phrase file is written each time the phrase is executed, that contains this macro. If you use a PhraseExpress Server, then all clients are updated with the new phrase file.

Output variable

This macro function outputs the contents of the variable with the specified name.

Delay

This macro function waits for a specified amount of milliseconds to give applications enough time to perform automated tasks invoked by PhraseExpress, e.g. loading a website.

String operations

String operation macro functions enable you to modify the specified contents, e.g. to change letter case, to determine the string length and to replace a text portion with another text.

Clipboard

This macro function copies text into the Windows clipboard which is currently highlighted in any application or paste the contents into the target application.

Insert clipboard

This macro function pastes the clipboard contents character-wise (key-by-key) instead of triggering the system clipboard paste (if you press CTRL-C). This specific macro is useful when you wish to use the current clipboard contents as a default value for a manual text input:

Set clipboard

This macro function fills the clipboard with the provided contents.

Keyboard layout

Set Keyboard Language

This macro function changes the Windows keyboard layout language.

This macro changes the Windows keyboard settings on an OS level.

Retrieve Keyboard Language

This macro function retrieves the current keyboard language scheme.

A list of language identifiers is available at Microsoft MSDN web page.

Table of Contents