Introducing the Erdiko User Admin

Introducing the Erdiko User Admin Package! A user administration package built with an Erdiko powered backend and a Angular 2 frontend.

We’re excited to introduce the Erdiko User Admin! A modular package that provides an attractive UX to allow you to manage your users.

This is still very much a work in progress, but since we’re so excited, we want to let everyone know about this project (and request some help to keep us moving).

Check out our User Admin Project at this Github Repository and our Packagist entry.

Project Features

We wanted to create a modular and simple User Admin you can ‘bolt-on’ a new or existing project. We keep this as lean and mean as we could, but still providing some cool stuff to help get you started.

While this package is still very much in development, it does provide some of the following features:

  • A sortable and paginated list of user records.
  • An attractive user interface allowing the user to create, edit & delete user records
  • JWT user authentication!

Here’s some screenshots of our UX:

Installation and Setup

The User Admin package is a part of the Erdiko module ecosystem. Installable and upgradable via Composer. This makes it very simple to start a new project via this simple command.

composer create erdiko/user-admin [PROJECT NAME]

Please note that as of this time, we have not created an official release. You will need to include the minimum stability flag when you create your project:

composer create erdiko/user-admin [PROJECT NAME] --stability DEV

Package Dependencies

Here’s a brief list (and a bit of a plug) of some of the other Erdiko Packages we as a team have been developing that we use to build this project. While we use these packages for our development, we have planned to make these as modular and replaceable as we can.

Here’s the list:

  • erdiko/core
    • The base package that provides our basic routing and templating.
  • erdiko/authenticate
    • Authenticate the user’s credentials to assert they are who they say they are.
  • erdiko/authorize
    • A package that helps us enforce some user roles.
  • erdiko/users
    • Our Erdiko package that provides the backend storage and basic routes we use to interact with these models.

AngularJS 2

We utilize the great Angular CLI project to start and maintain the Angular code itself. This project was a great boon to help us get started on a well structured and maintainable Angular application.

The internal structure is “just” a simple app, but we have updated the NPM script to compile and move the resulting files to an directory accessible to the Erdiko application Home route.

NPM Run Scripts

Here is a quick list and an explanation of some of the custom NPM run commands we have for this project.

  • Start the local Angular Development server: npm run start
  • Run the unit tests: npm run test
  • Run the e2e/functional tests: npm run e2e
  • Compile and export files for end user: npm run build

Next Steps

Here’s an incomplete list of some of the next things we plan on working on, and completing, with the project in the future:

  • Jasmine Unit Tests to cover our angular code
  • KarmaJS Functional Tests to cover the entire application end-to-end
  • A basic User facing profile designed for user extension

How to Contribute

If you have an idea for a new feature, have an idea on how to improve a feature, or (gasp) you have found a bug please report this on our Github Repo Issues page.

However if you are just excited about this project, feel free to “star” this repo on Github to show your support.

We would also love to know if and how you use this module in your own projects!

To set your environment up for local development, please follow these steps:

  1. Clone your fork of the User Admin project into a local directory
  2. Clone the following packages into the same directory
  3. Copy the composer-dev.json file to composer.json
  4. Start your docker container docker-composer up --build

Conclusion

Thanks for reading about our exciting new package! Feel free to leave a comment or ask questions below, or feel free to comment on our Github Repo page!

Themes in the Erdiko Framework (Part 2)

In the first post we talked about how themes works in the Erdiko framework and covered important files to configure it. We continue with more advanced Erdiko theme topics and introduce new classes to discover more features, including layouts.

Today, I’m going to show you more concepts around themes in the Erdiko framework.  There are more concepts and classes to know and understand.

Layouts

To introduce the Layout class we need to define what is a layout: it includes the HTML for a basic web application structure in order to provide your own content. After made this clarification, we realize that a layout could be made by one, two, three or whatever number of columns.

Let’s look at the next code from Erdiko framework:

/**
 * Get two column layout example
 */
public function getTwocolumn()
{
    // Set columns directly using a layout
    $columns = array(
        'one' => $this->getView('examples/one'),
        'two' => $this->getView('examples/nested_view')
        );
    
    $this->setTitle('2 Column Layout');
    $this->setContent($this->getLayout('2column', $columns));
}

This code is an action from Example controller from code base of Erdiko framework. We can see how passing an array of views we can get a new layout built with ‘2column’ parameter. This way we instruct to Example controller what design we want to set to our application, and the final result will be something like this:

2columns

It’s important to take care about this latest parameter, it must exist as layout in the layout’s folder and the name must match exactly. Let’s recall our Erdiko folder structure:

layouts

the key method is Controller->getLayout():

 $this->setContent($this->getLayout('2column', $columns));

Under the hood, the controller delegates to a new Layout object composed of 2 views (one for each column) the call to render html code:

return  $layout->toHtml();

Pages

In order to reuse code the framework gives the chance of include html code often used, i.e. Header and Footer. This kind of content normally stay static around  the application. When we say “static” talk about structure however we also could include mustache code within the pages by using the {{ variable }} sintaxis.

Header

The header is a good example of html code that probably will not change in our web app. Erdiko framework installation provides us a nice default html code in the file:
app/themes/bootstrap/templates/pages/header.html

Something interesting to comment is the next piece of code:

<div class="navbar-collapse collapse" id="navbar-main">
  <ul class="nav navbar-nav">
    {{# menu.main }}
        <li>
            <a href="{{href}}">{{title}}</a>
        </li>
    {{/ menu.main }}
  </ul>
</div>

Ok, what is that sort of tag “menu.main”? Don’t worry just let’s say that we can create a html menu programmatically. When we talk about “Regions” will expand a better explanation. One important thing to highlight: the menu is built from the key “menu” in application.json file.

Footer

Footer section is more or less the same concept we talked previously with “header” but applied to the footer of application. Erdiko framework provides a default footer, the big difference against Header is the region used:

<div class="col-lg-12">
        <ul class="list-inline">
            <li class="pull-right"><a href="#top">Back to top</a></li>
            {{# menu.footer}}
                <li><a href="{{href}}">{{title}}</a></li>
            {{/ menu.footer}}
        </ul>
        <p>{{site.copyright}} {{site.full_name}}<br />
           Powered by <a href="https://github.com/ArroyoLabs/erdiko"
                         target="_blank">Erdiko</a>
        </p>
</div>

This time, the region used is ‘main.footer’ and the key used from application.json is “menu.footer”.

FlashMessages

To conclude with pages, another great and useful example is FlashMessages that provides (and being redundant) a flash message on top of the header page and denotes something important to show to the user application.

Unlike Header and Footer, FlashMessages is a helper, and you can call it:

<?php $messages = \erdiko\core\helpers\FlashMessages::get() ?>

‘$messages’ is an array and you are able to loop around it in order to give html structure:

<?php foreach($messages as $message): ?>
   <div class="alert alert-<?php echo $message['type'] ?> 
     alert-dismissible" role="alert">
     <button type="button" class="close" 
             data-dismiss="alert" aria-label="Close">
                <span aria-hidden="true">&times;</span>
    </button>
    <?php echo $message['text'] ?>
   </div>
<?php endforeach ?>

If you can get messages, it’s logic that you can set messages too 😉 :

<?php 
$message ='This is a success message to show.';
//what color we want to show the message? 'danger' is by default.
$type = 'success';
\erdiko\core\helpers\FlashMessages::set($message,$type);
?>

Regions

In the first post when we talked about Mustache we understood how a content is rendered exactly in the right position into the html code. In order to conceive Regions, we can take the same concept, regions is just a “mark” in the html code to teach the framework about what kind of html structure we want to create, just in the right position where should be placed.

Let’s take the region part of footer.html:

 {{# menu.footer}}
     <li><a href="{{href}}">{{title}}</a></li>
 {{/ menu.footer}}

When the framework process this region tag, as result we will get a nice footer created programmatically. The million dollar question is:
– How the framework makes possible to know about footer structure?
Easy, Erdiko reads the section ‘menu.footer’ and iterates the key/values within  in application.json file.

Scripts and Styles

Previously, in our post “sample application using Erdiko Framework” we proposed as example a little dice to roll with a very simple view. That view used the controller method addJs() and addCss() in order to add css and js code to the view respectively. The method signature  is the next:

/**
 * Add Css includes to the page
 *
 * @param string $name
 * @param string $file
 * @param int $order
 * @param int $active
 */
public function addJs($name, $file, $order = 10, $active = 1)
{
    $this->getResponse()
        ->getTheme()
        ->addJs($name, $file, $order,$active);
}

Both methods share the same order and number of parameters.

Views

A view object is a piece of code to provide a visual representation of model data, in object terms is a very simple class where we can modularize our html code. Let’s take an example from Erdiko framework:

$this->addView('examples/about', $data);

here we add the view ‘examples/about’ to the  controller response. The views can receive parameters, here is the constructor:

public function __construct($template = null, $data = null, $templateRootFolder = ERDIKO_APP)
{
    $this->initiate($template, $data, $templateRootFolder);
    $this->setTemplateFolder('views');
}

by reading this code we can understand easy, what kind of parameters a view needs, look how the folder ‘views’ is assigned by default.

There is no more to talk about Views, the content will be rendered by the controller with addView() method internally, calling to:

$this->appendContent($view->toHtml());

Using properties

There are a set of  properties  defined and accessibles to the entire application, we can use it between {{ variableName }} in views or templates because are just keys/values already created in application.json config. file. To mention a few of them:
– site.name
– site. description
– site.copyright

Default.php

Default.php is, paradoxically, the default template theme applied to a given view. In a general manner, default.php is a complete html page with formal sections (head, body, etc) but instead make use of static code, it call the previously defined dynamic pages as header, footer and messages. Let’s see a fragment just to understand how the sections are referenced:

<?php echo $this->getTemplateHtml('header'); ?>
<?php echo $this->getTemplateHtml('messages'); ?>
<?php echo $this->getContent(); ?>
<?php echo $this->getTemplateHtml('footer'); ?>

where the method call:

$this->getContent()

what we want is to render the View code itself.

Conclusion

Erdiko framework provides a very flexible solution to easily change the aspect of a complete web application as complex as we propose it, the key to achieve that is setup properly all our config. files and templates.
Thanks for reading!

Dependency Injection

Dependency Injection is a widely used design pattern. We will define the concepts of this pattern and show a popular PHP implementation with a simple example.

What is DI?

Dependency Injection is a software design pattern that implements Inversion of control by decoupling software modules, introduced by Martin Fowler.

Usually a dependency injection container is used to manage and automate the construction and lifetimes of interdependent objects.

di_uml

Design pattern explanation and Use

Basically, if your class needs an object of other class, in this pattern you pass the dependency object as a constructor parameter or via property setters, instead of invoke factory or create dependency. You make it someone else’s problem.
Example 1:
class MyClass {
    private $objectA;
    public function __construct(ObjectA $object) {
        $this->objectA = $object;
    }
}
Example 2:
class MyClass {
    private $objectA;

    public function setObjectA(ObjectA $object) {
        $this->objectA = $object;
    }
}

In both examples, we don’t care how or where to create the objectA we just use it.

Some popular PHP DI-Container implementations

  • PHP-DI: is an interesting implementation of DI Container that has integration with several frameworks and IDEs like PHPStorm.
  • Symfony DependencyInjection: The DependencyInjection component allows you to standardize and centralize the way objects are constructed in your application.
  • Zend – DI: DI Container implementation for Zend framwork.
  • Pimple: Is a Dependency Injection Container from SensioLabs.

Pimple Presentation

This is an implementation from SensioLabs, and you guessed it, the same guys that created the Symfony libraries.

This is a friendly implemented package, lightweight and easy to use.
To install you just need to add to your composer.json,
$ ./composer.phar require pimple/pimple ~3.0
and you’re ready to use it!
$container = new \Pimple\Container();
Since it implements \ArrayAccess interface, you can store variables and factories as it was an array.
example of parameters:
$container['cookie_name'] = 'SESSION_ID';
an example of factory as a closure:
$container['session'] = $container->factory(function ($c) {
    return new Session($c['session_storage']);
});
It also provides methods to protect parameters, modify services after defined, extends, and more.
For more info refer to Pimple site.

Example Use Cases

Let’s imagine that we want to create factories dynamically based on a JSON configuration like this:
auth_config1
Then we can create a Trait with a method that will fill our container based on an argument that could be an array create from the decode of above JSON.
traits_builder
Here’s how we can use this trait:
di_using
Let’s break down the example above:
the class that implements the __construct method has defined a member attribute, container, that is an instance of Pimple.
Since we are using traits to buildAuthenticator, the result of the foreach block will be assigned into the class container attribute.
Within the build, we need to create a new temporary Pimple object. This is a hack I found to store nested containers.
This is needed because otherwise each time you attempt to add a sub-item within the “AUTHENTICATION” it overrides the previous one.
So once we have created all factories, we just set the temporal container in “AUTHENTICATION” cell of the main container.
To use your created object in the container you just need to do something like that:
$auth = $this->container["AUTHENTICATION"]["mock"];
$result  = $auth->doSomething();

Final Thoughts

This pattern is very useful and widely used these days especially in modern web development, in particular if you see it used in the Angular framework.
Even when you should pick the product that better match your requirements in each case, I can say that I feel very comfortable with Pimple. As I showed, it is very flexible, allowing you to create your own wrap class to customize its behavior and fit your needs.
Hope you enjoyed! Thanks for reading and see you on next posts!

Angular 2 Animations

Animations are a very important part of User Experience design for web applications. We’ll will explore how animations are created and configured in Angular 2 and provide some concrete examples.

Introduction

Continuing on our series of Angular 2, we’re now going to explore  animations in Angular 2. Clearly smooth animation and transitions are an important part of the UX design for interactive applications.

Let’s start off by talking about how we animated things in Angular 1.x.

Animations in Angular 1

Angular 1.x allowed for animations between states for a handful of directives and elements, which when coupled with the nature of an Angular application, presented some great results. Two methods were provided to allow the user to add these transition states: CSS and Javascript. While both methods had some pros and cons, it also led to different interfaces that could easily confuse a developer.

CSS transitions were provided simply by using CSS3 transitions, which have the benefit of not requiring additional JS libraries and are as fast as your browser can render. Most of the control of this style of animation is controlled by using a unique class name structure and Angular handles a class change based upon a unique naming scheme.

The ngAnimate module provided a Javascript interface to control animations. This module allowed the user to use (most likely) jQuery’s animation controls or a 3rd party JS lib to render animations. This has some benefits of allowing some fine grain control, but you were also limited to what the 3rd party library allowed you.

Animations in Angular 2

Angular 2 uses the Web Animations API to really let your browser control animations with the highest possible performance and timing control.

Unlike Angular 1.x’s interface, the entire animation library is contained within a single module. This allows for a common simple interface, but since it uses the Web Animation API, also allows the browser to optimize the animation control to a finer control that previously allowed by CSS3 only animations.

While I should note that this also requires a compatible browser to run these animations, there is a polyfill available to cover legacy browsers that is easily installed.

Let’s explore some of the basic concepts used for defining and controlling Angular 2 animations.

Triggers

Triggers are the term for a function that defines the states and transitions used for an animation. These are defined in the component annotation metadata fields and have a corresponding placement on a component’s template to indicate where an animation is applied when the end user interacts with the application.

Here’s an example of triggers defined in a simple component, and explains where we put the settings we explain later in this post:

animations: [
  trigger(
    'pState', 
    [
      state('inactive', style({
        transform: 'scale(.9)'
      })),
      state('active', style({
        fontWeight: "bold",
        transform: 'scale(1)'
      })),
      transition('active => inactive', animate('50ms ease-out')),
      transition('inactive => active', animate('50ms ease-in'))
    ]
  )
]

States

States are a defined condition, or a specific point in time by, that you can define in your Angular 2 component via a string. These finite conditions allows you to define a value you can pass into your components template to help set up your animation conditions. Examples of these states are “active” and “inactive” that can identify an element that is “On”. See our first example for a demonstration of these states.

Timing

Timing in Angular 2 is defined by three properties: duration, delay and easing

Duration controls how long an animation runs. Defined by a string or an integer in milliseconds or seconds, it’s never been easier to define the length of time a transition occurs. Here’s an example of a duration of two seconds “2s” and 200 milliseconds “200ms”.

Delay, much like you assume, is about the time that elapses between the trigger execution an the start of the animation. You can even define the delay in the same line you define the duration in this example where it last two seconds after a delay of 3 seconds: “2s 3s”

Easing is how angular controls the animation accelerates and decelerates during it’s runtime and is a pretty succinct way to add some ‘realism’ to your animation. Identified by a string, these have the same common names as the control parameter in CSS3. Some more information can be found here on this site, easings.net.

Callbacks

Callbacks are just methods called when an animation starts and stops. This is useful for executing code based on an animation’s timing, and if you have ever tried to chain commands together using browser timing alone, you will seriously jump for joy.

Here’s an example from the official angular guide with the callback methods “animationStarted” & “animationDone”:

...
  <li>
    (@flyInOut.start)="animationStarted($event)"
    (@flyInOut.done)="animationDone($event)"
    [@flyInOut]="'in'" >
    {{hero.name}}
  </li>
...

 

Example 1: P Tag State on Button Click

Our first example shows hows we can animate the two states (Active & Inactive) of a displayed P tag. Keeping this simple, we illustrate how to set up a component to use the animation library and how to set up two simple states and their transitions.

Click the gif of the plnkr below to see the code in an active plnkr:

ex_1-p_tag

Example 2: Multi-Step Animation with Callbacks

Our second example shows a multistep animation that uses keyframes to add multiple steps to a transition, and callbacks that output the start and end of each animation to the console.

Check out this plnkr, and open your console, to see this in action:

ex_2-multi-step

Conclusion

Animations add so much to web applications that it’s a mistake not to include them. Thankfully Angular 2 makes this easier to include and trigger your animations with minimal work from the developer.

Themes in the Erdiko Framework (Part 1)

As web applications and sites become more complex it becomes important to organize your view layers with themes. We explain how to leverage the Erdiko theming engine and how to keep your code tidy and consistent. This is the first of a series of posts about Erdiko theming.

Why do we need themes?

Typically when we start a new web project, we are focused on the workflow and technical details about how the applications will work and what solution will provide to the end user. At some point of the planning process, we should start thinking about how our application will look, what data will offer, and then we begin to define our needs:

  • What is dynamic and what is static
  • What will be changed according our business logic
  • What is the menu, header, footer etc

Most of the time the HTML code will deliver rendered data elements, but half the battle of frameworks is deciding how to organize your code.

remember that design patterns are tools that you can use to solve specific problems , In MVC the Controller is responsible for determining which View is displayed in response to any action including when the application loads, if some parts of the view are very similar probably you need themes, don’t reinvent the wheel!

Currently we can find this behavior in any web application or SPA :

  • The header and footer are consistent across pages
  • The content changes according to the link we click in the navbar
  • The navbar (below the header or left aligned) will probably change according  to user level (admin, operator, visitor, etc).

At the end of the day we can realize that we don’t have to repeat over and over the same code, and we want to promote the re-usability of our code.

Thankfully, much of this work has been solved by many modern frameworks (re-inventing this is not an easy task). Let’s examine how we accomplish this with the Erdiko theming engine.

Paths and files

Let’s discuss what is in our Erdiko folder structure:

paths

For the moment just keep focusing on the “themes” folder and their nested folders. There are a lot of files right? Don’t worry let me explain:

  • themes: where each different theme is stored.
  • bootstrap: the default Erdiko’s theme.
  • views: This is where we put our HTML templates, where we render the data from our models.

Within the bootstrap theme:

  •  templates/layouts: we got templates in the most common variety: 1, 2, 3 columns and a menu.
  • templates/page: this part is the easier to understand, footer and header content, a messages file to show flash message alerts, and two special files: ‘google_header’ and ‘google_body’.  These last two allow us to insert Google Tag Manager and Google Analytics information.
  • theme.json: this file is one of the most important in order to use themes feature. Here we can set up all the previous files we talk, using json format.
  • app/config/{context}/default.json: another important config file to set up what theme will be used by the Erdiko application (theme, namespace, how many columns? And the home url). In order to demonstrate the flexibility of Erdiko framework, you can define many different contexts for a web application (default, production, etc).
  •  Default.php: the backbone file for Erdiko’s themes, here we give the main html5 structure to the final app  and also (and most important) we make use of the previous dynamic files (header, footer, example) calling the method:
Theme::getTemplateHtml().

In the same way we can show the dynamic code corresponding to the footer:

$this->getTemplateHtml('footer');

 We finally don’t know how this magic happens, how to mix dynamic data and html code in the exactly and specific parts. Is a dirty job but somebody has to do it… and the candidate is Mustache!

But what is mustache?

Mustache is a logic-less templating language that can be used to take most of the work out of creating re-usable HTML templates.

Let’s see a little example:
1. define the mustache template:

<h1>{{header}}</h1>

Please note the ‘header’ word between curly brackets.

2. define the model to user over that template:

{ "header": "Hello world!"}

3. Apply that model to the template and render it:

<h1>Hello world!</h1>

This pattern is extremely useful. Not just for re-use, but making debugging far easier.

Currently Mustache offers a lot of useful functionality but this is the most basic and important one. What we got here is the idea how it works, but remember that Mustache is One of many template systems, and the framework is not limited to use it.

Themes

The Theme class is the key element here, we need to understand how it works, their methods names are self-exaplanatory, the most important task is to process data and html templates to obtain a final html code. When a controller is created, a theme attribute is built in order to provide structure to the application. All necessary parts before to render are prepared by the _before() hook:

public function prepareTheme()
{
    $this->getResponse()
         ->setTheme(new \erdiko\core\Theme($this->getThemeName()));
}

Each time we call an action on a controller (except the ajax controllers) we automatically are setting a Theme, by inheriting the class \erdiko\core\Controller. When the action is done, tipically we create a new view passing a data array as second parameter:

$this->addView('examples/list', $data);

Or maybe we don’t want to show a view, we can just show a basic content with controller::setContent() method:

// Entering raw text on the page
$this->setContent("
    <div class=\"container\"><p>
    This is the simplest page possible.</p>
    </div>");

Then if the action is finished, the internal Theme will render their html stored. The most important methods of class Theme are:

  • addMeta(): Manages metadata of the application.
  • setPageTitle() and setBodyTitle(): Manages the title.
  • getCss() and getJs(): their setters add units of code, but the getters retrieves an array of that specific nature (array of css, or array of js stored). The result is a well formed <link> tag according to each array cell.
  • getTemplateHtml($aPartialToBeRendered): we can switch the template for a theme to render html with data.
  • toHtml(): finally we got html rendered.

In this first half of our blog post, we offer a big picture view of how theming works in Erdiko framework. At this point, we know that Controllers ‘under the hood’ already has prepared a theme ready to use with our defined content, and these themes are able of make html code. But they are not the only actors in this movie and the render concept needs to be explained a little more in depth. The next post we will continue talking about themes and discovering more actors and abilities. Thanks for reading!

Angular 2 Attribute Directives

Attribute Directives are a powerful way to affect the appearance or behavior of a DOM Element in your Angular 2 Application. We examine how attribute directives work, and how you can build re-usable custom code for your projects.

Introduction

AngularJS really introduced the concept of organizing and extending the DOM for use in real web applications. AngularJS 1.x brought us the idea of a Directive, or a way to indicate that a DOM element was “special” and will have a behaviors or an appearance that will be controlled by your code. AngularJS 2 took this idea and ran with it, but this also means we need to explain some stuff. We now have 3 tools at our disposal for interacting with the DOM: Components, Structural Directives and Attribute Directives.

Components, which you should have at least read about by now, are the most basic of the angular building blocks. Everything is a component and all components have directives; components are created from one or more directives. Directives are the method to identify a component’s behavior or associate a variable to a component.

Structural Directives are used to add or remove elements from the DOM. Common examples are *ngIf or *ngFor. These directives allows you manipulate a component based on a variable value or allow a component to iterate a series of values.

Finally, we have Attribute Directives. Attribute directives allow you to attach a behavior to an element or affect it’s appearance and re-use this throughout your application or package it up as something you use in all your projects.

Using Attribute Directives you can create a stylized DIV tag that formats all text and adds an event listener to change the color when the user mouses over the text. Show off your example code with some syntax highlighting!

I should also note that Attribute Directives can access and manipulate application values, but primarily are focused on affecting the component they have been attached. Think of this as more like CSS Selector Class on steroids. Make sure you do the “real math” of your application in your components.

Anatomy of an Attribute Directive & How to use it

Attribute Directives can be simple or complex. The simplest example of an Attribute Directive could be a simple CSS property attached to a P Tag:

<p [style.background]="'red'">I'm red!</p>

Anything more complex than the above example requires a little more wiring. Let’s look at an commented example from the official docs called “Highlight”:

// Import some stuff from the core library
import { Directive, ElementRef, Input, Renderer } from '@angular/core';

// create a Directive to decorate. To prevent confusion let's call this myHighlight to 
// illustrate the fact this this is a custom appearance
@Directive({ selector: '[myHighlight]' })

export class HighlightDirective {

    /* 
    This is a pretty simple example, we just need a constructor. Pass the element we wish to affect in as "el" and make sure we interact with the DOM renderer with the obvious name of "renderer"
    */
    constructor(el: ElementRef, renderer: Renderer) {

       /* 
       Set the element's Background Color CSS property to Yellow, as though we "highlighted" it with a marker.

       Note we reference the element itself as el.nativeElement so we actually update the rendered DOM model itself.
       */
       renderer.setElementStyle(el.nativeElement, 'backgroundColor', 'yellow');
    }

}

Use and apply your custom directive attribute in your application
<p myHighlight>Highlight me!</p>

Some Attribute Directive Examples

Italic & Underline

A very simple example showing how we can make something italic, and underlined, using a simple attribute directive.

@Directive({ selector: '[alItalic]' })

export class ItalicDirective {
 
  constructor(el: ElementRef, renderer: Renderer) {
    renderer.setElementStyle(el.nativeElement, 'fontStyle', 'italic');
    renderer.setElementStyle(el.nativeElement, 'textDecoration', 'underline');
  }
 
}

Plnkr

Blink

We can also bring back the much missed BLINK tag using an attribute directive. This example illustrates how we can actually encapsulate some logic and manipulate the DOM element’s CSS with this logic by using an attribute directive that can be placed on any block element.

@Directive({ selector: '[alBlink]' })

export class BlinkDirective {
  
    constructor(el: ElementRef, renderer: Renderer) {
      setInterval(() => { 
        let style = "hidden";
        if(el.nativeElement.style.visibility && el.nativeElement.style.visibility == "hidden") {
          style = "visible";
        }
        renderer.setElementStyle(el.nativeElement, 'visibility', style); 
      }, 750);
    }
    
}

Plnkr

Detected User Event – Click

Finally, here’s an example where we can listen for a user event (click) on an element by simply using an attribute directive.

import { Directive, ElementRef, Input, Renderer, HostListener } from '@angular/core';

@Directive({ selector: '[alClick]' })

export class ClickDirective {
  
  private _el: ElementRef;
  
  constructor(el: ElementRef, renderer: Renderer) { 
    this._el = el;
  }

  @HostListener('click') onClick() {
    let str = this._el.nativeElement.innerHTML;
    alert("innerHTML from the element you clicked: " + str);
  }
    
}

Plnkr

Conclusion

We really only scratched the surface of what you can do with Attribute Directives. AngularJS has always been a framework that allowed you to organize and extend your DOM based applications, but AngularJS 2 has taken this to a whole new level.

Hope you enjoyed this post!

User Auth… What does it really mean?

Auth, a widely use term that can be a bit confused. We will show the meaning and how to work with both definitions as a system.

Auth, a term we can see every where these days. But, what does it really mean?
Honestly, it can be confusing when just saying Auth. Are you talking about authorization or authenticating?
More over, which is the difference between those two terms? Yeah, you got the point!

So now that I have your attention, let’s start by explaining what each is and how they are different and then how we can use both in our systems.

Difference between Authenticate and Authorize

We can roughly say, in the context of computer systems, authenticate is the process that ensures and confirms a user’s identity.

In other hand we can say that authorize or authorization, is the process responsible to determine the level of access that a user has in relation with a resource.

As you may already guessed, both of these should work together as a team.

That’s cool, but how to do that?

Let’s start with Authentication

Okay, starting from a very basic example, where you need to present two keys to the system, for example, username and password, where the first one will identify you and should be unique all system wide, and the other one would confirm that you are who you said you are.

Nowadays there are other architectures that requires multi-level security layers, tokens like oAuth, and so on, but I won’t go deeper on those in this post since this is just an overview.

So, going back to the previous example, you can tackle it at different level. That means, you can go with Sysadmins and request to keep .htaccess and .htpasswd files up to date, or you can choose to tackle at application level.

As you may guess, we will discuss the last one, programmatically. Here, again, we have a bunch of alternatives based on languages, patterns, etc.

My first thought when I had to work on that was, “why should I choose one? why not define an structure that let users select and implement the most appropriate for  each project?”
Yeah, sounds great, but how can I accomplish it? Well, actually is not a big deal (unless you’re trying to reinvent the wheel), is just take a look at already implemented things. The Database layer was my inspiration.

Let me explain how so. I’ve started defining a minimal interface that any Authenticator class should implement, that way I ensure that my controllers will not be broken when I change the configuration.

iauth

As a second step, I’ve added another two interfaces, one that defines requires method to store and retrieve “session” record of current user, and the other that ensure we have at least a “login” method.

storage_interface

Finally, I mixed all this stuff in a basic atuhenticator class, that with the use of Dependency Injection pattern (Pimple in my case) allow us to load based on a config file, any authenticator class that implements our interfaces. That means, I can choose to authenticate against a plain text file, database record or oAuth server like Facebook or Twitter, I just need to implement the logic for the selected service and put it in a config file.

mock_auth

And what about Authorization?

The good news is there’s a lot of alternatives. The bad news is that most of then are not implemented for all languages, instead, it seems that each programming language pick one and discard the other.

Don’t worry, most of them can be categorized in one of those big groups:

  • Role-based access control

from wikipedia

In computer systems security, role-based access control (RBAC) is an approach to restricting system access to authorized users. It is used by the majority of enterprises with more than 500 employees, and can implement mandatory access control (MAC) or discretionary access control (DAC). RBAC is sometimes referred to as role-based security.

Role-based-access-control (RBAC) is a policy neutral access control mechanism defined around roles and privileges.

  • Access Level Control

from wikipedia

An access control list (ACL), with respect to a computer file system, is a list of permissions attached to an object. An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. For instance, if a file object has an ACL that contains (Alice: read,write; Bob: read), this would give Alice permission to read and write the file and Bob to only read it.

  • Identity Management

from wikipedia

In computer security, identity and access management (IAM) is the security and business discipline that “enables the right individuals to access the right resources at the right times and for the right reasons”. It addresses the need to ensure appropriate access to resources across increasingly heterogeneous technology environments and to meet increasingly rigorous compliance requirements.

In my case, I based on Ruby On Rails’ CanCan gem. Is very nice the way they implemented the “ability” class to grant users and groups the access to specific resource.
This time I’ve based on AC\Kilinka (compose package from American Council) and basically extended it to cover my needs.
Let’s breakdown a bit to make things more clear, there are two big parts, Authorizer and Guard, and two interface that defines them.
The first one, GuardInterface define four basic methods that will be responsible for get and check policies related with an specific resource, the other one, AuthorizerInterface, has two method, one for register guards and “can”, that decides if an action on a resource is permitted.
kalinka_guardinterface
kalinka_authorizerinterface

 

This package also provides some basic implementations. I’ve chosen RoleAuthorizer that better match to my needs, because users used to have a role associated. However, you can use a SimpleAuthorizer that allows you to allow/deny access by user instead of group.

The main difference is the way you config your permissions, here’s an example of what I did in a JSON format:
auth_json

Final thoughts

I have presented a brief overview about how you can identify users and manage permissions to your app resources.
Hope you enjoyed, thanks for reading, and stay tuned in this blog because we will bring you a new Erdiko packages that implements those things, soon!

Angular 2 Pipes

Angular 2 pipes replaced filters as a method to format and manipulate text for output. We explore some background behind pipes and provide some simple examples to explain these concepts.

Introduction

Pipes are a feature of Angular 2 that allows you to contextually manipulate and format text on the front end. From simple date formatting, to a complete transformation, pipes allow you to separate how you display data provided from the backend.

Prior to Angular 2, text transformation was provided by “filters”. Conceptually the same in usage, Angular 2 gives us a little more power and flexibility to how we can package up the text manipulation power of these smaller components.

Commonly used & built in Pipe examples

Some pipes merely intake a string and return a formatted result, others take parameters to help construct the resulting output.

The best part of using these are literally built into the framework. No extra file library inclusions are required.

UpperCasePipe & LowerCasePipe

UpperCasePipe & LowerCasePipe are two built in pipes that allow you to transform text, as their names would imply, before outputting to the DOM.

These are the most simple of pipes (and really, could be replace with some CSS) but they illustrate the mechanic: The value you wish to transform goes on the left a “pipe” (this “|” character) and then the transformative function goes on the right.

Here are two quick examples:

<p>{{ firstname | lowercase }}</p> // Foo -> foo 
<p>{{ lastname | uppercase }}</p> // Foo -> FOO 

Pretty simple, and lets us explain some more complex setups.

DatePipe & CurrencyPipe

There are also some slightly more complex built in pipes, some of which take in full objects, other take expressions from which to transform the text they transform.

DatePipe

DatePipe formats and transforms a Date object into a string based on a provided expression and locale rules.

Here are some example DatePipe usages with some of the build in expressions:

<p>{{ now | date }}</p> // Nov 15, 2016 
<p>{{ now | date:'medium' }}</p> // Nov 15, 2016, 12:05:08 PM 
<p>{{ now | date:'M-d-y' }}</p> // 11-15-16

CurrencyPipe

Like the DataPipe, CurrencyPipe also formats using a provided express and based on the browser’s locale. I’ll leave you to check the official documentation, but this is a very basic example.

<p>Total: {{ total | currency:'USD':true:'4.2-2'}}</p> // $10.99

Creating Custom Pipes

Creating custom pipes can be a little scary and intimidating at first, but is not hard in principle. We’ll walk you through the basics and provide a few examples to work from.

Structure and formatting your Pipe definition

Creating a pipe is pretty easy, in fact it looks like how you create an angular component. Let’s break down this example:

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({name: 'foobar'})
export class FooBarPipe implements PipeTransform {
 
    transform(value: string, args: string[]): any {
        return "FooBar" + value;
    }
 
}

After including the Pipe & PipeTransform libraries from angular/core, you simply need to use the @Pipe decorator. The decorator accepts a parameter called “name” which is used to reference your custom pipe in your template code.

Finally, your pipe must implement a method called “transform” which, coincidentally, transforms your provided text or object.

And including into your app module is also quite simple:

import { FooBarPipe } from './foobar.pipe';

...

@NgModule({
 imports: [ BrowserModule ],
 declarations: [ App, FooBarPipe ],
 bootstrap: [ App ]
})
export class AppModule {}

Parameters

As we noted previously, you can also pass parameters to a pipe to affect the how the value piped in is transformed. You can send multiple parameters as well each separated by a colon (“:”) and extract them in your transform method.

Example 1: Prefix “FooBar” to a provided string

This is a simple example of a custom pipe that prefixes “FooBar”:

Example 2: Multiply a provided integer by Number

Show an example where we multiply the output by 42 (provided by the component) and return a result. This will illustrate the idea of stateful pipes.

Example 3: Convert string to Pig Latin

Here is an example of a pipe that converts a provided string to Pig Latin.

Conclusion

Pipes are a useful and easy to learn concept in angular 2. While it’s easy to think they are limited to formatting and displaying text, we have also shown some re-usable examples where a company can have a small arsenal of pipes at their disposal.

Angular 2 Routing

Angular 2 Routing is bit complicated when compared to routing in Angular 1.x but it is very powerful. We hope to clear up some of the common confusion when setting up routing and provide some practical examples as references.

Understanding routing in you application is the key to creating a single page application. Routing is what allows view navigation in your application like ‘detail views’, end user bookmarking and even allows you to set up a ‘logged in’ version of your applications views.

Routing isn’t included by default in Angular 2, in fact you have to explicitly include it as a library. I also will say, it’s not incredibly intuitive to configure. We’ll take some time to explain the history of the router and dive into some of the basic concepts.

Basic Concepts of Routing in Angular 2

Router Library

The router itself is implemented in the optional Router Module, which is kept separate to keep the base library size low. Include it in your main module like this:

import { RouterModule } from '@angular/router';

...
@NgModule({
 declarations: [ ... ],
 imports: [
     RouterModule.forRoot(routes),
     ...
 ],
 providers: [ ... ],
 entryComponents: [AppComponent],
 bootstrap: [AppComponent]
})
export class AppModule {

}

Base HREF

The base HREF is the starting point for your application and is used to create your home route. It’s this starting point that your browser will also use to create a history to prevent ‘breaking the back button’ which is always a sticking point in SPAs.

Here’s the syntax you need to add to you html:

<base href="/">

Configuration & Routes

const routes = [ 
    // Default, or home, path. This matches your Base HREF
    { 
        path: '', 
        component: HomeComponent 
    }, 

    ...

    // Wildcard, or the 'catch-all' route pattern. If the requested
    // route does not match anything above, this route is displayed.
    { 
        path: '**', 
        component: HomeComponent 
    } 
];

Resolves & Guards

Resolves are services that must be completed before allowing the route to be accessed and loaded. This is how we can ensure that the data is available for the route prior to allowing the user to access the route.

A quick example of this would be a UserResolve class that retrieves a list of users before displaying the route.

Guards are a method to prevent a route from being accessed unless a certain state is met.

A quick example of this would be a LoggedInGuard class that prevents a user from accessing a route unless they are logged in.

Child Routes

Child routes are a way to add specific routes to a feature.

Example 1: A One Route Application

Below is an example of an application with a single route. This illustrates including the router module, a base href and a very basic route configuration.

Example 2: A One Route Application with a Resolve

Below is an example of an application with a single route that requires a service to resolve a data retrieval before rendering.

Example 3: A multiple route application with a child route

Below is an example of an application with two routes and a child route.

Conclusion

While it may take some time to completely wrap your mind around routing in angular it’s clearly an important part of creating a real SPA. Don’t be afraid to take and reference your own notes!

Sample Application Using The Erdiko Framework

This time we will show you how to set up a quick and easy application using the Erdiko framework. You can roll the dice and try your luck!

Sometimes we need to create an application from scratch and there are a little set of things to get in mind relative to how and what we want to build: what language, to define the architecture, gather all the assets and (maybe) a long list of items more.

   A great idea is to use the Erdiko framework for building web apps quickly using well known MVC patterns and make the php deployment easy. Here we will create a little web app to roll a dice and get a result in two flavors: using a view and getting the result as AJAX call.

MVC is the separation of model, view and controller, it’s simply a paradigm; an ideal that you should have in the back of your mind when designing classes. Avoid mixing code from the three categories into one class

Roll the dice

    We took a fresh installation of Erdiko framework and created a view to the main page.Here we see 2 buttons:

  • One for go to the ‘get’ request.
  • Another one to get the same request above but using an ajax call, in this case you will not note difference into the current page after click the button because the roll result is coming in background as a json object.

 

new_main

The Model

    For the model we created a super-very-simple class with just only one method, “roll_dice”.

   This method returns a random value and it’s very easy to understand, the value will be used later to select the correct dice image and set up the view.

The Controller

erdiko_app_controller_get_dice_action

    With the goal of keep things simple, we will reuse the Example controller and added one new action: getDiceRequest(). What the action does is create a new Dice model instance and get the random value generated with the call to Dice::roll_dice(). After that, sent the result to the view to be shown in the front end.

    Also to the ajax call we will use the existing AjaxExample controller and made a very similar action: getDice().

erdiko_app_controller_ajax_get_dice_action

   What it does is mimic the action of the getDiceRequest action in Example controller but is managed in different way: the browser will never change the page and the result of the Dice::roll_dice() method is sent encapsulated in a json response.

   On the other side, the view is waiting for this json object in order to change the things quiet. Is for that reason the browser will never open a new tab or hop to a new page.

The View

   For this post finally we created 2 view, the main and the dice request. Both are purely 100% html as we can see:

erdiko_app_controller_index

    We can note how the controller knows how to insert javascript code to the final html render with the public function addJs() and is a good  “glue example”  between php world and html world, and how to keep a minimal separation of concerns.

jscode

A framework follows the Hollywood principle: “Don’t call us; we’ll call you.” It acts as a constraint that solves the particular problem it was designed to solve

    The Javascript part is not so complicated. We take the dice value and map the name of the right picture to show in the view.

    If the request is solved by backend php rendering instead of an ajax response with javascript, we just display the expected image with pure html:

dice_examples_view

Et voilà, the dice number is shown!:

dice_ajax_get_request

    I hope you enjoyed this post. You can apply good design patterns and quickly build a web app with the Erdiko framework. Thanks for reading!

https://github.com/arroyolabs-blog/roll-dice