Private Models

Introduction

Content models are a main building block in Headless CMS. The first step to storing information in a Headless CMS is to create a content model.

Let’s delve into the details of both public and private models and explore how you can leverage them in Webiny.

Public Models

Public models in Webiny are those content models that are visible within the admin app. These models come with a generated navigation menu, allowing easy access to content entries through the user interface.

Creating public models involves the conventional process of logging into the admin app and using the user interface to create a content model or you can also define public content model via code. The result is the automatic generation of an API, including a GraphQL type and a set of resolvers for seamless data interaction. Alternatively, you can also build public models through code using a plugin.

Private Models

Private models, in contrast, remain hidden from the admin app UI. These models are defined programmatically through a plugin. While the schema and resolvers aren’t auto-generated, developers have the freedom to design them on the backend or API.

Use Cases

Private models find their significance in scenarios where UI visibility is not necessary. They don’t generate a navigation menu, UI, or expose content models in the CMS API endpoints.

Examples

In Webiny, we used private models in various apps. Notable examples include the file manager, folders component, and advanced filters in the Headless CMS UI. These applications showcase the power and flexibility of private models in developing tailored UIs.

Building a PrivateBookModel

Let’s walk through the process of building a private model, taking the Book model with title and price fields as an example. We will also implement create book and list books operations on this model.

Step 1: Create a Book App

We will start by creating a Book App, which is a collection of various plugins needed for Private models. In simple terms, the Book App is a package containing various plugins. We will explore each plugin in the upcoming steps.

Create a directory named packages/books at the root of the Webiny project, and create package.json and tsconfig.json files.

Now, create an src directory under the packages/books directory. We will write our custom code in this directory.

Step 2: Define Model Definition

Create a file (book.model.ts) where you define the private model for your content. This file includes the definition of the book model with fields like title and price, along with their respective validations. We will utilize the createPrivateModel utility for this.

Please create these two files in the packages/books/src directory.

Step 3: Implement CRUD Operations

Now that the private model Book is ready, the next step is to perform CRUD operations on the private model. In this example, we will demonstrate two operations: Create Book and List Books. We will do this in the following three steps.

Step 3.1: Define Context and Various Types

We will use these Context and types further, so for now, let’s define them.

Create a file named src/types.ts.

Step 3.2: Define Interfaces & Methods for Creating and Listing Books

In this step, we will define interfaces for book objects, input for creating books, and methods for creating and listing books.

Create a file named src/books.crud.ts.

Step 3.3: Implement Storage Functionality

Now we will implement storage functionality for the private model and interact with the storage layer using the CMS SDK. We will define a class BooksStorage with methods for creating and listing books and for converting CMS entries to book objects.

Create a file named src/books.storage.ts.

Step 4: Define GraphQL Schema

Our CRUD operations are ready. Now, let’s learn how to make them accessible through the GraphQL API. For this, we will use GraphQLSchemaPlugin. Whenever you want to add something new to GraphQL in Webiny, you register a GraphQLSchemaPlugin and specify type definitions and resolvers. Here, we will define type definitions and resolvers for querying and mutating books.

Create a file named src/books.graphql.ts.

Step 5: Create Book App and Register Plugins

As the next step, we will register all the plugins that we created earlier, i.e.

• the private model created in Step 2
• the CRUD operations defined in Step 3
• and the GraphQL schema plugin created in Step 4

Let’s register all these plugins. Create a src/books.app.ts file. This file sets up the context plugin for handling CRUD operations and the GraphQL schema plugin for exposing CRUD operations via GraphQL.

Step 6: Export the App

Create an index file src/index.ts, export the created app.

Step 7: Register the Book App in Webiny

As the next step, we will register the Book App in the Headless CMS application. Let’s make the following changes in apps/api/graphql/src/index.ts file:

Step 8: Deploy the Application

1. Run the yarn command from the Webiny project root to build our newly created package.

2. Run the deploy command

Step 9: Testing

Once the application is deployed, you will be able to see Query and Mutation related to the Book model.

Here are two example Query and Mutation that you can try in API playground.

Next Steps

Video Reference

For more code examples, references and further exploration, please refer to the attached video.

Example Code References

If you’re looking for code references on private models, as mentioned earlier in Webiny, we used private models in various apps like File Manager, Advanced Content Organization, Advanced Publishing Workflow, etc. You can have a look into the codebase for more details on how we used them.