Warning
You're browsing the documentation for an old version of Webiny. Consider upgrading your project to Webiny 5.40.x.
Can I Use This?
  • This feature is available since Webiny v5.39.2.
What you will learn
  • what is private model
  • how to create a private model
  • how to implement CRUD operations for a private model

Introduction
anchor

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
anchor

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
anchor

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
anchor

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
anchor

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
anchor

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.

The code that we cover in this tutorial can also be found in our GitHub examples repositoryexternal link.

Step 1: Create a Book App
anchor

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.

package.json
tsconfig.json

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

Step 2: Define Model Definition
anchor

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.

book.model.ts

Step 3: Implement CRUD Operations
anchor

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
anchor

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

Create a file named src/types.ts.

types.ts

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

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.

books.crud.ts

Step 3.3: Implement Storage Functionality
anchor

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.

books.storage.ts

Step 4: Define GraphQL Schema
anchor

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.

books.graphql.ts

Step 5: Create Book App and Register Plugins
anchor

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.

books.app.ts

Step 6: Export the App
anchor

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

index.ts

Step 7: Register the Book App in Webiny
anchor

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:

apps/api/graphql/src/index.ts

Step 8: Deploy the Application
anchor

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

  2. Run the deploy command

Use the webiny watch command to continuously deploy application code changes into the cloud and instantly see them in action.

Step 9: Testing
anchor

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
anchor

Video Reference
anchor

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

Example Code References
anchor

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