ROPE - CodeProject

1. What is ROPE?
2. What is ROPE good for?
3. How does ROPE work?

3.1 Symbols and references

3.2 Template file

3.3 Table of global symbols
4. ROPE tags

4.1 <rope:insert sym="symname">

4.2 <rope:foreach in="<rope-array>" as="symname" [key="key_symname"]> ... <rope:next>

4.3 <rope:include file="filename">

4.4 <rope:if sym="symname"> ... [<rope:else>] ... <rope:endif>

4.5 <rope:set sym="symname" val="value">

4.6 <rope:domacro sym="symname">

4.7 <rope:defmacro sym="symname"> ... <rope:endmacro>

4.8 <rope:loadmacro sym="symname" file="filename">
5. ROPE intag attributes

5.1 ropeit:isym="symname"
6. See "test page" and download ROPE
1. What is ROPE?
ROPE (Runtime Operational template Processing Extension) is a useful complementary tool for PHP programming.

2. What is ROPE good for?
The purpose of ROPE is to make easier and more flexible to separate the static and dynamic parts of the websites and so the work of the coder and the designer. With its help the large 'document here' printings in PHP routines can be avoided which are confusing the original concept of program and makes impossible the flexible changing of the design and the code independently of each other.

IMPORTANT: I can't declare in all situations that ROPE is more useful than the conventional methods. I dare to state this out only after a long period of using. Anyway it has been giving me a lot of help, which is understandable because it has been developed by my own needs.

3. How does ROPE work?
Truly ROPE is a simple text processor which inserts, replaces and ignores blocks of text. For its operation the next elements are needed:

3.1 Symbols and references
ROPE works with symbols and their values with references in <rope: ...> tags and intag attributes. ROPE uses global and local symbols just like other programming languages.
Global symbols are visible and available in the whole template and must be defined by the caller PHP routine in the global symbol table.
Local symbols are generated runtime while the template is being processed. (eg. <rope:set ...>, <rope:foreach ...>, etc...) Their availability and visibility are limited to the block defining them.
The symbols are resolved the same way as it is common in other programming languages, which means ROPE tries to resolve starting from the most internal block heading out for the global namespace. Undefined symbol (unsuccessful resolving) does not cause failure because it would be inconsistent with the main concept of ROPE. (See ROPE tags)
Symbolhandling of ROPE supports using of references. Syntactically it is indicated by a "$" character written before the name of the symbol. (for example: if the value of the symbole 'foo' is 'bar' then the expression 'sym="$foo"' is equal to the expression 'sym="bar"'). A reference can be multiple (eg. sym="$$$foo").
ROPE supports multidimensional arrays embedded in each other at any levels. At the moment arrays can be defined only by caller PHP routine (in global namespace)! (eg. search results, etc...) The command <rope:set ...> and other tags generating local symbols (eg. <rope:foreach ...>) can define only basic symbols but it is possible to refer to arrays in their attributes.
IMPORTANT: ROPE always works with associative array management, so the PHP-like usage of quotation marks for the keys is forbidden!!! (because of the main concept of ROPE)
Eg. a valid array expression: <rope:set sym="Zaphod" val="$foo[$bar[1][2]][42]">

3.2 Template file
is a simple textfile containing the static part of the output, the embedded <rope: ...> tags and the ROPE intag attributes. Because undefined tags are ignored in browsers usage of HTML files is highly recommended so the designer can edit the template file as a normal HTML one.

3.3 Table of global symbols
is an associative array in which the key is the symbolname used in the template file and the value - what a surprise - is the value of the symbol.

After building up the the table of symbols the PHP routine using ROPE calls

either the function rope_process( "<template_file_name>", <global_symbol_table> ) which processes the template file and prints out the result on standard output,
or the function rope_process_buffer( "<template_file_name>", <global_symbol_table> ) which processes the template file and returns with the result in a string.
The latter one is excellent for generating newsletters, etc.

4. ROPE tags
While processing a template file the functioning of ROPE is influenced by directives and instructions specified in <rope: ...> tags. Practically template file can be "programmed" this way.

4.1 <rope:insert sym="symname">
Resolves the symbol named "symname" and replaces the whole tag with its value. Eliminates the tag if resolving is unsuccessful.

4.2 <rope:foreach in="<rope-array>" as="symname" [key="key_symname"]> ... <rope:next>
A tag useable for iterative access of elements of ROPE arrays. With its help tables, lists, enumerations and practically any - even multilevel - iterative items can be generated.
If the symbol named in attribute "in" is an array its elements will be placed step by step into the local symbol named in attribute "as" and valid inside the <rope:foreach...> block and this block will be iteratively processed. In the local symbol named in optional "key" attribute the actual key (index) will be accessed.

4.3 <rope:include file="filename">
Opens and includes the file named "filename" (if it exists).

4.4 <rope:if sym="symname"> ... [<rope:else>] ... <rope:endif>
If the symbole named "symname" is defined and its value is not null the tag will be replaced with "if-branch". Otherwise if there is an "else-branch" it will be inserted, if not the tag will be eliminated.

4.5 <rope:set sym="symname" val="value">
Assignes "value" to the symbole named "symname" in actual namespace, and creates it if does not exist.
IMPORTANT: It is not usable to define arrays! (at the moment) :)

4.6 <rope:domacro sym="symname">
If it is defined the macro named "symname" will be processed at the place of the tag. The macro must be defined either in local or in global namespace as a ROPE symbol. The macro can be generated by the caller PHP routine or can be defined inside the template file using of <rope:defmacro sym="symname"> ... <rope:endmacro> tag or can be loaded from file with the <rope:loadmacro sym="symname" file="filename"> tag.

4.7 <rope:defmacro sym="symname"> ... <rope:endmacro>
Defines the macro named "symname" in actual namespace.

4.8 <rope:loadmacro sym="symname" file="filename">
Loads the file named "filename" (if it does exist) and defines a macro named "symname" with its content.

In ROPE tags can be embedded in each other at any way and level ( the only limit is the capacity of the webserver :)) ).

5. ROPE intag attributes
ROPE allows the usage of ROPE tags inside other HTML or ROPE tags but HTML standard itself does not define tags embedding. Therefore a tag inside an other tag corrupts the static view of template files, which severely contradicts the main concept of ROPE i.e. the template file must be editable as a normal HTML one. To resolve this problem the usage of "ROPE intag attributes" has been introduced which function is completely identical with ROPE tags mentioned above but their application is allowed inside other tags according to syntactical rules of HTML attributes.

5.1 ropeit:isym="symname"
Identical with <rope:insert sym="symname"> tag
e.g.:
<SELECT name="myselect">
<rope:foreach in="results" as="res_array" key="res_cntr">
<option ropeit:isym="res_array[selected]" value="ropeit:isym="$cntr"">
<rope:insert sym="res_array[text]">
</option>
<rope:next>
</SELECT>

At the moment there is only the "ropeit:isym" ROPE intag attribute implemented but the others will be resolved too in case of need and if I will cook up the adequate syntactics. Because of the fatal lack of time this really will happen only in case of inescapable need. :((

6. See "test page" and download ROPE

Licence:
The licence of ROPE is very simple, GPL-like i.e. you can use and redistribute it free. If you change it you should document it. ( if you would be so kind to notify me about it :)) )
If you use ROPE on your website you should present the link "Powered by ROPE" (http://www.reidea.hu/rope) somewhere on your site - even with the smallest letters.
Altough if you don't do that I can do nothing. :))

Download and tests:

download ROPE and sample files (zip format)
static view of ROPE test template file (with "view page source" the syntactics of ROPE can be seen)
result of ROPE test (the result of processing of template file can be seen)

If you find BUG or anything does not work:
Róbert Koszorús
(+36)20 579 929 5
or mail me
Enjoy ROPE!!!
Robi

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here