| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| en:tutorials:minitutorial:1.1.x [2009/01/03 08:36] – goofy | en:tutorials:minitutorial:1.1.x [2012/04/15 08:36] (current) – laurent |
|---|
| ====== Mini Tutorial ====== | ====== Mini Tutorial ====== |
| |
| The goal of this tutorial is to quickly show you how you can develop an application with Jelix 1.1. | The goal of this tutorial is to quickly show how you can develop an application with Jelix 1.1. |
| |
| |
| ===== Download and installation ===== | ===== Download and installation ===== |
| |
| First, [[en:download:stable:1.1#developer-edition|download the "developer" edition of Jelix]]. Jelix needs at least PHP 5.2. | First, [[en:download:stable:1.1#developer-edition|download the "developer" edition of Jelix]]. Jelix requires at least PHP 5.2 (See [[http://docs.jelix.org/en/manual-1.1/installation/requirements|here a detailed list of requirements]]) |
| |
| Unarchive then the file you have downloaded, with your uncompress software. For example, with tar: | Then, unpack the archive file you have downloaded, with your archiver software companion. For example, with tar: |
| |
| <code bash> | <code bash> |
| </code> | </code> |
| |
| After this, you have a directory @@F@jelix-1.1/lib/@@ in which there are all libraries used by jelix, and jelix itself. | After this, you have a directory @@F@jelix-1.1/lib/@@ in which you'll find all libraries used by jelix, and jelix itself. |
| |
| For this tutorial, move the jelix-1.1 directory in the directory of your web site, so it will be accessible with a browser, at this URL for example: @@http://localhost/jelix-1.1/@@. (You can rename @@F@jelix-1.1/@@ as you wish). | For the purpose of this tutorial, move jelix-1.1 folder in a directory of your web site. So that it will be accessible with a browser, at this URL for example: @@http://localhost/jelix-1.1/@@ (You can rename @@F@jelix-1.1/@@ as you wish). |
| |
| ===== Jelix scripts ===== | ===== Jelix scripts ===== |
| |
| A script for command line, @@F@jelix.php@@, is available in the @@F@lib/jelix-scripts/@@ directory. This script allows you to create quickly some different files for your application. So open a console and go into this directory : | A script for command line, @@F@jelix.php@@, is available in the @@F@lib/jelix-scripts/@@ directory. This script allows you to create quickly different files of your application. Open a console and go into this directory : |
| |
| <code bash> | <code bash> |
| </code> | </code> |
| |
| You have to use @@F@jelix.php@@ with the command line version of PHP and give it as parameter a Jelix command with some other parameters and options. | You have to use @@F@jelix.php@@ with the command line version of PHP. this script requires, as parameter, a Jelix command. Each command defines a number of required parameters and options. |
| |
| | To invoke a command : |
| <code bash> | <code bash> |
| php jelix.php --application_name command_name [options] [parameters] | php jelix.php --application_name command_name [options] [parameters] |
| | </code> |
| | |
| | To invoke help: |
| | <code bash> |
| | php jelix.php help // generic help, lists all commands available |
| | php jelix.php help command_name // specific command help |
| </code> | </code> |
| |
| |
| ===== Creation of an application ===== | ===== Application creation ===== |
| |
| Let's create the tree structure of the application using the @@createapp@@ command. Our application will be named "example": | Let's create the tree structure of your application using @@createapp@@ command. Suppose your application will be named "example": |
| |
| <code bash> | <code bash> |
| </code> | </code> |
| |
| You will then get a @@F@example/@@ directory, at the same level as the @@F@lib/@@ directory. Its content is the following : | As a result, you'll get an @@F@example/@@ directory, at the same level as the @@F@lib/@@ directory. Its content wil be : |
| |
| example/ | example/ |
| |
| |
| ===== Creation of a module ===== | ===== Module creation ===== |
| |
| A module gathers a whole of actions. At least one is necessary in an application. This is why a module is created automatically when you run @@createapp@@ command. | 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: | Here is the directory which has been created: |
| |
| |
| If you want to create other modules later, you can use the @@createmodule@@ command: | If you want to create other modules later, use @@createmodule@@ command : |
| |
| <code bash> | <code bash> |
| ===== First display ===== | ===== First display ===== |
| |
| Before to display the start page of your new application, you should put write access on some directories for the web server. This directories are @@F@temp/example@@ and @@F@example/var/log@@ : | 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) : | For example, on linux (ubuntu or debian) : |
| </code> | </code> |
| |
| We are now ready to display the page. Your application is accessible at this URL: @@http://localhost/jelix-1.1/example/www/@@. Enter this URL in your browser. you should see: | You are now ready for prime. Your application is accessible at this URL: @@http://localhost/jelix-1.1/example/www/@@. Enter this URL in your browser. you should see: |
| |
| {{en:tutorials:minitutorial:start_page_white_en.png}} | {{en:tutorials:minitutorial:start_page_white_en.png}} |
| |
| You notice this message saying that a CSS file is missing. Copy the @@F@jelix-1.1/lib/jelix-www@@ directory in @@F@jelix-1.1/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. | Noticed this message saying that a CSS file is missing ? Copy the @@F@jelix-1.1/lib/jelix-www@@ directory into @@F@jelix-1.1/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: | Now you should see: |
| ===== Implementing an action ===== | ===== 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", and a controller can implement several actions. Open the @@F@example/modules/example/controllers/default.classic.php@@ file: | 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> | <code php> |
| </code> | </code> |
| |
| We state here that we retrieve a @@C@jResponseHtml@@ object throw the @@M@getResponse()@@ method because of the "html" type as it is indicated. Then we return it to indicate that its content must be returned to the browser. | 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 controller, you see that the @@C@assignZone()@@ method is called. It says: get the content of the 'check_install' zone which is stored in the 'jelix' module, and put this content into the template variable named @@V@MAIN@@. You will see what is a zone later. 'Check_install' zone is a zone which show the main content of the start page. As we don't need it anymore, delete this line so you will have this in your controller: | @@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> | <code php> |
| ==== Response object ==== | ==== Response object ==== |
| |
| The @@C@jResponseHtml@@ object generates a HTML response (a HTML page). It generates automatically 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, before the return: | 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> | <code php> |
| </code> | </code> |
| |
| Reload the page. The title of the page is now display in your browser title bar. But the page contains this: | 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}} | {{en:tutorials:minitutorial:minituto_1_en.png}} |
| |
| How is this possible although we don't have anything in our controller ? | How is this possible whereas we don't define any content in our controller ? |
| |
| We saw that @@M@getResponse('html')@@ returns a @@C@jResponseHtml@@ object. However, it is possible to return an other object for the "html" type. It can be an other object which inherits from @@C@jResponseHtml@@, and which set things which are common for all actions. For example: CSS style sheets, the main template etc. This is very useful because you don't need to repeat this settings in your actions. And because this is very useful, the @@createapp@@ command creates a such class and a default template. This sort of classes are stored in the @@F@responses/@@ directory of the application, and are declared in the configuration file. | 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@@: | Let's see the content of @@F@example/responses/myHtmlResponse.class.php@@ created by @@createapp@@: |
| class myHtmlResponse extends jResponseHtml { | class myHtmlResponse extends jResponseHtml { |
| |
| public $bodyTpl = 'exemple~main'; | public $bodyTpl = 'example~main'; |
| |
| protected function doAfterActions() { | protected function doAfterActions() { |
| </code> | </code> |
| |
| This "customized" response set up in @@P@bodyTpl@@ the default template which will be used to generate the @@<body>@@ content of all pages : "exemple~main". This is the @@F@main.tpl@@ file in the example module. "exemple~main" is called a selector. A [[en:manual-1.1:selectors|Jelix selector]] is a shortcut to refer to a resource of a module. Here is the content of this template: | 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.1/selectors|Jelix selector]] is a shortcut to refer to a resource of a module. Here is the content of main.tpl: |
| |
| <code html> | <code html> |
| <h1 class="apptitle">example<br/><span class="welcome">{@jelix~jelix.newapp.h1@}</span></h1> | <h1 class="apptitle">Title for example<br/><span class="welcome">{@jelix~jelix.newapp.h1@}</span></h1> |
| {$MAIN} | {$MAIN} |
| </code> | </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. | @@{$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. |
| |
| The method @@M@doAfterActions@@ 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). | @@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: | Now you know why there is a content displaying on the start page. Now let's modify the template with this content: |
