VueJS & neoan3: a love story.

originally posted on blua.blue

play tutorial video

To stay aligned with the video, we will call our app & project-folder "video" and our frame "vuePhp"

What is the challenge?

I noticed that division between front- & back-end, packaging tools like webpack as well as containerized delivery has created many over-engineered solutions to the basic development flow of applications. As a full-stack developer, I often develop the front- and back-end simultaneously while requiring to serve resources

• dynamic
• selective (don't want a particular view/endpoint to load unused components)
• fast
• without additional development servers, build processes etc.

Manipulating the way neoan3 serves files

Whether it be the serve.file endpoint, the autoloader or the conditional rendering: neoan3 doesn't seem to be set up to work nicely with VueJS. But then there is the layer of the frames that let's us easily alter the very way the core executes the rendering process. What we will do is combining the cli-tool's built-in capability to use templates with combined with the extensibility of core functionality provided by a neoan3 frame.

In order to do this we will

1. create a new neoan3 app
2. create a new neoan3 frame
3. create cli-templates

1. create a new neoan3 app

If you haven't already, please install the cli globally (npm i -g neoan3-cli). Then, after navigating to a new folder in our localhost (optional, you can also use neoan3's server.php to run the app), we create a new project using our terminal:

neoan3 new app video

2. create a new neoan3 frame

After running neoan3 new frame vuePhp, we want to extend the constructor and the output of the core:

<?php
/* Generated by neoan3-cli */

namespace Neoan3\Frame;

use Neoan3\Core\Serve;

class VuePhp extends Serve
{
    function __construct(){
        parent::__construct();
    }
    function output($params = []){
        parent::output($params);
    }
}

After installing vue (npm i vue), we want to include the framework. The file "vue/dist/vue.js" includes vue's development tools while the file "vue/dist/vue.min.js" does not. So what we want to do is to include the development environment when we are serving via localhost:

if($_SERVER['HTTP_HOST'] == 'localhost'){
        $this->includeJs(base . 'node_modules/vue/dist/vue.js');
} else {
        $this->includeJs(base . 'node_modules/vue/dist/vue.min.js');
}

We can place this snippet in the constructor after calling the parent's constructor.

neoan3's default hooks for views are

• header
• main
• footer

What we want to achieve is to wrap the complete main container in a vue element and subsequently use components. To achieve that, we will directly write to the js stream of neoan3 and overwrite the main container in the output function before we execute the parent function:

$this->js .= 'new Vue({el:"#root"});';
$this->main = '<div id="root">' . $this->main . '</div>';

NOTE: there are cleaner solutions, but this "quick & dirty" hack is stable and reliable

Your complete frame should now look like this:

<?php
/* Generated by neoan3-cli */

namespace Neoan3\Frame;

use Neoan3\Core\Serve;

class VuePhp extends Serve
{
    function __construct()
    {
        parent::__construct();
        if($_SERVER['HTTP_HOST'] == 'localhost'){
            $this->includeJs(base . 'node_modules/vue/dist/vue.js');
        } else {
            $this->includeJs(base . 'node_modules/vue/dist/vue.min.js');
        }
    }
   
    function output($params = [])
    {
        $this->js .= 'new Vue({el:"#root"});';
        $this->main = '<div id="root">' . $this->main . '</div>';
        parent::output($params);
    }
}

What we are still missing is a nice way to integrate/load our custom vue components. We will set it up in a way that divides view (template) and js as we want to allow for dynamically changing the templates. Additionally, we will create the possibility to use component-based css (optional). To do so, we are going to provide routes with a new function called "vueComponents" to be placed in our frame:

function vueComponents($components, $params = []){
    // ensure that at least "base" is available
    $params['base'] = base;

    // iterate through provided component names
    foreach ($components as $component){
        $path = path . '/component/' . $component . '/' . $component  . '.ce.';

        // if template exists, write template to footer
        if(file_exists($path . $this->viewExt)){
            $this->footer .= '<template id="' . $component . '">' .
            $this->fileContent($path . $this->viewExt, $params) . '</template>';
        }

        // if js exists, write to js stream
        if(file_exists($path . 'js')){
            $this->js .= $this->fileContent($path . 'js', $params);
        }

        // if stylesheet exists, write to style stream 
        if(file_exists($path . $this->styleExt)){
            $this->style .= $this->fileContent($path . $this->styleExt, $params);
        }
    }
    return $this;
}

This is probable a little confusing. But our plan is to make custom elements vue components that we can load into endpoints with this function.

3. create cli-templates

The neoan3 cli-tool generates route components per default to be used with the Unicore. For our setup, we want to directly extend the frame rather than using the Unicore layer. Additionally, we want to have a handy boilerplate for our vue components. To achieve both, we will make use of the template capability of the cli tool. The cli tool respects such templates if they are defined in a folder "_template" in our neoan3 app. After creating this folder, we want to create 3 files:

• ce.html
• ce.js
• route.php

With the following content:

ce.html

<div>{{name}}</div>

ce.js

Vue.component('{{name}}', {
    template: document.querySelector('#{{name}}')
});

route.php

<?php

namespace Neoan3\Components;

use Neoan3\Frame\VuePhp;

class {{name}} extends VuePhp {

    private $loadedComponents = [];

    function init(){

        $this->hook('main', '{{name}}')
            ->vueComponents($this->loadedComponents)
            ->output();
    }
}

What does this do? From now on, whenever we create a new custom element it will generate our vue component boilerplate. And whenever we create a new route component it will generate our setup intended to use these components.

How to use

Let's try it out. We assume a new endpoint called "home":

neoan3 new component home and chose "route component" using our frame.

Now we generate a new vue component called "login":

neoan3 new component login and chose "custom element"

Next, we open up "component/home/Home.ctrl.php" and add "login" to the array $loadedComponents. (note: in case sensitive environments, please be aware that you additionally have to change the second parameter of "->hook" to start with a lower case letter).

Now we open "component/home/home.view.html" and write the tag "login"

<login></login>

Visiting the endpoint /home, you should now see the string "login". This is the content of "component/login/login.ce.html" which is used as a template by "component/login/login.ce.js": Hack away!