search

emiloberg / liferay-ddmtool

Tool for authoring, uploading, downloading and synchronizing Liferay DDM related stuff (Structures and Templates) across environments.
MIT License
36 stars 16 forks source link

readme

Liferay DDM Tool

Command Line Tool for authoring, uploading, downloading and synchronizing Liferay DDM related stuff (Structures and Templates) across environments. All transactions are done over JSON Web Services.

Demonstration recorded at Liferay DevCon 2014

Screenshot of YouTube video

Flowchart

Flowchart of DDM Tool

Abilities

What is "DDM related stuff"?

Installation

Requires Node.js (if unsure if you have node install, run node -v in a console.)

Install with npm:

sudo npm install -g liferay-ddmtool

and then run:

ddm

If this is the first time you use this App. You most probably want to download all structures and templates to a local folder.

  1. Create a new project by following the wizard in the App.
  2. Select the just created project and choose "Download All"
  3. A folder containing all structures and templates has now been created in the path you selected when you created the project. Maybe you want to make this into a git repository?

Common use cases

Version contol

The DDM tool will upload (and download) files from a folder on your local machine to a Liferay server of your choice. If you put that local folder under version control you may check in and out your structures and templates just as any other source code.

Live template development in the editor/IDE of your choice

Screenshot of Watch mode When developing templates, set the Liferay DDM Tool in "watch mode" and as soon as you save a template in your favorite editor, it'll upload to the Liferay server and is used immediately.

Usually you want to upload files to your localhost development environment.

Pro tip: Run DDM Tool with the -w/--watch flag to go straight into watch mode:

ddm -w --project <awesomeproject> --server <servername>

Setting up a new environment, such as a new live/dev server

Screenshot of Upload

Checkout all structures and templates from your resposity, run the DDM Tool and select "Upload all"

Pro tip: Run DDM Tool with the -u/--upload flag to upload all files without any menu selections.

ddm -u --project <awesomeproject> --server <servername>

Deploying all to the live server as a part of the release process

Just as if you were setting up a new environment, just checkout all ddm stuff and run "Upload all" to deploy all structures and templates.

If you just want to deploy some of the files, go into "Find Diffs" > "Select and upload files which differs", and pick the files you want to deploy.

Making sure that each environment have the same structures and templates

Screenshot of Diff

Start up the DDM Tool and go into "Find Diffs". From there you may show all diffs straight from the command line, open an external diff tool (see Project settings below) or upload/download diffing files.

Pro tip: Run DDM Tool with the -i/--diffs flag to go straight into diffs mode:

ddm -i --project <awesomeproject> --server <servername>

Download all DDM Stuff

Want to save all structures and templates from a server to your local disk? Just run the app and select "Download All"

Pro tip: Run DDM Tool with the -d/--download flag to go straight into download mode:

ddm -d --project <awesomeproject> --server <servername>

Command line arguments

You may also start the App with some command line arguments. One common way to start the app is ddm --project <project-name> --server <server-name> to skip the project and server selection menues. Run with --help to get all available arguments.

Limitations

Settings

All config files are saved as JSON in $USERHOME/.ddmtool.

Project Configuration Files

For each project, there's a project configuration in $USERHOME/.ddmtool/config/projects/project-name.json.

Sample Project Setting File

{
  "projectName": "myproject",
  "filesPath": "/code/ddm-repo",
  "defaultLocale": "en_US",
  "externalDiff": "/usr/bin/opendiff %1 %2",
  "allowSelfSignedCerts": true,
  "watchIgnorePattern": "^(\\#.*|.*\\~)$",
  "hosts": [
    {
      "name": "local",
      "host": "http://localhost:8080",
      "username": "test@liferay.com",
      "password": "test",
      "email": "test@liferay.com"
    },
    {
      "name": "prod1",
      "host": "http://123.123.123.123",
      "username": "admin",
      "password": "superstrongpassword",
      "email": "admin@company.com"
    }    
  ],
  "ignoreDDMs": [
    "EVENTS",
    "INVENTORY",
    "ISSUES TRACKING"
  ]
}

Project Settings

Host(s)
Optional

Custom Class Names Configuraiton

By default, the App will look for Liferay standard DDM entities (such as structures and templates for journal articles, ADTs, dynamic data lists, etc).

If you want the App to be able to handle custom structures and templates for custom DDM entities you may create a customClassNameConfig.json file in $USERHOME/.ddmtool/config/.

  1. Figure out the className of the new structure/template by querying the database for select value from classname_ where classNameId = 12345. If the App finds a structure/template it does not recognize, it will tell you. It'll also tell you the server classNameId of that structure/template which you'll use in the query.
  2. Create/update the customClassNameConfig.json file, like below:

Sample Custom Class Name Configuration

[
    {
        "filesPath": "generic_record_set",
        "friendlyName": "Generic Record Set",
        "clazz": "com.monator.moh.genericddm.model.GenericRecordSet",
        "getTemplate": false,
        "mayHaveTemplates": true,
        "mayHaveStructures": true,
        "isNativeDDM": true
    }
]