Tag files

From phpCMS

Contents 1 Using tag files 1.1 Why should I use tags at all? 1.2 Structure of a tag file 1.3 Working with tags 1.4 Some examples

[edit] Using tag files

Tag files represent a very important and useful phpCMS feature. Unfortunately many people underestimate this powerful feature. So let us explain how to use tag files correctly.

[edit] Why should I use tags at all?

It is the most asked question about tags at the beginning. Tags are nothing else than a synonym for (HTML-)tags. This definition is correct in general, but doesn't show the real power of tag files, because they can do so much more.

The actual idea behind tag files is the following: Assumed there are 10 existing content files and each of them contains several tips noted in a red and bold font. Between the tips there is a horizontal row to divide each tip from another. If you now change the template to a red background or you don't like horizontal rows any more, then (without tag files) you would have to edit every single content file. But this naturally isn't the purpose of a content management system. Using tags decreases the work if you want to change the design. In addition, tag files can also save much writing as you can replace long code blocks with short tags.

[edit] Structure of a tag file

Each project file owns a tag file. But one single tag file can be used by several project files at the same time. Comments are allowed in tag files, too. To avoid restriction of the user, the semicolon ; which is used as comment char, is only interpreted as a comment char if it stands at the beginning of a line. Surplus white spaces and tabs are extracted automatically during reading of the file, so you can optimize the formatting of the tag file to meet your needs.

A tag definition begins with the expression which is to be defined, followed by the assignment symbol :=. After this you write the replacing expression. You can also use variables within tags. This is multiplying the power of tags! To use variables, you have to specify all parameters at the left side within quotation marks (double quotes: ") and separated by comma. You can change this delimiter in your configuration file. A variable generally looks like $nameofvariable. Then you can use the just defined variables on the right side. These variables are only valid within the tag they have been defined. Or, differently expressed: If you use a variable $test at the left side each time, it will be a "different" variable in each tag definition. Look at the following examples to clarify the usage of tags.

[edit] Working with tags

If a tag is declared in a tag file, it can be used elsewhere (in the same project - if you use this tag file in more than one project, then even there). You can use it either in templates or in content files. If a tag used in a template or content file isn't declared in the tag file, it will be passed on untouched. An existing tag which has no replacement won't be passed on. The tag replacement in phpCMS works recursive. This means a tag may contain further tags. It depends on the position of the tags towards each other within the tag file (tags, which are first processed, can be used in later definitions).

[edit] Some examples

As mentioned above here are some examples. In the demo tag file delivered with the phpCMS download package, you can find the following part. This part is responsible for the replacement of the german umlauts by the according HTML-codes. It is meaningful to define this part in the tag file as it makes possible to write normal text in the templates and content files so that these files are much more readable.

ä:=ä
ö:=ö
ü:=ü
Ä:=Ä
Ö:=Ö
Ü:=Ü
ß:=ß

Next, we define an instruction to show important messages:

[HINT]:=<b><i>
[/HINT]:=</i></b>

You can use such an instruction like any other in any template and any content file. For example, in a content file this may look like this:

[HINT]This is a hint.[/HINT]

As the curly brackets are used as the placeholder sign, they cannot be used elsewhere. But you can make a replacement with tags to re-enable these chars. The so produced code behaves like before, but phpCMS processes it correctly.

<(>:={
<)>:=}

Last but not least let's demonstrate the usage of variables. Sometimes this is very useful. But to make it as easy as possible we show only a very simple example:

[PIC "$url,$alt"]:=<img src="$url" alt="$alt" />

This tag provides showing images in a quick an easy way. In a content file it could be noted like this:

{CONTENT}
A Picture: [PIC "/images/test.png,testing picture"]

As this example shows, you mustn't use commas and quotation marks within variables because they are already used otherwise. The following examples would lead to an error:

{CONTENT}
A Picture: [PIC "/images/test.png,testing picture, from phpCMS"]
Another Picture: [PIC "/images/test2.png,testing picture "phpCMS""]

If you changed the delimiter in the parser configuration to something else then you can use the comma in your variables. Please notice that you have to change the examples above too if you changed the delimiter!