Skip to content

Latest commit

 

History

History
224 lines (157 loc) · 12.1 KB

README.md

File metadata and controls

224 lines (157 loc) · 12.1 KB
Raw

ember-exclaim CI

This addon allows apps to expose declarative, JSON-configurable custom UIs that are backed by Ember components.

Simple Examples

The building blocks available to an ember-exclaim UI are defined by the app it's used in, but the dummy application in this project contains implementations of several basic components that might be useful. For example, in the demo application, the following would render a header with some filler content below it:

{
  "$vbox": [
    { "$header": "Very Important Content" },
    { "$text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." }
  ]
}

Components can also read from and write back to an underlying data structure. For example, given this environment:

{
  "target": "world"
}

The following UI would render "Hello, world!":

{
  "$text": {
    "$join": ["Hello, ", { "$bind": "target" }, "!"]
  }
}

And something like this would render an input that would update the underlying value of target as the user made changes:

{
  "$input": { "$bind": "target" }
}

hello

Usage

The entry point to a UI powered by ember-exclaim is the <ExclaimUi> component. It accepts the following arguments:

  • @ui: an object containing configuration for the UI that should be rendered
  • @env: a hash whose keys will be bindable from the ui config, to be read from and written to
  • @implementationMap: a mapping of names in the ui config to information about their backing implementations
  • @onChange(envPathOfChangedValue): an optional function that will be invoked when a value in the env changes
  • @wrapper: an optional component that will wrap every rendered component in your UI configuration. The wrapper component will receive the ComponentSpec as @spec (more on ComponentSpec here), the Environment as @env and the component's resolved @config.
  • @useClassicReactivity: an optional flag that, if set, will cause any environment bindings Exclaim constructs to use classic Ember computed machinery rather than native getters and setters that assume data is appropriately @tracked.

Each of these things is described in further detail below.

UI Configuration

The configuration for an ember-exclaim UI boils down to three special keys: $component, $helper and $bind.

$component

Components are used to render content to the screen in an ember-exclaim UI. The basic way to invoke a component is with a hash containing a $component key. The value of this key will be used to look up the underlying Ember component implementation according to the configured implementationMap, and all other keys in the hash will become that component's config. As a concrete example, consider the following usage of a hypothetical text component:

{
  "$component": "text",
  "content": "Hello"
}

This would invoke whatever Ember component is configured under the text key of the given implementationMap, passing it a hash of configuration that looks like { content: 'Hello' }.

$helper

Helpers are used to transform data for an ember-exclaim UI. Unlike components, they don't directly render anything. Helpers are invoked by inserting a hash containing a $helper key. The value of this key will be used to look up the underlying implementation for the helper.

As a concrete example, if you wanted to render an array of items as a comma separated list using the text component above, you might use a join helper:

{
  "$component": "text",
  "content": {
    "$helper": "join",
    "items": ["one", "two", "three"],
    "separator": ", "
  }
}

This would invoke whatever helper function is configured under the join key of the given implementationMap, passing it a hash of configuration that looks like { items: ['one', 'two', 'three'], separator: ', ' }.

$bind

To read and write values in the environment, the UI author can use $bind. For example, dynamically rendering whatever the value the configured environment has for greeting using the same text component described above might look like:

{
  "$component": "text",
  "content": { "$bind": "greeting" }
}

Similarly, an input component could write to the environment's greeting value as the user makes changes:

{
  "$component": "input",
  "value": { "$bind": "greeting" }
}

Note that component implementations might also expose $bindable values to their children, such as an each component that iterates an array and exposes each item in that array under a given name.

Shorthand Syntax

You may have noted that the examples in this section appear more verbose than those at the top of the document. By supplying the name of a shorthand property, components and helpers can be invoked using their name prefixed with a $ as a key for that property, skipping the $component or $helper key completely.

For example, the text component in the demo application declares its shorthand property to be content, making this:

{
  "$component": "text",
  "content": "Hello, world!"
}

Equivalent to this:

{ "$text": "Hello, world!" }

Similarly, if the join helper mentioned above declared items to be its shorthand property, then this:

{
  "$helper": "join",
  "items": [1, 2, 3],
  "separator": " + "
}

Would be equivalent to this:

{
  "$join": [1, 2, 3],
  "separator": " + "
}

The Environment

Keys on the given env object are what powers $bind directives in the configured UI. The object in question may be a simple POJO or something richer, like an Ember Data model. Avoid swapping the env object out wholesale, as this will cause unnecessary rerenders.

Note that $bind works with paths, too, so { $bind: 'foo.bar' } would access the bar key of the foo object in the environment.

The Implementation Map

The @implementationMap given to <ExclaimUi> dictates what components it can render. It should be a hash whose keys are the component and helper names available for use in the UI config. The value for each key should itself be a hash describing the component or helper with that name.

  • component (for components): the name to the Ember component to be invoked when this exclaim-ui component is used in the config, as you'd give it to the {{component}} helper
  • helper (for helper functions): a function that receives a config hash and env information and should return the output value for the helper
  • shorthandProperty (optional for both helpers and components): the name of a property that should be populated when shorthand notation is used for this component or helper (see above)

Implementing Components

The demo app for this repo contains a variety of simple component implementations that you can use as a starting point for building your own.

An ember-exclaim component implementation will receive two arguments when rendered: @config and @env.

@config

The @config argument of the implementing component will contain all other information supplied in the $component hash representing it in the UI config. Any $bind directives in that config will be automatically be resolved when they are read or written. As an example, consider a lightweight implementation of the input component mentioned above.

<input type="text" value={{@config.value}} oninput={{action (mut @config.value) value='target.value'}}>

When invoked as { "$component": "input", "value": {"$bind":"x"} } with x in the environment having the value 'hello', this component will receive the equivalent of { value: 'hello' } as its config, except that reading and writing config.value will redirect back to x on the environment.

@env

The @env arg to components in the UI will contain the same @env value passed to <ExclaimUi> (or an extension of that value). Components should rarely need to access it directly, but it's available as a grab bag of shared state that all components in an instance of a UI have access to.

Rendering Children

In many cases, components may want to accept configuration for subcomponents that they can render under different circumstances, such as an if component that conditionally renders some content, or an each component that renders the same child multiple times against different values. Implementations can accomplish this by {{yield}}ing the configuration for the child component.

For example, the vbox component in the demo application applies a class with flex-flow: column to its root element and then simply renders all its children directly beneath:

{{#each @config.children as |child|}}
  {{yield child}}
{{/each}}

By default, children will inherit the environment of their parent. This environment can be extended by passing a POJO with additional key/value pairs as a second parameter to {{yield}}. Check the implementation of each and let in the demo app for examples of how this can be used.

Implementing Helpers

The demo app for this repo contains a handful of helper implementations that you can use as a starting point for building your own.

An ember-exclaim helper implementation is simply a function that takes two arguments, config and env, which are the same two values described for components above. The value returned when this function is called will be the ultimate value of the { $helper: ... } hash in the UI configuration.

Migrating from v1 to v2

The v2 release of ember-exclaim simplified and modernized the internals of the addon to enable clean operation against @tracked data, while also eliminating the need for using get and unwrap when working with data using the classic computed reactivity model. In addition, some inconsistencies and overly-complex APIs that had organically evolved over the course of v1 were cleaned up, resulting in a handful of breaking changes:

  • Exclaim now requires Ember 3.28+ and has dropped support for Internet Explorer. It has also been converted to a v2 addon, meaning consumers must be using Embroider or ember-auto-import@2.
  • By default, ExclaimUi now uses native getters and setters for helpers and bindings in UI config, assuming data in the environment is appropriately @tracked.
    • Support for the "classic" computed reactivity model is now opt-in via the @useClassicReactivity flag on ExclaimUi.
    • Calling .get() or .set() on an object retrieved from a component's config or environment is now deprecated with the classic reactivity model, and fully unavailable under the tracked model. Fields on config or the environment may be read via direct access, and should use Ember's importable set if they require classic reactivity semantics.
  • The @env passed into ExclaimUi is no longer wrapped in an Environment object
    • It no longer automatically has EmberObject methods such as get and set.
    • There is no longer an .extend() method; instead of yielding this.args.env.extend(someExtraData) to expose extra data to children, components should just yield someExtraData.
    • The rarely-used wrap export has been removed, and the less-rarely-used unwrap export is now a deprecated no-op.
    • The @resolveFieldMeta arg and metaForField env method have been removed.
  • The shape of the implementation map has been adjusted:
    • componentPath is now component, and expects a ComponentLike value rather than a string
    • componentMeta and helperMeta have been renamed simply meta