Introduction

Temma in 3 minutes

Temma is a Model-View-Controller (MVC for short), designed to facilitate and accelerate website development.

The framework takes care of incoming requests, saving you from re-developing the lowest layers of your applications over and over again, leaving you to focus on the “business code”, the most important part.


1Installation

Please refer to the installation documentation page to find out how to install Temma.


2Basic principles

Temma facilitates the development of sites made up of URLs such as:

http://www.site.com/controller/action/p1/p2/p3

URLs are split into 3 parts:

  • The name of the controller, an object that will be instantiated upon receipt of the request.
  • The name of the action, a method of this object that will be called.
  • A variable number of parameters that this method will be able to use.

The following code will then be executed:

Controller::action(p1, p2, p3)

By default, the framework will generate a page by interpreting the templates/controller/action.tpl template file

Obviously, it is possible to modify the default behaviors. A controller can choose to read data received in POST instead of − or in addition to − those received in GET parameter. An action can define a specific template to use, or even define a completely different type of view (which will generate JSON or XML instead of HTML, for example).


3Development example

For this example, we'll create a very simple website with two pages. The first will display a list of articles, the second will display the requested article.


3.1Configuration

The first thing to do is to create the project configuration file. This is the etc/temma.php file.

Refer to the configuration documentation for the different options.

Temma installation provides sample files, but here is the content of the one we'll be using:

<?php

return [
    'application' => [
        'dataSources' => [
            // database configuration
            'db' => 'mysql://user:passwd@localhost/mybase'
        ],
        // root controller configuration
        'rootController' => 'Articles'
    ],
    // thresholds for writing logs
    'loglevels' => [
        'Temma/Base' => 'ERROR',
        'Temma/Web'  => 'WARN',
        'default'    => 'WARN',
    ],
    // automatically imported template variables
    'autoimport' => [
        'siteName' => 'Demo site'
    ]
];
  • Line 7: Configuration of the connection to the database.
  • Line 10: The rootController directive is used to define the root controller of the site, that is to say the one that will respond when we connect to the address http://www.monsite.com/.
  • Line 14 to 16: We define the minimum levels of errors that will be recorded in the log/temma.log file.
  • Line 20: We define a template variable containing the name of the site.

3.2Database

First of all, we will create a table in the database. You need to run the following query on your database:

CREATE TABLE articles (
    id     INT UNSIGNED AUTO_INCREMENT,
    title  TINYTEXT,
    text   MEDIUMTEXT,
    author TINYTEXT,
    PRIMARY KEY (id)
);

And we can add data to it:

INSERT INTO articles (title, text, author)
VALUES ('Frist article',  'Text of the first article',  'John'),
       ('Second article', 'Text of the second article', 'Bob'),
       ('Third article',  'Text of the third article',  'John');

3.3Controller

We will write our first controller. A controller is an object that receives connections and manages them to send data back.
Controllers have actions, and each action can be assigned parameters.

Our controller will be called Articles. It will contain two main methods:

  • list(), to display the list of articles.
  • show(), to display a single article.

There will be added the __invoke() method whose only role is to receive connections on the root of the site and to redirect them to the list of articles.

In the controllers/ directory of your project, create a file named Articles.php.

<?php

/** Articles management controller. */
class Articles extends \Temma\Web\Controller {
    /** Tell the framework to automatically create the DAO. */
    protected $_temmaAutoDao = true;

    /** Root action (no explicit action). */
    public function __invoke() {
        // redirection to the list of articles
        $this->_redirect('/article/list');
    }

    /** Action that displays the list of articles. */
    public function list() {
        // retrieving the list of items from the database
        $articles = $this->_dao->search();

        // the list is made available for the template
        $this['articles'] = $articles;
    }

    /**
     * Action that displays the full content of an article.
     * @param  int  $id  Article's identifier.
     */
    public function show(int $id) {
        // retrieval of article content from the database
        $article = $this->_dao->get($id);

        // we check if the requested item exists or not
        if (!$article) {
            // it does not exist, redirect to the list
            $this->redirect('/article/list');
        } else {
            // it exists, data are sent to the template
            $this['article'] = $article;
        }
    }
}
  • Line 4: Controllers must inherit from the \Temma\Web\Controller object.
  • Line 6 : The controller contains a protected attribute named _temmaAutoDao, which tells Temma that it should automatically create a DAO (Data Access Object), which will be used to read or write to the database. This object is automatically configured to access the articles table (based on the controller name).
    For now, just know that this object offers a search() method which returns the list of all entries in the articles table, and a get() method which returns an element from its identifier.
  • Line 9: The root action is executed when no action is specifically requested. As this controller has been defined as the root controller (rootController in the etc/temma.php file), this is therefore the action that will be called when accessing the site root.
    • This action responds to the following two URLs:
      http://www.my-site.com/
      http://www.my-site.com/articles
    • Line 11: The Internet user is redirected to the page which displays the list of articles.
  • Line 15: The list action, which displays the list of items.
    • This action responds to the URL: http://www.myn-site.com/articles/list
    • Line 17: The DAO object is used to retrieve data for all items.
    • Line 20: We copy the value of the $articles variable into the articles template variable. The used template will (implicitly) be the templates/article/list.tpl file.
  • Line 27: The show action, which displays the content of an article whose identifier is provided as a parameter on the URL.
    • This action responds to the URL: http://www.my-site.com/articles/show/2
    • Line 29: The DAO object is used to retrieve item data from its identifier.
    • Line 31: If the article does not exist, we redirect to the list of articles.
    • Line 34: If the article exists, we save it as a template variable. The used template will (implicitly) be the templates/article/show.tpl file.

3.4Templates

Temma uses the Smarty template engine, which is very popular and has a very easy to understand syntax.

For the page that displays the list of articles, we will create the file templates/article/list.tpl:

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    <ul>
        {* loop on the list of articles *}
        {foreach $articles as $article}

            {* add a link to the article *}
            <li><a href="/articles/show/{$article.id}">
                {$article.title|escape}
            </a></li>

        {/foreach}
    </ul>
</body>
</html>
  • Line 3: The name of the site is placed in the <title> tag. It is escaped, to convert any special characters into HTML entities.
  • Line 8: Loop through the items in the article list.
  • Lines 11 to 13: Creation of the link to the page of an article. The title of the article is escaped, to convert special characters to HTML entities.

For the page that displays an article, we will create the file templates/article/show.tpl:

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    {* display the article's title *}
    <h1>{$article.title|escape}</h1>

    {* display the article's author *}
    <h2>par {$article.author|escape}</h2>

    <p>
        {* display the article's content *}
        {$article.text}
    </p>
</body>
</html>
  • Line 3: The site name is placed in the <title> tag, and its special characters are escaped.
  • Line 7: The title of the article is placed in an H1 tag, and its special characters are escaped.
  • Line 10: The author's name is placed in an H2 tag, and its special characters are escaped.
  • Line 14: The text of the article is placed in a paragraph (P tag), and its content is not escaped (it is already HTML).

4Further reading

Complete Temma Documentation