Basic informations

Tutorial (First steps)

Now, we will move through 5 basic steps to create simple web page. It will be the under-construction page with possibility to add your email for receiving news.

Before start, make sure you have set public/ as root directory on your virtual server.

1. Creating model schema

Firstly, we will need a database, where we will store email addresses from visitors. We will store email and date of submition. Schema will be looking like this:


<?php
class SubmitSchema extends DBSchema{
  protected $create=true; //we want execute create and drop table
  
  function create(){
    //setting attributes of table
    $this->primary('id')
    ->string('email', 60)
    ->date('addDate')
    ->createTable() // creating
  }
}
?>

Now we need to create it. Firstly, look in config/config.php and set your database connection info on the bottom of the file. Afther this open file application/start.php and uncomment part starting with define(.... Then open index page. Table in database will be created. After this, comment it back and in schema file set variable $create to false, which will grant not to create table next time.

2. Model creation

Now we are ready to create model, which will work with database. We want to define id as 0, which is default value when auto inceremnting ID and also set date of adding email. We also would like to change stored date to more user friendly format.

<?php
//class can be empty, if you didnt need some additional methods
//or change existing ones
class Submit extends Model{

  //override create method in SQLQuery with adding some actions
  static function create($data){
    //prepare data
    $data['id']=0;
    $data['addDate']=date('Y-m-d');
   
    //call original method
    return parent::create($data);
  }

  //create new method to get user friendly formated date
  public function getDate(){
    //convert stored date of Submit object to another format and return it
    return DateTimes::convertDate($this->addDate);
  }
}
?>

Now, we are done with data flow between controller and database. Lets have a look to the next step.

3. Preparing HTML template

Creating HTML code also supports some additional framework statements to speed up and simplify the work. There are:

{{$var}} - print the var, where var can be $variable, $array.key or method call or class attribute. PHP functions or statements are not supported.
@block(nameOfBlock) text... @endblock - creates a block of HTML, which can be show by these directives:
- @show(nameOfBlock) - shows block
- @showIfSet(nameOfBlock, var) - shows block if var is set
- @showIfNSet(nameOfBlock, var) - negation of showIfSet
- @showIfTrue(nameOfBlock, var) - shows if var is true
- @showIfFalse(nameOfBlock, var) - similarly...
- @showIfEquals(nameOfBlock, var1, var2) - check if var1 == var2 and if yes, shows block
- @showEach(nameOfBlock, $data) - where $data is array of items, which will be one by one saved in $each variable and shown in block.
Strings can be concatenate with + sign.

Now we would like to create simple home Under-construction page with some text and form for submitting email address. We will start with header shown for every page, which has not another header file in subdirectory:


<html>
<head>
  <title>Under construction</title>
</head>
<body>

and similarly footer file:


<p>This site is running on {{HTML::link("chameleon.ako-na.sk", "Chameleon framework", NULL, true)}}.</p>
</body>
</html>

Now, we are done with header and footer. Now we will create mine content of index page in home direcotory:


@block(addOk)
<p>Your email was submited successfully</p>
<hr/>
@endblock

@block(addError)
<p>Your email cannot be submitted. Please correct these errors:</p>
{{HTML::ul($errors)}}
<hr/>
@endblock

<h1>Under construction</h1>
<p>Welcome to my first page in Chameleon template.</p>
<p>Please subscribe for news in form below:</p>
@showIfTrue(addOk, $submitState)
@showIfSet(addError, $errors)
{{Form::create('home/submit', $data, 'send')->get()}}

Its all we will need for client-side web page. Now, we have to look on joining it all together.

4. Joining parts together in controller

This last step shows, hove to join all - model and template in controller. When visitor open out page www.something.com/, framework resolves it without parameters like www.something.com/home/index/. Home represent page and identify controller, which will be called. Index represent action in controller, which will be executed. After this, there can be other values, which will be passed to controller action handle as parameters.

We will implement 2 actions in our controller. First for home page and second for work out subscribe form:

<?php
class HomeController extends Controller{
  //method is called before every action
  function beforeAction(){
    $formData=array('email'); //prepare form data
    
    $this->mainView()
    ->set('data', $formData); //pass variable $formData as $data to template
  }

  //index action handle
  function action_index(){
    
    return $this->mainView(); //return template to render
  }

  //handle of email submit in form
  function action_submit(){
    //first check, if is form really submitted
    if (Input::present()){
      //prepare rules for validation of imput
      $rules=array('email' => 'required|email');

      //create validation object
      $validate=new Validator(Input::getAll(), $rules);

      //execute validation and store result
      $state=$validate->check();
      if ($state){ //if OK
        //save email
        $newSubmit=Submit::create(Input::getAll());
        $newSubmit->save();

        $this->mainView()
        ->set('submitState', true); //inform template about state
      }else{ //if input was wrong, just inform about errors
        $this->mainView()
        ->set('submitState', false)
        ->set('errors', $validate->getErrors());
      }

      //before return, change template to show index
      //cos we wont show home/submit.php template / dont exists
      return $this->mainView()
      ->changeTemplate('home@index');
    }
  }
}
?>

5. Adding language package

Now we are done with whole site. Just open it and you will see results. But there is still some work to do. Form and other structures are using text packages to print text. For example, if you want show send in slovak language, you need to create default slovak language package:

<?php
$texts=array(
  'send' => 'Odoslať',
);
?>