Modules

A module (typically a laravel package) is a feature that can be active/inactive, and can be installed via composer. Modules can have its own settings, a description, and will be displayed on the modules page.

Important notes

Laravelpackage.com provides good documentation for the development of a laravel package.

You might use the following Qore Module template for reference to get started: https://gitlab.qlic.nl

Composer package

You should make your module be installable via composer. You can achieve this by adding a gitlab-ci.yaml to your module. Gitlab will automatically register your package whenever you push a tag. For example:

stages:
    - deploy

variables:
    TAG: '0.0.1'

deploy:
    stage: deploy
    only:
        - tags
    script:
        - 'apt-get update; apt-get -y install curl'
        - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=$TAG "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"'

info

You can find more information here: Installing Modules & Plugins.

Now when you push your changes, Gitlab will register your module as a composer package. For example: https://gitlab.qlic.nl/qore/plugins/postcode/-/packages

info

There is an existing dev module which can be used as an example: https://gitlab.qlic.nl/qore/modules/skeleton-dev.

There is also an example which registers Vue templates: https://gitlab.qlic.nl/qore/modules/qore-issue-tracker.

Do note though that these are example modules, and they are not registered as Gitlab composer packages.

Updating documentation and release notes

After you have created a module, please take some time to add a page to https://qore.qlic.nl. You can do this by updating this project: https://gitlab.qlic.nl/qore/docs:

• Update the config/extensions.php
• Add a note to resources/views/notes/modules/<your-module.md>

Getting started

To get started you can create a new (Laravel) package ( see Package development or copy an exisiting module.

You can create a repository in this group: https://gitlab.qlic.nl/qore/modules

Registering your module

You can register your own module in your service provider:

class IssueTrackerServiceProvider extends ServiceProvider
{
    public function boot()
    {
        app(Modules::class)->register(new IssueTrackerModule);
    }
}

Your module should extend QoreModule. Here is an example:

class CRMModule extends QoreModule
{
    public function boot()
    {
        app(Resources::class)->register(new Employee);
        app(Resources::class)->register(new Project);
    }

    public function composerName(): string
    {
        return 'qore/crm';
    }

    public function title(): string
    {
        return 'CRM';
    }

    public function description(): string
    {
        return 'Dit is een test module die ervoor zorgt dat je medewerkers en projecten kan beheren.';
    }
}

info

Each module that is registered, will be booted in the Skeletons' ModuleServiceProvider.

Settings in modules

Commonly, you will need the user to configure some settings in order to use your module.

You can achieve this by adding 3 methods:

public function settingsUrl(): ?string
{
    return 'issue-tracker';
}

public function settingFields(): ?FieldCollection
{
    return new FieldCollection(
        Text::make(__('Url'), 'gitlab_url')
            ->default(setting($this->composerName(), 'gitlab_url', 'https://gitlab.qlic.nl'))
            ->setMaxWidth('md')
            ->rules('required', 'min:3', 'max:60')
            ->hint(__('Url van de gitlab omgeving')),
        Text::make(__('Token'), 'gitlab_http_token')
            ->setMaxWidth('md')
            ->rules('required', 'min:3', 'max:60')
            ->default(setting($this->composerName(), 'gitlab_http_token', ''))
            ->hint('Persoonlijke HTTP auth token'),
    );
}

public function settingFieldsLayout(): ?FieldLayout
{
    return (new FieldLayout())
        ->column(['gitlab_url', 'gitlab_http_token'])
}

public function storeSettings(array $data)
{
    auth()->user()->tenant->setSetting($this->composerName(), 'gitlab_url', $data['gitlab_url']);
    auth()->user()->tenant->setSetting($this->composerName(), 'gitlab_http_token', $data['gitlab_http_token']);
}

Prevent disabling

You can prevent users from deactivating your module by adding the following method:

/**
 * This Module can not be deactivated by the user
 *
 * @return bool
 */
public function canBeDisabled(): bool
{
    return false;
}

Hiding from index

You can hide your module from the index page by adding the following method:

public function isVisibleForUser(): bool 
{ 
  return false; 
}

Module hooks

Every Qore extension (module/plugin) will have the following hooks that you can override:

    /**
     * Boot is called on every request (while this extension is enabled)
     * You might want to register resources here for example
     */
    public function boot()
    {
    }

    /**
     * Optional: if this extension gets enabled
     * For example, you might run a permission seeder here
     */
    public function onEnable(): void
    {
    }

    /**
     * Optional: if this extension gets disabled
     * For example, you might remove permissions here
     */
    public function onDisable(): void
    {
    }

Helper methods

Back-end

You can get all modules:

modules()

You may retrieve a specific module:

module('qore/crm')

Check if a module is active:

module_is_active('qore/issue-tracker')

Front-end

You can retrieve all modules in Vue templates

this.$modules

You may retrieve a specific module:

this.$module('qore/issue-tracker')

Check if a module is active:

this.$isModuleActive('qore/issue-tracker')

For example:

<IssueTracker v-if="$isModuleActive('qore/issue-tracker')"/>