Markup Instructions for EMU_RESPONSE
These topics describe markup instructions for the emulator markup service and how to implement the instructions. Sample markup instructions are provided:
For customers migrating from MySabre API, the instructions in this topic are taken from Appendix C of MySabre API Programmer’s Reference Manual.
Protected Text and Message Characteristics
This topic describes the instructions for the message size, protected text, and colors.
Instructions for Message Size, Protected Text, and Colors
A Red App provides the markup service (referred to as "Red App" in this appendix).
-
The emulator identifies the maximum rows that can be displayed on the emulator and the quantity of rows in the current message. It returns this information to the Red App.
maxline=n
Where n is the maximum quantity of rows that the screen supports. The emulator usually displays a maximum of 26 rows.
msgline=n
Where n is the quantity of rows in the current message.
-
The emulator identifies protected rows and their location, and returns this information to the Red App. Instructions and an example follow.
protected.count=n
Where n is the quantity of instructions for protected text in this message. The count begins at 0.
If protected.count=0 or it does not exist, no text is protected. No further instructions are returned. If protected.count is greater than 0, this is the quantity of protected instructions. Protection instructions start at 0.
protected.0.beginrow=n
Where 0 is the first instruction, and n is the first row with protected text in the first instruction.
protected.0.rowcount=n
Where 0 is the first instruction, and n is the quantity of protected rows in this instruction.
protected.n+.beginrow=n
Where n+ is the next instruction, and n is the first row with protected text in the next instruction.
protected.n+.rowcount=n
Where n+ is the next instruction, and n is the quantity of protected rows in this instruction.
Example Showing Protected Text
parameters=maxline=26, msgline=19, protected.count=2, protected.0.beginrow=2, protected.0.rowcount=3, protected.1.beginrow=7, protected.1.rowcount=9
In this example, the maximum quantity of rows the message can have is 26. The current message has 19 rows. The quantity of instructions for processing protected text is 2, which is represented as protected.count=2. The first instruction for protection indicates that the first row of protected text is row 2, and 3 rows are protected.
In protected.0.beginrow=2, 0 is the first instruction for protection processing, and the first row of protected text that corresponds to the first instruction is 2.
In protected.0.rowcount=3, 3 is the total quantity of rows that are protected in the first instruction, 0. Therefore, rows 2 through 4 are protected.
The second instruction for protection processing, indicated by protected.1, begins with row 7, as illustrated by beginrow=7.
In protected.1.rowcount=9, the second processing instruction says that 9 rows are protected. Nine rows are protected starting from row 7; protected rows are 7 through 15.
This example has a message of 19 rows, with 12 total rows being protected.
-
The emulator returns instructions for applying color.
The Map is returned with instructions for colors that the emulator uses. Although Red Apps are not restricted from using the same colors used in the emulator, they may want to use other colors to draw greater attention to the marked-up text. Using different colors helps end-users identify the marked-up text more easily.
emu.fg= 00ff00; the foreground color of the emulator (a shade of green)
emu.bg= 000000; the background color of the emulator (black)
emu.pc.fg= ffff00; the foreground color of Point and Click in the emulator (yellow)
emu.pc.bg= 00ff00; the background color of Point and Click in the emulator (a shade of green)
emu.rv.fg= ffff00; the reverse foreground color of Point and Click in the emulator (yellow)
emu.rv.bg= 00ff00; the reverse background color of Point and Click in the emulator (a shade of green)
Markup Features: Description, Instructions, and Examples
This topic explains the instructions for properties and markup, the highlight feature, the modify feature, and the action layout section.
Valid Instructions for Properties and Markup
The order in which a Red App must send instructions for highlight and modify is from the beginning to the end of the message. The instructions cannot be in any other order, for example, within the same instruction set, your Red App must modify row 2 before modifying row 16.
The markup features that Sabre emulator currently support are highlight and modify. For both of these features, the first pointer is the control flag that signifies the action to take. The second pointer defines the quantity of processing instructions. Pointers include the index for the count of instruction sets that Sabre emulator must process and the type of modifications to make.
While the processing order of instructions must be from the beginning to the end, the Red App can send highlight and modify instructions in any order that makes sense. For example, if you want to insert 5 lines and highlight them, you would send modify instructions that insert the lines before sending the highlight instructions.
Highlight Feature
The highlight feature changes the colors of specific rows or columns of text. Restrictions are not placed on colors your Red App can use, but it is your responsibility to ensure clear interaction with end-users by choosing non-conflicting color schemes.
The complete highlight instructions have two general elements, the control flag that enables highlighting, and the count that tells Sabre emulator the quantity of instruction sets that are included. Each instruction set has the following elements:
-
A pair of beginning and ending rows
-
A pair of beginning and ending columns
-
Instructions for color
The instructions are explained below.
api.highlight=true
Required. This is the first instruction in the string. It is the control flag, and it signifies the action for Sabre emulator to take.
For a Red App to modify the response message, this flag is present and the value is set to true. The default value is false. If false, processing does not occur.
api.highlight.count=n;
Required. This is the second instruction in the string. The value of n represents the quantity of instruction sets or instances that are requested for the highlight instruction type.
api.highlight.index.identifier.row=n;
Required. The row refers to the response. This is the pair of beginning and ending rows to receive highlight instructions in a given instruction set. The index defines the count of instruction sets. The value of index for the first instruction set is 0, and it is incremented for each instruction set to equal the value of (count “1). This is because the value of index starts at 0. Assuming count=3, the value of index for each instruction set is 0, 1, and 2, which represents 3 instruction sets.
The values for identifier are begin and end. Two of these identifiers must be included in an instruction set along with the number of the first and last row to receive highlight instructions. The first row is numbered 0.
If the Red App adds rows, the row numbers start at 1000 + n where n is the added row. For example, 1001 is the second row that is added.
api.highlight.index.identifier.column=n;
Optional. This is the pair of beginning and ending columns to receive highlight instructions in a given instruction set. The index defines the count of instruction sets. The value of index for the first instruction set is 0, and it is incremented for each instruction set to equal the value of (count “1). This is because the value of index starts at 0. Assuming count=3, the value of index for each instruction set is 0, 1, and 2, which represents 3 instruction sets.
The values for identifier are begin and end. Two of these identifiers must be included along with the number of the first and last column to receive highlight instructions.
api.highlight.index.color= #hexcode;
At least 1 color instruction is required. This is the color instruction for a given instruction set. Colors must be sent as hexadecimal values. Two color parameters are usually sent as follows:
color - Defines the foreground
backgroundcolor - Defines the background
Example:
api.highlight.0.backgroundcolor= #000000;
Modify Feature
Red Apps use the modify feature to insert or delete rows from responses.
The complete modify instructions have two general elements, the control flag that enables modifications, and the count that tells Sabre emulator the quantity of instruction sets included. Each instruction set has the following additional elements:
-
An Index paired with an identifier. The index starts at 0 and it is incremented for each instruction set. The identifier of the index tells Sabre emulator to insert or delete.
-
An action type. The action type tells Sabre emulator to insert or delete rows.
-
A location specification. The location specification tells where to insert or delete the rows based on a number identifier or match.
api.modify=true
Required. This is the first row. It is the control flag, and it signifies the action for Sabre emulator to take. If the Red App wants to request processing of the response message, this flag must be set to true. If markup instructions are passed, it must be set to true.
If this flag is not set, the default value is false. If false, no markup processing will occur.
api.modify.count=n;
Required. This is the second instruction in the string. The value of n represents the quantity of instruction sets or instances requested for the modify instruction type.
api.modify.index=identifier;
Required. This is the index and identifier. The index defines the count of the instruction sets. The value of index for the first instruction set is 0, and it is incremented for each instruction set to equal the value of count(-1). This is because the value of index starts at 0. Assuming count=3, the value of index for each instruction set is 0, 1, and 2, which represents 3 instruction sets. One pair of index and identifier instructions must exist for every instruction set.
The Red App must create the identifier attributes and settings. You name the identifier. Each identifier lays out item values for each action type in an action layout section of the application. If multiple action types are needed, then multiple action sections must be coded in the application.
api.modify.index=type;
Required. This is the action type. The action types for the modify features that Sabre emulator supports are the following. You must use these names for type.
line.insert
line.delete
The index reflects the instruction set.
api.modify.index.before /after / match=row number;
This specifies the location of the row to add or delete.
Your Red App must track the rows it adds. The row numbers start at 0. If a newly added row needs to be modified, it is identified by adding 1000 + n to the added row number. For example, 1001 is the second added row. For an example of numbering rows that are added, see "Example of Highlight Feature Instructions."
How to identify the rows is described as follows.
api.modify.index.before=n inserts or deletes the row before row n.
Example: before=2
api.modify.index.after=n inserts or deletes the row after row n.
Example: after=5
api.modify.index.match=re.n finds the regular expression (represented by re) in the message that matches the string identified by n. The n is the number or key of the regular expression identifier, and it is defined in the action layout section of the Red App.
If the regular expression matches text that spans multiple rows, only the first row is used.
Whenever match is used, a before or after instruction cannot be included. Match is used instead of before or after.
In the action layout section of the Red App, the row location is identified by an offset value. The offset value specifies a row number and can only be used with match.
The offset value tells Sabre emulator where you want to insert or delete a line by including one of these values:
0 replaces or removes the matched row.
“1 adds or deletes a row before the matched row.
+1 adds or deletes a row after the matched row.
Example: offset=+1
A location specification is required.
Example of Highlight Feature Instructions
This example is divided into four parts: the general settings and the three instruction sets.
General Settings for All Highlight Instruction Sets
api.highlight=true;
api.highlight.count=3;
The preceding example tells Sabre emulator that 3 instruction sets are included.
First Highlight Instruction Set
api.highlight.0.begin.row=1;
api.highlight.0.end.row=2;
api.highlight.0.begin.column=1;
api.highlight.0.end.column=6;
api.highlight.0.color= #FFFF00;
api.highlight.0.backgroundcolor= #000000;The first highlighting instruction starts at row 1 and ends before row 2. A total of 1 row will receive highlight instructions.
The highlight type instruction is applied starting with the beginning column specified, and stopping before the ending column specified. In this example, highlighting starts at column 1 and ends after column 5, just before column 6.
The selection to be highlighted uses yellow for the foreground and black for the background.
Second Highlight Instruction Set
api.highlight.1.begin.row=10;
api.highlight.1.end.row=12;
api.highlight.1.begin.column=1;
api.highlight.1.end.column=6;
api.highlight.1.color=#EE0000;
api.highlight.1.backgroundcolor=#0088FF;This highlight instruction is applied to rows 10“12, columns 1“6.
Third Highlight Instruction Set
api.highlight.2.begin.column=18;
api.highlight.2.begin.row=1003;
api.highlight.2.end.column=50;
api.highlight.2.end.row=1003;
api.highlight.2.color=#EE0000;
api.highlight.2.backgroundcolor=#0088FF;The first highlighting instruction starts at column 18 of the newly added row in the message. Newly added rows will start at 1000 + n where n is the added row number. The highlighting ends at column 50 of the same row.
Example of Modify Feature Instructions
This example is divided into two parts: the instructions and the corresponding action layout section.
Markup Instructions
api.modify=true;
api.modify.count=3;
api.modify.0=apiInsert;
api.modify.0.type=line.insert;
api.modify.0.before=0;
api.modify.1=apiDelete;
api.modify.1.type=line.delete;
api.modify.1.before=2;
api.modify.2=anotherApiInsert;
api.modify.2.type=line.insert;
api.modify.2.match=re.1;In the above example, count=3 tells Sabre emulator that there are 3 instruction sets.
In the first instruction set, the first action layout section is named apiInsert. The action type instructions tell Sabre emulator to insert a line (line.insert) before row 0 of the response.
The second instruction set, named apiDelete, requests a deletion (line.delete) before row 2.
The third instruction, named anotherApiInsert, inserts a line based on finding a match with the regular expression key 1.
The specific instructions for apiInsert, apiDelete, and anotherApiInsert are in the action layout section of the Red App.
Action Layout Section That Corresponds to the Markup Instructions
The action layout section has one identifier for every identifier of instruction sets. Every identifier has a count in the action layout section that tells the quantity of each action type to perform.
apiInsert.item.count=1;
apiInsert.item.0=Line1 to insert\nLines2 to insert\nLines3 to insert;
apiDelete.count=1;
apiDelete.offset=0;
anotherApiInsert.item.count=1;
anotherApiInsert.offset=-1;
anotherApiInsert.item.0=Another line to insert;
re.1=WPNI;apiInsert.item.count=1 tells apiInsert to perform 1 add action, and the line to add is identified in the instructions part by before=0.
apiDelete has 1 delete action before line 2. In the instructions part of the code, the deletion is identified by api.modify.1.before=2.
In anotherApiInsert, the match finds WPNI and is referenced with the regular expression key earlier in the code, re.1. offset=-1 inserts 1 line before the location of the match.