Method Hooks

purpose

Manipulate the content of DOM elements with ff functionality

usage

If ff finds a php class with the same name as your template file, it will be used for method hooks: presenter/myPresenter.html, presenter/myPresenter.php.
This php class needs to extend the ffPresenter class: class myPresenter extends ffPresenter{}.

The return value of a public method of that class, which name matches with the data-ffMethod value of an element of your template will modify said element.

short notation

file myPresenter.html

file myPresenter.php

<?php
class myPresenter extends ffPresenter {
    public function myMethod() {
        return 'hello, world';
    }
}

This will call the method "myMethod" of your presenter class and will inject the string "hello, world" into the div. The browser receives:

<div>hello, world</div>

passing arguments

You can pass the (optional) args property, that will be passed to the method.

string notation

class myPresenter extends ffPresenter {
    public function myMethod($DOMNode, $foo) {
        return 'hello, ' . $foo;
    }
}

myMethod will receive "foo" as the second argument.

array notation

class myPresenter extends ffPresenter {
    public function myMethod($DOMNode, $foo, $bar) {
        return 'hello, ' . $foo . ' and ' . $bar;
    }
}

myMethod will receive "foo" as the second, and "bar" as the third argument.

object notation

<div data-ffMethod='{"name":"myMethod", "args": {"foo": "bar", "bar": "baz"}}'></div>

class myPresenter extends ffPresenter {
    public function myMethod($DOMNode, $foo) {
        return 'hello, ' . $foo['foo'] . ' and ' . $foo['bar'];
    }
}

myMethod will receive named arguments as an associative array as the second argument.

hook into other presenters

<div data-ffMethod="anotherPresenter::itsMethod"></div>
<div data-ffMethod='{"name":"anotherPresenter::itsMethod"}'></div>
<div data-ffMethod='{"name":"anotherPresenter::itsMethod", "id":"itsId"}'></div>

combine multiple hooks in one element

You can bind multiple method calls to the same element.

<div data-ffMethod='[{"name":"myMethod1","args":{}}, {"name":"myMethod2","args":{}}]'></div>

options

{
  "name" : null,   // name of the public method to hook into
  "args" : null,   // (optional) arguments that are passed to the method. takes string, array or objects
  "mode" : 'inner' // (optional) Define the mode, in which the returned string replaces the existing node.
                   // 'inner' return value replaces the innerHtml of the node
                   // 'outer' return value replaces the node itself (needs to be valid html)
                   // 'append' return value is appended to the innerHtml of the node
                   // this option is ignored, if the method returns anything other than a string.
                   // for legacy reasons, this option can also be a boolean,
                   // where 'false' equals to 'inner' and 'true' equals to 'outer'
}

return values

The return values of the method may be of various types:

(string): innerHtml of DOMNode gets replaced (unless the template specifies a "mode" option):

class myPresenter extends ffPresenter {
    public function myMethod() {
        return 'hello, world';
    }
}

(?bool) true or null: no changes to DOMNode:

class myPresenter extends ffPresenter {
    public function myMethod() {
        return true;
    }
}

(bool) false: DOMNode gets deleted:

class myPresenter extends ffPresenter {
    public function myMethod() {
        return false;
    }
}

(array):
- first argument should be one of the three types as described.
- the second (optional) argument holds an associative array with key-value pairs of HTML attributes to set/overwrite. If the key is class or style, the values will append to existing values. If the value is boolean false, an existing attribute will be removed
- the third (optional) bool element defines, if the content of first element overwrites the node itself (true), or inserts inside the node (false, default). If true is used, make sure that the output of the method is already a valid dom element string (<div>...</div>)

class myPresenter extends ffPresenter {
    public function myMethod() {
        return [
            'Hello, world',
            [
                'class' => 'foo',    // will append "foo" to existing classes
                'data-foo' => 'bar', // will set the data-foo="bar" attribute
                'data-bar' => false  // will remove the data-bar attribute
            ]
        ];
    }
}

direct manipulation of the DOMElement

Since the DOMElement is passed to the method as the first argument, the method can also be used to directly manipulate the DOMElement itself.

class myPresenter extends ffPresenter {
    public function myMethod(DOMElement $el) {
        $el->setAttribute('foo', 'bar');
    }
}

12 März 2024