Hello Grid!¶

This guide will show you how to use the limel-grid component to control which widgets to display within a given area.
We'll also go over how to handle different screen sizes.

For more information on what to expect from limel-grid, see the lime-elements documentation.

Creating a Package¶

While you can use limel-grid within an existing package, you will most likely want to separate your widgets and your grid.
So we'll start by running lime-project to create a new package:

lime-project new package

It can be named anything, but in this guide we'll name it My Grid.

Enter the plugin directory and generate a new web component:

cd limepkg-my-grid
lime-project generate web-component hello-grid

When the first component is created, some project setup is needed which may take a while to complete.

Setting up Our Example¶

Once finished, we can navigate to the root directory for web components and start up our favorite code editor.

cd frontend
code .

Our hello-grid component is located in src/components/lwc-limepkg-my-grid-hello-grid/lwc-limepkg-my-grid-hello-grid.tsx.

Within the boilerplate render() method replace the limel-button component with a limel-grid component:

public render() {
    return (
        <limel-grid>
        </limel-grid>
    );
}

We'll add some some mock components to the limel-grid component:

public render() {
    return (
        <limel-grid>
            <my-deep-red-component />
            <my-red-component />
            <my-orange-component />
            <my-yellow-component />
            <my-green-component />
            <my-turquoise-component />
            <my-blue-component />
            <my-dark-blue-component />
            <my-magenta-component />
            <my-light-grey-component />
            <my-dark-grey-component />
        </limel-grid>
    );
}

We'll use these mock components in this example, but you can replace them with actual components if you'd like.

Note

When using a real component, you need to pass the platform and context properties to it, like this:

<my-deep-red-component platform={this.platform} context={this.context} />

Now we need to add a few things to the stylesheet for this component so we'll modify our scss file.

Open src/components/lwc-limepkg-my-grid-hello-grid/lwc-limepkg-my-grid-hello-grid.scss. The file should be empty.

Since we're using mock components, we need to add styling to be able to see and tell them apart.

If you decided to use real components instead of mocks, go ahead and skip this step.

Add the following code to the file:

// Below is stuff that's only here for the boxes in the grid
// to look nice in this example. You wouldn't use any of this
// when placing real components into a grid.

my-deep-red-component {
  background-color: var(--lime-deep-red);
}
my-red-component {
  background-color: var(--lime-red);
}
my-orange-component {
  background-color: var(--lime-orange);
}
my-yellow-component {
  background-color: var(--lime-yellow);
}
my-green-component {
  background-color: var(--lime-green);
}
my-turquoise-component {
  background-color: var(--lime-turquoise);
}
my-blue-component {
  background-color: var(--lime-blue);
}
my-dark-blue-component {
  background-color: var(--lime-dark-blue);
}
my-magenta-component {
  background-color: var(--lime-magenta);
}
my-light-grey-component {
  background-color: var(--lime-light-grey);
}
my-dark-grey-component {
  background-color: var(--lime-dark-grey);
}

Configuring the Grid¶

To configure the grid, we need to give each component in the grid a "name" by which we can reference it later.

You can name them anything you want, like salespipe, or infotile-active-support-tickets.
However, keeping the names to a fixed number of characters improves code readability when we configure the grid.
One to three characters is probably a good number for most cases.

Add this to the top of the scss-file:

my-deep-red-component {
  grid-area: drd;
}
my-red-component {
  grid-area: red;
}
my-orange-component {
  grid-area: ora;
}
my-yellow-component {
  grid-area: yel;
}
my-green-component {
  grid-area: grn;
}
my-turquoise-component {
  grid-area: trq;
}
my-blue-component {
  grid-area: blu;
}
my-dark-blue-component {
  grid-area: dbl;
}
my-magenta-component {
  grid-area: mag;
}
my-light-grey-component {
  grid-area: lgr;
}
my-dark-grey-component {
  grid-area: dgr;
}

And finally for this step, to configure the layout, we add the following code just below the above segment:

limel-grid {
  --lime-grid-columns: 4;

  --lime-grid-area: "drd drd blu dbl" "trq trq blu dbl" "red red red red"
    "dgr mag mag lgr" "ora ora yel yel" "grn grn .   .  " "grn grn .   .  ";
}

Note

We use . to signify empty cells on the grid.

Different Configurations for Different Screen Sizes¶

Let's go back to our component.
Using the @Device decorator, we can update the grid configuration to suit the circumstances.

Add State to the imports from @stencil/core:

import { Component, Element, Prop, State } from "@stencil/core";

Then add SelectDevice to the imports from @limetech/lime-web-components:

import {
    LimeWebComponent,
    LimeWebComponentContext,
    LimeWebComponentPlatform,
    SelectDevice,
} from '@limetech/lime-web-components';

Then use these two decorators as follows:

@State()
@SelectDevice()
private device: any;

Note that the State decorator ensures that the component is re-rendered whenever the value of this.device is changed.

public render() {
    return (
        <limel-grid class={`${this.device?.type}`}>
            <my-deep-red-component />
            <my-red-component />
            <my-orange-component />
            <my-yellow-component />
            <my-green-component />
            <my-turquoise-component />
            <my-blue-component />
            <my-dark-blue-component />
            <my-magenta-component />
            <my-light-grey-component />
            <my-dark-grey-component />
        </limel-grid>
    );
}

The reason we use this.device?.type instead of just this.device.type is so that we don't get an error if this.device is null or undefined.

Our component should look like this:

import {
    LimeWebComponent,
    LimeWebComponentContext,
    LimeWebComponentPlatform,
    SelectDevice,
} from '@limetech/lime-web-components';
import { Component, h, Prop, State } from '@stencil/core';

@Component({
    tag: 'lwc-limepkg-cool-package-hello-grid',
    shadow: true,
    styleUrl: 'lwc-limepkg-cool-package-hello-grid.scss',
})
export class HelloGrid implements LimeWebComponent {
    /**
     * @inherit
     */
    @Prop()
    public platform: LimeWebComponentPlatform;

    /**
     * @inherit
     */
    @Prop()
    public context: LimeWebComponentContext;

    @State()
    @SelectDevice()
    private device: any;

    public render() {
        return (
            <limel-grid class={`${this.device?.type}`}>
                <my-deep-red-component />
                <my-red-component />
                <my-orange-component />
                <my-yellow-component />
                <my-green-component />
                <my-turquoise-component />
                <my-blue-component />
                <my-dark-blue-component />
                <my-magenta-component />
                <my-light-grey-component />
                <my-dark-grey-component />
            </limel-grid>
        );
    }
}

Configure the grid for different states (device types)¶

Modify the limel-grid scss style rule properties:

Note that the first set of rules is essentially a "default" configuration, which we override when a certain class is set on the element.
This is so that if the SelectDevice decorator is updated to supply a new state name we don't know about, we still have that default configuration to fall back on, instead of showing nothing.

limel-grid {
  --lime-grid-columns: 2;

  --lime-grid-area: "drd drd" "trq trq" "red red" "dgr lgr" "ora ora" "grn grn"
    "grn grn" "blu dbl" "blu dbl" "mag mag" "yel yel";

  &.tablet {
    --lime-grid-columns: 4;

    --lime-grid-area: "drd drd blu dbl" "trq trq blu dbl" "red red red red"
      "dgr mag mag lgr" "ora ora yel yel" "grn grn .   .  " "grn grn .   .  ";
  }

  &.desktop {
    --lime-grid-columns: 8;

    --lime-grid-area: "drd drd blu dbl red red red red"
      "trq trq blu dbl dgr mag mag lgr" "ora ora yel yel grn grn grn grn"
      "ora ora yel yel grn grn grn grn";
  }
}

Install your new package¶

Install the package containing this grid component into your solution, restart the server, and your new grid should be there to greet you next time you log in.

If you're working directly within a solution, e.g. you simply generated this grid component within your solution, you'll need to rebuild the frontend for the new grid component to show.
It should be built from the frontend/src folder, so run the following commands:

cd frontend/src
npm run build

Configuring a web-component Slot¶

To add our grid to the dashboard of your solution. In Lime Admin go to the System section and then to Start Pages.
Add your web component with the name lwc-limepkg-cool-package-hello-grid.

Note

In older versions of Lime CRM, components were attached to the dashboard on the start page designer, or usings slots.

To configure the start page, you may have to add the following to your solutions config.yaml

features:
    useMultipleStartPages: True

Hello Grid!¶

Creating a Package¶

Setting up Our Example¶

Configuring the Grid¶

Different Configurations for Different Screen Sizes¶

Configure the grid for different states (device types)¶

Install your new package¶

Configuring a web-component Slot¶

Further reading¶