Upgrade from 6.0 to 6.1

With the launch of the 6.1.0 platform release, new developer tools have been made available for usage. The process of optimizing for web (building) and serving (hosting) instances has changed.

An important change in the tooling is that it no longer depends on the task-runner 'gulp'. Because gulp is no longer used, the gulpfile.js in the root of your instance is now deprecated. Any custom routes, which your instance might have, will need to be partially rewritten. This process is described in Upgrading routes.

The tools also require an updated version of NodeJS due to the use of ECMA2015 programming syntax. The minimal required version is greater than or equal to 5.3.0. You can check your NodeJS version with node -v.

Updating configuration

Several new files are introduced in version 6.1.0, some are changed and some have become obsolete.

  1. Delete ci.json.
  2. Create config.json.

    Once you've created the file, open gulpfile.js. Copy and paste the scope variable to the newly created config.json file. Note that you are copy and pasting from a javascript file to a json file which requires a different syntax.

    tasks(gulp, {
    	// ...
    	scope: {
    		documentIds: ['test.ditamap']
    	}
    	// ...
    });
    
    
    {
    	"scope": {
    		"documentIds": [
    			"test.ditamap"
    		]
    	}
    }
  3. Update package.json.

    Because of the new build-tools you are required to make two changes to your package.json file.

    1. Add npm scripts configuration.

      Preferably below the private property.

      {
      	// ...
      	"scripts": {
      		"build": "node ./node_modules/fontoxml-build/bin/fontoxml-build",
      		"build-server": "node ./node_modules/fontoxml-dev-server/bin/fontoxml-dev-server --dist",
      		"server": "node ./node_modules/fontoxml-dev-server/bin/fontoxml-dev-server"
      	}
      	// ...
      }
    2. Replace devDependencies configuration.

      {
      	// ...
      	"devDependencies": {
      		"fontoxml-build": "./tools/fontoxml-build",
      		"fontoxml-dev-server": "./tools/fontoxml-dev-server"
      	}
      	// ...
      }
  4. Update README.md.

    The README.md file in the 6.1.0 release contains relevant information for using the new build tools. Manually merge the configuration.

The config.json file is used when starting the development server. If it's present it will try and read configuration values defined inside and overwrite default values.

The package.json file is updated in order to make the npm run commands work.

Upgrading routes

Your instance has custom routes defined.

With the new development server you do not have direct access to the HTTP app instance. Instead you need to make use of an express.Router.

  1. Create a new file dev-cms/configureDevCms.js and paste the following code.

    'use strict';
    
    
    const myCustomRouterRoute = require('./routes/myCustomRouterRoute');
    
    
    module.exports = (router, config) => {
    	return {
    		routes: [
    			myCustomRouterRoute(router, config)
    		]
    	}
    };
  2. Use best practices to name new files for each server route.

    Create a new file dev-cms/routes/myCustomRouterRoute.js and paste the following code.

    'use strict';
    
    
    module.exports = (router, config) => {
    	router
    		.route('/my-custom-router')
    			.get((req, res, next) => res.json(config));
    
    
    	return router;
    };
  3. Delete gulpfile.js

After the routes are upgraded, you can use the editor like before with the custom routes in place.

After you have succesfully upgraded the routes to use the new router, you can manually call the endpoints and check if they return valid results.

Was this page helpful?