#
# Documentation about the new template files for the Attachment Mod
#

(Note: Please excuse my grammatical failures and my bad english, but i hope you can understand me at all)

(The Basic Understandings)
1. Basic description of template variables, switches and Blocks
    1.1. Variables
    1.2. Switches
    1.3. Block Variables
(Now the Attachment Mod specific things)
2. How to modify existing template-sets (what you should have in mind if you do or use a template)
    2.1. posting_body.tpl
    2.2. viewtopic_body.tpl
    2.3. viewforum_body.tpl

3. Explanation of the template files stored in main template directory
    3.1. posting_attach_body.tpl
    3.2. viewtopic_attach_body.tpl



1. Basic description of template variables, switches and Blocks

1.1. Variables

ok, how to begin... let's have a look at a basic template layout, with some variables included:
<html>
<head>
<title>{TITLE}</title>
</head>
<body bgcolor="{T_BODY_BGCOLOR}" text="{T_BODY_TEXT}" link="{T_BODY_LINK}">
{L_MY_HOMEPAGE}
</body>
</html>
as you can see, there are some really strange things... there is text enclosed between {}, what did this mean ? The template system of phpBB2 can replace everything within these braces and instead of it putting things in. if a variable is not defined at the php-files it will be replaced with nothing by the template system.

an example:

{L_MY_HOMEPAGE}

as you can see, there is a L_ before the name MY_HOMEPAGE, this is just a convention the phpBB-Group set, saying that everything beginning with L_ should be a language-thingy. ok, say, in the english language files there is a line saying "My Homepage" and in the german language file it's saying "Meine Startseite". if you have set english to your board language {L_MY_HOMEPAGE} get's replaced with "My Homepage":

My Homepage

another example:

{TITLE}

there is no L_ before it, therefore it must be a configurable thing or a value from the database (this can be topic-names, post-texts ...). ok, {TITLE} is the title of your page... maybe:

PhpBB.com

You may wonder what the T_ stands for ? :) i think these are those variables defined in the Styles Administration... Another predence not listed here is S_, this stands for complete input or select-fields. And last but not least, the U_ precedence. This is used for Links... (<a href="{U_DOWNLOAD_LINK}" /> for example)

Ok, to sum this up: Those Text, enclosed between {} got replaced with those Strings defined in the php-files. To get a complete list of all available variables you have to wait till phpBB2 Final is released.

oh, i forgot to show you the parsed html-code (as your browser will see it):

<html>
<head>
<title>PhpBB.com</title>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#003366">
Meine Startseite
</body>
</html>
:)


1.2. Switches

Switches are basicly ... switches. ;)
In phpBB2 you or the developers don't want to display things if not a particular action or situation is given.
A little example:
<!-- BEGIN user_logged_in -->
{L_WELCOME_USER}
<!-- END user_logged_in -->

as you can see, switches have to definable areas, one with a BEGIN, and one with a END. all code between it get only parsed if the Switch is "True" (this means, that the action or situation is taken, at this example, the user is logged in). Switches have to be in ONE Line, no other code can be around one switch-line (spaces don't count).

BAD (the switch don't work):

<body bgcolor="#FFFFFF"> <!-- BEGIN user_logged_in -->
        {L_WELCOME_USER}     <!-- END user_logged_in -->

GOOD (the switch will work):
        <!-- BEGIN user_logged_in -->
{L_WELCOME_USER}
        <!-- END user_logged_in -->
ok, i think you've got it, now the parsed one:

if the user is logged in:

Hello Acyd Burn, welcome to our new board.

if the user is not logged in then there is nothing.


1.3. Block Variables

Ok, this is the really cool stuff in templating. If you have ever asked why the templates are so small, and the board layout is so big, ever asked why there is only one table for all posts, than the answer is: block variables. :)

Block Variables are switches with Variables that predefine the switch-name. ok, i see, you don't understand the last sentence, i will give an example:

Say we have two posts:

My post message is here.

and:

This message is also here.

ok, these two lines are our posts at our board. Now, how do we display them ?

<!-- BEGIN postrow -->
{postrow.MESSAGE}
<!-- END postrow -->
We have a switch and a Variable here, but the Variable looks strange... the switch name is prescended to the Variable Name. {MESSAGE} is our post message, therefore {postrow.MESSAGE} is every message in postrow. the row gets evaluated every time the template can find a corresponding variable. You can think of an array or a buffer of variables, postrow is like an array.

and for the better understanding another example:

Message 1:
    Attachment 1
    Attachment 2
    Attachment 3

Message 2:
    Attachment 1
    Attachment 2

We want to do this:
Display every Message (we don't know how many these are) and within every Message the posted Attachments (we don't know how many there are for every Message).
What we use are two blocks, one for every message and a second block (within the first one) for the Attachments:

<table>
<!-- BEGIN postrow -->
  <tr>
    <td>
      {postrow.MESSAGE}

  <!-- BEGIN attachrow -->
      <hr>
      {postrow.attachrow.ATTACHMENT}
      <br />
  <!-- END attachrow -->

    </td>
  </tr>
<!-- END postrow -->
</table>

I hope you understand Block Variables now a little bit.


2. How to modify existing template-sets (what you should have in mind if you do or use a template)

2.1. posting_body.tpl

The first change to make is the addition of an enctype to the form-element. Every time you submit a post all the Data for that post is carried through the specified target at the form-tag:
        <form action="{S_POST_ACTION}" method="post" name="post" onSubmit="return checkForm(this)">
The Script that will process this post is {S_POST_ACTION} (you know, this gets evaluated by the template).
Normally you have one form in your posting_body.tpl.
But to getting Attachments to work we need additional informations, therefore we have to say the form-tag which "data-type" we want. For Attachments this is multipart/form-data. We have to add this to our form:
      <form action="{S_POST_ACTION}" method="post" name="post" onSubmit="return checkForm(this)" enctype="multipart/form-data">
The next part is to decide where to put the Attachment Box (where the user can Add, Delete ... Attachments), this Box is one Template Variable:
        {ATTACHBOX}
This Variable get's evaluated and it's evaluated content is in posting_attach_body.tpl (see 3.1). You can put this Variable whereever you want to show up the Attachment Box in your template, normally this is before the Poll entry ({POLLBOX})


2.2. viewtopic_body.tpl

To display your Attachments within a topic and every Message you have to add the Variable {postrow.ATTACHMENTS} (you see ? this is a Block Variable) between the switch "postrow". The Contents of this Variable is stored in viewtopic_attach_body.tpl (See 3.2).

For example, if you want the Attachments Display before your Signature you have to put {postrow.ATTACHMENTS} before {postrow.SIGNATURE}, if you want the display after the signature, put it after {postrow.SIGNATURE}.


2.3. viewforum_body.tpl

Only one new Variable, {topicrow.HAS_ATTACHMENTS_IMG}, this Variable gets evaluated to the Image you specify under Attachments->Management, this is your "Attachment Topic Icon". :)
This Variable have to put between the "topicrow"-switch, as you can see on the variable name.



3. Explanation of the template files stored in main template directory

3.1. posting_attach_body.tpl

This is used for the Attachment Box if you post, reply or edit a message.

ok, first of all, the source:

        <tr>
                <th class="thHead" colspan="2">{L_ADD_ATTACH_TITLE}</th>
        </tr>
        <tr>
                <td class="row1" colspan="2"><span class="gensmall">{L_ADD_ATTACH_EXPLAIN}</span></td>
        </tr>

        <tr>
                <td class="row1"><span class="gen"><b>{L_FILE_NAME}</b></span></td>
            <td class="row2"><span class="genmed"> <input type="file" name="fileupload" size="50" maxlength="{FILESIZE}" value="{FILENAME}" class="post"> </span></td>
        </tr>
        <tr>
                <td class="row1"><span class="gen"><b>{L_FILE_COMMENT}</b></span></td>
            <td class="row2"><span class="genmed"> <input type="text" name="filecomment" size="40" maxlength="60" value="{FILE_COMMENT}" class="post"> &nbsp;
                <input type="submit" name="add_attachment" value="{L_ADD_ATTACHMENT}" class="liteoption" /> </span></td>
        </tr>

        <!-- BEGIN switch_posted_attachments -->
        <tr>
                <th class="thHead" colspan="2">{L_POSTED_ATTACHMENTS}</th>
        </tr>
        <!-- END switch_posted_attachments -->

        <!-- BEGIN attach_row -->
                <tr>
                        <td class="row1"><span class="gen"><b>{L_FILE_NAME}</b></span></td>
                        <td class="row2"><span class="gen"> <a class="gen" href="{attach_row.U_VIEW_ATTACHMENT}" target="_blank">{attach_row.FILE_NAME}</a></span>
                        </td>
                </tr>
            <tr>
                        &lt;td class="row1">&lt;span class="gen">&lt;b>{L_FILE_COMMENT}&lt;/b>&lt;/span>&lt;/td>
                        &lt;td class="row2">&lt;span class="genmed"> &lt;input type="text" name="comment_list[]" size="40" class="post" maxlength="60" value="{attach_row.FILE_COMMENT}" />&lt;/span> &nbsp;
                        &lt;input type="submit" name="edit_comment[{attach_row.ATTACH_FILENAME}]" value="{L_UPDATE_COMMENT}" class="liteoption" />
                        &nbsp; &lt;input type="submit" name="del_attachment[{attach_row.ATTACH_FILENAME}]" value="{L_DELETE_ATTACHMENT}" class="liteoption" /> </td>
                </tr>
                {attach_row.S_HIDDEN}
        <!-- END attach_row -->

I will only explain the Variables and switches, not the html. ;)

Ok, first of all the normal Variables, at the left the Variable Name, at the middle a explanation, at the right the evaluated things:

{L_ADD_ATTACH_TITLE}        Lang - Title                        Add an Attachment
{L_ADD_ATTACH_EXPLAIN}      Lang - Explanation                  If you do not want to add an attachment to your post leave the fields blank
{L_FILE_NAME}               Lang                                Filename
{L_FILE_COMMENT}            Lang                                File Comment
{L_ADD_ATTACHMENT}          Lang                                Add Attachment
{L_POSTED_ATTACHMENTS}      Lang                                Posted Attachments
{L_UPDATE_COMMENT}          Lang                                Update Comment
{L_DELETE_ATTACHMENT}       Lang                                Delete Attachment
{FILESIZE}                                                      The Max allowable Filesize
{FILENAME}                                                      The entered Filename
{FILE_COMMENT}                                                  The entered File Comment

Now we have our normal switch "switch_posted_attachments":

        <!-- BEGIN switch_posted_attachments -->
        <tr>
                <th class="thHead" colspan="2">{L_POSTED_ATTACHMENTS}</th>
        </tr>
        <!-- END switch_posted_attachments -->
This content is only displayed if the User have already posted or added an Attachment.

The only Block is the "attach_row", this are all Attachments the User have posted or added to his post:

        <!-- BEGIN attach_row -->
                <tr>
                        <td class="row1"><span class="gen"><b>{L_FILE_NAME}</b></span></td>
                        <td class="row2"><span class="gen"> <a class="gen" href="{attach_row.U_VIEW_ATTACHMENT}" target="_blank">{attach_row.FILE_NAME}</a></span>
                        </td>
                </tr>
            <tr>
                        <td class="row1"><span class="gen"><b>{L_FILE_COMMENT}</b></span></td>
                        <td class="row2"><span class="genmed"> <input type="text" name="comment_list[]" size="40" class="post" maxlength="60" value="{attach_row.FILE_COMMENT}" /></span> &nbsp;
                        <input type="submit" name="edit_comment[{attach_row.ATTACH_FILENAME}]" value="{L_UPDATE_COMMENT}" class="liteoption" />
                        &nbsp; <input type="submit" name="del_attachment[{attach_row.ATTACH_FILENAME}]" value="{L_DELETE_ATTACHMENT}" class="liteoption" /> </td>
                </tr>
                {attach_row.S_HIDDEN}
        <!-- END attach_row -->
The Block Variables are:

{attach_row.U_VIEW_ATTACHMENT}                The Adress to preview the Attachment
{attach_row.FILE_NAME}                        The Filename of the Attachment
{attach_row.FILE_COMMENT}                     The File Comment of the Attachment
{attach_row.ATTACH_FILENAME}                  The physical Filename of the Attachment
{attach_row.S_HIDDEN}                         All Hidden fields for the Attachment
Every posted or added Attachment have these 5 Variables.


3.2. viewtopic_attach_body.tpl

The vietopic_attach_body.tpl is proposed for the Attachment View in viewtopic, there are Block Variables for any situation. If this File gets evaluated we are alreade in a Block Switch (postrow).

Because we can have more than one Attachment in one post, at the beginning of this file we have another Block Variable, attachmod. At the beginning the switch has to be opened with <!-- BEGIN attachmod --> and at the end of the file it has to be closed with <!-- END attachmod -->. Therefore all Variables have to be preceded with postrow.attachmod.

I will list now all content between the first Block Variable:

                          <br /><br /><hr><br />

                        <!-- BEGIN denyrow -->
                          <span class="postbody">[{postrow.attachmod.denyrow.L_DENIED}]</span><br /><br />
                        <!-- END denyrow -->

                        <!-- BEGIN imagerow -->
                          <span class="postbody">{postrow.attachmod.imagerow.DOWNLOAD_NAME}<br />
                          <img src="{postrow.attachmod.imagerow.IMG_SRC}" alt="{postrow.attachmod.imagerow.DOWNLOAD_NAME}" /></span><br />
                          <span class="gensmall">{postrow.attachmod.imagerow.L_DOWNLOAD_COUNT}</span><br /><br />
                        <!-- END imagerow -->

                        <!-- BEGIN attachrow -->
                          <span class="postbody">

                                <!-- BEGIN upload_image -->
                                  <img src="{postrow.attachmod.attachrow.upload_image.UPLOAD_IMG}" alt="" />
                                <!-- END upload_image -->

                          <a href="{postrow.attachmod.attachrow.U_DOWNLOAD_LINK}" target="_blank">{postrow.attachmod.attachrow.DOWNLOAD_NAME}</a> - {postrow.attachmod.attachrow.FILESIZE} kb<br /></span>
                          <span class="gensmall">{postrow.attachmod.attachrow.L_DOWNLOAD_COUNT}</span><br /><br />
                        <!-- END attachrow -->

DENYROW:

                        <!-- BEGIN denyrow -->
                          <span class="postbody">[{postrow.attachmod.denyrow.L_DENIED}]</span><br /><br />
                        <!-- END denyrow -->

Ok, the first Block Variable is denyrow. denyrow is used if the Mime Group or Mime Type for the posted Attachment get's disabled. The Variable {postrow.attachmod.denyrow.L_DENIED} is a language variable and gets evaluated to:
"mime type <here the mime type is displayed> was deactivated by an board admin, therefore this attachment is not displayed"

IMAGEROW:

                        <!-- BEGIN imagerow -->
                          <span class="postbody">{postrow.attachmod.imagerow.DOWNLOAD_NAME}<br />
                          <img src="{postrow.attachmod.imagerow.IMG_SRC}" alt="{postrow.attachmod.imagerow.DOWNLOAD_NAME}" /></span><br />
                          <span class="gensmall">{postrow.attachmod.imagerow.L_DOWNLOAD_COUNT}</span><br /><br />
                        <!-- END imagerow -->

The second one is the imagerow. This Block will be used for every Attachment that is inlined, that means an Attachment viewed directly (normally this is an image).
The Variables for this are:

{postrow.attachmod.imagerow.DOWNLOAD_NAME}         The Name of the File
{postrow.attachmod.imagerow.IMG_SRC}               The File itself
{postrow.attachmod.imagerow.L_DOWNLOAD_COUNT}      The Language Line, saying how often the File is viewed or downloaded
ATTACHROW:
                        <!-- BEGIN attachrow -->
                          <span class="postbody">

                                <!-- BEGIN upload_image -->
                                  <img src="{postrow.attachmod.attachrow.upload_image.UPLOAD_IMG}" alt="" />
                                <!-- END upload_image -->

                          <a href="{postrow.attachmod.attachrow.U_DOWNLOAD_LINK}" target="_blank">{postrow.attachmod.attachrow.DOWNLOAD_NAME}</a> - {postrow.attachmod.attachrow.FILESIZE} kb<br /></span>
                          <span class="gensmall">{postrow.attachmod.attachrow.L_DOWNLOAD_COUNT}</span><br /><br />
                        <!-- END attachrow -->
The attachrow is for displaying an Attachment that can only be downloaded (by clicking it). We have another Block Variable in it:

UPLOAD_IMAGE:
                                <!-- BEGIN upload_image -->
                                  <img src="{postrow.attachmod.attachrow.upload_image.UPLOAD_IMG}" alt="" />
                                <!-- END upload_image -->
This content of this block is only displayed if you have specified a "Path to an image for attachments", the upload image (normally this little paperclip).
{postrow.attachmod.attachrow.upload_image.UPLOAD_IMG} is the source to this little Upload Image (normally images/icon_clip.gif).

The Block Variables for the attachrow:

{postrow.attachmod.attachrow.U_DOWNLOAD_LINK}        This is the Download-Link to the Attachment
{postrow.attachmod.attachrow.DOWNLOAD_NAME}          The displayed filename of the Attachment
{postrow.attachmod.attachrow.FILESIZE}               The Filesize of the Attachment
{postrow.attachmod.attachrow.L_DOWNLOAD_COUNT}       The Language Line, saying how often the File is viewed or downloaded
Ok, this is not too hard, or ? i hope not. :)

If you have questions or want to correct me please contact me. ;) i am only a human and maybe i am totally wrong with something i said, so please point me to the right direction.

Acyd.