emotion-sdk v0.1.0

Emotion-SDK

@celonis/emotion-sdk

Emotion SDK is a Celonis-internal SDK built in Angular which provides @celonis/emotion, @celonis/emotion-charts and Celonis Internal Services as a bundle, ready to be used in Angular projects.

How to install Emotion SDK

Once you've got your development environment set up, your ~/.npmrc should contain a reference to the Celonis-internal npm package repository. Emotion SDK is then available through a simple $ npm install @celonis/emotion-sdk or $ yarn add @celonis/emotion-sdk, depending on your package manager of choice. (We generally use and recommend yarn.)

How to use Emotion SDK in your own Angular project

Add Emotion SDK to your project

Create a new Angular project (if you don't already have one) and switch to its root folder:

$ ng new my-project
$ cd my-project

As above, run

$ yarn add @celonis/emotion-sdk

(or npm install …) to make Emotion SDK available within your project (provided it is not already available globally, see above).

Add EmotionSdkModule and its dependencies to your Angular module

Add Emotion SDK's EmotionSdkModule as an import to every NgModule in which you would like to use Emotion SDK components. So for a freshly created Angular project, where in the beginning you only have the app module, this would belong into my-project/src/app/app.module.ts:

import { EmotionSdkModule } from '@celonis/emotion-sdk'; // <-- add this line

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    EmotionSdkModule.forRoot(), // <-- add this line
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Import assets

To make Emotion SDK elements actually look as expected, import all Emotion SDK assets (icons, fonts, i18n, etc.) by adding the lines

{ "glob": "**/*", "input": "node_modules/@celonis/emotion/dist/assets/", "output": "./assets/" },
{ "glob": "**/*", "input": "node_modules/@celonis/emotion-sdk/assets/", "output": "./assets/" }

to your assets in my-project/.angular-cli.json, i.e.:

{
  "apps": [
    {
      "assets": [
        "assets",
        "favicon.ico",
        { "glob": "**/*", "input": "node_modules/@celonis/emotion/dist/assets/", "output": "./assets/" },
        { "glob": "**/*", "input": "node_modules/@celonis/emotion-sdk/assets/", "output": "./assets/" }
      ],
      ...
    }
  ]
}

Lastly, import the shared Emotion SDK styles (the ones shared by all components) by adding the following line to my-project/src/styles.css:

/* Import all CSS "content", i.e. the actual Emotion styles. */
@import '~@celonis/emotion-sdk/assets/emotion-sdk.shared.css';

Note that styles that are specific to particular Emotion SDK UI elements are not part of the above import but come separatively with every UI element (i.e. with the Angular component it corresponds to).

Finally, you might also be interested in using the Sass variables, functions and mixins that Emotion SDK defines (e.g. the commonly defined brand colors etc.) in your own Sass stylesheet. To this end, do:

// Import Sass variables, functions, mixins.
@import '~@celonis/emotion-sdk/styles/main';

in your .scss file. Note that this import statement doesn't produce any CSS "content", i.e. it doesn't produce any styles, but only makes Emotion's variables/functions/mixins available so that they can be used in your own Sass stylesheet.

Building Emotion SDK

Run $ yarn run bundle to pull all dependencies and build Emotion SDK as a standalone package.

Working on Emotion SDK

If you want to make changes to Emotion SDK and, at the same time, test them in any app, running $ yarn run bundle every time you make a change can be quite cumbersome. You might therefore be interested in a setup where your ongoing changes to Emotion SDK will automatically be available in an app:

Suppose, you have cloned the Emotion SDK into the directory emotion-sdk.

In emotion-sdk, run $ yarn install to install dependencies and $ yarn link into ./dist/emotion-sdk (if you don't have this folder already, make sure you have run yarn run bundle) to make Emotion SDK known to yarn. After that, go to your angular app's root folder and run $ yarn link @celonis/emotion-sdk to link your app against the local version of Emotion SDK you're having in emotion-sdk. (Technically, this will simply create a symlink from YOUR-APP/node_modules/@celonis/emotion-sdk to the emotion-sdk directory.) This linking step also needs to be done only once. Finally, run $ yarn install inside the app's folder to install all remaining dependencies that the app needs.

Now, while making changes to Emotion SDK, have $ yarn run dev running in your emotion-sdk directory so that these changes will automatically cause the build in the emotion-sdk/dist/ to be updated as well, so that $ yarn start in the app will pick them up automatically.

Deployment

Emotion SDK is built on Bamboo. All commits to the master branch are automatically published as a new patch version. To release a new minor or major version, increment the version manually in package.json.