This shared configuration can be used to develop modules for the Open-Xchange Appsuite UI. It has been part of the generator-ox-ui-module project, that can help you getting started building own modules using yo, but has been extracted to be released on its own.
If you used yo to generate a stub project, you are already setup and ready to use all the goodness.
To manually enable the shared tasks, they need to be loaded in your local Gruntfile.js. For this to work, you need to
npm install --save-dev @open-xchange/shared-grunt-config
This will add the shared configuration as a dependency to your project and install it.
Our recommended Gruntfile.js looks like this:
'use strict';
module.exports = function (grunt) {
grunt.loadNpmTasks('@open-xchange/shared-grunt-config');
// load custom tasks
// those can be used to override configuration from shared-grunt-config
if (grunt.file.isDir('grunt/tasks/')) {
grunt.loadTasks('grunt/tasks/');
}
};
The important line is grunt.loadNpmTasks('@open-xchange/shared-grunt-config');, which will actually load all the shared tasks.
Find here a few tasks that might be useful during development of an Open-Xchange Appsuite UI module.
Some of the tasks are only available, if some dependencies are present in the node_modules/ directory of the project using
this shared configuration.
This task will check for all development dependencies to be installed. If not, npm install will be run.
Then the build task will be run, to provide a runnable version of the software in the build/ directory.
This is a collection of tasks needed to actually build the module. Currently it will lint the code (statically check for
problems in the code), run all copy:build_* tasks, run all concat tasks, run all less tasks and run compile_po to
generate i18n JavaScript modules from po files in i18n/.
Extract strings that are used by the require-gettext module (gt) from the JavaScript files and store them in i18n/ox.pot.
This files can be used by translators to create language specific po files to enable translation.
Create a distribution ready version in the dist/ directory. Everything from this directory can later on
be copied over to a prefix directory and will be served correctly from there. So this directory contains
the final directory structure that just needs to be copied over to the destination.
Remove all files created temporarily during development. Installed dependencies (node_modules/) are
not counted as such temporary files. Those have to be removed manually, if needed.
Run all install tasks for production. Currently, this is an alias to run both, install:static and install:dynamic tasks.
Install all files which should be distributed (generated by the dist task into dist/ directory) into the directory specified
with the --htdoc command line option.
All provided files can now be served statically by a Webserver.
This task is not strictly needed if no static files are supposed to be served.
In order to deactivate this task, this can be overriden in a project by placing a file into grunt/tasks directory:
module.exports = function (grunt) {
// disable install:static
// we do not need any static files served by the Webserver
grunt.registerTask('install:static', []);
};Example:
grunt dist install:static --htdoc=/var/www/Install all files which should be distributed (generated by the dist task into dist/ directory) into the directory specified
with the --prefix command line option.
All files provided by this task are supposed to be available to a middleware component for dynamic consumption.
Example:
grunt dist install:dynamic --prefix=/opt/open-xchange/Use grunt-bump to manage versioning of the project.
In order to have local less files compiled against a default theme, you
would need to provide a coreDir variable. This can be provided via
command line or via a file in grunt/local.conf.json. This coreDir
variable needs to point to a directory containing core less files, like
a distributed version of the core UI or the core UI repository itself.
In order to build local less files against more themes, those will also be looked up from directories specified in
the appserver.prefixes array (local.conf).
Those tasks are only available, if the following dependencies are installed:
- appserver
- grunt-contrib-connect
- grunt-contrib-watch
This task will start the MITM (appserver) proxy at http://localhost:8337 and serve the build/ directory by
default. It will also start a karma server ready to run the unit tests. It will then start the watch
task to watch the directory for changes and act on them.
Start a MITM (appserver) proxy serving the build/ directory by default. It will also start a livereload server, so
it is possible to trigger a reload event to all browsers that are connected to the server.
Only useful to run in combination with the watch task, like grunt connect watch. See serve for a
stand-alone version of this task.
Sometimes, a production setup requires to have correct host names setup and be used to develop or debug against a system. In such cases, it is possible to activate a proxy server that will send certain requests through the MITM (appserver) proxy and proxy all other requests directly like real proxy servers (like squid) do.
In grunt/local.conf.json just add an entry "proxy": true to start a proxy server at the default port (8080). Instead of
true, a custom port number might be specified.
Once the connect:proxy task is running, a browsers proxy settings might be configured to use localhost:8080 as a proxy
server for HTTP(S) traffic.
Drawback: when using the proxy server, livereload middleware can not be used, yet. A browser plugin for livereload would be needed in such cases, or reloads must be triggered manually.
To configure HTTPS protocol for the development server, switch to "protocol": "https" in appserver section of
grunt/local.conf.json.
Additionally, values for key, cert and ca can be provided.
Those will be added to the configuration of the connect:server subtask as documented for
grunt-connect.
The default settings are:
{
"key": "ssl/host.key",
"cert": "ssl/host.crt",
"ca": "ssl/rootCA.crt"
}
Those values might point to files that are automatically read or raw PEM data.
Watch certain directories for changes and trigger tasks when any change happens. This will trigger a build, once any of the source files have changed, then it will send a livereload event to all browsers connected to the MITM (appserver) proxy and finally it will issue a test run.
If some grunt configuration changes, grunt will reload itself.
If some files in the spec/ directory changes, those will be copied to the build/ directory and a test run
will be initiated.
Force a reload of the UI (incl. cache busting) in a browser that has a connection to a running livereload server.
This helps during development, if grunt dev is used (or at least the watch task is running). A call to
grunt refresh will then reload the browser window with the latest code served by the connect middleware.
Run the connect task but wait for ever after the server has been started. Use this to run a MITM proxy without the watch task.
In order to test files in semi-production environments before uglify task has run, all files from build/ directory can
be installed to some arbitrary location using this task.
The --dest command line option is mandatory in this case.
Example:
grunt default install --dest=~/public_html/appsuite/Those tasks do not have any new direct dependencies, but are targeting the tasks used for development.
The intention behind those tasks is to support detection of common pitfalls and repair them if possible.
None of those tasks will do any destructive operation, except when called with the --force option.
Wipe the node_modules/ directory followed by an npm install.
Check for potential problems with TLS connections and the appserver proxy component. Sometimes, the server to develop against does not provide valid TLS certificates. Be it, because it is a development machine, or for any other reason. In order to still use the server, there is a new option, allowing to accept untrusted connections in the proxy server.
To reset this to the default, remove appserver.rejectUnauthorized option from grunt/local.conf.json or set it to true.
Make sure the file grunt/local.conf.json exists.
This will create the file with a default configuration, if it did not exist.
It will not overwrite any custom configuration.
Run all the repair:check_* tasks mentioned above.
Run all repair:* tasks mentioned above.
Use the --read-only option for a "read-only" version, which will just print out potential problems.
Those tasks are only available, if the following dependencies are installed:
- grunt-karma
Run all tests from spec/ directory once in phantomjs browser.
Start an instance of the karma test server and wait for browser connecting to http://localhost:9876. By default, a phantomjs browser will connect this URL automatically.
Start a testrun on a running testserver and run the tests on all browsers connected to http://localhost:9876. It will skip the testrun, if no server is found running.
Those tasks are only available, if the following dependencies are installed:
- grunt-exec
- gettext tools installed globally (msgmerge)
Perform a msgmerge operation in the i18n/ directory. This will merge all
changes from the pot file in the i18n/ directory into all po files found.