Skip to main content

Admin Area Package

WHAT YOU’LL LEARN
  • how to quickly create a functional app Admin area app

Prerequisites#

Before you start this tutorial, make sure that you have Webiny installed and to read our Introduction tutorial.

Overview#

The UI scaffold is our boilerplate React application that works out of the box without you needing to actually write any code. It will enable you to create, update and delete the data via the form and to list and view it. In this article we will go through the process of generating the code.

The command you will run is yarn webiny scaffold, and you run it from the project root.

You will get a set of simple questions to answer and, in the end, a React application package will be generated.

Also note that in this tutorial we will use CarManufacturer as our data model name.

Running the Scaffold#

Run the scaffold command and follow the questions. Select the Admin Area package option and let's go through all the questions in detail:

1. Enter the name of the initial data model#

This is the name of your API data model, so type it in. As mentioned before, we will use CarManufacturer in this tutorial.

The GraphQL queries, mutations, responses, and variable names in the code will use this value in singular and plural, kebab-case, camel-case or some other form.

export const LIST_CAR_MANUFACTURERS = gql`
query ListCarManufacturers(
$sort: [CarManufacturerListSort!]
$where: CarManufacturerListWhereInput
$limit: Int
$after: String
) {
carManufacturers {
listCarManufacturers(sort: $sort, where: $where, limit: $limit, after: $after) {
data {
id
title
description
isNice
createdOn
savedOn
createdBy {
id
displayName
type
}
}
}
}
}
`;
export const CREATE_CAR_MANUFACTURER = gql`
mutation CreateCarManufacturer($data: CarManufacturerCreateInput!) {
carManufacturers {
createCarManufacturer(data: $data) {
data {
id
title
description
isNice
createdOn
savedOn
createdBy {
id
displayName
type
}
}
error {
code
message
data
}
}
}
}
`;

The name value is also used to create both the defaults for the package location and the package name.

The initial data model has 3 fields (title, description and isNice) to show you how to structure your data model.

Validation of the data model name allows only a-z and A-Z. You can name your model all lowercase or all uppercase. It is up to you - but try to keep it in pascal-case.

2. Enter the package location#

A full location of the package, where the package files will be generated, from the root of the project.

info

The value given in the previous question is used to create the default package location.

We think it is best to organize your packages in packages directory, so by default it is set into that directory, but you can type whatever location you want.

note

To learn more about Webiny's project organization, checkout this article.

The default value is packages/car-manufacturers/admin-app. Notice that the data model name CarManufacturer is in plural and kebab-cased.

3. Enter the package name#

The package name that you will reference to in the code.

info

As in the location step, the value from the first question is used to create the default package name.

The default value is @car-manufacturers/admin-app as we like scoping packages. You can set it to what ever you want, providing it is passing the validation.

The Code#

Generated code contains:

  1. src/views/graphql.ts with GraphQL queries and mutations for the data model.
  2. src/views/CarManufacturers.tsx with a React component that renders both the list view and the form.
  3. src/views/CarManufacturersDataList.tsx with a React component that lists existing data models via the GraphQL queries.
  4. src/views/CarManufacturerForm.tsx which utilizes our @webiny/form package to display and populate the form.
  5. src/rotues.tsx with RoutePlugin definition to add the route in the admin area.
  6. src/menus.tsx with AdminMenuPlugin definition to display the menu in the admin area.
  7. src/types.ts with interfaces for entry items and data list props.
  8. src/index.ts with exports of the plugins to be used in the admin app.

Using the Generated Code in Your Project#

In the main admin app file you need to import your package and include it in the plugin registration array.

apps/admin/code/src/plugins/index.ts
// at the top of the file
import carManufacturerPlugin from "@car-manufacturers/admin-app";
// in the end of the registration array
carManufacturerPlugin()

Changing the Form#

Let's say you want to add a new field named country to identify where is the Car manufacturer located.

You would add a new Cell component with Bind and Input components to the existing form, something like this:

packages/car-manufacturers/admin-app/src/views/CarManufacturerForm.tsx
<Cell span={12}>
<Bind name="country">
<Input label={"Country"} />
</Bind>
</Cell>

You need to change GraphQL as well, for example we will add it into mutation for creating the entry:

packages/car-manufacturers/admin-app/src/views/graphql.ts
export const CREATE_CAR_MANUFACTURER = gql`
mutation CreateCarManufacturer($data: CarManufacturerCreateInput!) {
carManufacturers {
createCarManufacturer(data: $data) {
data {
id
title
description
isNice
# add new field here
country
#
createdOn
savedOn
createdBy {
id
displayName
type
}
}
error {
code
message
data
}
}
}
}
`;

You need to make changes in other mutations and queries as well.

Changing the List#

After you have the country field, you want to be able to sort by it. You would add it to the sorters in the data list component:

packages/car-manufacturers/admin-app/src/views/CarManufacturersDataList.tsx
const sorters = [
{
label: "Newest to oldest",
value: "createdOn_DESC"
},
{
label: "Oldest to newest",
value: "createdOn_ASC"
},
{
label: "Tile A-Z",
value: "title_ASC"
},
{
label: "Title Z-A",
value: "title_DESC"
},
// add sorters here
{
label: "Country A-Z",
value: "country_ASC"
},
{
label: "Country Z-A",
value: "country_DESC"
}
];

Adding the Menu#

If you want to add some new menu in the Admin area, check out the packages/car-manufacturers/admin-app/src/menus.tsx file. You can make a copy of that file, name it myMenu.tsx and import it into the packages/car-manufacturers/admin-app/src/index.ts.

Adding the Route#

If you want your created menu to load some route, check out the packages/car-manufacturers/admin-app/src/routes.tsx file. Also, you can copy that file and change what you require. Remember to import it into the index.ts file.

Building the Code#

When you make changes to the code, make sure you run yarn webiny ws run build --folder=packages/car-manufacturers/admin-app to actually compile your code for the deployment.

You can even have a watcher running for your code with yarn webiny ws run watch --folder=packages/car-manufacturers/admin-app.

Of course, the folder value is your package location.

Run locally#

Unlike the API, you can run the React application locally:

  1. cd apps/admin/code
  2. yarn start --env=YOUR_ENVIRONMENT

This will start the local build of the Admin app. Also, it will automatically rebuild and refresh when it detects changes in the code.

Deploy the Admin App#

To use the generated React application online, you must deploy it. To deploy, use the command:

yarn webiny deploy apps/admin --env YOUR_ENVIRONMENT

Next Step...#

Now you have the functional UI in the admin area to create, update, delete, and list the CarManufacturers.

Last updated on by Bruno Zorić