Docs Wvm Template Directives Import

Template directive: Import

This @import() directive has been introduced in the earlier versions of the framework. The main purpose of directive is to import all stored static resource urls handled by the Resource class from the res/res.php file. This Resource class features is inherited by the Res class which is later used in the res/res.php file. The url links of local or remote files are stored as groups and later imported into the web page by calling the group name. A simple example of this is shown below:

Sample: Url Storage in res/res.php file
  Res::name('my-scripts') //set a group name
     ->url('res/css/file.css') //set relative path to a css file
     ->url('res/js/file.js') //set relative path to a javascript file
     ->close() //close group declaration
Sample: Template File Scripts Importation
<head> @import(':my-scripts') </head>
From the sample above, the res/res.php file is loaded internally. Once configured, the stored urls will be imported when the @import() directive is applied. This directive is equivalent to the Res::import() method. However, the issue with url stored in this way is that urls are validated at declaration and the internal merging of groups took extra resources. This also means that urls that are not needed may end up consuming more resources because they were initially handled as separate entities and groups. The version 1.5 of the framework sees to it that urls were uniquely named to make it easier to control the urls. This led to the introduction of the @load() directive which made it easier to merge groups due to introduction of new methods like bind() and bindTo() on the Resource class. However, the immediate validations of urls still caused issues. Starting from version 2.6, a more subtle approach is used to reduce url validations to only the required urls by a web page. This new behaviour has led to an upgrade in the way that @import() directive works. The new update now uses a different resource handler class Ress to render urls. This class is much faster, flexible and even makes it easier to build or generate custom theme files for web pages. We suggest to visit Ress documentation to learn more about the usage of this class. The import() new function that comes with this update is now being used by the @import() to import static urls.

Import directive 2.6+
From version 2.6+, the @import() can be used to import theme files and url groups into the web page. By default, the res/res.php file is still accepted as the default url storage file. This means that all url and url groups declared from this root design file will still be accesible by the @import() template directive. A sample of this is shown below
import()
  <?php
  
  Ress::url('file1.css')->named('f1-css') //declare url with unique group name  
      ->url('file2.css')->named('f2-css') //declare url with unique group name  
      ->url('file1.js')->named('f1-js')   //declare url with unique group name  
      ->url('file2.js')->named('f2-js')   //declare url with unique group name  

      ->bind('f1-scripts', ['f1-css','f1-js'])//bind groups to new unique group name  
      ->bind('f2-scripts', ['f2-css','f2-js'])//bind groups to new unique group name
From the above, assuming the url declarations and storage was made in the res/res.php file, we can easily import the resolved scripts into any of our template files using any of the methods below: 
  <head>
  @import('#f1-css') // import url found in group name
  @import(':f1-js')  // import url found in group name
  @import(':f2-scripts') // import all urls found in group name 
  </head>
The importations above is made possible because all unique names or group share the same storage space. This means that a unique name can only be used once for group. Either the hash # or the colon : can be used for importing a group name just as seen above. The beauty of the @import() directive is that we can easily pull a design file from any folder within our web application aside from the default res/res.php file. This feature is possible due to the new method Res::pull() or Ress::pull() introduced into the static resource handler classes. This example is shown below:
Sample file: path/theme.php 
  <?php 

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

    ];
                    
  <head>
    @import('path.theme')  // extend to theme.php file
    @import('#designCss')  // import the specified group name
    @import('#designJs')   // import the specified group name
  </head>
From the illustration above, the first importation directive was done to extend to the path/theme.php file after which the desired groups were loaded into the template file by calling the url group name. This can also be done on a single line as shown below: 
  @import('path.theme:designCss,designJs')

Setting Parent Directory
The new update made to the resource handler classes makes it possible to set a default parent directory where all resource storage files can be accessed from. This configuration is done within the icore/init configuration file. We can easily setup a default parent directory by running the sample mi command below : 
  > php mi resource_path windows.designs
Once configured, the @import() directive will attach the configured parent directory as prefix to all relative urls supplied. For example, in reference to the path defined above, the Resource handler classes will remember to look within the windows/designs directory for all design files since this directory will become the root directory for importing files.

Docs Wvm Template Directives Import