Getting Started

So you are new to PHeasel and want to get an idea how things work? Then you are in the right place and it will just take a few minutes. This page will give you a kickstart into performing tasks with PHeasel. The examples below cover the important things you need to know, but be sure to have a look at the reference page later on, to find details about the possiblities.

Working with Markup

You will create your website in PHeasel's /site/ subdirectory; it is your realm. The directory structure within can be set up completely at your convenience. Well, except the /static/ directory... we will cover this one later.

Pages – Mapping Pretty URLs to Your Content

To create a page, simply create a new file anywhere within the /site/ directory - the filename must contain the word page, separated by a dot (.) from the rest, e.g. mypagefilename.page.php or page.mypagefilename.php. To make the page accessible through a pretty URL, we need to add a little configuration tag to the markup, see example on the right.
Voila – the page can be accessed by entering e.g. http://localhost/my-page/ into the browser adress bar. Pretty URL. Pretty easy.
For more details, have a look at the page markup reference.

Example: page markup

        <!DOCTYPE HTML>
        <html>
        <head>
            <ph:config id="mypage" url="/my-page/">  
        </head>
        <body>
            Page content goes here.
        </body>
        </html>

Links – Referencing Pages

Have you noticed the (yet) unused id in above example? You won't be surprised to hear that you need the ID in order to reference your page.
For more details, have a look at the URL placeholder reference.
Bonus: in case your eyes (or your syntax highlighter, or your validator) freak out at the sight of tags within tags, just have a look at the second link and be happy that PHeasel's tags are flexible enough for your to use curly instead of angle brackets and single instead of double quotes.

Example: link

             
            <a href="<ph:url pageid="mypage">">
                Link to my new page
            </a>

Example: alternative syntax for the same link

             
            <a href="{ph:url pageid='mypage'}">
                Link to my new page
            </a>

Templates – Re-using Surrounding Markup

Nearly every website out there has a common portion of markup wrapping the actual page content, e.g. logo, navigation and footer. With PHeasel you can put this markup into a template. Simply create another markup file anywhere in the /site/ directory. Templates need to have the word tmpl in the file name, e.g. tmpl.mytemplatefilename.php.
Again, an ID is needed to reference the template. In addition, the template markup must contain a <ph:page> to indicate where the actual page markup is to be inserted.

Example: template markup

            <!DOCTYPE HTML>
            <html>
            <head>
                <ph:config id= mytemplate>  
            </head>
            <body>
                Navigation goes here.
                <ph:page> 
                Footer goes here.
            </body>
            </html>

The only thing left to do is to tell our page which template to use. To do so, we need to add a template parameter to the config section of our page.
For more details, have a look at the template markup reference.

Example: referencing a template from a page

            <ph:config
                id       = mypage
                url      = /my-page/
                template = mytemplate
            >

Snippets – Re-using Contained Markup

It is also quite common to have common pieces of markup within the content of different pages, e.g. teaser boxes or code for advertising. You can outsource these into PHeasel snippets. Make sure your snippet markup file contains the word snip, e.g. snip.mysnippet.php and assign an ID to your snippet.

Example: snippet markup

            <!DOCTYPE HTML>
            <html>
            <head>
                <ph:config id=mysnippet>  
            </head>
            <body>
                Snippet content goes here.
            </body>
            </html>

You can reference snippets from pages, templates and even from other snippets.
For more details, have a look at the snippet markup reference and the snippet placeholder reference.

Example

             
            <ph:snippet id=mysnippet>

Internationalisation (I18N) and Localisation (L10N)

Translating a hand full of web pages to a second language is not hard: First duplicate, then translate.
But you probably have experienced that it can get very complex when the site grows more extensive, undergoes structural changes or more languages need to be added. Prematurely localised websites often evolve into huge constructs of duplication and eventually become confusing or even unmaintainable.
Decent internationalisation was one of the driving ideas behind PHeasel, and it comes with out-of-the-box localisation support.

Markup Localisation

The following example covers the easiest way to localise markup files with PHeasel. It involves markup duplication (yet in a structured manner) and is ideal for websites with a lot of textual content and clean, semantic HTML markup. For more complex user interfaces (e.g. web applications having more HTML markup than text in the pages) a second way is in the making, which avoids markup duplication by having all messages strings in INI-files. Expect it to be available within the next few weeks.

Getting back to the example above, adding a translation of our page consists of three simple steps:
Step 1: Rename the page markup file to have en anywhere in the file name, again separated with a dot, e.g. page.mypagefilename.en.php.
Note: any separated two-letter sequence in the filename is assumed to be a language definition.
Step 2: Duplicate the file, using e.g. de instead of en in the filename e.g. page.mypagefilename.de.php.
Step 3: Translate the new file and choose an appropriate URL for it.
Please note that the ID does not change.

Example: page markup translated to German

            <!DOCTYPE HTML>
            <html>
            <head>
                <ph:config
                    id       = mypage
                    url      = /meine-seite/
                    template = mytemplate
                >  
            </head>
            <body>
                Seiteninhalt kommt hier hinein.
            </body>
            </html>

Advantages and Disadvantages of PHeasel I18N Concept

You might ask yourself: "How is the PHeasel approach any different from simply duplicating the complete website?"
Admittedly, in this simple example the differences are not very obvious, but there are some advantages (and maybe one disadvantage, depending on your usage) compared to other I18N concepts:

File system independency: The markup files can be grouped in subdirectories to your liking. When maintaining a multilingual website alone, it might be preferable to have the source language markup file side-by-side with the translation files, so that changes can easily be adopted. However, if there are different translators for different languages, it is convenient to have a directory per language, making it easier to find recent changes in a specific language and what needs to be translated.

Locale-independent references: only the page ID is needed to create a link to it. You do not have to think about URLs when copying a link from one language to another, PHeasel will sort this out for you.

Selective duplication: You do not have to duplicate all markup files - like in the example above, you are free to have localized pages with non-localized snippets or templates. Which is totally fine in some cases, e.g. when markup files simply do not contain any text. PHeasel will take care of falling back to the non-localized markup if it cannot find a localized one.

Super-pretty URLs: your URLs are neither limited by the file system nor by a CMS/framework. Just a short example: Less elegant solutions would force us to use URLs like
de.pheasel.org/getting-started/,
pheasel.org/de/getting-started/ or
pheasel.org/de/erste-schritte/ (somewhat better).
It is not that bad (and if you prefer: of course you can do that with PHeasel, too), but it can be better. The URL path should be localized ("getting-started" in English, "erste-schritte" in German), and if it is, we do not need a two-character country code in the URL. Look at this:
pheasel.org/getting-started/ (en) and pheasel.org/erste-schritte/ (de).
That is catchier, isn't it?

But this procedure also introduces the possibility of cross-language URL naming conflicts: consider mounting a multilingual download page, which would be called /download/ in most of this world's languages. That's the obvious drawback, but one can still resort to /download-de/, /download/de/, or anything else.