grunt-cep

A Grunt plugin that helps debugging and packaging HTML5-based extensions for Adobe Creative Cloud applications.

By using this task you can debug and package HTML5-based extensions for Adobe® Creative Cloud® products directly from Grunt, in a totally automated manner and without the Adobe Extension Builder plugin.

The tool can automatically generate self-signed certificates for extension packaging and automates some error-prone tasks such as bundle and extension manifest files creation. It supports hybrid extensions and lets you create different builds of an extension bundle based on targeted Adobe products.

It is based on the csxs command line tool by Creative Market.

Please note: the plugin is currently in alpha stage and may contain bugs. Options are not frozen and may change in future versions.

Changelog

Latest Version

0.5.0:

• Added support for CC2019.
• Updated dependencies to the latest versions.

Thanks to Lilipi for contributing to this version.

Previous Releases

0.4.5:

• Fixed CEFCommandLine parameters not being applied to all builds.
• Updated dependencies to the latest available versions.

Thanks to alebianco for contributing these changes.

0.4.4:

• Fixed extension packaging for Animate CC 2017 and CC 2018.

Thanks to alebianco for contributing this fix.

0.4.3:

• Added support for CC2018.
• Fixed XML manifest versions to comply with XSD schema released by Adobe.

Thanks to pcdeshmukh for contributing to this version.

0.4.2:

• Fixed ZXPSignCmd not working on Mac.
• Fixed bundle information not being used to fill in manifest templates.
• Updated dependencies to the latest available versions.

0.4.1:

• Added support for CC2017.

Thanks to barooney for contributing these changes.

0.4.0:

• Added support for CC 2015.5.

0.3.5:

• Added support for extension lifecycle configuration (see extension.lifecycle in the configuration section below).

0.3.4:

• Added support for ZXPSignCmd -tsa option (see package.timestamp_url in the configuration section below).
• Various bug fixes.

Thanks to Rhuagh and MattMcNam for contributing fixes and improvements.

Please note: version 0.3.3 was published by mistake and it did not include the ZXPSignCmd binaries. It should NOT be used.

0.3.2:

• Improved Premiere support.

Thanks to Rhuagh for contributing this fix.

0.3.1:

• Improved Mac support.
• Added support for CEF command line parameters and extension type in config (see extension.cef_params and extension.type in the configuration section below).

Thanks to MattMcNam and jDmacD for contributing these changes.

0.3.0:

• Added support for Adobe Creative Cloud 2015 release.
• Added support for debugging extensions inside multiple host applications at the same time. This required some changes to the way debug ports are assigned to extensions (base port is now 8000 instead than 8080), see the updated configuration section below if upgrading from a previous version.
• Added experimental support for bundling custom files alongside the extension (see bundle.files in the configuration section below).
• Improved Mac support, still not completely working.
• Added preliminary support for After Effects and Dreamweaver.
• Updated dependencies to the latest available versions.

0.2.1:

• Added support for packaging multiple extensions in a single extension bundle.
• Added support for Adobe Creative Cloud 2014 release.

Warning: contains breaking changes to the task configuration options, see the updated configuration section below if upgrading from a previous version.

0.1.2

• Improved changelogs management, bug fixes.

0.1.1

• Bug fixes.

0.1.0

• First release.

Getting Started

This plugin requires Grunt ~0.4.5. Please refer to the official documentation to get started with Grunt. You may install this plugin with this command:

npm install grunt-cep --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile as usual:

grunt.loadNpmTasks('grunt-cep');

Project Boilerplate

You can use the grunt-init-cep template to easily get started. The template tool will install all the required files automatically and provide you with a basic extension boilerplate, already configured to run inside the chosen target applications.

Please refer to the grunt-init-cep documentation for installation and usage instruction.

Advanced Setup

Bundle icon, manifest, MXI and update.xml files provided by the template can also be found in the res/bundle folder located inside the plugin installation folder. If you prefer, you can manually copy these files instead of using the grunt-init-cep template.

grunt-cep is setup to use these files by default, so just copy the res/bundle folder to the root of your project (that is, the same folder of your Gruntfile.js) and you should be good to go.

Custom Manifest, XML and MXI Files

XML and MXI template files are populated at build time using configuration properties. For most extensions the provided templates should work just fine, but for complex extensions it might be necessary to make changes to these files or even provide custom ones.

Note that grunt-cep makes no assumptions about and does no validation on extension files content, so be sure to provide valid files and to modify extension configuration accordingly.

The cep Task

You may run the task with this command:

grunt cep

Options

grunt-cep has several options that you can customize to fit your needs. To avoid cluttering your Gruntfile.js it is more advisable to keep the options in an external Javascript or JSON file for easier editing and import them at run-time using either:

require('cep-config.js');

or:

grunt.file.readJSON('cep-config.json');

Options defined in the external file can be overwritten in child tasks as needed (see the example below). Default values and a more in-depth description for all the properties below can be found in the /options/defaults.js file in the plugin installation folder.

options

These properties define base task options.

options.bundle

Contains information about the extension bundle, that is the container for all the extensions specified below. If required data is not specified here, grunt-cep will try to load it from the firstextension specified in the cep.extensions array.

options.extensions

An array containing information about each single extension that will be added to the bundle. Each extension object holds information such as extension name, author, version, etc. The properties defined here are used to fill in manifest and other extension related file templates.

options.builds

The ability to specify single builds is one of the most powerful feature of grunt-cep when dealing with complex extension bundles.

The cep.builds property is an array of objects describing the various builds that should be executed, each one resulting in a separate ZXP file that will be bundled with the final ZXP installer.

Each build object contains the following properties and extends the main task configuration, giving you the ability to override base configuration values on a per-build basis.

options.launch

Only used when the launch profile is active, holds information needed to launch a target host application.

options.package

Only used with the package profile, holds information related to bundle packaging and distribution.

Usage Examples

The example configuration below is based on the grunt-init-cep project template and defines an extension for Adobe Photoshop CC. It registers two tasks (debug and release) which respectively launch debug inside Adobe Photoshop CC and package the full extension.

All the icons and file templates referenced in the configuration are available in the project template (see the Getting Started section).

// cep-config.js
module.exports =
{
    bundle: {
        version: '0.1.0',
        id: 'com.foo.exampleBundle',
        name: 'Example Bundle',
        author_name: 'Foo',
        mxi_icon: 'bundle/icon-mxi.png',
    },
    
    extensions: [{
        version: '0.1.0',
        id: 'com.foo.exampleBundle.examplePanel',
        name: 'Example Panel',
        author_name: 'Foo',
        icons: {
            panel: {
                light: {
                    normal: 'icons/icon-light.png',
                    hover: 'icons/icon-light-hover.png',
                    disabled: 'icons/icon-light-disabled.png'
                },
                dark: {
                    normal: 'icons/icon-dark.png',
                    hover: 'icons/icon-dark-hover.png',
                    disabled: 'icons/icon-dark-disabled.png'
                },
            }
        },
        size: {
            normal: { width: 320, height: 440 },
            min: { width: 320, height: 440 },
            max: { width: 600, height: 600 },
        },
        main_path: 'example.html',
        script_path: 'extendscript/example.jsx',
    }],

    builds: [
        // Adobe Photoshop CC
        {
            bundle: { manifest: 'bundle/manifest.bundle.cc.xml' },
            extensions: [{ manifest: 'bundle/manifest.extension.xml' }],
            products: ['photoshop'],
            source: 'src',
        },
    ],

    'package': {
        certificate: {
            password: 'example_password',
        }
    },
};

// Grunfile.js
grunt.initConfig({

    // ...

    cep: {
        options: require('./cep-config.js'),

        debug: {
            options: { 
                profile: 'launch',
                launch: {
                    product: 'photoshop',
                },
            }
        },

        release: {
            options: { profile: 'package' }
        },
    },

    // ...
    
});

By running:

grunt cep:debug

grunt-cep will compile all the files in the src folders along with other extension files, install the resulting extension and launch Photoshop for testing.

If you want to package the Example extension just run:

grunt cep:release

and a compiled .ZXP file will be created in the staging folder.

Automatic Deploying

Something that I find particularly useful is the ability to automatically deploy the compiled extension to a website. This can be easily achieved using the grunt-ftp-deploy plugin:

grunt.initConfig({
	// grunt-cep
	cep: {
		// Your config here...
	},

	// FTP deploy
	"ftp-deploy": {
		release: {
			auth: {
				host: 'foo.it',
				port: 21,
				authKey: 'foo'
			},
			src: 'staging',
			dest: '/release',
			exclusions: ['debug', 'package', 'release'] // Exclude work directories
		},
	},
});

// Load plugins
grunt.loadNpmTasks('grunt-cep');
grunt.loadNpmTasks('grunt-ftp-deploy');

// Integrated packaging and deploying
grunt.registerTask('deploy', ['cep:release', 'ftp-deploy:release']);

When the deploy task is run, the cep:release task will package your extension and ftp-deploy will upload the relevant files (ZXP installer and "update.xml") to the foo.it website.

Contributing

Contributions are extremely welcome! Extension development for Adobe applications is a complex subject and has a lot of scarcely documented features and issues. Feel free to file issues or contribute fixes to code or documentation.

License

Copyright © 2014 Francesco Camarlinghi

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyrights & Trademarks

Based on code created by Creative Market. The included binaries are copyright Adobe Systems Incorporated. "Creative Suite" and "Creative Cloud" are registered trademarks of Adobe Systems Incorporated.