Common Build Scripts to build Joomlashack extensions.
- Phing v2.16
- php v7.2
- JShrink v1.3.3
- NodeJS v14.5.0
- node-sass
The default target builds and creates an install package using the current version number in the primary manifest file:
phing build
or just
phing
To update and create an install package for a new version, use this command (Note that version/creation dates for all local related extensions will also be updated to the new version):
phing build-new
If you only want to update any minified files or compile the scss files:
phing pre-build
You can see all available targets:
phing -l
There are several ways to install phing depending on your preferences and technical skills. We recommend using composer to make management of your phing installation easier. To install composer:
- MacOS/Homebrew
- Install Homebrew
- Use the terminal command:
brew install composer
- MacOS Install Composer
- Windows Install Composer
Use this command in a terminal window to verify that composer is successfully installed:
composer --version
Then you can install phing globally on your system using this command:
composer global require phing/phing
Verify phing is correctly installed with:
phing -v
The minification feature requires JShrink. If, as recommended you have installed composer globally:
composer global require tedivm/jshrink
We recommend using nvm (Node Version Manager) to manage installation of npm (Node Package Manager) and Node.
Although some don't recommend it, nvm can be installed using homebrew
brew install nvm
When the install completes, look for instructions on adding lines to your terminal run file. On most normal systems this will be ~/.profile.
export NVM_DIR="$HOME/.nvm"
[ -s "/usr/local/opt/nvm/nvm.sh" ] && \. "/usr/local/opt/nvm/nvm.sh" # This loads nvm
[ -s "/usr/local/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/usr/local/opt/nvm/etc/bash_completion.d/nvm" # This loads nvm bash_completion
See Installing nvm for full details. Summary - Use the following command in a terminal window:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
nvm is primarily maintained for *nix systems (like MacOS). Corey Butler has created a windows version that works perfectly for windows. For details see his Github repository for nvm.
Download and run the appropriate Windows installer for your system:
Download Windows installer v1.1.8
nvm -v
npm -v
node -v
Once you have installed Node JS, you can easily install the needed modules using npm.
To process SCSS files, the node-sass node.js package must be installed.
npm -g install node-sass
node-sass -v
Create a new file in your project folder, named build.properties
.
The only required setting is:
builder.path=/path/to/AllediaBuilder/local/copy
See clients/build.dist.properties for more details on available properties.
Many build.properties
settings will be common to many projects.
These properties can be set in global.properties
in your local
clone of this repository.
On some systems, you may have to tell the builder where to find composer's autoload.php file. If you have installed the composer dependencies globally as described above, this is typically the home directory for your user account
home.path=/path/to/user/home/directory
The builder expects to find the file .composer/vendor/autoload.php
in the specified
directory.
See global.dist.properties for more properties that are appropriately set globally.
If you extension has one or more related extension/project, you must set its local copy path alias:
project.AnotherExtensionName.path=/the/path/to/anotherextension
You can set one line per related extension. Use this to map the installer library or any other required project.
If a Pro version has a corresponding Free version, you must indicate this with two properties:
project.hasFreeVersion=1 project.FreeExtensionName.path=/path/to/FreeExtension
Any project using this builder must copy the build.xml file
from the clients
folder here into the project's root folder.
All free repositories should be named as the product name. All pro repositories should start with the name of the free product, followed by -Pro. The local cloned folders, need to have the same name as the repository, for both.
The pro extension package will be built grabbing the source from the free extension, and copying over it the content from the pro source repository. The folders will be merged and files with the same name will be overwritten. So usually the pro repository will have the language files named with an extension prefix ".pro" and will be merged on the build time.
While building the pro extension, the builder will detect the respective
free extension using the property extra.name
from the composer file.
For both, pro and free extensions, the language files are in the language
folder. The files for the free version should be named normally.
The files for the pro version must have a .pro
extension prefix, like:
en-GB/en-GB.com_myextension.pro.sys.ini
or `en-GB/en-GB.com_myextension.pro.ini.
They will be merged during the build process.
You can use phing to merge the files:
phing merge-languages
This command will create merged language files inside the ./packages/dev/language/en-GB folder.
All extensions need to have a composer.json
file in the root folder, which is used by the phing
scripts and deploy server to extract information about your project.
{
"name" : "mycompany/myextension",
"description" : "MyExtension",
"minimum-stability": "stable",
"license" : "GPL-2+",
"type" : "joomla-plugin",
"extra" : {
"element" : "plg_content_myextension",
"element-short" : "myextension",
"name" : "MyExtension",
"folder" : "content",
"client" : "site",
"package-license": "free"
},
"authors" : [
{
"name" : "Name",
"email": "hello@myemail.com"
}
],
"require" : {
"php" : ">=7.2.5"
}
}
Key | Description |
---|---|
type | extension type |
extra.element | Full element name for the extension |
extra.element-short | Short element name, without any type or folder prefix |
extra.name | Extension name. On pro, used to detect the repo for the free extension |
extra.folder | For plugins, the folder/type of plugin |
client | 'client' or 'admin' |
package-license | 'free', 'pro' or 'paid' |
You can automatically pack other extensions while building the package. You just need to specify the related extensions on the manifest file, using this tag as example:
<alledia>
<relatedExtensions publish="false"
downgrade="false"
uninstall="false">
<extension type="library"
element="allediaframework"
downgrade="false"
uninstall="false">AllediaFramework</extension>
<extension type="component"
element="anotherextension1"
downgrade="true"
uninstall="true">AnotherExtension1</extension>
<extension type="plugin"
element="anyplugin"
folder="content"
publish="true"
uninstall="true"
downgrade="true"
ordering="first">AnyPlugin</extension>
</relatedExtensions>
</alledia>
Defaults can be set in the <relatedExtensions> tag. Defaults when nothing specified anywhere are in bold
tag | values | Description |
---|---|---|
downgrade | true|false | Allow downgrade on update of the main extension. |
uninstall | true|false | Allow uninstall when the main extension is uninstalled. |
publish | true|false | Plugins only - Publish the right after new install (ignored on updates) |
ordering |
|
Plugins only - force a specific order on new installs |
Scripts can be minified and optionally merged creating a bundled file. This requires the JShrink library.
To minify script files you create a <minify>
tag inside the <alledia>
tag.
You can specify single script files, as well create bundle files.
You can specify a custom suffix to be added to the compressed file, right before the extension. The default suffix is ".min".
<minify suffix="-min">
</minify>
The minification is applied while building the package. If you need to run it on developing time, like before committing changes, you can call the task: phing pre-build
.
Single files are defined by a <script>
tag:
<alledia>
<minify>
<script>media/js/script1.js</script>
<script>media/js/script2.js</script>
</minify>
</alledia>
This will result in new files:
- media/js/script1.min.js
- media/js/script2.min.js
A bundle can be created merging files defined inside a <scripts>
tag. The destination is set on the "destination" attribute:
<alledia>
<minify>
<script>media/js/script1.js</script>
<script>media/js/script2.js</script>
<scripts destination="media/js/script-bundle.js">
<script>media/js/script3.js</script>
<script>media/js/script4.js</script>
</scripts>
</minify>
</alledia>
This will result in new files:
- media/js/script1.min.js
- media/js/script2.min.js
- media/js/script-bundle.js
- media/js/script-bundle.min.js
SASS SCSS files can be compiled by inclusion of the <scss>
tag under the <alledia>
tag.
This requires node-sass to be installed.
<alledia>
<scss destination="folder-name" style="compressed">
<file>scss-file-name</file>
</scss>
</alledia>
Folder and file paths are all relative to the project source folder.
<scss>
tag accepts the following attributes:
Attribute | Value |
---|---|
destination | Folder name [default to same as original] |
style | nested|expanded|compact|compressed |
Obsolete items will be unistalled or deleted before install any related extension. You can set 3 types of obsolete items: extension, file and folder. For file and folder, use relative paths to the site root.
<alledia>
<obsolete>
<extension type="plugin"
group="system"
element="oldshortelementname"/>
<file>/components/com_mycomponent/oldfile.php</file>
<file>/administrator/components/com_mycomponent/oldfile.php</file>
<folder>/components/com_mycomponent/oldfolder</folder>
</obsolete>
</alledia>
If the main project is a plugin, the publish and ordering can be used similar to their usage in related extensions.
<alledia>
<element publish="true" ordering="first">myplugin</element>
</alledia>
These views are packed by the installer library and loaded by all extensions.
./views
| |-- installer
| | |-- default.php
| | |-- default_info.php
| | |-- default_license.php
Your extensions can override any file and add a new one: body_*.
./views
| |-- installer
| | |-- default_custom.php