ember-emeis

The frontend for the emeis user management service

Compatibility

• Ember.js v3.20 or above
• Ember CLI v3.20 or above
• Node.js v10 or above

Installation

$ ember install ember-emeis

Then add the following lines to your app/styles/app.scss:

@import "ember-uikit";
@import "ember-emeis";

Register the engine in app/app.js:

export default class App extends Application {
  // ...

  this.engines = {
    "ember-emeis": {
      dependencies: {
        services: ["store", "fetch", "intl", "notification", "router"],
      },
    },
  };
}
});

Emeis requires the following services to be injects:

• store - almost all of the data fetching is done using ember data
• fetch - the user export requires a fetch services that handles authentication
• intl - ember-intl for i18n
• notification - handles success and error messages
• router - the ember router service

Configuration

Emeis options

Basic configuration of ember-emeis can be done via the emeis-options service. To generate it, run ember g service emeis-options and add it to the dependencies in app/app.js:

export default class App extends Application {
  // ...

  this.engines = {
    "ember-emeis": {
      dependencies: {
        services: ["store", "intl", "notification", "router", "emeis-options"],
      },
    },
  };
}
});

The config service supports the following options:

import Service from "@ember/service";

import DummyButton from "dummy/app/components/dummy-button/dummy-button";

export default class EmeisOptionsService extends Service {
  // number of items in list views
  pageSize = 10;

  // force the locale of models to a specific value (i.e. to make it "untranslated")
  forceLocale = {
    scope: "en",
  };

  // hide "username" field
  emailAsUsername = false;

  // show only a subset of the main navigation entries
  navigationEntries = ["users", "scopes"];

  // user view specific settings
  user = {
    /*
    Within the actions block you can define functions which evaluate the visibility of the "deactivate" and "delete" buttons in the model edit form. The visibilty must be defined for each model separately. The model must support the "isActive" property for deactivation capabilities, which are currently only supported by user and scope.
    */
    actions: {
      deactivate: (model) => myUser.canChange(model),
      delete: {
        label: "some.translation.key", // you can optionally override the label for the action button with translation key or static string
        func: (model) => myUser.canDelete(model), // in case of label overrides, you have to define th function override via the "func" key
      },
    },
    // show only a subset of the "additional" fields on the user model
    additionalFields: {
      phone: "required",
      language: "required",
      address: "optional",
      city: "optional",
      zip: "optional",
    },
    // adds additional custom columns to this model's list view. *Scopes are not supported, since they are represented as a tree!*
    customColumns: [
      {
        heading: "Funktion", // ember-intl or string
        slug: "additional-column-function", // relative to "model.metainfo[slug]"
        sortable: true, // whether sorting is supported for this column
        localized: true, // whether to expect a plain value or a object with localized values
      },
    ],
    /*
    On each model edit view (e.g. users) you can define a custom component. The component will be rendered at the bottom of the edit view, but above the primary form buttons. Each component can be designed freely and the model will be passed into the component as `@model` argument. For a working demo have a look at our "dummy-button" at "dummy/app/components/dummy-button".
    */
    customComponent: DummyButton,
    /* 
    Exclusively on USER model - Optionally hide the "active" / "inactive" filter buttons on top of the user list. You can pass
    a function, boolean or string as value.
    */
    filtersVisible: () => true,
    /* 
    Exclusively on USER model - define a custom component which will get displayed next to the 'inacitve' pill on top of the user detail view. Ideally this will be an inline element.
     */
    statusComponent: DummyStatus,
  };

  scope = {
    actions: {
      deactivate: () => false, // statically deactivate the deactivate-button
      // leaving out the "delete" key here will always display the delete button
    },
    // define custom fields for a given context (user, scope, role or permission)
    metaFields: [
      {
        slug: "test-input",
        label: "My Input", // this could also be an ember-intl translation key
        type: "text",
        visible: true,
        readOnly: false,
        required: false, //marks this field as optional
        placeholder: "some.translation.key", //ember-intl translation key or plain string
      },
      {
        slug: "test-input-2",
        label: "some.translation.key",
        options: [
          // insert a static list of options (value, label), or a (async) function which resolves to a list of options
          {
            value: "option-1",
            label: "Option one",
          },
        ],
        type: "choice",
        visible: () => true,
        readOnly: false,
        required: true, //marks this field as required
      },
    ],
  };
}

Watch out - the translation key has to be present in your local translation files.

There are special options available for options, type and visible properties.

type - meta field

Defines the type of the output component and can either be a text or a choice.

required - meta field

Marks this field as optional or validates its presence in case it's set to true. Custom choice fields may not be validated as required, tho.

options - meta field

In combination with type:"choice" the options can be a list of options ({value, label}) or a (async) function which resolves to a list of options.

visible & readOnly meta field

Accepts a boolean value for static visibility or a (async) function which evaluates to a boolean value. Submitted functions will evaluate live while rendering.

The evaluation function will receive the current model as argument. For instance if you are on the scope route, you will receive the scope model as first argument. Same for user | role | permission

So the function signature looks like this for visible and readOnly.

type visible = (model: scope | user | role | permission) => boolean;

And an actual implementation example, which makes use of the model.name property:

{
  // ...
  visible: (model) => model.name === "test-scope",
  // ...
}

For a complete emeis-options configuration open the test config.

Emeis store

If you need to customize your store service passed to emeis, use: ember g emeis-store <your_name>

This will generate a store service and an adapter for you. In those two files you can then configure custom api endpoints or hosts and/or custom authentication.

Contributing

See the Contributing guide for details.

License

This project is licensed under the LGPL-3.0-or-later license.

<3