Customizing Flick

Flick is highly customizable, making it easy to add your own assets; including forms, dropdowns, views, and translation (language) files.

• Dropdowns
• Forms
• Translations
• Views

Adding Your Own Assets

To use your own assets, you'll need to tell flick where they're stored. You do this by creating an "assets" directory and telling Flick where that directory is via the $config array.

For clarity, let's call the assets directory myFlickAssets. Flick will go into myFlickAssets and look in the following directories for your files. If those files are not available, Flick will look for default files with the same name, or throw an error if they're not found.

You don't need to add all of these directories; only the ones required for your form.

myFlickAssets/
 ├─ dropdowns/  <- put your dropdowns here
 ├─ forms/      <- put your forms here
 ├─ lang/       <- put your language files here
 └─ views/      <- put your view files here

Dropdowns

A dropdown file is an array used to build a <select> menu. This is really handy as you can build up a library of menus for various forms, then drop them into the dropdowns directory, and they're ready to be included in your form.

Each dropdown list is contained in a single file, with the filename being the name of the list. If we wanted to create a list of books, we could do it like this.

1. Create a file inside myFlickAssets/dropdowns and name it books.php

myFlickAssets
 ├─ dropdowns
 │   └─ books.php

2. Add an array to books.php, with the key being the item's value.

<?php

return [
    'the-stand' => 'The Stand',
    'not-dead-yet' => 'Not Dead Yet',
    'the-iliad' => 'The Iliad',
    'steve-jobs' => 'Steve Jobs',
    'based-on-a-true-story' => 'Based on a True Story'
];

3. Now, call your list when creating a form by entering its filename as a string.

In this example we're using the select() method, so we'll add our list to the fourth parameter as a string.

$form = new Flick([
    'assets' => 'myFlickAssets'
]);

$form->select('book', 'Favorite Book', '', 'books');

4. Here's your list.

<select name="book" id="book">
    <option value="the-stand">The Stand</option>
    <option value="not-dead-yet">Not Dead Yet</option>
    <option value="the-iliad">The Iliad</option>
    <option value="steve-jobs">Steve Jobs</option>
    <option value="based-on-a-true-story">Based on a True Story</option>
</select>

(Output simplified for clarity — the actual markup also includes your view theme's wrapper div, label, and CSS classes.)

We can also add our list to the create() method and get a similar result...

$form = new Flick([
    'assets' => 'myFlickAssets'
]);

$form->create('Favorite Book|select(books)');

Forms

Along with prebuilt dropdown lists, you can also prebuild entire forms. This works in pretty much the same way as dropdowns with a couple of slight differences.

1. Create a file inside myFlickAssets/forms and name it subscribe.php

myFlickAssets
 ├─ forms
 │   └─ subscribe.php

2. Add a form array to subscribe.php

<?php

return [
    'action' => '/',
    'method' => 'POST',
    'attributes' => [
        'id' => 'form-subscribe'
    ],
    'button' => [
        'text' => 'Subscribe'
    ],
    'fields' => [
        'email' => [
            'type' => 'email',
            'name' => 'email',
            'label' => 'Enter Your Email to Subscribe',
            'rules' => ['required', 'email'],
            'messages' => ['required' => 'Please enter a valid email']
        ]
    ]
];

3. Now add the filename to Flick's create() method and prepend it with a forward slash. The slash tells Flick to use a prebuilt form.

$form = new Flick([
    'assets' => 'myFlickAssets'
]);

$form->create('/subscribe');

4. Here's your form.

<form action="/subscribe.php" method="POST" id="form-subscribe">
    <input type="hidden" name="_id" value="form-subscribe">
    <input type="hidden" name="_token" value="...">
    <label for="email">
        Enter Your Email to Subscribe
    </label>
    <input type="email" name="email" id="email">
    <button type="submit">Subscribe</button>
</form>

(Output simplified — theme wrappers and classes omitted. An 'action' => '/' in the form file posts back to the current page, so the rendered action is the current script's path. The hidden _id and _token fields are always rendered: submitted() matches on _id, and _token is the CSRF token.)

Translations

Flick supports localization by allowing you to create translation files and drop them into the lang directory. A translation file consists of form validation messages (which you can also override when creating a form) and general error messages — including the messages Flick Pro's services show your users. The default language is English (US).

Creating a Translation File

Let's create a Spanish translation file in our assets directory to see how this works.

1. Create a new directory in the assets directory and name it lang

myFlickAssets
├─ lang

2. Create a new directory in the lang directory and name it es

myFlickAssets
├─ lang/es/

3. Copy both files from vendor/flickphp/flick/lang/en/ into the es directory.

myFlickAssets
├─ lang/es/messages.php
└─ lang/es/rules.php

4. Translate the text, leaving the array keys in English.

rules.php returns the per-rule validation errors:

return [
    'required' => 'El campo :key es obligatorio',
];

messages.php returns Flick's own notices, and — if you use Flick Pro — the messages its services put in the error bag. Those keys are prefixed with the service name (Otp, Throttle, ReCaptcha, Turnstile, Upload, Mail); there is no separate Pro translation file. Some carry :placeholders that Flick fills in, such as :count or :size — keep them in your translation. The shipped vendor/flickphp/flick/lang/en/messages.php lists every key.

return [
    'MessagesHeader' => 'Por favor corrija los siguientes errores:',
    'SessionHasExpired' => 'Su sesión ha expirado. Actualice la página.',
    'OtpCodeIncorrect' => 'El código es incorrecto.',
    'ThrottleTooManyAttempts' => 'Demasiados intentos. Inténtalo de nuevo en :wait.',
];

5. Finally, point Flick at your assets directory and the language you want.

$form = new Flick([
    'assets' => __DIR__.'/myFlickAssets',
    'lang' => 'es'
]);

Views

You can create your own view files too. As before, add your own views to the myFlickAssets/views directory and you're done. Flick will look for your views, and will load the default views if yours are not found.

The recommended way to get started is to copy the .view.php files out of the theme folder you use (e.g. vendor/flickphp/flick/resources/views/flick/) directly into myFlickAssets/views/, then modify as desired.

myFlickAssets
 └─ views
     ├─ input.view.php     <- overrides the default input view
     └─ select.view.php    <- overrides the default select view

Read more about using views in the Views docs.