Instruction set reference
HIPE_OP_APPEND_TEXT
Appends a text element as the last child element within the specified tag element.
- location: The proud parent element.
- arg[0]: A string of text to append.
- arg[1]: Text mode: "0" (the default, also used if the argument is empty), "1", "2" or "3". See the table below.
- arg[2]: Mode 3 only: the locations used in the markup's hipe-loc attributes, e.g. "57,1000-1499". See "Locations".
Text modes
In modes 0, 1 and 2, the characters <, >, " and ' are shown as typed. Text that looks like an HTML tag, such as <b>, is never treated as markup, so there is no need to remove such things from arg[0]. These modes differ in what happens to & and to newlines, carriage returns and tabs. In mode 3, arg[0] is HTML.
| Mode | & | Newlines, carriage returns and tabs | Text read back with HIPE_OP_GET_CONTENT |
|---|---|---|---|
| "0" | Shown as typed. | Not converted. | The same as arg[0]. |
| "1" | Shown as typed. | Converted: a newline becomes a line break, a carriage return an empty paragraph, a tab a wide space. | Differs from arg[0]: the newlines and carriage returns are now elements, not characters, and each tab is a wide space character. |
| "2" | Starts a character entity: × shows as ×, & as &. | Not converted. | arg[0] with its entities replaced by the characters they stand for. |
| "3" | Starts a character entity, as in mode 2. | Not converted. | The text of the elements arg[0] created. HIPE_OP_GET_CONTENT mode 1 returns them as HTML. |
Mode 3: markup
- arg[0] is HTML, and the tags and attributes in it are created as written, including class. Write a literal < or & in its text as < or &.
- The markup stays inside the element: unclosed tags are closed at the end of arg[0], and a closing tag can't end the element itself.
- To use an element later (request its events, set its attributes or source, get a frame key for an iframe, draw on a canvas), give it a location: write hipe-loc="N" on it with a number reserved by hipe_reserve_location(), and list the number in arg[2]. hipe_send_markup() does the listing for you. Other elements created this way have no location. See "Locations".
- Tags that do nothing in a Hipe frame, such as script, do nothing here either. See "Tags, attributes and styles".
Where newlines and tabs are not converted (modes 0 and 2), how they look depends on the element. Most elements show any run of spaces, tabs and newlines as a single space, as HTML normally does. An element that keeps whitespace, such as a pre tag or one styled with white-space: pre, shows them as line breaks and tab stops.
Also in modes 0 and 2, a carriage return is stored as a newline, and a carriage return followed by a newline is stored as one newline.
In every mode, the character U+2029 starts a new paragraph, with a gap or an indent set by CSS, in any element. See "Paragraph breaks" on the "Tags, attributes and styles" page.
Which mode to use
- Mode 0 for most text, and for any text that will be read back or edited and must come back the same, such as a source file shown in a pre tag. To show a symbol, put the character itself in the text: arguments are UTF-8. Also for the CSS of a style tag: modes 1 and 2 would change it.
- Mode 1 for showing text you don't control, such as an error message or a command's output, in an ordinary element with its line breaks and tabs visible and no styling of your own.
- Mode 2 for text you write yourself, where you want symbols by name, such as a calculator button labelled ×. Don't use it for text that may contain & for any other reason: some older entity names are recognised without their closing semicolon, so ¶m shows as ¶m and ×, as ×,.
- Mode 3 for formatted text sent in one instruction, such as syntax-highlighted code as span tags with classes, or HTML you already have.