@export(old.About.Liaison)

Liaison

Liaison ties everything together. Packages & their components, view lookups, config values, routing, events, and more??

Basic Usage

$lia = new \Liaison();  
$lia->addPackage(  
    ['dir'=>__DIR__.'/my-package/',  
     'name'=>'MyPackage'  
     ]  
);  
$lia->deliver();  

This will load files from your package and route appropriately.

$lia, Methods to know

• deliver($url=null)
  • uses the requested url by default, but you can pass in a url, which may include a get string like ?cats=cute
• addPackage($options): $options is an array
  • dir: The root directory of your package
  • name: The name to be used for retrieving your package.
    -Each package must have a unique name
• package($name): retrieve a package by name
• packages(): A list of packages
• compo($name): For each package, get any components named $name.
  • 0 components found, return null, 1 component found, return the component, 2+ components found, throw an exception
• set($key, $value) & get($key,$valueIfNotFound): Store & retrieve values across the $lia instance
• view($name, $passthru): Get a view (from any package) by $name, passing $passthru to the view.
  • See Views for more information
• register($eventName, $object, $method=null): Register the event to be executed
• send($eventName,$arg1, $arg2, $arg3, ....): Execute the given event, passing the list of args along.
  • See Events

@export(TODO.RouteObject)

• Document the route object

@export(Old.View.Base)

The View Object

• Each package can implement their own view object and method of handling data. The following docs regard \Lia\View, used in the base package.
• Generally, retrieve a view through liaison or the ViewHandler component.
  • You may also do new \Lia\View($viewPath,$data,$liaisonObject,$viewName=null), such as if you're creating your own package implementation.
• Data passed in (through lia OR the constructor) will be extract()ed
• The content is loaded in the constructor
• Resources are loaded into liaison during the constructor. So you just call $lia->view($viewName), if all you want is to use the associated css & javascript resources.
  Display your view with echo $view

View Structure

We have a view named "Form/Blog" at view/Form/Blog/. All your views go in the view directory and the path to the relative path to the view is it's name.

view/Form/Blog/  
 - init.php: (optional) code to run before the template  
 - template.php: (recommended) The PHP file to load, this is your html layout for the most part  
     - template.php & init.php are in the scope of the \Lia\View object that loads the files. Therefore, `$this` refers to the view object  
     - $lia, the Liaison object, is also available  
     - Uninentionally, $viewPath, $data, $viewName, & $path are available, but you should not rely on them. They will likely be removed.  
 - template.html: If a template.php file is not present, then template.html will be used.  
 - css/ (optional)  
     - BlogEditorStyle.css  
 - js/ (optional)  
     - BlogAutosaver.js  

You don't actually have to have a template. css & js resources will still load

Every css file in the css dir will be found and added to liaison through the Red_AddStyleFile event, which passes the absolute file path along to the event.
Same for js, but Res_AddScriptFile.

@export_end(Usage.Package.DefaultConfigs)

protected $config = [
'dir'=>
[
'component' => 'core',
// 'public' => 'public',
'autoload'=> 'class',
'view' => 'view',
'cache' => 'cache',

        'public'=>[  
            'dir' => 'public',  
            'baseUrl'=> '',  
        ]  
    ],  
  
'route'=>  
    [  
        'force_trail_slash'=>true,  
        'index_names'=>  
        [  
            'index'  
        ],  
        'hidden_extensions'=>  
        [  
            'php'  
        ],  
    ],  
'class'=>  
    [  
        'view' => '\\Lia\\Obj\\View'  
    ],  
'views'=>  
    [  
        'conflict' => 'throw'  
    ]  

];

@export(old.Event.Class)

Events are the primary way that different packages and different parts of a package communicate with one another.
Any component (using the base package) may declare onNamespace_EventName($event,$arg1,$arg2,....) to automatically have the event registered when the package is added.
Namespaces aren't entirely required, but it's better that way.

Each Event callable will receive an $event object. This object is always the same \Lia\Event component object. This needs to be improved.

@export(old.Event.register)

• register($eventName, $object, $method=null): Register the event to be executed
  • if $method is null, $object MUST have a method 'on$eventName'
  • if $method is a string, the a callable will be stored as [$object, $method]
  • Uses the Event component of the base package
  • The first paramater of your callback must take an $event object (which is poorly implemented)
  • It may accept any paramaters after that, as specified by the registered event
  • This might be renamed soon
• send($eventName,$arg1, $arg2, $arg3, ....): Execute the given event, passing the list of args along.
• has($eventName): check if event has been registered.

@export(old.Event.Events_Sort)

When an event has multiple methods registered to it, the Events_Sort event is called, to allow you to filter which methods to execute.
If you implement the Events_Sort event, you must return an array of all the events that should be executed.
Your method should be like:

onEvents_Sort($event,$EventName,$argsArray,$arrayOfEvents){  
    //unset one of the events because... the dog barked  
    return $arrayOfEvents;  
}  

If there are multiple methods registered to Events_Sort... that's bad. It'll break stuff

@export(old.Events.ReturnValue)

Return values from an event call depend upon how many events are registered and what they return.

• 0 registered events: Return null
• 1 registered event: Return the exact value returned by that event
• 2+ registered events: Any return value === null will be discarded
  • all other return values will be added to an array
  • That null-filtered array will then be re-checked for 0 or 1 values
  • If the null-filtered array has more than 1 value, an array of return values will be returned, in no intentional order.

You may further refine this by registering to the event "Resolve{$EventName}".
The resolve event will also follow the return value rules as listed here, so you could potentionally have an event like 'ResolveResolveResolveTooManyRegistered'.
Like, please don't do that? Lol. But you caaannn... I think.

@export(old.Resources.Events)

Resources are stored through events & subsequently printed through them.

• You must do $lia->set('Resource.tempDir',$tempDir) and $lia->set('Resource.pubDir', $pubDir).
  • The tempdir stores meta information about files (to prevent unnecessary recompilation)
  • The pubdir is where your compiled files saved (and subsequently loaded from during the request)
• Script (and style) files are output in the order they're received. This is bad, but it's how things are right now.
• You MAY set $lia->set('css.forceRecompile',true) and/or $lia->set('js.forceRecompile',true) to force a recompile.
  • file mod times are used to check if files need to be recompiled... but that can be finicky. This is also pretty inefficient.
• Nothing is minified, and file paths are put in comments in your compiled sheets... for debug reasons... another thing to fix.

The Resource-related events are:

• Meta Info:
  • Res_SetPageTitle($title): Set the title for a given page
• Styles:
  • Res_AddStyleFile($filePath)
  • Res_AddStyleCode($cssCode)
  • Res_AddStyleURL($url)
• Scripts:
  • Res_AddScriptFile($filePath)
  • Res_AddScriptCode($jsCode)
  • Res_AddScriptURL($url)
• Output:
  • Res_PrintHeadResources: This compiles the resources and prints them out. Generally this event call would go in your section

Remember that Each event handler receives $event as the first paramater

@export(old.Route.rawFile)

Routed files not otherwise handled will be sent, with the correct headers, including browser caching headers.
Example: For file public/funny/kitty.png, url /funny/kitty.png will deliver the image file, as you would expect.
Mimetypes (for headers) are derived from a PHP file internal to Liaison. It's not particularly efficient.