Quickstart

In this tutorial we will show you how to setup both Contember Engine and Contember Admin to create your first project.

Prerequisites

Installed NPM version 6+
Installed Docker with Docker Compose

Step 1: Install and run Contember locally#

npm init @contember quickstart

It will create a new folder with basic Contember setup. After it is done:

cd quickstart

And then install dependencies:

Windows
Mac
Linux

npm i

And you're ready to go. Just start Docker and Contember is running.

docker-compose up

Contember is running

Admin at http://localhost:1480
API endpoints at http://localhost:1481 (you can authorize with token 0000000000000000000000000000000000000000)
- To connect to the GraphQL you can use pre-packed client (Apollo Playground) available at http://localhost:1481/playground
Adminer database management tool (Adminer) at http://localhost:1485
Minio local S3 provider at http://localhost:1483 (you can sign in with contembeer / contember credentials)
Mailhog testing SMTP at http://localhost:1484
PostgreSQL database at localhost:1482 (you can sign in with contember / contember credentials)

Step 2: Create first project#

From the Step 1 you should have a folder that looks like this:

quickstart
  └── admin
      ├── SideMenu.tsx
      ├── index.html
      ├── index.tsx
      ├── pages
      ├── vite-env.d.ts
      └── vite.config.ts
  └── api
      ├── acl.ts
      ├── index.ts
      ├── migrations
      └── model
  ├── contember.yaml
  ├── docker-compose.override.dist.yaml
  ├── docker-compose.override.yaml
  ├── docker-compose.yaml
  ├── node_modules
  ├── package-lock.json
  ├── package.json
  ├── scripts
  └── tsconfig.json

Create your first data model#

First you have to tell Contember Engine, how your data model looks like. The init command automatically created api/model/index.ts file, so go there.

Here you start defining your project schema. Really simple example looks like this:

api/model/index.ts

import { SchemaDefinition as d } from '@contember/schema-definition';

export class Page {
    title = d.stringColumn()
    content = d.stringColumn()
}

You import SchemaDefinition so you'll get TypeScript autocompletion.
You define your fist entity - Page. For this example let's just add two columns named title and content, both are string.

Then you need to generate a database migration for Contember Engine:

npm run contember migrations:diff quickstart add-page

npm run contember is a Contember CLI, if you call this command you'll see all the available commands
We'll use migrations:diff command. It'll go through your schema and generate migration - how to get from previous state to your new one.
This command needs two parameters: first is name of your project (quickstart in our example) and then name your migration. It can be anything you want.

Run this command and choose an option Yes and execute immediately. It will create your migration and execute it imediatelly (you have to confirm this). Now if you look into your database, you'll see there table page with three columns: id, title, content. Nice.

Create your administration UI#

Now we have something we want to edit in UI. Let's start by adding a listing page for our pages.

Add listing page#

Go to admin/pages and create new file Pages.tsx.

admin/pages/Pages.tsx

import { TablePage, TableCell, Field } from "@contember/admin";

export const PageList = (
    <TablePage entities="Page" pageName="pages">
        <TableCell><Field field="title" /></TableCell>
    </TablePage>
)

Import @contember/admin package for TypeScript autocompletion.
Export new PageList (you can name it anyway you like)
Use TablePage component.
Tell it what entitities you'd like to edit Page (same name we used in model)
Name your list (pageName="pages"). Name is used for url in administration.
Tell it what data you want to see. We'll want to see title in our example. (And added it into TableCell which we'll make use of later.)

If you go to localhost:1480/pages you'll see list of your pages. Which is empty as we didn't add any data there yet.

Let's add some data.

Add create page#

admin/pages/Pages.tsx

import {
  TablePage,
  TableCell,
  Field,
  CreatePage,
  TextField,
  TextAreaField
} from "@contember/admin";

export const PageList = (
...
)

export const PageCreate = (
    <CreatePage
        entity="Page"
        pageName="pageNew"
    >
        <TextField field="title" label="Title" />
        <TextAreaField field="content" label="content" />
    </CreatePage>
)

For simplicity we'll add it to the same file.
This time we'll use CreatePage component.
We'll tell it what we want to add (Page), how is this component named (pageNew).
We'll use two new components - TextField and TextAreaField and tell them what fields to edit.

Now at localhost:1480/page-new you can create new page. And if you go to the list of page you'll see the data are there.

But it doesn't work very well. One of the thing missing is to go to edit mode after you created new page. So let's start by adding edit page:

Add edit page#

admin/pages/Pages.tsx

import {
  ...
} from "@contember/admin";

export const PageList = (
  ...
)

export const PageCreate = (
  ...
)

export const PageEdit = (
    <EditPage
      entity="Page(id = $id)"
      pageName="page"
    >
        <TextField field="title" label="Title" />
        <TextAreaField field="content" label="content" />
    </EditPage>
)

For simplicity we'll add it to the same file as well.
Looks almost the same as create page - but we have to tell it which page to edit.

Let's use it. We'll redirect user from create page to redirect page after the page is sucessfully created:

admin/pages/Pages.tsx

export const PageCreate = (
    <CreatePage‚
        entity="Page"
        pageName="pageNew"
        rendererProps={{ title: 'Add page' }}
        redirectOnSuccess={(request, id) => ({
            ...request,
            pageName: 'page',
            parameters: {
                id,
            },
        })}
    >
        <TextField field="title" label="Title" />
        <TextAreaField field="content" label="content" />
    </CreatePage >
)

We added two new things: rendererProps and redirectOnSuccess.
rendererProps are pretty simple in this case: just added title so we know that we're on this page.
redirectOnSuccess is more complicated: we take user to page with id of the newly created page.

Now if you create new page you're automatically redirected to edit page.

What's missing is edit button to the list of pages.

admin/pages/Pages.tsx

export const PageList = (
    <TablePage entities="Page" pageName="pages">
        <TableCell><Field field="title" /></TableCell>
        <TableCell shrunk><PageLinkById to="page">edit</PageLinkById></TableCell>
    </TablePage>
)

We've added new TableCell and into it a PageLinkById component.
This component is pretty simple - it will create a link to a component called page and sends id as parameter. Which is actually our edit page.
Minor touch is use of shrunk with tells the cell to be as small as possible.

That's it. One last thing is to add our pages to the left sidebar:

Add pages to side menu#

admin/SideMenu.tsx

import { Menu } from '@contember/admin'

export const SideMenu = () => {
    return (
        <Menu>
            <Menu.Item>
                <Menu.Item title="Dashboard" to="dashboard" />
                <Menu.Item title="Pages" to="pages" />
                <Menu.Item title="Create new page" to="pageNew" />
            </Menu.Item>
        </Menu>
    )
}

And that's it!