PhraseExpress v3 for Mac - 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 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.

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

PhraseExpress for Windows, 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 12/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 become available for other phrases.

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. 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.

Macro parameters

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

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

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.

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.

Important: The Mac does not allow to manage global variables at this time. Global variables are supported in the Mac version primarily to provide compatibility with the Windows version. The Windows version include a Global Variable Manager, allowing you to manage global variables.

Converting macros into global variables

To turn a macro into a global variable, check the option "Global" next to the macro name input box.

When converting the macro into a global variable, in the background, 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.

Global variables cannot be managed/deleted in the Mac Version at this time.

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.

Inserting global variables

To insert a global variable into a phrase, type the global variable name, enclosed in two curly brackets, e.g. {{MyGlobalVar}}.

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.
  • 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
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.

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. 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.

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.

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

 

Text label

This macro function adds a text label to the form:

Form label

 

External Data

Embed external file

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

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. The items can also include macro functions.

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.

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.

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.

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

Open a web page

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

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 focus macro function. 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.

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, sin, cos, tan, ctg, abs, sqrt, !, ^, /, *, -, +.

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

Insert clipboard

This macro function pastes the clipboard contents character-wise (key-by-key) instead of triggering the system clipboard paste (if you press CMD-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.

Table of Contents