Monster Media 1993 #2

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1993 #2 / Image.iso / graphics / ripsc154.zip / TEMPLATE.DOC < prev

Wrap

Text File | 1993-07-18 | 48KB | 1,137 lines

WHAT IS A TEMPLATE? ------------------- A template is a special variety of a host command that is used to construct other host commands. They are only used with the RIP_BUTTON command, not with RIP_MOUSE or RIP_QUERY. Their use is solely dedicated to the Button command. In fact, their usefulness is predominantly designed for Radio Buttons and Check Box Buttons but this doesn't mean that you cannot use them for other purposes. A template, like a normal "raw" Host Command, is stored in the Host Command field of the RIP_BUTTON command. Unlike Raw Host Commands that get sent to the Host immediately, templates do not transmit immediately. In fact, it's possible for a Template to never get transmitted to the BBS at all. Templates are not normally sent directly to the BBS - they are almost always used in conjunction with some other button's host command. HOST COMMANDS - ADDING ANOTHER WRINKLE -------------------------------------- As you know with normal Mouse Host Commands, you can send any piece of text you want when the user clicks on that button. You could send the word "HELLO" to the BBS for example if they click on a certain mouse button. This is an example of a "Direct Host Command". There are three types of Host Commands. There are: 1) DIRECT HOST COMMANDS - Send a string of text to the host immediately after the associated button is clicked. 2) TEMPLATE DEFINITIONS - Defines a template to be used by other buttons (if ever). See below for further details about how to define templates. 3) TEMPLATE EXECUTION - This allows you to plug a piece of string data into one or more templates (defined previously). The resulting string is then acted upon like a Direct Host Command and transmitted to the BBS immediately. The RIP_BUTTON command "segments" its Text Parameter Block into three portions - the Icon File, Text Label followed by the Host Command block. Each of these segments is separated by the two character delimiter "<>" like this: ICONFILE.ICN<>Button Label<>HOST COMMAND. With the Button command, the Host Command segment can be sub-divided into numerous smaller sub-segments, or Command Blocks. This is done with another two character delimiter "[]". So, technically, you could do this: ICONFILE.ICN<>Button Label<>HELLO^m[]WORLD^m This command would show an Icon Button using the file ICONFILE.ICN as its Icon Image, labeling it with the phrase "Button Label", and defining an extended Host Command block with two segments. If the user clicks on this button, the following will be sent to the BBS: HELLO<cr> WORLD<cr> Notice how the "[]" is not transmitted. This is because it is simply a delimiter separating two Command Blocks from each other. Now each of these two command blocks are DIRECT HOST COMMANDS, but they don't have to be. One of them could have been a Direct Host Command, and another could just as easily have been a template definition. TIPTOE THROUGH THE TEMPLATES ---------------------------- There can be up to 36 different templates defined simultaneously. Each template number corresponds directly to a Button Group Number. Templates are identified by a single meganum 0-9 and A-Z, leaving 36 distinctly separate groups. To define a template, you use a variation of the Command Block delimiter "[]" with the template identifier followed by a colon like this: [5:]This is template #6's definition [G:]This is template #16's definition Defining a template is simple. Activating a template however, is another story. What if three buttons in the same group all define their own templates for the same group/template like this: Button #1: [5:]This is button #1's template Button #2: [5:]This is button #2's template Button #3: [5:]This is button #3's template Now, when these three buttons are received by the terminal, it [the terminal] knows the Host Commands for each button (it memorized each of them). Now, which of these three templates is the currently active one? None of them! A template definition doesn't become the active template until that button containing its definition is clicked (selected). What this means is, you can have a bunch of buttons all belonging to the same Button Group with their own respective template definitions, but only the template relating to the most recently clicked button will be the currently active template for that group. Whew, that was a mouthful! There are two ways of activating a template: 1) Draw a button as "pre-selected" - in other words, the button is drawn pre-clicked immediately when it is received by the terminal. When this happens, the Host Command for that button is processed immediately and if a template definition exists in that host command, it is acted upon immediately thus making that template the currently active template for that Group. 2) The user clicks on a button containing a template definition. If a template is already active in that group, it is overwritten by the newly activated template. In either case when templates are defined, nothing is actually transmitted to the BBS unless the Command Block contains some Direct Host Command sub-block(s) like this: [5:]Template definition[]hello world^m If this button were clicked, then Group number 5 would have the template activated with the template text "Template definition". Then the Direct Host Command "hello world^m" would be transmitted to the BBS. In this example, we see how a single host command can do multiple things - in this case, it defined a template in group #5 AND transmitted something to the BBS! TEMPLATES, RADIO BUTTONS AND CHECK-BOX BUTTONS ---------------------------------------------- We have seen how templates are defined and activated. Before we go any further, let's explain how they are used for Radio Buttons and Check-Box buttons. Radio Buttons are a "type" of button group. Only one button in that group can be active (clicked) at any one time. If a button that is not active is clicked, any other buttons in that group that ARE clicked are de-selected and the one that is being clicked is selected. If that newly clicked button has a Host Command, it is processed. If it has a template definition, it too is processed, overwriting the currently defined template for the specified group. Since Radio Buttons can only have one currently active button in a single given Radio Group, similarly you can only have one template active for that group at any given moment. Check Box Buttons are another "type" of button group. Unlike Radio Buttons, Check Box buttons can have zero or more buttons active (clicked) at any one time. If a check box button group has ten buttons defined in it, zero, five or all ten of those buttons can be active simultaneously. What about each of their respective Host Commands? They too are all processed when the buttons are individually clicked. Now what about templates? Since you can only have one template defined in a group at any given moment, how do check box buttons accomplish this multiple-template concept? Whenever a check box button is clicked (or unclicked), the template for that group is re-calculated. Any buttons in that group that have template definitions are scanned, and any check box buttons in that group that are selected, have their template definitions concatenated together (strung together) end on end. The result is one large template which is built up from the template definitions of each selected check box button. Let's take a couple simple examples step-by-step to see how templates are maintained internally. In the first example, we will explore the Radio Buttons and the way templates relate to them. In the second example, we'll examine check box buttons and templates. EXAMPLE 1 - RADIO BUTTON TEMPLATES ---------------------------------- Let's say you have four buttons in Button Group #3, and that button group is defined as a Radio Button group. Here are the host command definitions for each of those buttons in this example: Button #1: [3:]ABCD Button #2: [3:]EFGH Button #3: [3:]IJKL Button #4: [3:]MNOP Now, if none of the buttons are clicked, then template group #3 is blank. If button #1 is clicked, the template for group #3 would be defined as "ABCD". Now, if button #4 is clicked, what would the template definition for group #3 be? That's right, "MNOP". Notice how only one of the given templates is active at any given moment. EXAMPLE 2 - CHECK BOX TEMPLATES ------------------------------- Now let's explore the slightly more complex world of check box templates. As stated previously, check box templates can be strung along together to make a larger template - template construction of sorts. Let's say you have a Button Group #2 defined as a check box group with 7 buttons defined in it. Each of the buttons are initially drawn as "unselected", or unclicked (inactive). Here are the button host command definitions for each of the 7 buttons: Button #1: [2:]Apples^m Button #2: [2:]Oranges^m Button #3: [2:]Cherries^m Button #4: [2:]Grapes^m Button #5: [2:]Pears^m Button #6: [2:]Banannas^m Button #7: [2:]Lemons^m Now, if all 7 buttons are not clicked, then template group #2 would be blank. Let's click on some buttons and see what the template will become as we change which buttons are clicked and which aren't: Button #3 clicked (ON) .... Template: Cherries^m Button #5 clicked (ON) .... Template: Cherries^mPears^m Button #3 clicked (OFF) ... Template: Pears^m Button #5 clicked (OFF) ... Template: <blank> Button #2 clicked (ON) .... Template: Oranges^m Button #1 clicked (ON) .... Template: Apples^mOranges^m Button #4 clicked (ON) .... Template: Apples^mOranges^mGrapes^m As you can see, the active template for a check box group is actually a combination of all selected buttons' templates, in ORDER OF DEFINITION, not in the order that they were clicked. Pay close attention to the end of the example where buttons were clicked in the order of 2, 1 then 4. If you notice the active template though, they are in 1, 2 then 4 order! They are in the order that the buttons were originally defined. TAKING ADVANTAGE OF TEMPLATES ----------------------------- We've already gone through and shown you how to define templates and how to activate them. Now you need to know how to put them to use - how to take a template and make it do something. If you've been confused up to this point, don't worry - we're going to put it all together in a few minutes into one big picture. There are two ways of using templates. One is called Template Chaining, and another is called Template Embedding. Each of these two methods are quite different, but give you quite a bit of flexibility. Let's take each of these methods step-by-step by describing each in detail separately. TEMPLATE EMBEDDING ------------------ Template embedding is a way of "inserting" a template inside another host command. What this means is that you can insert the contents of an active template inside of a button's Direct Host Command. The direct host command is "expanded" around the inserted template and the contents of the specified template are made part of the direct host command. Let's illustrate this with an example. Taking the check box example above which had a list of fruits as check box buttons, we can expand on this example to show how template embedding can be a useful tool. In this example, we will build a menu to take someone's order for fruit. Here is what the simple menu screen will look like: +----------------------------------------+ | What would you like to order? | | | | +-----------+ | | |X Apples | | | | Oranges | +------------+ | | |X Cherries| |Submit order| | | | Grapes | +------------+ | | |X Pears | | | | Banannas| | | |X Lemons | | | +-----------+ | +----------------------------------------+ As you can see, we have a set of 7 check box buttons on the left of the menu with the choices of the fruits for sale. On the right is a button to submit your order. To implement this example, we will use two separate button groups. Group #0 will contain one button, the "Submit Order" button. Button Group #2 will be a check box button group containing our seven choices of fruits as in the preceding example. Here are the Host Command definitions for each of the eight buttons: Group #0 (normal button - not a radio or check-box button) ---------------------------------------------------------- SUBMIT ORDER: I wish to order $?2$ right now^m Group #2 (check box button group) --------------------------------- APPLES: [2:]APPLES^m ORANGES: [2:]ORANGES^m CHERRIES: [2:]CHERRIES^m GRAPES: [2:]GRAPES^m PEARS: [2:]PEARS^m BANANNAS: [2:]BANANNAS^m LEMONS: [2:]LEMONS^m Notice in the "Submit Order" button that there is a special code in the Direct Host Command "$?2$". This is a special variation of a text variable. This form of text variable is used only in Template Embedding. What it does is instructs the terminal to "insert template #2 here". The format of the template embedding code is: $?x$ ...where "x" is the template identifier (0-Z) that is to be inserted. Now back to the example, if the user clicked on "APPLES", "CHERRIES", "PEARS" and "LEMONS" as in the menu shown above, then clicks on "Submit Order", what would the Host Command look like when it gets transmitted to the BBS? Well, for starters, the Submit Order button's host command reads: I wish to order $?2$ right now^m After template #2 is inserted where the embedding code is, the host command would look like this: I wish to order APPLES^mCHERRIES^mPEARS^mLEMONS^m right now^m And after the ^m's are converted to carriage returns the final host command would be like this: I wish to order APPLES CHERRIES PEARS LEMONS right now What if the user didn't click on any of the fruits, but did click on the Submit Order button? Well, since template #2 belongs to a group that is a Check Box group, which can have zero or more items selected simultaneously, the $?2$ code would be expanded to a null string, or nothing, so the final host command would be: I wish to order right now If template #2 was associated with a Radio group which has to have one button clicked at all times, and none of the buttons were active, then the terminal would hilight all the radio buttons in group #2 and instruct the user to choose one first. This is done automatically by the terminal, you don't need to worry about Radio Buttons. Just remember, Check Box buttons can legitimately have a blank template, but Radio Buttons cannot due to the very nature of the buttons. The final host command after template embedding is limited to 4096 bytes of data. If a host command would grow beyond 4096 bytes due to embedding, it is truncated to exactly 4096 bytes. TEMPLATE CHAINING ----------------- Now, on to the second form of using templates, Template Chaining. Template Chaining is another method of using templates. Unlike Template Embedding though, template chaining is quite different. Rather than inserting the contents of a template into a host command, like in embedding, template chaining feeds data into a template and then takes the result and transmits that to the BBS. In other words, Template Embedding inserts a template into a Host Command. In Template Chaining, a Host Command is inserted into a template (the exact opposite). If you recall from the Template Embedding discussion earlier, there was a code for inserting a template into a host command. The command was $?x$ where "x" was the template number. Template Chaining uses a similar insertion code but with a subtle different - there is no template identifier. The code is: $?$ This is a "generic insertion code". It is used in the template definition itself, not in the Direct Host Command like the template embedding code was used. The actual data that replaces the $?$ depends on the Direct Host Command that is "feeding" the template. Before template chaining becomes crystal clear, we need to muddy the waters some more by introducing one more thing - the Chaining command. A template chaining operation is performed almost exactly like defining a template with a subtle difference, the colon (:) is omitted from the template definition like this: [5]This is template chaining [5:]This is template definition What's the difference? In the case of the [5:], a template for group #5 is defined. In the [5] example, the template chaining instruction is invoked on Template #5. The phrase "This is template chaining" will be fed into template number 5. If template number 5 has a generic insertion code $?$ in it, then it will be replaced with the phrase "This is template chaining". The final result after the replacement will be a direct host command that will be transmitted to the BBS. Since template #5 doesn't have an insertion code, the phrase "This is template chaining" will be lost in the chaining process and the final host command would be "This is template definition". Here are a couple examples of template chaining illustrating several ways that it may be used (we'll only show "active" template definitions): [3:]This is a plain old template [4:]This template inserts $?$ here! [5:]This has two insertion codes $?$ and $?$ [3]This text is lost in the chaining process [4]SOMETHING [5]HERE This would be the result of the three chaining operations: 3 ... This is a plain old template 4 ... This template inserts SOMETHING here! 5 ... This has two insertion codes HERE and HERE We skipped over the "user clicked on this button" operations and went directly to the end results to make the example as clear as possible. There are three distinctly different situations in this example. The first shows a regular template without an insertion code being used in a chaining operation. As you can see, the data that was fed into template #3 was lost because template #3 didn't have an insertion code. In the second example, a single insertion code is used and the word "SOMETHING" is inserted in place of the insertion code. The third example shows that an insertion code can be used more than once in a given template. What if you tried to chain to a template that hasn't been activated yet (ie, a blank template)? If the template in question belongs to a radio group, then the terminal would instruct the user to click on one of the radio buttons to activate the template (he doesn't know that templates are invovled of course). If it was a check box template, then the final host command would be nothing and in effect, nothing would be transmitted to the host. If the template in question belonged to a generic button group, then also nothing would get transmitted to the BBS. In the preceding Template Chaining examples, only one template was used (chained-to). In reality, you can chain to multiple templates with ease. The format of multiple Template Chaining is simple, just add the template identifiers for the templates you want to chain to in the order you wish to chain to like this: [1E3]This is a three-level chaining operation Notice how the Template Chain command has three template identifiers in it, 1, E and 3. The Host Command would be fed into template #1 first. After any replacements, the final result of the template #1 chaining would be finished and that string of text would be fed into template #E. After any replacements/insertions are performed on template #E, then the final result is fed into template #3 and the final result of that chaining operation is sent to the BBS. Here is an example of multiple template chaining calls: [1:]red green $?$ blue [E:]LOUD QUIET $?$ YELL [3:]soft $?$ hard smooth gritty [1E3](host command) In this example, the phrase (host command) is fed into template #1, then the result into template #E then that result into template #3 then finally transmitted to the BBS. We can break this down conceptually into three separate chaining operations to illustrate what happens step-by-step: [1E3](host command) Results in: [E3]red green (host command) blue Resulting in: [3]LOUD QUIET red green (host command) blue YELL And then finally: soft LOUD QUIET red green (host command) blue YELL hard smooth gritty This last phrase is then sent to the BBS verbatim. As you can see, things can get pretty complex when multiple template chains are used, however some dramatic things can be achieved with a little bit of effort and some well thought out planning of your template definitions. Template chaining is useful for controlling HOW particular data is transmitted to the BBS, while template embedding is useful for controlling WHAT data is transmitted to the BBS. You can think of template chaining as a method of defining "commands" that will be sent to the BBS where the commands can be different depending on which buttons are clicked in that group. Template embedding on the other hand is often used for controlling the data parameters that are used with particular commands. You are allowed up to 36 separate template chaining levels in one template chaining operation. After all chaining is completed, the final host command cannot exceed 4096 bytes. If a chaining operation would exceed that amount, it is truncated to exactly 4096 bytes. GETTING FANCY WITH TEMPLATES ---------------------------- You've already learned about Template Embedding and Template Chaining. These two methods of using templates do not need to be separate methods. You can combine these methods if you wish. This means that you can have embedded templates inside of template chains. This provides for utter flexibility in doing whatever you want. Here are a couple of examples of combinations: EXAMPLE 1 --------- [5:]EMBEDDED VALUE [3:]Here is a $?$ and an $?5$ [3]CHAINED HOST COMMAND This would result in: Here is a CHAINED HOST COMMAND and an EMBEDDED VALUE EXAMPLE 2 --------- [5:]EMBEDDED VALUE [3:]Here is a $?$ and an $?5$ [4:]print("$?$") [34]CHAINED HOST COMMAND This would result in: print("Here is a CHAINED HOST COMMAND and an EMBEDDED VALUE") EXAMPLE 3 --------- [4:](hello) [5:]ANOTHER $?5$ EMBEDDED $?4$ VALUE [3:]Here is a $?$ and $?5$ [3]CHAINED COMMAND This would result in: Here is a CHAINED COMMAND and ANOTHER ANOTHER $?5$ EMBEDDED $?4$ VALUE EMBEDDED (hello) VALUE Taking this one step-by-step: Step #1: Here is a CHAINED COMMAND and $?5$ Step #2: Here is a CHAINED COMMAND and ANOTHER $?5$ EMBEDDED $?4$ VALUE Step #3: Here is a CHAINED COMMAND and ANOTHER ANOTHER $?5$ EMBEDDED $?4$ VALUE EMBEDDED (hello) VALUE <end of processing> EXAMPLE 4 --------- [5:]HELLO [3:]$?5$ $?$ WORLD [4:]print("$?$")^m [344](silly) This would result in: print("print("HELLO (silly) WORLD")^m")^m Example #1 shows a situation with a single chaining operation and a single embedding operation done at the same time. You can see how the final host command is in relation to the data fed into the templates at different points. Example #2 shows a more complex situation where multiple levels of template chaining are going on while embedding is also being used. Example #3 is somewhat different though. Why weren't the embedded template codes expanded at the lowest level of template #5? If you look closely at template #5, it has an insertion code instructing the system to insert template #5 (itself) in the middle of the template. This is legal, but only because an embedded template inside an embedded template cannot have any more embedding performed on it. In other words, you are allowed up to two levels of embedded templates, but the lowest level (2nd) cannot have any insertion codes, text variables, control characters or pick-list definitions in it - if it does, they will be treated as "raw" text instead of host command directives. Example #4 shows a more involved Template Chaining operation in which the same template is chained to more than once in a given operation. This is allowable for extra flexibility, although in the real world will probably not be used much. TEMPLATES, TEXT VARIABLES, PICK LISTS AND CONTROL CHARACTERS ------------------------------------------------------------ Now that we have thouroughly discussed templates, we come upon another subject - that of text variables, pop-up pick lists, and control characters. In any template definition or host command, you can have text variables, pick lists or control characters anywhere. This gives you the ability to do a great many things. You can freely use text variables, control characters or pick lists anywhere in a Direct Host Command, in a template chains and embedded templates. There is nothing unusual about text variables, pop-up pick lists or control characters when they're used in template chains or Direct Host Commands. They do get a bit odd though in how they interact with Embedded Templates - but only if you have an embedded template within an embedded template. Recall from a previous discussion about embedded templates within embedded templates. At the lowest level of the embedding, there is no processing done on the string of text. This is to prevent endless loops and combinatorial explosion of data and CPU time. Text Variables, pick lists and control characters WILL be processed at the first level of an embedded template, but not at the second level. Here are some examples that better illustrate text variables: EXAMPLE 1 --------- [3:]The date is $DATE$ ... $?$ [3]HELLO Results in: The date is 07/18/93 ... HELLO EXAMPLE 2 --------- [3:]The date is $DATE$ HELLO THERE, $?3$ Results in: HELLO THERE, The date is 07/18/93 EXAMPLE 3 --------- [2:]The time is $TIME$^m [3:]The date is $DATE$^m HELLO THERE^m$?3$$?4$ Results in: HELLO THERE The date is 07/18/93 The time is 03:43:32 EXAMPLE 4 --------- [1:]The day is $DOW$^m [2:]The time is $TIME$^m [3:]The date is $DATE$^m$?1$^m HELLO THERE^m($?3$)($?4$)($?1$) Results in: HELLO THERE (The date is 07/18/93) The day is $DOW$^m (The time is 03:43:32) (The day is Sunday) Notice how the $?1$ embedded template used in template #3 does not get processed - it is just inserted raw. PROCESSING OF TEMPLATES ----------------------- As stated previously, template definitions may contain text variables, pick lists, control characters, and template insertion codes. When do these special "directives" get processed? The answer is when the template gets USED, not when it becomes ACTIVE! To better illustrate this, let's look at a simple example. Let's say you have three radio buttons (group #2) on the screen and another button (group #0) which uses the template for the radio button group 3. Here's the host command definitions for each of these four buttons: Group #2 - Radio Button Group ----------------------------- Button #1: [2:]It's a pretty day at $TIME$ Button #2: [2:]It's a rainy day at $TIME$ Button #3: [2:]It's a hazy day at $TIME$ Group #0 - Ordinary button group -------------------------------- Button #4: Today's forecast:^m$?2$ Now, let's say that none of the radio buttons are drawn as "selected" for starters. At 11:45:03 in the morning, the user clicks on button #2 indicating it's a rainy day. The active template for group #2 would be defined as: It's a rainy day at $TIME$ At 11:46:37 he clicks on the Forecast button. What would be the host command sent to the BBS in this example? It would be: Today's forecast: It's a rainy day at 11:46:37 Notice that the time that is inserted in place of $TIME$ is the time that the user clicked on the Forecast button, NOT the time he clicked on the "rainy day" button which activated the proper template. This illustrates that text variables, pick lists, and control characters are not "processed" until they are referenced (used) by some other button or template in an active Host Command situation. COMMAND BLOCKS - SEGMENTING A HOST COMMAND ------------------------------------------ Near the beginning of our discussion of templates we spoke about Direct Host Commands, Template Definitions and Template Execution. You have seen how to define templates with a template definition command like [3:]HELLO, and how to execute templates by either Chaining (eg, "[3]WORLD"), or by using Embedded Templates (eg, "$?3$ WORLD"). Now, remember that we spoke about how a single Host Command can be segmented into multiple "Command Blocks" by separating them with the delimiter "[]". An example of this might be: HELLO^m[]WORLD^m This would transmit the following to the BBS: HELLO<cr> WORLD<cr> Realistically, you wouldn't use such an overly simple example like this, but would use the following instead: HELLO^mWORLD^m This would produce the same result. But it doesn't illustrate the purpose of Command Blocks. Here's a real-world example of a host command broken down into several command blocks: [3:]Template Definition[4]Template chaining[]BBS TEXT If you look carefully at the above host command, three distinct things are happening. First, template #3 is defined with the text "Template Definition". Secondly, the phrase "Template chaining" is chained (fed) into template #4 (whatever that one is) and the final result of the chaining operation is sent to the BBS. Finally, the last command block is processed which happens to be a Direct Host Command, so the text "BBS TEXT" will be transmitted to the Host as well. If a host command doesn't have one of the command block delimiters like a template definition (eg, "[3:]"), or a template chain directive (eg, "[3]"), or a Direct Host Command Directive (eg, "[]"), then the Host Command is, by default, considered to be a Direct Host Command. The following are all considered Direct Host Commands and they all do the exact same thing: HELLO^mWORLD^m HELLO^m[]WORLD^m []HELLO^mWORLD^m []HELLO^m[]WORLD^m Here are some more examples of Command Blocks using the previous example as a foundation, but this time we throw in another command block. Again, all four of these examples do the exact same things: HELLO^mWORLD^m[3:]Template Definition HELLO^m[]WORLD^m[3:]Template Definition []HELLO^mWORLD^m[3:]Template Definition []HELLO^m[]WORLD^m[3:]Template Definition COMMAND BLOCKS, RADIO BUTTONS AND CHECK BOX BUTTONS --------------------------------------------------- If you recall from our earlier discussions about Radio Buttons and Check Box Buttons, the templates definitions are activated based upon a Button being activated. If you think about Command Blocks though, you might be inclined to think that figuring out which template definition block of a command block to activate might get insane. It could! Look at the following set of three Radio Button definitions: Button #1: [3:]Hello world[3:]This is Pluto Button #2: [3:]Hello world[3:]This is Saturn Button #3: [3:]Hello world[3:]This is Jupiter What happens if button #2 is clicked, thus activating that template? What template command block is used to create the final, active template? The answer is the last one! The text that becomes the actual active template for template #3 would be this: This is Saturn If a Host Command references this template as in the following example, you will see that the secondary template definition is the one that is actually in use: I'm a martian singing in the rain^m$?3$ Resulting in: I'm a martian singing in the rain This is Saturn In short, Command Blocks are processed in all situations, and if a discrepency exists where two or more template definitions in the same Host String correspond to the same template group, the last definition is the one that becomes active. This applies even if you are dealing with Check Box buttons. In the above example of the martian, if Buttons #1, 2 and 3 were Check Box Buttons instead, the "Hello World" template definitions would still be lost and would NOT get concatenated together to create the final Host Command. If buttons #1 and #3 are clicked, then template #3 would be: This is PlutoThis is Jupiter It would NOT be: Hello worldThis is PlutoHello worldThis is Jupiter CONTROL CHARACTERS ------------------ Not all BBS'es will allow you to use control characters on their Service. Regardless of that, the capability to send any Control Character exists for your Host Commands. The most commonly used Control Characters are: INDIVIDUAL CONTROL CHARACTERS SPECIAL KEYSTROKES =========================================================== ^@ ... Null (ASCII 0) ^[[A ... Up Arrow ^G ... Beep ^[[B ... Down Arrow ^L ... Clear Screen (Top of Form) ^[[C ... Right Arrow ^M ... Carriage Return ^[[D ... Left Arrow ^C ... Break (sometimes) ^[[H ... Home Key ^H ... Backspace ^[[K ... End Key ^[ ... Escape character ^[[L ... Control Home ^S ... Pause data transmission ^Q ... Resume data transmission Some hosts use the ^ (caret) for their own purposes. In these cases, you can use the ` (backquote) character instead of the caret. Some systems allow you to specify the caret symbol as two carets (^^). Consult your Host Software documentation to determine the best method for your needs. NOTE: RIPterm uses ^ or ` and a character to represent a control character. IT IS NOT A CONTROL CHARACTER BY ITSELF, IT IS TRANSLATED BY RIPterm. In other words, ^M does not send a ^ and then an M, it sends a carriage return (ASCII 13). Likewise, RIPscrip commands like Query do not use an ^[, an actual escape character (ASCII 27) is used. TEXT VARIABLES -------------- A special feature of RIPterm allows it to understand what a Text Variable is. A text variable is a piece of text that both RIPaint and RIPterm know something about. For example, the Text Variable $DATE$ is known to represent the current Date on your PC. The host may ask your system what the values of one or more of these variables are, and if your terminal knows these particular Text Variables, it will tell the host. There are three types of Text Variables. -- Built-In Text Variables that RIPscrip products will ALWAYS know about. These include Text Variables like date and time that return a value -- Another type of built-in Text Variable are Active Text Variables, which perform an action, but return nothing to the host. These include turning the status bar on/off, clearing the graphics screen, and playing some simple sounds, and many more. -- Then there are also User Text Variables that can contain a variety of information depending on what the user entered at the time the variable was created. For example, the host might ask you what the contents of the $FULL_NAME$ variable is, and if RIPterm doesn't know, it could pop-up a field on the screen and ask you about it. From then on, RIPterm will remember that piece of information for the next time it is needed by a host. You may use either the pre-defined Text Variables, or the User Text Variables at any place that allows Text Variables. LOCAL RIPscrip FILE PLAYBACK ---------------------------- You can re-play a .RIP file that you have locally on your hard disk from anyplace that allows text variables. The format of the variable is somewhat different than user variables, or pre-defined text variables. After the initial dollar sign ($), enter the greater-than symbol (>) followed by the filename (with or without the .RIP extension), then ending in another dollar sign ($). Several examples of this are as follows: $>MYFILE.RIP$ $>FILE1$ $>FILE1.RIP$$>FILE2.RIP$$>FILE3$ Note in the last example, a file extension other than .RIP was used. You are not limited to playing back local .RIP files. In fact, you can play-back any file you want. You could load any simple text file, ANSI picture image, or other such thing. When loaded, the data is not sent to the host; it is strictly echoed on your local screen. If the file is a .RIP file, it will replay any graphics that were in the file and if any Mouse Regions are defined, it will create those fields for you as well, thus allowing you to pop-up dialog screens or other such things that are not built-in to RIPterm normally. Each "local RIP playback" variable you enter will search for the .RIP file in the current host's icon directory. If it cannot find the file in that directory, it will check the ICONS\ directory. When Local RIPscrip File Playback is chosen, the file is not played back immediately. Whatever operation is being processed (like a host command being sent to the BBS, etc) will be completed. After the completion of the command in question, the RIPscrip file is played back locally. An internal Queue of files is stored in memory in RIPterm. Each time it gets a Local RIP file playback command, it adds the filename to the queue. When the current operation is completed, the queue is flushed by playing back all of the files in the queue in the order that they were received. POP-UP PICK LISTS ----------------- Any place that you can use a Text Variable (Queries, Button and Mouse Field return strings, and Keystroke Macros), you can take advantage of a unique feature of RIPscrip - Pop-Up Pick Lists. A Pop-Up Pick List is simply a list that pops up allowing you to choose from one of several available values. Whichever entry in the list you choose will insert it's associated command in the Host Command returned back to your host. A list is created by putting the special list instructions inside two sets of parenthesis like this: (( and )). The list consists of an optional question followed by two colons (::), followed by one or more list entries. For example, ((Send Email to?::Sysop,Cosysop,Joe)) says to pop-up a list asking you "Send Email to?", giving you the choices of "Sysop", "Cosysop", and "Joe". By default, if you press ESC instead of picking an entry in the list, then nothing will be inserted into the text of your Command. You can indicate that the user must pick an entry by putting an asterisk (*) at the beginning of the question. For example, ((*Send Mail to?::Sysop,Joe)). This would make it so that the user must choose either Sysop or Joe. In the previous examples, Sysop and Joe are the text responses that are inserted into your Host Command. These commands are also the same things that are displayed in the listing. If you want to use something else in the listing instead of the return text, you can. When you make the list entry, add an @description to the end of it. For example: ((Send Mail To?::Sysop@Head Honcho,Cosysop,Joe)) ...would display a pop-up pick list of Head Honcho, Cosysop, and Joe. One final feature of Pop-Up Pick Lists allows you to specify a hotkey for each entry in the list. For example, if you wanted the first character of each entry to be highlighted (thus allowing you to select that character to activate the entry), simply put a tilde (~) or an underline (_) before and after the keystroke. For example "_S_ysop" would highlight the "S" in "Sysop" appearing like this: Sysop You can highlight more than one character, but only the first one will be the active hotkey. If you omit the second tilde or underline, then the remainder of the description will be highlighted. NOTE: If you use a tilde or an underline in the Text Response (not the description), then those characters are inserted into your Host Command when it is transmitted to the host. You probably don't want to do this. Recommendation: only use hotkey features on list entries where you specify a description! If you do not specify a question, then the list default to the question: Choose one of the following: You may specify up to twenty entries for any one list. In RIPterm version 1.52 and earlier, the total length of a pick list was 256 bytes. In version 1.53 and later, this limit has been increased to 1024 bytes. Some characters have special significance in the RIPscrip language. These characters are ! (exclamation mark, or for you Unix-heads, bang), \ (backslash), and | (vertical bar). To use these characters in a Text Response, they must be preceded by a backslash (! becomes \!, \ becomes \\, and | becomes \|). RIPaint automatically adds these when creating Text Responses. You need to be aware of this only if you are editing RIPscrip files with a text editor. The _ (underline) and ~ (tilde) characters used to indicate the hotkey in a Text Response are not able to be preceded by a backslash to be used by themselves. They will be returned to the host if they exist in a Text Response (not in the description), however everything after the underline or tilde will be underlined, and the first character will be considered the hotkey. Examples: ((Send E-Mail to?::Sysop,Joe,Mike)) ((*Send E-Mail to?::Sysop@The Head Honcho,Joe,Mike@My Brother)) ((::Sysop@_T_he Head Honcho,Joe,Mike@My _B_rother)) WHAT CAN GO WHERE? ------------------ With all this talk about Templates, Text Variables, Local RIP file playback, pop-up pick lists and control characters, you might be interested in knowing what can be used where in the RIPscrip language. It has already been stated that Templates can be used only in Button Host Commands. Text Variables, Local RIP file playback, pop-up lists and control characters can be used in several places though. The places that these commands can be used and not used are listed in the following chart: +-----------------------------------+ | T | D V | T | P | C | L | | E | A A | A E | I | T | O | | M | T R | C X | C | R | C | | P | A I | T T | K | L | A | | L | A | I | | | L | | A | T B | V V | L | C | | | T | E L | E A | I | H | R | | E | X E | R | S | A | I | | S | T S | S | T | R | P | |-----------------------------------| | | | | | | | Button Host Commands| Y | Y | Y | Y | Y | Y | | | | | | | | Host Simple Mouse Fields | N | Y | Y | Y | Y | Y | Related | | | | | | | Commands Query Command | N | Y | Y | Y | Y | Y | | | | | | | | |-----------------------------------| | | | | | | | Button Labels | N | Y | N | N | N | N | | | | | | | | Text Output RIP_TEXT_XY | N | Y | N | N | N | N | Related | | | | | | | Commands RIP_TEXT | N | Y | N | N | N | N | | | | | | | | +-----------------------------------+ THINGS TO TAKE SPECIAL CARE WITH -------------------------------- Special care must be taken when executing Host Commands or Query commands that contain local RIP file playback or that contain active text variables. Either of these operations could instruct RIPterm to destroy all Mouse Fields by either performing a RIP_RESET_WINDOWS command ($RESET$), a RIP_KILL_MOUSE_FIELDS command ($MKILL$), a restore mouse fields text variable ($RMF$) or other such things. If a situation like this happens, care should be taken to preserve currently processed Host Buffer. If it is a mouse field's host command that is being processed, you wouldn't want your application destroying the very buffer that you're processing before you're done processing it, would you? In the case of RIPterm, we do a sub-string search on the Host buffer before any processing is done. We search for the following strings: $RMF$ ... Restore Mouse Fields $> ... Beginning segment of a Local RIP playback command $APP ... Instruction to execute an external application $RESET$ ... Performs a RIP_RESET_WINDOWS command $MKILL$ ... Destroys the contents of the internal mouse table If any one of the above strings are found, RIPterm will physically back-up the Host buffer into another location - one that won't be destroyed by the execution of the above commands. The processing of the Host buffer is then done on the new buffer, not the actual buffer. In this way, the application can destroy the mouse table to its heart's content but the processing of the buffer will not be affected.