Taeluf.com

Liaison App (aka Package)

A Liaison app can include routes, views, methods, hooks, and more. You can include as few or as many parts as you like.

Apps typically do one of two things: create features for other apps to use or implement features other apps provide. Most features are created through Addons. Most features are implemented through directory structures & configurations.

Also See:

Through these examples, we'll build a fully functional Liaison app.

Sections of this document

  • Directory Structure
  • config.json
  • Routing
    • Files
    • addRoute()

TODO:

  • Views
  • Addons
  • Hooks
  • Seo Headers
  • Css & Javascript files

App Directory Structure

You can include one, multiple, or all of these files & directories.

App/
    - config.json <- Package settings
    - public/ <- Public files to be routed to. 
        - index.css
        - index.php <- home page
        - contact.php <- /contact/
    - view/ <- Views
        - theme.php <- site layout
        - theme.css
    - addon/ <- Addons (extend \Lia\Addon)
        - MyAddon.php
    - class/ <- Classes to autoload, PSR4 style, but you should use composer instead.

Note: You don't need to make any files until you're ready for them.

config.json

config.json is optional & there are likely to be breaking changes.

@file(test/input/sample_config.json)

Notes:

  • namespace does nothing currently. It was supposed to, but we're actually using name and fqn. We will likely change this.
  • the Server package loads the configs & for any config that has a matching property on the package class will overwrite that property.

Routing

Routing is available through your public dir, and through $lia->addRoute('/pattern/{slug}/', callable).

To test:

  1. Create deliver.php following the Web Server Documentation
  2. php -S localhost:3000 /deliver.php

/public/ Files

/public/index.php: (Your home page /)

<?php
    // add a css (or js) file to the page. Files of the same type are compiled together.
    $lia->addResourceFile(__DIR__.'/index.css');
    // public_file_params from your config.json are available here 
?>

<h1>Elections in My Town, Some State</h1>
<p>My Town's city council & school board elections are approaching soon! The school board race is cotentious with only 3 seats available, but 7 candidates running - some with very different perspectives. ...</p>

<?php 
// $lia->view('elections.php', $args=[]); # We'll use this later.
?>

/public/index.css:

h1 {
    font-size:1.6em;
    margin:0;
    padding:8px;
}
p {
    max-width: 80ch;
    padding: 12px;
}

Visit http://localhost:3000/.

Note: Public files can also use patterns, like public/election/{slug}/, just like programmatic routes below.

$lia->addRoute()

Routes can be added programmatically with or without paramaters, and can point to a callable or a file.

Also See:

  • @see(docs/api/code/class/Objects/Route.php.md, Lia\Obj\Route)
  • @see(docs/api/code/class/Objects/Response.php.md, Lia\Obj\Response)
<?php
// \Lia $lia
$lia->addRoute('/election/2023-city-council/', 
    function(\Lia\Obj\Route $route,\Lia\Obj\Response $response) use ($lia){
        $response->content = $lia->view('office', ['year'=>'2023', 'election'=>'city-council']);
    }
);

// or you can use paramaters
$lia->addRoute('/election/{year}/{$name}/', 
    function(\Lia\Obj\Route $route,\Lia\Obj\Response $response) use ($lia){
        $response->content = $lia->view('office', 
            [
                'year'=>$route->param('year'), 
                'election'=>$route->param('name')
            ]
        );
    }
);

//optional paramaters don't have to be at the end.
$lia->addRoute('/candidate/{uuid}/{?slug}/', ...);

// only allow post requests (also works with a callable)
$lia->addRoute('@POST./submit_voter_opinion/', 'path/to/some/file.php');

// allow get & post
$lia->addRoute('@GET.@POST./candidate_questionnaire/', 'path/to/some/file.php');

Notes:

  • Routes are retrieved from @see(docs/api/code/addon/Router.php.md, Lia\Addon\Router), and processed in @see(docs/api/code/addon/Server.php.md, Lia\Addon\Server); see process_route().
  • addRoute accepts a third paramater, which is passed to files as the variable $package; it is not available in callable routes.

Views - /view/

View Directories

  • view help/errors resides at $view_dir.'/help/errors.php' and may have errors.css and errors.js next to it that will be automatically included
  • TODO: Document more and better

Add Views

  • Add view files into existing view directories
  • $lia->addon('lia:server.view')->addViewFile('view_name', 'path/to/file.php'), file.php should output content
  • or $lia->addon('lia:server.view')->addViewCallable('view_name', function(string $view_name, array $args){ return 'content';});
  • or $lia->addon('lia:server.view')->addView('view_name', '/views/directory/')

Addons Lia\Addon

TODO - fill in view docs for libraries

Hooks

Hook into an event:

<?php
// DASHBOARD_DISPLAYED is a string constant and is part of another library 
$lia->hook(\Tlf\User\Hooks::DASHBOARD_DISPLAYED,
    // Each hook defines it's own function signature (essentially by passing the correct paramaters when calling the hook)
    function(\Lia $lia, \Tlf\User\EasyServer $server){
        // may contain css to switch to a full-width page to better display the dashboard
        $lia->addResourceFile(dirname(__DIR__).'/file/user-dashboard.css');
    }
);

// Alternatively:
// $lia->addon('lia:server.hook')->add(DASHBOARD_DISPLAYED, function(){});

Call a hook:

<?php
// each arg after the hook name is passed directly to each registered callable.
$lia->call_hook(\Tlf\User\Hooks::DASHBOARD_DISPLAYED, $lia, $easy_user_server);

// Alternatively:
// $lia->addon('lia:server.hook')->call(DASHBOARD_DISPLAYED, $lia,$easy_user_server);

SEO Headers

TODO

Css & Javascript files

TODO