Core Module
It's important to know that a module and a theme, is just a simple composer package. Meaning that if your module has a dependency on another package or AsgardCMS-module, you can add those in the require
key of the composer.json
file of your module.
This also means that modules fetched via composer, cannot be edited, those changes will get overwritten in the next composer update
.
But how does AsgardCms know to put the modules in the Modules
folder and themes in the Themes
folder ?
It's pretty easy actually, just check the type
key in your composer.json file.
"type": "asgard-module",
,"type": "asgard-theme",
.That's it, thanks to this, AsgardCms knows where to put those packages. Make sure your modules and themes have the correct type set.
In case you don't want to use composer to download a package in your project, scroll down to the Download an existing Module section.
Now that you know that a module or theme is a simple composer package, to install one on you AsgardCms project, just run the usual composer require vendor/name
in your terminal.
If there are additional steps required to install the module, for instance running migrations, the module will have this stated in its readme.md file.
To run the migrations of a module, run the following in your terminal:
php artisan module:migrate ModuleName
Run the following command in your terminal:
php artisan module:seed ModuleName
Module assets are located in the Assets/
directory of the module. The have those copied in your public/
folder run the following command:
php artisan module:publish ModuleName
This will publish the module assets in the following directory:
public/modules/ModuleName
Sometimes you'll want to change the copy of static texts of a particular module. If that module is a module fetched with composer, you have to treat that module as a composer package, meaning you cannot perform changes in that module, or those changes will get overwritten in the next composer update
.
Module translation files can be published by running the following command in your terminal:
php artisan module:publish-translation ModuleName
This will publish the translation files in the following directory:
resources/lang/ModuleName
To fetch updates from a module or a theme you can run composer update
.
This is an alternative way of downloading existing modules. This won't use composer, instead it will directly download and place the desired modules in the Modules/
directory. There are some advantages and disadvantages to doing it this way versus using composer.
Advantages to using composer:
Disadvantages to using composer:
composer update
Advantages to using download feature:
Disadvantages to using download feature:
After having downloaded a module, you can instantly start to customise it to your needs, and add it to your version control system.
The download command is simple:
php artisan asgard:download:module vendor/name
Let's say you want to download the AsgardCMS/Contact module. Run this command to do so:
php artisan asgard:download:module asgardcms/contact
This will download the Contact module in your Modules/
folder.
Running migrations
php artisan asgard:download:module asgardcms/contact --migrations
Running seeds
php artisan asgard:download:module asgardcms/contact --seeds
Publishing module assets
php artisan asgard:download:module asgardcms/contact --assets
Of course all those options, can be specified together:
php artisan asgard:download:module asgardcms/contact --migrations --seeds --assets
# or
php artisan asgard:download:module asgardcms/contact --demo
The previous commands requires the wanted module to have a github release. This might not always be the case (though recommended). For this situation you can specify which branch to download using the --branch
option
php artisan asgard:download:module asgardcms/contact --branch=master
This will not download the latest release, but instead the master branch.
If you want to remove a module, you can use the following command:
php artisan asgard:delete:module ModuleName --migrations
This will remove the module's tables, and remove any user or role that had permissions for this module.