Docs Wvm Middlewares

Middlewares

Middlewares are operations that either runs before or after a class or method is called. They are mostly executed through class methods. Their activity can affect the performance of window files. In wvm, middlewares can be applied to shutters once the url is resolved but before it is rendered. Once a url is rendered, shutter middlewares will run before a corresponding method or class is called. While middlewares can be applied to shutters from the super() method of Frame files, it is mostly preferred to use them in other class method in which a shutter method is applied. Their flexible structure makes it possible for methods or windows to inherit them. While shutters have been discussed earlier, here, we will focus on how to apply middlewares to shutters. Middlewares can be applied through the ONCALL() method or by passing the SELF::ONCALL constant key into a specific shutter list of accepted urls. It can also be applied by setting a preload function on urls using the self::preload() method. When supplied, these functions will execute before the method or class is resolved.

self::preload()

This method can be applied to specific urls immediately a url is resolved but not before it is authenticated. A url is usually first resolved before it is allowed to render. Between the resolving and the rendering of a url, middlewares are allowed to act as bridge to determine how a url responds. The preload() method takes a list of direct urls as its first argument and a boot function as its second argument. A syntax and an example is shown below:

Syntax: self::preload()
  #sample stucture 1: self::preload($acceptableUrls, $boot)

  $acceptableUrls //an array list of valid urls
  
  $boot  //a function that is called before a url is rendered


Example: self::preload()
    <?php 

    use Window;

    class Docs extends Window {

        function __construct() {

            self::preload( 
                [ 
                    'docs/user/settings',
                    'docs/user/profiles',
                ], 
        
                function() {
                    
                    echo "middleware applied";
        
                }
            );

        }

    }

Using the example above as reference, if the url docs/user/settings or docs/user/profiles is visited, the text "middleware applied" will be printed on the page before the content of the page itself is rendered.

SELF::ONCALL()

This method is a preload method that can be applied on any of the four shutter methods. The first argument declares the type of middleware to be applied. These options are:

  • CASTED::CALL(or CASTED::CAST)
  • CASTED::ROOT
  • CASTED::BASE
  • CASTED::PATH
  • CASTED::E404
Each of these options defines the shutter environment in which a boot function can execute its operations. As their name implies, they only execute their operation when a relative shutter method comes into play. In a situation where multiple shutters are pended for another, we may need to define our boot function for specific shutters. Hence, when any of the defined shutter is called then the function will execute.

SELF::ONCALL()
  #sample stucture 1: self::ONCALL($option, $urls)

  $option //casted options
  
  $urls  acceptable urls and their respective boot options


The code structure below is an example of its usage:

SELF::ONCALL()
    <?php

    use Window;

    class Home extends Window{

      function __construct() {
  

          //set middlewares for direct paths
          SELF::ONCALL(CASTED::CALL, [
              
              'home/user/settings' => function() {
                  // run this for settings
              },
              
              'home/user/profiles' => function() {
                  // run this for profiles
              }

          ]);
  
          //set middlewares for base paths
          SELF::ONCALL(CASTED::BASE, [
              
              'home/user' => function() {
                  // run this for user
              },
                
              'home/room' => function() {
                  // run this for room
              }

          ]);
  
          //set valid direct paths
          SELF::CALL($this, [
              
              'home/user/settings' => 'root',
              'home/user/profiles' => 'profiles',
  
          ], false);
  
          //set valid base paths
          SELF::BASECALL($this, [
              
              'home/user' => 'user',
              'home/room' => 'room',
  
          ]);
  
      }

    }


The code structure above is a complex relationships between shutters and predefined or preloaded function. This relationship is explained below:

  • The SELF::ONCALL(CASTED::CALL) method is used to set a preset (or preload) function on the list of urls it contains which is only applied within the SELF::CALL() method.
  • The SELF::ONCALL(CASTED::BASE) method is used to set a preset (or preload) function on the list of urls it contains which is only applied within the SELF::BASECALL() method.
  • If the SELF::CALL() can resolve any of its urls, then the function for SELF::ONCALL(CASTED::CALL) will be called before the url is rendered. However, if it cannot resolve its urls, then because it was pended, it will continue to SELF::BASECALL().
  • If SELF::BASECALL() can resolve any of its urls, the SELF::ONCALL(CASTED::BASE) function will be called for the relative url. If basecall cannot resolve its url also, then a 404 error page is returned.

According to the explanation made above, this means that CASTED::BASE, CASTED::CALL, CASTED::PATH and CASTED::ROOT will respond similarly only to their respective or relative shutter methods. However, the CASTED::E404 defines that a middleware should only be applied when a 404 error occurs.

While the approach above may be useful, it can be a tedious process and setting up boot functions this way can cause a lot of confusion even if it is handled separately. We can however shorten this function, making it more comprehensible by passing SELF::ONCALL key on the shutter itself.

SELF::ONCALL - RECOMMENDED

This SELF::ONCALL key is a preload method can be applied within any list of urls for any of the four shutter methods. We don't have to apply any casted option since we are within the shutter itself.

Sample: SELF::ONCALL
  SELF::CALL($this, [
    
    'home/user/profiles' => 'profiles',
    'home/user/settings' => 'settings',

     SELF::ONCALL => function() {

            if( invoked('home/user/profiles') ) {
                //do this if resolved
            }

            if( invoked('home/user/settings') ) {
                //do this if resolved
            }

        }

    ])
The code structure above is more concise and understandable than when we applied the SELF::ONCALL() method. The only difference is that here, our function is more localized and will not extend to a subsequent call method. For example, if the SELF::CALL() method above was pended, then another SELF::CALL() or any shutter method below it will not inherit the SELF::ONCALL constant key. The invoked() function is a case sensitive function that helps to match the current page url with the supplied url. To declare function as insensitive, the url supplied must be initialized with an exclamation mark "!".

Docs Wvm Middlewares