tar xzf jelix-1.5.x-dev.tar.gz
After this, you have a directory @@F@jelix-1.5.x-dev/lib/@@ in which you'll find all libraries used by jelix, and jelix itself.
For the purpose of this tutorial, rename the jelix-1.5.x-dev folder to jelix and move it in a directory of your web site. So that it will be accessible with a browser, at this URL for example: @@http://localhost/jelix/@@.
===== Jelix scripts =====
A script for command line, @@F@createapp.php@@, is available in the @@F@lib/jelix-scripts/@@ directory. This script allows you to create quickly an application. Open a console and go into this directory :
cd jelix/lib/jelix-scripts/ # under linux
To invoke the command, run the script @@createapp.php@@ with the php binary (php.exe under windows), and give it the path of the new application
php createapp.php path/to/the/new/application
After creating the application, you will saw a @@cmd.php@@ script into it, which will allow to execute other commands on your application.
===== Application creation =====
Let's create the tree structure of your application using @@createapp@@ command. Suppose your application will be named "example":
php createapp.php ../../example
As a result, you'll get an @@F@example/@@ directory, at the same level as the @@F@lib/@@ directory. Its content will be :
example/
application.init.php the file to initialize the jelix environment and the application
cmd.php the script to launch some commands to develop
modules/ the modules of your application
plugins/ the plugins of your application
var/config/ the configuration files of your application
var/log/ the log files
var/themes/ the different possible themes in your application
var/overloads/ will contain the different files that you will redefine, from modules.
www/ the root of the site
An other directory @@F@temp/example/@@ is created. It contains all cache and temporary file generated by jelix.
===== 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 @@createapp@@ command.
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 @@createmodule@@ command with the @@F@cmd.php@@ script:
php cmd.php createmodule cms
It will create a module named "cms".
===== First display =====
Before displaying the start page of your new application, you have to be sure your web server has write access to directories @@F@temp/example@@ and @@F@example/var/log@@ :
For example, on linux (ubuntu or debian) :
sudo chown www-data:www-data ../../temp/example ../../example/var/log
sudo chmod 755 ../../temp/example ../../example/var/log
You are now ready for prime. Your application is accessible at this URL: @@http://localhost/jelix/example/www/@@. Enter this URL in your browser. you should see:
{{en:tutorials:minitutorial:start_page_white_en.png}}
Noticed this message saying that a CSS file is missing ? Copy the @@F@jelix/lib/jelix-www@@ directory into @@F@jelix/example/www@@ by renaming it to "jelix" (on a dedicated apache server, it is better to create an alias). This directory is important because it contains some files needed by jForms or other components.
Now you should see:
{{:en:tutorials:minitutorial:start_page_en-1.5.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:
/**
* @package example
* @subpackage example
* @author yourname
* @copyright 2013 yourname
* @link http://www.yourwebsite.undefined
* @license All right reserved
*/
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;
}
}
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:
class defaultCtrl extends jController {
/**
*
*/
function index () {
$rep = $this->getResponse('html');
return $rep;
}
}
==== Response object ====
a @@C@jResponseHtml@@ object generates an HTML response (an HTML page). It automatically generates the @@@@ 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:
$rep->title = 'Hello World !';
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_1_en.png}}
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 @@createapp@@ 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 @@createapp@@:
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','no content
');
}
}
This "customized" response assigns to its @@P@bodyTpl@@ member the default template which will be used to generate the @@@@ 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.5/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@@:
Title for example
{@jelix~jelix.newapp.h1@}
{$MAIN}
@@{$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 @@"no content
"@@ 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:
My web site
{$MAIN}
And in the constructor of the @@M@doAfterActions@@ method, we add an instruction to setup a CSS style sheet:
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::config()->urlengine['jelixWWWPath'].'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','no content
');
}
}
Now you see:
{{:en:tutorials:minitutorial:minituto_2_en-1.5.png|}}
==== Your first content ====
Let's define the content of our start page (in @@F@example/modules/example/controllers/default.classic.php@@):
class defaultCtrl extends jController {
function index () {
$rep = $this->getResponse('html');
$rep->title = 'Hello World !';
$rep->body->assign('MAIN',"Hello !
");
return $rep;
}
}
So here, we put "Hello !
" in the "MAIN" template variable. We now see: {{:en:tutorials:minitutorial:minituto_3_en-1.5.png|}} ==== 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 specific to the action. Let's create the @@F@hello.tpl@@ in the templates directory:
Message
Hello {$name} !
@@"{$name}"@@ is a variable template. Now modify the controller:
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;
}
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_4_en-1.5.png|}}
===== 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:
$name = $this->param('name');
$tpl->assign('name', $name);
Now type:
http://localhost/jelix/example/www/index.php?name=Max
You will see:
{{:en:tutorials:minitutorial:minituto_5_en-1.5.png|}}
===== 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/jelix/example/www/index.php/example/default/index
(If it doesn't work, verify that your server is configured to accept pathinfo).
In our example, the url indicates the default action of the application. which is specified in the @@F@example/var/config/index/config.ini.php@@ file, in @@V@startModule@@ and @@V@startAction@@ options:
startModule="example"
startAction="default:index"
You can change it later if you want.
You can also define your own URL by using an other URL engine provided by Jelix. And finally, you can change the "DocumentRoot" of the web site and to set it to the @@F@jelix/exemple/www@@ directory, or move the content of the @@F@example/www@@ to the root of your web site.
===== Conclusion =====
This were the first concepts of Jelix. You can continue to discover it by following the [[en:tutorials:main|main tutorial]].
-----
* Go back to the [[en:documentation|documentation]]
* Continue to discover Jelix with the [[en:tutorials:main|main tutorial]]