FreeScout Modules Dev

Modules allow to extend application functionality (just like WordPress plugins). Modules are developed using Laravel-Modules v2 package.

Documentation

Laravel-Modules Documentation

Sample Module

Sample FreeScout module is available here.

Module Naming

• Module folder name must be in a singular form (for example, TelegramNotification), it never changes and must be unique.
• Module alias in module.json is the identifier of the module, it must be equal to the module folder name, lowercase, it never changes and must be unique, no spaces allowed.
• Module name in module.json can be any unique text, it can be changed in future, no quotes allowed.
• To search modules in FreeScout use only \Module::findByAlias('modulealias') function, as other functions like Module::find('Name') are searching modules by name which may change.

In php artisan module:... commands use name (for example, "Sample Module").

To check in the main app if module is active: \Module::isActive('alias')

Step-by-Step Instruction

1. Generate module files in /Modules folder:

php artisan module:make SampleModule

where SampleModule will be the name of the module folder and module's alias.

2. Change parameters in module.json:

You can set any name as you wish. active parameter is not taken into account by the app, modules active flag is stored in DB modules table.

3. In generated server provide create a constant containing the alias of your module to use it in your module:

define('SAMPLE_MODULE', 'samplemodule');

You can give any name to your constant, just make sure that it is unique and that it is ending with _MODULE:

define('TELEGRAM_NOTIFICATION_MODULE', 'telegramnotification');
define('TN_MODULE', 'telegramnotification');

This constant can be used anywhere: in module controllers, views, etc.

4. Develop your module.

5. Run the following console command to create public symlinks and migrate DB:

php artisan freescout:install-module

Module Settings

Get module option:

\Module::getOption(SAMPLE_MODULE', 'title_max_length')

where the first argument is the module's alias from module.json, the second - option name.

Save module option:

\Module::setOption(SAMPLE_MODULE, 'title_max_length', 255);

Default module settings can be set in module's Config/config.php:

'options' => [
    'title_max_length' => ['default' => 90],
],

Actions and Filters

Modules interact with the application via actions & filters (read more).

Default priority is 20.

If you need to add some action/filter to the application to use in your module, just create a pull request.

Fire action:

Eventy::action('sample.action', 'awesome');

in blade:

@action('sample.action', 'awesome')

Process action:

Eventy::addAction('sample.action', function($what) {
    echo 'You are '. $what;
}, 10, 1);

\Eventy::addAction('sample.action', [$this, 'processAction']);

Run filter:

$value = Eventy::filter('sample.filter', 'awesome');

in blade:

@filter('sample.filter', 'awesome')

Process filter:

Eventy::addFilter('sample.filter', function($what) {
    $what = 'not '. $what;
    return $what;
}, 10, 1);

JavaScript localization and PHP variables

1. Add strings or variables to /Resources/views/js/vars.blade.php
2. Run php artisan freescout:module-build

Retrieving localized strings in JS:

Lang.get('messages.hello_world');
Lang.get('messages.hello_world', { name: 'Joe' });

Retrieving variables in JS:

alert(Vars.hello_world);

Routes

Routes configuration is located in /Modules/ModuleName/Http/routes.php

In order to have access to the route in JS, add laroute => true to the route:

Route::group(['middleware' => 'web', 'prefix' => 'samplemodule', 'namespace' => 'Modules\SampleModule\Http\Controllers'], function() {
     Route::get('/{id}', ['uses' => 'SampleModuleController@index', 'laroute' => true])->name('samplemodule_index');
});

Using in JS:

laroute.route('samplemodule_index', {id: 7'});

Public Assets

Module's public files can be added to the application in the module's service provider:

// Add module's css file to the application layout
\Eventy::addFilter('stylesheets', function($value) {
	array_push($value, '/modules/'.SAMPLE_MODULE.'/css/style.css');
	return $value;
}, 20, 1);

// Add module's JS file to the application layout
\Eventy::addFilter('javascripts', function($value) {
	array_push($value, '/modules/'.SAMPLE_MODULE.'/js/module.js');
	return $value;
}, 20, 1);

Extra service providers:

module.json:

    "providers": [
        "Modules\\SampleModule\\Providers\\ExtraProvider"
    ],

Service provider from module's vendor:

    "providers": [
        "\\Service\\Provider\\PathProvider"
    ],

and add to the main service provier:

// It has to be included here to require vendor service providers in module.json
require_once __DIR__.'/../vendor/autoload.php';

Packages Configs

Copy package config files into module's /Config.

Add to registerConfig():

$this->mergeConfigFrom(__DIR__ . '/../Config/package.php', 'package');

or

    public function overrideConfigs()
    {
        config([
            'package_config.param' => false
        ]);
    }

Console Commands

Add to service provider:

    public function registerCommands()
    {
        $this->commands([
            \Modules\SampleModule\Console\CommandName::class
        ]);
    }

Module Composer Dependencies

Module may include composer packages in it's composer.json:

    "require": {
        "rivsen/hello-world": "0.1.0"
    }

cd /Modules/SampleModule
composer update

Module's packages are stored in the it's vendor folder, committed and distributed with the module

If some package requires a package which is already loaded in the main composer.json, just ignore it like this:

    "replace": {
        "laravel/framework": "*"
    }

Create .gitignore file in the root of your module with the following content (to ignore .git folders inside module's vendor directory):

/vendor/**/.git

Include autoload in start.php file:

require __DIR__.'/vendor/autoload.php';

Now you can access added classes as usually:

\Rivsen\Demo\Hello

ATTENTION: Do not run Laravel-Modules's module:update command, it will add requirements from module's composer to the main FreeScout composer.json, which is not allowed.

To enable package's service provider add it to module.json:

"providers": [
    "\\Package\\PackageServiceProvider",
],
"aliases": {
    "Package": "\\Package\\Laravel\\Facades\\Package"
},

Troubleshooting

If module's service provider not found, module is automatically deactivated and floating flash message is shown to admin. Other exceptions are processed normally.