#Meta

Refine is a paid package. To purchase, head to hammerstone.dev.

Every application is going to have different needs regarding what data needs to be sent to the frontend. To accommodate for that, we've provided a withMeta function that allows you to attach any arbitrary information to a condition.

#Attaching Meta

Consider the scenario where you want to send hint text to your frontend to display in the UI. There is no out of the box feature for that, but you could accomplish that by putting the information into the meta array, like so:

TextCondition::make('name')
    ->withMeta([
        'hint' => "The employee's first and last name."
    ]);

Now when the condition is sent to the frontend, it will include the hint in the meta key:

{
    "id": "name",
    "display": "Name",
    "type": "text",
    "meta": {
        "hint": "The employee's first and last name."
    }
}

Now you can use this hint value anywhere you want on the frontend.

If you're only adding a single piece of meta, you can pass the key as the first parameter and the value as the second:

TextCondition::make('name')
    ->withMeta('hint', "The employee's first and last name.");

#Calculated Meta

If you ever need to, you can pass a closure for the value using either style:

TextCondition::make('name')
    ->withMeta('something_complex', function() {
        // Some calculated value
    });
 
// Or...
 
TextCondition::make('name')
    ->withMeta([
        'something_complex' => function() {
            // Some calculated value
        }
    ]);

#Hiding Data From the Frontend

There may be times when you need to add something to a condition's meta but you don't want that information being sent out to the frontend.

Any meta key you prefix with an underscore gets removed before being sent to the frontend.

TextCondition::make('name')
    ->withMeta([
        '_secret' => 'Never makes it to the frontend'
    ]);

We take advantage of this underscore convention in the OptionCondition to separate the option's id and value. Go here to read more.

#Adding Macros

Following the example of "hint text" from above, you may find yourself creating conventions that utilize the storing of information in the meta key and decide that you need to formalize the convention.

Because the base Condition class uses Laravel's Macroable trait, you can extend the class's functionality without having to crack it open.

In our hint text scenario, you could use a macro to create a proper hint method.

Condition::macro('hint', function ($text) {
    return $this->withMeta('hint', $text);
});

Now you can just call hint and you don't have to futz about with adding it to meta every time, or potentially adding the meta under the wrong key.

TextCondition::make('name')
    ->hint("The employee's first and last name.");