Get started with PW Mvc Module By Harmster

[Harmster]

Introduction

Dear community.

As some of you may know I've been busy creating a MVC Module for Processwire. I've finished quite a bit of it and I am now ready for a tutorial on a quick website to get you started!

For this tutorial I am using a clean install of Processwire 2.3 and my Module 0.2.4

Get the module at Github http://github.com/hawiak/mvcmodule

.

Main focus of the module is to split logic from design without losing the flexibility of Processwire we all fell in love with.

Alright lets get started.

Installation

Once you have the module downloaded we are going to install it, we need the MvcModule folder in the /site/modules folder. 

And we need the AppController in the /site/templates folder (You can find the AppController in the /site/templates folder)

Once you've put the folder in there we are going to install the module, check for new modules and you'll see MvcModule

Click on it and hit install to install the module.

Once you've installed the module you'll see some configure settings and you'll notice a new tab on your admin.

But click submit, dont forget this or all the paths WONT WORK!

Setting up your home controller

Ok we are ready to set up our first controller. To easily set up your template to enable MVC we are going to the MVC tab in your navbar.

You'll notice a button saying " Create controller"

Click on "Create controller"  and for this tutorial we are going to use the home template, select the home and click "Create".

If everything is correct you will see this:

 Now we are done in the process side of it and we'll get into the coding.

Get your favourite code editor open and lets create our controller. Open the /site/templates/home.php file in your editor.

Remove the code thats in there completely. And save it.

For the module to work with the template file we need to create a class called HomeController and extend AppController.

like so:

<?php
class HomeController extends AppController{

}

Creating Views and layouts

If you go to your websites homepage you'll see something along the lines of:

 

Fatal error: Exception: Error encountered Method index not found in HomeController for index in controller HomeController (in C:\xamp\htdocs\pwmvc\site\modules\MvcModule\Error.class line 6) #0 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(426): MvcError->show('Method index no...', 'index', Object(HomeController)) #1 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(354): MvcModule->render() #2 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(293): MvcModule->create_mvc(Object(HookEvent)) #3 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(229): Wire->runHooks('render', Array) #4 C:\xamp\htdocs\pwmvc\wire\modules\PageRender.module(250): Wire->__call('render', Array) #5 C:\xamp\htdocs\pwmvc\wire\modules\PageRender.module(250): TemplateFile->render() #6 [internal function]: PageRender->___renderPage(Object(HookEvent)) #7 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(271): call_user_func_array(Array, Array) #8 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(229): Wire->runHooks('renderPage', Array) #9 C:\xamp\htdocs\pwmvc\wire\co in C:\xamp\htdocs\pwmvc\index.php on line 214

This error message was shown because site is in debug mode ($config->debug = true; in /site/config.php). Error has been logged.

Thats because by default you will need an Index method, a home method for your controller, so lets create one!

<?php
class HomeController extends AppController{
    public function index(){

    }
}

Lets try it again!

Oops...

 

Fatal error: Exception: Error encountered View C:/xamp/htdocs/pwmvc//site/templates/Home/index.tmpl not found! for index in controller HomeController (in C:\xamp\htdocs\pwmvc\site\modules\MvcModule\Error.class line 6) #0 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(481): MvcError->show('View C:/xamp...', 'index', Object(HomeController)) #1 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(424): MvcModule->render_view() #2 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(354): MvcModule->render() #3 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(293): MvcModule->create_mvc(Object(HookEvent)) #4 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(229): Wire->runHooks('render', Array) #5 C:\xamp\htdocs\pwmvc\wire\modules\PageRender.module(250): Wire->__call('render', Array) #6 C:\xamp\htdocs\pwmvc\wire\modules\PageRender.module(250): TemplateFile->render() #7 [internal function]: PageRender->___renderPage(Object(HookEvent)) #8 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(271): call_user_func_array(A in C:\xamp\htdocs\pwmvc\index.php on line 214

This error message was shown because site is in debug mode ($config->debug = true; in /site/config.php). Error has been logged.

Well it seems like we're missing a view, so lets create the view, we first need to create a folder with called Home (the same as the controller name but start with capital)

And in that folder we'll create a file called index.tmpl

Now of you run it you'll see that you are not quite done yet you'll see something like this:

Fatal error: Exception: Error encountered Layout not found for index in controller HomeController (in C:\xamp\htdocs\pwmvc\site\modules\MvcModule\Error.class line 6) #0 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(431): MvcError->show('Layout not foun...', 'index', Object(HomeController)) #1 C:\xamp\htdocs\pwmvc\site\modules\MvcModule\MvcModule.module(354): MvcModule->render() #2 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(293): MvcModule->create_mvc(Object(HookEvent)) #3 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(229): Wire->runHooks('render', Array) #4 C:\xamp\htdocs\pwmvc\wire\modules\PageRender.module(250): Wire->__call('render', Array) #5 C:\xamp\htdocs\pwmvc\wire\modules\PageRender.module(250): TemplateFile->render() #6 [internal function]: PageRender->___renderPage(Object(HookEvent)) #7 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(271): call_user_func_array(Array, Array) #8 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(229): Wire->runHooks('renderPage', Array) #9 C:\xamp\htdocs\pwmvc\wire\core\Wire.php(293): Wire->_ in C:\xamp\htdocs\pwmvc\index.php on line 214

This error message was shown because site is in debug mode ($config->debug = true; in /site/config.php). Error has been logged.

 

 

I promise after we create the layout we are done.

 

So lets create a folder called layouts and a file called layout.php in there.

 

Displaying data

 

Now we're done with the setup and we can start coding, lets say you want to get the content fromt he field body on your page displayed? 

Well thats easy put this in your index method.

$this->set('body', $this->page->body); 

What this does is that it sets a variable in the view we can use called body so all we need to do to display this is go to our view.

And add 

{{body}}

 to the view.

Now go and refresh your page! oh wait... nothing shows up...?

Oh yes we use Twig template engine we need to add this to our layout.php

{% block view %}
{% endblock %} 

(Yes yes I know its complicated for just a simple task but trust me you'll love it later!)

Refresh your page and check it out!

You'll see that the text is displaying but the markup isn't really working, we need to use the |raw extension in order to make this work, so change the index.tmpl content to this

{{ body|raw }}

 

Use |raw for all the HTML markup, always. 

Styles, scripts and snippets

Now this is quite boring, I know but lets start doing some interesting stuff, lets implement Bootstrap!

go and download bootstrap at getbootstrap.com  

Once you've downloaded create a folder in /site/templates called "assets" the dist copy the bootstrap.min.css out of /dist/css to /site/templates/assets/styles and /dist/js/bootstrap.min.js to /site/templates/assets/scripts/

Now we want to use this, MvcModule has some great options for this!

Change your HomeController to this

<?php
class HomeController extends AppController{
   public $scripts = array(
      '1' => 'bootstrap.min.js');
   public $styles = array(
      '1' => 'bootstrap.min.css');

   public function index(){
      $this->set('body', $this->page->body);
   }
}

Now go over to your layout and change the contents of your layout to this:

<head>
   {{ this.render_headers()|raw }}
</head>
{% block view %}
{% endblock %}

You'll now see your style (If not try going to the MvcModule configure settings and remove the first / from /site/templates/assets)

Now we forgot to include JQuery, so lets  download jquery at jquery.com 

We need to put that in the /site/templates/assets/scripts 

And we need to put it in the array, you can just do that as follow:

public $scripts = array(
   '2' => 'bootstrap.min.js',
   '1' => 'jquery.min.js');

The number in this array indecates the order on which the scripts will be loaded.

Now you should see something like this!

Now lets create a navbar with all the pages using the bootstrap navbar component.

To do this we will create a snippet

create a folder called snippets in /site/templates and a file called navbar.php

Lets first create a variable with all the pages in the index method

$this->set('menu', $this->pages->find('/'));

Lets now create our snippet, lets just create this first in our snippet navbar.php

<nav class="navbar navbar-default" role="navigation">
  <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
    <ul class="nav navbar-nav">
       <li class="active"><a href="#">Link</a></li>
      </ul>
  </div>
</nav>

We need to tell the controller to use this snippet we do that by using an array. Change your controller to the following:

<?php
class HomeController extends AppController{
   public $scripts = array(
      '2' => 'bootstrap.min.js',
      '1' => 'jquery.min.js');
   public $styles = array(
      '1' => 'bootstrap.min.css');
   public $snippets = array(
      'navbar' => 'navbar.php');

   public function index(){
       $this->set('body', $this->page->body);
       $this->set('menu', $this->pages->find('/'));
   }
}

And change your layout to this:

<head>
	{{ this.render_headers()|raw }}
</head>
{% block navbar %}
{% endblock %}
{% block view %}
{% endblock %}

You see that I created a block here and called in Navbar. The snippets content (that we assigned to navbar => file_name) will be put in this block!

So lets now use our variables and the Twig template engine to the fullest!

Change the navbar.php snippet to:

<nav class="navbar navbar-default" role="navigation">
  <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
    <ul class="nav navbar-nav">
    {% for item in menu %}
  	 <li class=""><a href="{{ item.url }}">{{ item.title }}</a></li>
    {% endfor %}
  	</ul>
  </div>
</nav>

You see we use a for loop here and use the PageArray menu here and generate the menu here.

You can use the variables in the view as well. 

Setting a title

Lets set a title, this is fairly easy, lets define a variable in our controller that will be the same for every view in this controller

public $title = "Home controller"; 

Now go to your layout.php and do add this to the head:

<title>{%block title %}{% endblock %} {{ this.controller.title }}</title>

Now as you can see we created a block, what this allows us to do is create the same block in the view like this:

{% block title %}Index{% endblock %}

And you will see that your title is "Index Home controller".

This is because the title block replaced the title block in the layout file.

Views

Inside views you still have access to processwire objects and even to the MvcModule as you've seen with render_headers().

The view template used is Twig, check out more here http://twig.sensiolabs.org/doc/templates.html

This is a basic setup for a website with MvcModule. I will extend this tutorial and update it whenever needed!