This extension integrates
voidlabs/mosaico with CiviCRM. Like CiviCRM, the main body of this extension is built on
PHP, MySQL, and AngularJS. You can generally develop updates to the extension in a regular CiviCRM environment.
There are a few important exceptions and additions: the stylesheets (
./css) and the editor (
If you wish to develop patches for these, then it will require additional tools and processes.
- Basic Development
- Stylesheet Development and Editor Development
nodejs(Currently the mosaico build script only works with node v8 and older. You can use nvm to use multiple versions of nodejs. Eg.
nvm install 8 && nvm use 8)
The process is similar to many CiviCRM extensions:
## Navigate to your extension directory, e.g. cd sites/default/files/civicrm/ext ## Download the extensions git clone https://github.com/veda-consulting/uk.co.vedaconsulting.mosaico ## Download additional dependencies cd uk.co.vedaconsulting.mosaico composer install ## Enable the extension via web UI or CLI, e.g. cv en mosaico
At this point, you can iteratively develop patches. Submit proposed updates via Github pull-requests.
We use Gulp and Sass for styling and handle different running tasks. Firstly, you should install node packages using npm package manager:
Styling changes should go into
sass directory and compiled to CSS using the following command:
Once you are done making your changes, please use BackstopJS (see Testing to check for any possible visual regression issues.
Commit changes for both SCSS and CSS. Submit proposed updates via Github pull-requests.
The CiviCRM extension (
uk.co.vedaconsulting.mosaico) depends on the editor (mosaico), which is an
independent project. The
mosaico component has its own requirements and workflows.
uk.co.vedaconsulting.mosaico uses a pre-built copy of
./packages/mosaico), so you may work on
without needing to understand
mosaico development. However, if you are doing development for both, then there are a few important details:
mosaico.gitin the extension: You may replace the pre-built folder (
./packages/mosaico) with a git repo. The extension specifically uses a fork (https://github.com/civicrm/mosaico) with a few small patches. Typical setup steps:
## Remove pre-built copy of mosaico rm -rf packages/mosaico ## Download git repo git clone https://github.com/civicrm/mosaico.git -b v0.15-civicrm-2 ## Build cd packages/civicrm npm install grunt build
- Branching for
civicrm/mosaicofork follows the Twigflow (Rebase) pattern. You will notice additional branches such as
v0.15-civicrm-2(a branch derived from
v0.15for use by
civicrm; it is the second major variant of the branch).
- Tagging for
mosaico.git: If there has been an update to
mosaico.git, then you should make a new tag (eg
v0.15-civicrm-2.1). Github will generate a pre-built package for the new version.
- Updating the dependency: If there is a newer build of
mosaico, then you may edit
./composer.jsonand update the the
vi composer.json composer update --lock
bin/setup.sh handles various build activities:
## Download dependencies ./bin/setup.sh -D ## Regenerate DAOs ./bin/setup.sh -g ## Build zip archive ./bin/setup.sh -z
Whenever a change is merged or pushed to
uk.co.vedaconsulting.mosaico, a bot on jenkins test-ci automatically builds a new
and publishes uk.co.vedaconsulting.mosaico-latest.zip.
The build/publish process has a few properties:
- It combines
civicrm/mosaico, and any other runtime dependencies into one
- The version number is determined by reading
<version>) and appending the current Unix timestamp.
- Example: If the
versionis declared as
1.0.beta1, then it will be published as
- Three files are published:
- The new
- A JSON document describing the build.
- An alias is provided under the folder
The bot does not publish the new version to
civicrm.org. To do this, download the
latest.zip to get the version from the info.xml (
Then add the actual release zip file to the release node on