Best Practices

This section documents best practices, issues to be aware of, and generally a checklist of things to look into when building your application.

Theming

When working on themes, its easy to get started by using an existing theme, and creating more specific rules in your own style sheets when you want to change a behavior. This practice tends to work well for small tweaks, but is problematic for larger changes. As designers start to exert influence on your application, you’ll find yourself moving farther and farther from any pre-made theme, and spending more and more effort overriding styles from themes rather than directly editing the theme.

As such, best practice is to copy a theme folder from /src/themes in the layer-ui-web repository, add this folder to your project, and modify the themes as needed.

It is not a violation of best practice to override styles from Layer’s themes, and does come with benefits (updating to latest version of the UI project gives you the latest themes), but as the number of overrides grows:

  1. You’ll waste time debugging how these rules work with Layer’s rules
  2. You’ll be loading a lot of unused rules
  3. Changes to layer’s themes on upgrading could have unanticipated effects on your own CSS

Card and Message Heights Should Not Change

There are exceptions to this rule, but the following should be understood:

  1. If a card or Message changes height, it pushes all messages below it down
  2. If the user is looking at the Message at the bottom of the message list when messages are pushed down, they will no longer be at the bottom of the Message List. This is bad.
  3. As soon as Messages load, the Message List automatically scrolls to the bottom. Any message that changes height after first rendering means that the user is now somewhere in the middle of the Message List, and somewhat confused by that.

Loosing track of this rule will result in a very bad user experience. Where is this commonly a problem?

  1. Images that size after they’ve finished loading the image from a server
  2. Videos that size after they’ve finished loading the video from a server
  3. Any kind of content that is waiting for a server…
  4. Animations of expanding/collapsing messages/cards

How best to insure that this doesn’t happen when loading variable content from a server?

  • Fixed height: Hardcode in a height into the Message, and whatever comes from the server must render within that height.
  • Metadata: Include data in your Message about how much height to allocate as the sender of the message presumably knows something about the content before its being sent. Metadata can be included by adding additional MessageParts with a JSON body.

Where is it acceptable to change the height of a message?

  1. The Message is in the user’s view and the user is interacting with it. Example: The user has clicked on a Message and you want to expand it to show more detail. Messages below it will be pushed down, but the user’s attention is on the widget that is resizing but not moving.
  2. The Message is at the very bottom of the Message List (its not pushing anything down). Even with this, you have to be careful; if you animate a size increase of the last message AFTER the Message List has rendered and scrolled to the bottom, the user is no longer at the bottom of the list. Resizing the bottom message must be accompanied by updating the scroll position.

Defining Webcomponents

While a <div/> element is defined to have a display: block, and a <span /> element is defined to have a display: inline, a newly defined WebComponent does not have a default display setting; this can cause unexpected rendering problems. They behave as though they are display: inline, which makes adjusting height and width problematic.

As part of defining any WebComponent, make sure that you define in a stylesheet what display that Webcomponent will use.

MessageHandler Mixins

You can defined a Card (i.e. a renderer for a given type of Message) using any webcomponent technology you want. However, using Layer’s UI framework to register a component, and pairing it with the Message Handler Mixin will give a consistent and understood widget lifecycle, with all the necessary event handlers wired up for you, and is the recommended best practice.

For more information, see Custom Cards.

Core Components Templates