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.
For modules: "type": "asgard-module",,
For themes: "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.
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.
Running module migrations
To run the migrations of a module, run the following in your terminal:
php artisan module:migrate ModuleName
Running module seeds
Run the following command in your terminal:
php artisan module:seed ModuleName
Publishing module assets
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:
Publishing module translation files
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:
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:
Not easy to customise the module if needed, since any changes made, will be overwritten on your next composer update
Advantages to using download feature:
Customisable out of the box
Disadvantages to using download feature:
No version management with the original repository
After having downloaded a module, you can instantly start to customise it to your needs, and add it to your version control system.
Downloading a module
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:
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