Knowledge Base

• # Introduction
• # Installation
• # Flow
• # Config flow
• # Set local development
• # Command set release
• # Command set to latest version
• # Configuration
• # Pages

In this section we show how you can alter the UI to support custom configuration.

Backend

1. enable UI -> config/builders.php percictence.driver => DatabaseDriver::class
2. add ENV setting BUILDERS_CONFIG_API_HOST => https://fragrant-star-s1v5s6idv6z2.vapor-farm-d1.com/api <– default
3. add ENV setting BUILDERS_CONFIG_API_KEY => you can request one from the blueprint team.

Frontend Follow section UI pages (Read more)

1. You can create configurations on the test server or locally.
2. The config server is a separate project hosting the configuration of all projects
3. You add configurations to a release to get them on accept or production
4. While building the accept or production backend the configurations are downloaded to your project database
5. After creating a release you get a release version the release version in the config/builders.php is used in step 4
6. You see that nothing is saved in the test database. Only when you press the ‘Set local development’ button for a configuration.

To make it possible to test every scenario on the testserver the configs are not downloaded with every build. You need to do it manually, go in the UI to a version and press the button set local development As result the config is downloaded from the config server and stored in the test database.

Signature: blueprint:builder:set-release

Options

• wipe (default true) – remove al configurations from project database and replace it with configurations from release
• version (optional) – the release version, when not provided the release from the builders/config.php is used

This command downloads only the latest versions of the configurations for your project.

php artisan blueprint:builders:set-latest-configs

RELEASE

PERSISTENCE

CONFIG MANIPULATORS

UI PERMISSION SERVICE

CONFIG SERVER HOST

CONFIGURATION TYPES

CLASSFINDER SERVICES

UI FIELD DEPENDENCIES

UI TEMPLATE

UI LABEL POSITION

UI OPERATORS

UI INPUT TYPES

UI FILTER INPUT TYPES

UI COLUMN TYPES

UI ACTION TYPES

UI ACTION SUB TYPES

UI PAGINATION TYPES

FEATURE TEST

The release version. When building a new version the command blueprint:builders:set-release will use this version to fetch the release configs from the config server.

Here you can switch between DatabaseDriver (UI) or filesDriver

        'driver' => DatabaseDriver::class,

        // FilesDriver only: The location(s) the config can be found
        'file_locations' => [
            base_path('builder/configurations'),
        ],

Not every option is supporter inside the UI. To add certain option to an UI form you can register a manipulator.

This class should implement the ConfigurationManipulatorInterface or extend the abstract class ConfigurationManipulator

example

return [
    'form_edit_release' => FormEditReleaseManipulator::class,
];

Available methods

• parse() This method is called after retrieving the configuration from the database
• getConfig() -> returns the ConfigInterface
• getRawConfig() -> returns the config array
• setRawConfig() -> stores the array as raw config
• rebuild() -> parse the raw config array to the config interface again

Example raw config

parse(): ConfigInterface
{
    $this->alterSomething()
    $this->rebuild();

    return $this->config;
}

The service used to populate the permission dropdown. You can change the service or method to add custom permissions (like group permissions)

    'ui' => [
        'enabled' => env('BUILDERS_UI_ENABLED', false),
        'permission_service' => [
            'method' => 'list', // The method used to populate permissionService dropdown,
            'class' => PermissionServiceContract::class,
            'key' => 'name', // The key used in the list,
            'value' => 'name', // The value used in the list,
        ],
    ],

Define the title of the form. (translation key) Config server host and api key. Normally configured in the env settings:

`BUILDERS_CONFIG_API_HOST`
`BUILDERS_CONFIG_API_KEY`

Not supported right now. Will be used in the future

Often you need to select a backend service class. This dropdown is filled with the output of a class finder. With this configuration you can add or remove namespaces from the finder.

Example

    'classfinder_service_namespaces' => [
        'Emendis\Laravel\Complete\Module\Dxp\Domain\Services',
        'Capturum\Auth\Domain\Services',
        'Capturum\BaseData\Domain\Services',
        'Capturum\File\Domain\Services',
        'Capturum\HistoricalData\Domain\Services',
        'Capturum\Localization\Domain\Services',
        'Capturum\Property\Domain\Services',
        'Capturum\Setting\Domain\Services',
        'Capturum\Blueprint\Domain\Services',
    ],

The UI forms use dependencies to make the forms easier to use. When adding a new backend action sub type you need to see the action_class and method inputs.

Currently supported:

• edit action form

  return  [
  'edit_action' =>
      [
          'action_class' => ['action.type:backend', 'action.type:backend_confirmation'],
          'action_method' => ['action.type:backend', 'action.type:backend_confirmation'],
          'confirmation_text' => ['action.type:backend_confirmation'],
      ]
  ];

The form templates.

The label position options.

Default

• above
• before

The selectable filter operators.

The input types selectable in the form builder.

The filter types selectable in the list builder filter section.

The column types selectable in the list builder.

The different action types.

Default

• dot_menu
• on_row_click
• on_column_click
• bulk_action
• header_button

The filter sub types. This the place where you can add custom actions.

Default

• navigate
• open_popup
• open_sidebar
• backend
• backend_confirmation

The dropdown values for list settings pagination type.

Default

return [
     [
         'key' => 'paginated',
         'label' => 'Paginated',
         'value' => 'Paginated',
     ],
     [
         'key' => 'infinite',
         'label' => 'Infinite',
         'value' => 'Infinite',
     ],
];

Trait BuildersTestHelpers contains some important helper methods to test your config.

With this method you download the latest config version from the config server to the test database.

addBuilderConfigToDatabase($key) // Add config to the test database

$this->listBuilderKey = 'cars'; // set the list key
$this->formBuilderKey = 'cars'; // set the form key

$this->builderConfigList(); // retrieve a list
$this->builderConfigForm(); // retrieve a form
$this->builderSourceList(); // retrieve a list source
$this->builderSourceForm($id); // retrieve a form source
$this->builderSubmitForm($data); // submit a form
$this->addContextToQuery($query); // Add context from the contextManager to the query string
$this->getSourceUrl($key, $id, $context, $meta) // build a source url

Example

    /**
     * A basic test example
     *
     * @return void
     */
    public function testLoadConfig(): void
    {
        $this->addPermissionToRole('user.show');
        $this->addBuilderConfigToDatabase('cars');

        $this->listBuilderKey = 'cars';

        $response = $this->builderConfigList();

        $response->assertStatus(200);
    }

Default

return [
     [
         'key' => 'paginated',
         'label' => 'Paginated',
         'value' => 'Paginated',
     ],
     [
         'key' => 'infinite',
         'label' => 'Infinite',
         'value' => 'Infinite',
     ],
];

There are couple of selectors you can use in your application to view some predefined lists

• To view list of configs you can use <cpb-config-list></cpb-config-list>
• To view list of releases you can use <cpb-release-list></cpb-release-list>
• To view list of configs that are in project database you can use <cpb-project-database-config-list></cpb-project-database-config-list>