en:tutorials:minitutorial:1.8.x

Trace:
This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
~~LANG:fr@fr:tutoriels:minitutoriel:1.8.x~~

====== Mini Tutorial for Jelix 1.8 ======

The goal of this tutorial is to quickly show how you can develop an application with Jelix 1.8.

Examples of commands are to be executed into a bash/linux shell. If you are
under windows, you probably have to modify them a bit.

===== Download and installation =====

Jelix is available with Composer. You can also download the framework manually
( a zip or tar.gz archive), but you learn [[https://docs.jelix.org/en/manual-1.8/installation/create-application#installing-sources-from-jelix-org|how to do in the manual]].

So you have [[https://getcomposer.org/doc/00-intro.md|to install Composer]], and
after this step, you would have a @@composer@@ command.

Create a directory for your project, initialize a composer.json file, and
install the package @@jelix/jelix-standard@@:


<code bash>
mkdir myproject
cd myproject
composer init
composer require "jelix/jelix-standard:^1.8.0"
</code>

At the end, you have a new directory @@vendor@@, containing the source code
of Jelix and other packages.


===== Application creation =====

Let's create the tree structure of your application using @@F@vendor/bin/create-jelix-app@@ script.
We choose to create the application into an "example" directory:

<code bash>
php vendor/bin/create-jelix-app example
</code>

A number of questions are asked to you, to help you to configure the project.
For this tutorial, let's keep the default answer, except for the question
"How to install jelix-www files?", for which you choose "copy".

<code bash>
The web site of your company >
The licence of your application and modules (default is 'All rights reserved') >
The url to the licence if any >
Copyright on your application and modules (default is '2019 example') >
The suffix of your modules id (default is '@example') >
The creator name (your name for example) (default is 'example') >
The email of the creator >
How to install jelix-www files?
   copy: will be copied into the www/ directory
   filelink: a symbolic link into the www/ directory will point to the lib/jelix-www directory
   vhost: you will configure your web server to set an alias to the lib/jelix-www directory
 (default is '')
  [0] copy
  [1] vhost
  [2] filelink
 > 0
Web path to the content of lib/jelix-www? (default is 'jelix/') >
Do you want to store sessions into a database? ( 'y' or 'n', default is n) >
Do you want to store sessions as files into a specific directory? ( 'y' or 'n', default is n) >
</code>


As a result, you'll get an @@F@example/@@ directory, at the same level as the @@F@vendor/@@ directory. Its content will be :

<code>
  example/
     app/
         system/       the configuration files of your application
         responses/    custom response object for the application (views)
         themes/       the different possible themes in your application
         overloads/    will contain the different files that you will redefine, from modules.
     application.init.php   the file to initialize the jelix environment and the application
     console.php   the script to launch some commands to manage the application
     dev.php       the script to launch some commands to develop
     modules/      the modules of your application
     plugins/      the plugins of your application
     temp/         It contains all cache and temporary file generated by jelix.
     var/
         config/   the configuration files of your application, that are
                   specific to the environment and the server
         log/      the log files
     www/          the root directory of the site (public files)
</code>

===== Module creation =====

A module gathers a whole set of actions dispatched in controllers. At least one
is necessary in an application. This is why a module is created automatically
when you run @@create-jelix-app@@ command. A module is similar to "bundle" you
could find into other frameworks.

Here is the directory which has been created:

   example/modules/
              example/                the directory of the module
                module.xml          file describing the identity of the module
                controllers/       the classes processing the actions
                   default.classic.php   a default controller
                classes/            your business classes and services
                daos/               the object-relational mapping files
                forms/              forms files
                locales/            locales files ("properties files")
                    en_EN/
                    fr_FR/
                templates/          templates of the module
                zones/              objects processing specific zones in a page


If you want to create other modules later, use @@module:create@@ command with the @@F@dev.php@@ script:

<code bash>
php dev.php module:create cms
</code>

It will create a module named "cms".


===== First display =====

We need of course a web server to run our application. For the demo, let's
use the internal web server of PHP, which is very simple to configure.
Just execute:

<code bash>
cd example
php -S localhost:8080 -t www

</code>


You are now ready for prime. Your application is accessible at this URL: @@http://localhost:8080/@@.
Enter this URL in your browser. you should see:

{{:en:tutorials:minitutorial:start_page_en-1.6.png?500}}

If there are some error messages in the "installation check" section, fix them.

===== Implementing an action =====

Let's implement a default action. An action is a process which generates a page.
It is implemented as a method in a class called a "controller". A controller can
implement several actions.

Open @@F@example/modules/example/controllers/default.classic.php@@ file:

<code php>

class defaultCtrl extends jController {

   function index () {
       $rep = $this->getResponse('html');

       // this is a call for the 'welcome' zone after creating a new application
       // remove this line !
       $rep->body->assignZone('MAIN', 'jelix~check_install');

       return $rep;
   }
}
</code>

What this code means is that **index** action of **default** controller
retrieves a @@C@jResponseHtml@@ object through the @@M@getResponse()@@ method by
passing "html" as argument. After processing, the action returns this response
thus indicating that its content must be returned to the browser.


@@C@jResponseHtml@@ has a @@P@body@@ property, which is a @@C@jTpl@@ object.
jTpl is a template engine provided by Jelix.

In the action code above, you see a call to @@C@assignZone()@@ method. This
means : get the content of the 'check_install' zone which is stored in the
'jelix' module, and assign this content to the template variable named
@@V@MAIN@@ (You will see what is a zone in details later). 'Check_install' is a
zone which shows results of install checkings. If those results are ok, you
don't need it anymore. delete this line so you will have this in your
controller:

<code php>

class defaultCtrl extends jController {

   function index () {
       $rep = $this->getResponse('html');

       return $rep;
   }
}
</code>

==== Response object ====

A @@C@jResponseHtml@@ object generates an HTML response (an HTML page). It
automatically generates the @@<head>@@ part of HTML, from some of its
properties.

Let's define the title of the page. Add this in the @@M@index()@@ method, just
before returning the response object:

<code php>
   $rep->title = 'Hello World !';
</code>

Reload the page. The page title should now display accordingly in your browser
title bar. But still your page contains this:

{{en:tutorials:minitutorial:minituto_en-1.6-1.png?500}}

How is this possible whereas we don't define any content in our controller?

We have seen before that @@M@getResponse('html')@@ returns a @@C@jResponseHtml@@
object. However, it could return another object for the "html" type. It could be
an instance of a class inheriting from @@C@jResponseHtml@@ and which set common
things for all 'html' actions. Think about defining common CSS style sheets and
JS scripts, your application main template etc. This  class is very useful as
you don't need to repeat this settings through all your actions. And because
this is very useful, the @@create-jelix-app@@ command creates such a class and a
default template. it is stored in the @@F@responses/@@ directory of your
application, and is declared in the configuration file.

Let's see the content of @@F@example/responses/myHtmlResponse.class.php@@
created by @@create-jelix-app@@:

<code php>
require_once (JELIX_LIB_CORE_PATH.'response/jResponseHtml.class.php');

class myHtmlResponse extends jResponseHtml {

    public $bodyTpl = 'example~main';

    function __construct() {
        parent::__construct();

        // Include your common CSS and JS files here
    }

    protected function doAfterActions() {
        // Include all process in common for all actions, like the settings of the
        // main template, the settings of the response etc..

        $this->body->assignIfNone('MAIN','<p>no content</p>');
    }
}
</code>

This "customized" response assigns to its @@P@bodyTpl@@ member the default
template which will be used to generate the @@<body>@@ content of all pages :
"example~main". This is the @@F@main.tpl@@ file in the example module.
"example~main" is called a selector. A
[[http://docs.jelix.org/en/manual-1.8/selectors|Jelix selector]] is a shortcut
to refer to a resource of a module. Here is the content of
@@F@example/module/example/templates/main.tpl@@:

<code html>
   <h1 class="apptitle">Title for example<br/><span class="welcome">{@jelix~jelix.newapp.h1@}</span></h1>
   {$MAIN}
</code>

@@{$MAIN}@@ is an instruction which says: display the content of the template
variable named @@V@MAIN@@. //{@jelix~jelix.newapp.h1@}// is an instruction which
says: display the localized string (a string which value depends on the lang)
identified by the "jelix.newapp.h1" key and stored in the "jelix" module.

@@M@doAfterActions@@ method is called after each action. In the example, it
assigns @@"<p>no content</p>"@@ to the MAIN template variable if this variable
doesn't exist yet  (so, if it is not set by the action).

Now you know why there is a content displaying on the start page. Now let's
modify the template with this content:

<code html>
<h1 class="apptitle">My web site</h1>

<div id="page">
{$MAIN}
</div>
</code>

And in the constructor of the @@M@doAfterActions@@ method, we add an instruction
to setup a CSS style sheet:

<code php>
require_once (JELIX_LIB_CORE_PATH.'response/jResponseHtml.class.php');
 
class myHtmlResponse extends jResponseHtml {
 
    public $bodyTpl = 'example~main';
 
    function __construct() {
        parent::__construct();
        $this->addCSSLink(jApp::urlJelixWWWPath().'design/jelix.css');
        // Include your common CSS and JS files here
    }
 
    protected function doAfterActions() {
        // Include all process in common for all actions, like the settings of the
        // main template, the settings of the response etc..
 
        $this->body->assignIfNone('MAIN','<p>no content</p>');
    }
}
</code>

Now you see:

{{:en:tutorials:minitutorial:minituto_en-1.6-2.png?500|}}

==== Your first content ====

Let's define the content of our start page (in @@F@example/modules/example/controllers/default.classic.php@@):

<code php>
class defaultCtrl extends jController {

   function index () {
      $rep = $this->getResponse('html');
      $rep->title = 'Hello World !';
      
      $rep->body->assign('MAIN',"<p>Hello !</p>");
    
      return $rep;
   }
}
</code>

So here, we put "<p>Hello !</p>" in the "MAIN" template variable. We now see:

{{:en:tutorials:minitutorial:minituto_en-1.6-3.png?500|}}


==== Template of an action ====

It should be more practical to put the content in a new template, dedicated to
your action, for example in @@F@example/modules/example/templates/hello.tpl@@.
So we have two templates: @@F@main.tpl@@ which contains the main structure of
the web site, and @@F@hello.tpl@@ which is specific to the action.

Let's create the @@F@hello.tpl@@ in the templates directory:

<code xml>
<div class="monbloc">
<h2>Message</h2>

<div class="blockcontent">Hello {$name} !</div>
</div>
</code>

@@"{$name}"@@ is a variable template. Now modify the controller:

<code php>
   function index () {
      $rep = $this->getResponse('html');
      $rep->title = 'Hello World !';

      $tpl = new jTpl();
      $tpl->assign('name','Me');
      $rep->body->assign('MAIN', $tpl->fetch('hello'));
    
      return $rep;
   }
</code>


Notice the use of the @@$tpl@@ object. The "fetch" method generate the content
of the given template. The 'hello' string is a selector of course.

You see now:

{{:en:tutorials:minitutorial:minituto_en-1.6-4.png?500|}}

===== Retrieving parameters =====

It would be interesting to be able to indicate the name to display in the
template, as a parameter of the url. We get a parameter value with @@M@param()@@
method:

<code php>
   $name = $this->param('name');
   $tpl->assign('name', $name);
</code>

Now type:
    http://localhost:8080/index.php?name=Max

You will see:

{{:en:tutorials:minitutorial:minituto_en-1.6-5.png?500|}}


===== URLs =====

To execute a specific action, you should add in the url the module name, the
controller name, and the method name of the action. For our example, we can
type:

   http://localhost:8080/index.php/example/default/index

In our example, this action has been mapped to the url @@/@@ into  @@F@exemple/app/system/urls.xml@@,
like this:

<code xml>
   <url pathinfo="/" module="exemple" action="default:index">
   </url>
</code>

This is why the url @@http://localhost:8080/@@ displays our page.

You can custom the url of any action in this urls.xml.

===== Conclusion =====


This were the first concepts of Jelix. You can continue to discover it by
following [[en:tutorials|other tutorials]].

-----
   * Go back to the [[en:documentation|documentation]]
   * Continue to discover Jelix with [[en:tutorials|an other tutorial]]
en/tutorials/minitutorial/1.8.x.txt · Last modified: 2023/04/12 16:14 by laurent