Spoova php framework for web development.

Spoova 2.6 Resource

In spoova, static resource files are compiled through the Resource class and imported through the Res class. The Resource internal static files url resolver class validates and saves urls within itself which can be imported later. The early validation of urls and resolving of scripts pulls unecessary resources especially for scripts that may not be required within a web page. Spoova 2.6 introduces a new url resolver and compiler class Ress which is faster because it only validates specific local resources needed on a webpage. Except the deprecated resources, most of the Resource class methods relating to static resource url storage and processing are also available on the Ress class. These methods are listed below:

RESS METHODS
Ress::url()
Ress::new()
Ress::urx()
Ress::named()
Ress::bind()
Ress::bindTo()
Ress::pull()
Ress::import()
Ress::export()
Ress::errors()
Ress::close()

Method: Ress::url()

The url() method is used to set the static resource url similarly to the Res::url() method. An example is shown below

 <?php 
 
 Ress::url('res/file1.css')
    ->url('res/file2.js')
    ->url('http/site.com/some-link/file3.css');

The sample above will store the supplied urls for future importation

Method: Ress::new()

The new() method is used to set a parent path for the url supplied. This parent path will only be adopted by relative urls. This is shown below.

 <?php 
 
 Ress::new('res/') // set a parent path

    ->url('file1.css')  # res/file1.css

    ->url('file2.js')   # res/file2.js

    ->new('')  // change parent path

    ->url('file3.css')  # file3.css

    ->url('http/site.com/some-link/file3.css'); // not affected

The sample above clearly explains the relationship between the new() and the url() method. The parent path will be added to only the relative urls.

Method: Ress::urx()

The urx() method is used to escape the predefined parent path. This is shown below:

 <?php 
 
 Ress::new('res/') // set a parent path

    ->url('file1.css')  # res/file1.css

    ->url('file2.js')   # res/file2.js

    ->urx('src/file3.css')  # src/file3.css

    ->url('http/site.com/some-link/file3.css'); // not affected

From the sample above, while "file1.css" and file2.js will inherit the parent path "res/", the file3.css will not be affected by the parent path. The urx() method is similar to the Res::xurl() method.

Method: Ress::named()

The named() method is used for naming urls similarly to the Res::named() method. When declaring resources, it is important to define unique names for urls. This makes it easier to perform complex operations like merging of resources.

 <?php 
 
 Ress::new('res/') 

    ->url('file1.css') -> named('file1')

    ->url('file2.js') -> named('file2')  

    ->urx('src/file3.css') -> named('file3') 

    ->url('http/site.com/some-link/file3.css') -> named('linkfile3');

From the sample above, each declared url is named with a unique name which will make it easier to perform url merging and importation.

Method: Ress::bind()

The bind() method binds the unique names of either urls or group of urls together into a new unique name. An example of this is shown below:

 <?php 
 
 Ress::new('res/') 

    ->url('file1.css') -> named('file1')

    ->url('file2.js') -> named('file2')  
    
    ->urx('src/file3.css') -> named('file3') 
    
    ->url('http/site.com/some-link/file3.css') -> named('linkfile3'); 

    // bind "file1" and "file2" into "files"
    -> bind('files', ['file1', 'file2'])
    
    // bind "files" and "file3" into "all-files"
    -> bind('all-files', ['files', 'file3']) # bind "file1" and "file2" into "files"

From the sample above, two unique group names were created. The first unique group name "files" contains both "file1" and "file2" while "all-files" will contain "file1", "file2" and "file3". The relative parent path of each url will be remembered during importation.

Method: Ress::bindTo()

The bindTo() method is used for binding a list of currently declared urls together under a new group name. Once this method is declared, the previous lists will be removed for a new url group listing. An example is shown below:

  <?php 
 
  Ress::new('res/') 

     ->url('file1.css') -> named('file1')
 
     ->url('file2.js') -> named('file2')  
     
       -> bindTo('files1') // bind file1, file2
     
     
     ->urx('src/file3.css') -> named('file3') 
 
     ->url('http/site.com/some-link/file3.css') -> named('link'); 

       -> bindTo('files2') // bind file3, link

From the sample above, each url list is saved until the bindTo() method is called which automatically defines a new unique name for the list of previously declared urls while reseting the urls list. The major advantage of bindTo() over the bind() method is that it can combine new named urls into existing names and can also perform the role of bind() method. An example is shown below

  <?php 
 
  Ress::new('res/') 

     ->url('file1.css') -> named('file1')
 
     ->url('file2.js') -> named('file2')  
     
       -> bindTo('files', ['file1', 'file2']) // bind file1, file2
     
     
     ->urx('src/file3.css') -> named('file3') 
 
     ->url('http/site.com/some-link/file3.css') -> named('link'); 

       -> bindTo('files2') // bind file3, link

From the sample above, the first bindTo() method is used to perform the role of bind() method. In this situation, the url listing is never being reset unless a single argument is supplied as in the case of bindTo('files2'). Also, unlike the bindTo() that can only be called once for a unique name, the bindTo() method can be used more than once. This is shown below:

  <?php 
 
  Ress::new('res/') 

     ->url('file1.css') -> named('file1')
 
     ->url('file2.js') -> named('file2')  
     
       -> bindTo('files', ['file1', 'file2']) // bind file1, file2
     
     
     ->urx('src/file3.css') -> named('file3') 
 
     ->url('http/site.com/some-link/file3.css') -> named('link'); 

       -> bindTo('files', ['file3']) // add 'file3' to existing 'files'

It is important to note that urls will be imported in the order in which they are defined and two similar file urls are never added more than once when resolved into the webpage.

Method: Ress::pull()

This is a new method added for both the previous and the new static resource url resolver classes Resource and Ress. It makes it easier to pull a resource configuration file from any directory in the project application. Since static configuration files are PHP files, they file extension names are not defined. The following is a sample configuration file expected to be pulled.

src/design.php

  <?php 
 
  Res::new('res/') 

     ->url('file1.css') -> named('file1')
 
     ->url('file2.js') -> named('file2')  
     
       -> bindTo('files1') // bind file1, file2
     
     
     ->urx('src/file3.css') -> named('file3') 
 
     ->url('http/site.com/some-link/file3.css') -> named('link'); 

       -> bindTo('files2') // bind file3, link

From the sample above, we configured a resource template file design.php within an src/ directory. The sample below shows how to pull these design rules.

  <?php 

  namespace \spoova\mi\windows\Routes;

  use Routes;
  use Ress;

  class Home extends Routes {

    function __construct() {

      Ress::pull('src.design'); // pull resource config file

    }

  }

The sample above will pull the design rules from the specfied path src/design.php. Now, we can easily import these resources using the Ress::import() method.

Method: Ress::import()

This method is used to import specific static resource files into the web application after they have been previously declared. A sample of this is shown below:

  <?php 

  namespace \spoova\mi\windows\Routes;

  use Routes;
  use Ress;

  class Home extends Routes {

    function __construct() {

      Ress::pull('src.design'); // pull sample resource config file

      $import = Ress::import(); // compile and import scripts

    }

  }

From the sample above, we pulled a configured resource declaration file from the relative path supplied. The Ress::import() is then used to compile and return the compiled scripts. Aside from pulling from Ress class declarations, we can also pull from a file returning an array. This is shown below.

windows/designs/theme.php

  <?php 

  return  [
    
    'designCss' => 'res/css/design.css',
    'designJs'  => 'res/css/design.css',
    'designs'   => ['designCss','designJs']

    ];

The sample above is one in which the design file theme.php was added into a windows/designs directory. The array key in the file above specifies the defined unique name of the resource file expected to be compiled while the value supplied is the relative file path or external static resource link itself. The array key "designs" is a unique name that is used to bind "designCss" and "designJs" unique names together into a new group. Now, we can import the resources by specifying the unique group to be imported. This is shown below:

  <?php 

  namespace \spoova\mi\windows\Routes;

  use Routes;
  use Ress;

  class Home extends Routes {

    function __construct() {

      Ress::pull('windows.design.theme'); // pull sample resource config file

      $importJs = Ress::import('designJs'); // compile 'designJs' and return script 
      $importCss = Ress::import('designCss'); // compile 'designCss' and return script
      
      $importDesigns = Ress::import('designs'); // compile 'designs' and return scripts
      
      $importMulti = Ress::import(['designJs', 'designCss']); // compile multiple names and return scripts 

    }

  }

The sample above shows different ways in which the unique resource url or url group names can be used to import the relative files attached to those names. It is however important to note that once a unique group name has been imported once, it cannot be imported again. Going by this, the $importDesigns and $importMulti above will return an empty value given the fact that they contain unique names that have already been imported earlier. Also note that unlike Res::import() class which uses the colon to specify groups to be imported, the Ress::import() uses the unique name explicity without any prefix colon.

Configuring Preferred Resource Handler.

By default, spoova uses the res/res.php as a top level static resource urls configuration file. This means any resource pulled within that file will be available automatically in routes. This configuration was being handled previously by the Res class. However, starting from spoova version 2.6, the configuration is now being handled by the Ress class. This new improvement is responsible for the addition of a new bridge function import() which is used import static resources based on the preferred resource handler between the old Res and the new Ress classes. Unlike Ress which is specifically used for static resources, the old Res class is used to perform other functions which is why it is not entirely replaced. By default, the newly introduced import() function uses the new Ress class to import its resources and this is also reflected in the res/res.php file. However, spoova still give options for developers to specify which resource handler class is expected to be used as default by manually configuring the icore/init file or by easily by running the command below from the command line which does the same thing.

  > php mi initConfig RESOURCE_HANDLER Res

The command above will switch to the old resource handler Res class. Once, this is done, the res/res.php should be manually updated to reflect these changes.

Importing Static Resources In Templates

Although, the resource handler classes have method such as import() or recall() that is used to import static resource files and the introduction of the import() function makes it easier to import static resources easily regardless of the resource handler classes preferred yet, in most cases when working within template files, the template directives such as @import() and @load() will be used to import from the resource handler chosen. The directive @import() is discussed here while the @load() directive is discussed here here while the