# Simple banner This guide shows how to build a simple banner component containing components and enumerations **Do you have suggestions?:** [Join our community](https://hygraph-community.slack.com) to suggest new recipe ideas! This guide shows how to build a simple banner component containing a title, a description, a component field for links, and an enumeration for theme selection. It will let you add a both internal documents through references or external URLs. ![Simple banner component with fields](https://hygraph.com/images/docs/recipes/banners/simple-banner-component-fields.png) Here is an example that shows how this banner could potentially look on your frontend: ![Example banner](https://hygraph.com/images/docs/recipes/banners/mock-banner-simple.png) ## Prerequisites - `REQUIRED:` You need to have a Hygraph account. If you don't have one, [you can sign up here.](https://app.hygraph.com/signup) - `REQUIRED:` You need to have a Hygraph project. - `OPTION 1:` [Create a project.](https://hygraph.com/docs/getting-started/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes. - `OPTION 2:` [Clone the basic models project.](https://hygraph.com/docs/recipes/banners/banner-simple#clone-the-basic-models) If you're already familiar with model creation and only want to follow the parts of the tutorial related to the banners, you can start here. - `OPTION 3:` [Clone the entire cookbook.](https://hygraph.com/docs/recipes/banners/banner-simple#clone-the-complete-cookbook) This is the way to go if you're curious about how the banners are made but don't want to follow the step-by-step creation process. This project contains the entire **Banners Cookbook** so you can compare them, or look into what instances they contain. - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this banner to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema. **Note:** - Take [plan limits](https://hygraph.com/pricing) into consideration when adding a recipe to your own project. - Are you new to Hygraph? You may want to check out our [Getting Started Tutorial!](https://hygraph.com/docs/getting-started/tutorial/tutorial-overview) ## Core concepts In this guide, you'll work with enumerations, references, components and basic component fields. Let's look into these concepts: - **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type. - **References:** References are relations between two or more content entries in your project. With references, you can reuse content entries by connecting them. Once the relation is configured, you can also use it to create related content from the content creation screen. - **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry. - **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry. - **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components. ## What you can do This guide offers two paths: - [Path 1:](https://hygraph.com/docs/recipes/banners/banner-simple/#step-by-step-guide) Use this guide to create a simple banner component that you can reuse across different models in your Hygraph projects. - [Path 2:](https://hygraph.com/docs/recipes/banners/banner-simple#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the banners right away, or you can clone the project that contains the entire **Banners cookbook** to compare the different banner configurations without having to clone multiple projects. ## Clone project ### Clone the basic models We have prepared a project that contains only the basic models - Author, Shop, and Book - in case you don't want to build them from scratch: [Clone this project](https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)) If you decide to clone this project, you can skip model creation and [start from this step](https://hygraph.com/docs/recipes/banners/banner-simple#create-a-link-component). ### Clone the complete cookbook We have prepared a project that contains the entire **Banners cookbook**: [Clone this project](https://app.hygraph.com/clone/720d86e74f47481ab3685aeb35090a11?name=Hygraph%20Recipes%20-%20Banners) This cookbook contains all the recipes we have so far to create banners, so you can compare the different banner configurations without having to clone multiple projects. To find this particular recipe in the cookbook project, navigate to the schema and look for **"Simple banner"**. This project also contains a demo model that includes all the banner components as basic components, as well as a modular component that you can use as a banner type selector. ## Step-by-step guide Before we can build our simple banner component, we sometimes need to create other schema elements that will later be added to those components as instances. In this guide, we will also be building nested components. When building nested components, you need to start building from the deepest level of nesting upwards, so you can have one component ready to nest it into the next one. We will divide this process in steps to make it more manageable: 1. **Create the models:** We will create 3 sample models - Author, Book, and Shop - to use in our references. 2. **Create a link component:** We will build a link component that we can add to other components as a button or link element. 3. **Create an enumeration:** We will create an enumeration that will allow users to select a theme for their banners. 4. **Create the simple banner component:** Finally, we'll combine the schema elements we created before to set up our simple banner component. ### Create the models **Would you like to skip this step?:** If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! [Click here to clone the project](https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)) and [skip over to the next section](https://hygraph.com/docs/recipes/banners/banner-simple#create-a-link-component) to continue the tutorial. Since our simple banner component will ultimately allow linking to external URLs as well as internal content, we need to create a set of models that we can reference later on. For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models: - Author - Book - Shop #### Author model ![Author model](https://hygraph.com/images/docs/recipes/banners/banner-author-model.png) Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information: | Field | Input | | ------------- | ------- | | Display Name | Author | | API ID | Author | | API ID Plural | Authors | We'll click `Add model` to save. Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image. Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | -------- | ----------------------------- | ---------------------------- | | Settings | Display Name | Author name | | Settings | API ID | authorName | | Settings | `Use as title field` checkbox | Leave this checkbox selected | We'll click `Add` to save. Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | ---------- | | Settings | Display Name | Author bio | | Settings | API ID | authorBio | We'll click `Add` to save. Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | ------------ | | Settings | Display Name | Author image | | Settings | API ID | authorImage | We'll click `Add` to save. Now that we're done with our **Author** model, let's move on to the **Book** model. #### Book model ![Book model](https://hygraph.com/images/docs/recipes/banners/banner-book-model.png) Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information: | Field | Input | | ------------- | ----- | | Display Name | Book | | API ID | Book | | API ID Plural | Books | We'll click `Add model` to save. Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author. Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | -------- | ----------------------------- | ---------------------------- | | Settings | Display Name | Book name | | Settings | API ID | bookName | | Settings | `Use as title field` checkbox | Leave this checkbox selected | We'll click `Add` to save. Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | ---------------- | | Settings | Display Name | Book description | | Settings | API ID | bookDescription | We'll click `Add` to save. Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | ---------- | | Settings | Display Name | Book cover | | Settings | API ID | bookCover | We'll click `Add` to save. Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model. We'll find the `Reference` field on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- | | Define | Reference type | Select `Allow only one model to be referenced` | | Define | Models to reference | Use the dropdown menu to select `Author` | | Define | Reference direction | Select `Two-way reference` | | Define | `Allow multiple...` checkbox | Select `Allow multiple Book per Author` and `Allow multiple Author per Book` | | Configure reference | Display Name | Author | | Configure reference | API ID | Author | | Configure reverse field | Display Name | Book | | Configure reverse field | API ID | book | We'll click `Add` to save. Now that we're done with our **Book** model, let's move on to the **Shop** model. #### Shop model ![Shop model](https://hygraph.com/images/docs/recipes/banners/banner-shop-model.png) Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information: | Field | Input | | ------------- | ----- | | Display Name | Shop | | API ID | Shop | | API ID Plural | Shops | We'll click `Add model` to save. Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location. Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | -------- | ----------------------------- | ---------------------------- | | Settings | Display Name | Shop name | | Settings | API ID | shopName | | Settings | `Use as title field` checkbox | Leave this checkbox selected | We'll click `Add` to save. Next, we'll add another `Single line text` field for the shop address. We'll use the following information: | Tab | Field | Input | | -------- | ------------ | ------------ | | Settings | Display Name | Shop address | | Settings | API ID | shopAddress | We'll click `Add` to save. Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | ------------ | | Settings | Display Name | Shop picture | | Settings | API ID | shopPicture | We'll click `Add` to save. Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | -------- | | Settings | Display Name | Location | | Settings | API ID | location | We'll click `Add` to save. Now that we're done with our three models, let's create the link component. ### Create a link component We are going to start by creating our first component. Our banners will need to have a link, and in this case we'll create a simple component for that. [Video](https://www.youtube.com/watch?v=zjh6Rgi_GbY) We'll click `+Add` next to **Components** and we'll use the following information to create one: | Field | Input | | ------------- | ----- | | Display Name | Link | | API ID | Link | | API ID Plural | Links | Click `Add component` to save. We can now start adding instances to this component. Let's start with a `Single line text` field, which will be the label of our link. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | ----------- | ------------------------------ | ---------------------------- | | Settings | Display Name | Link label | | Settings | API ID | linkLabel | | Settings | `Use as title field` checkbox | Leave this checkbox selected | | Validations | `Make field required` checkbox | Select this checkbox | We'll click `Add` to save. We want our users to be able to add internal and external links, so we'll add a `Reference` field to relate internal content, and a `Slug` for external URLs. We'll start with the external links. Let's add a `Slug` field, which will be our link URL. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Settings | Display Name | External link | | Settings | API ID | externalLink | | Settings | `Lowercase` checkbox | Leave this checkbox selected | | Validations | `Set field as unique` checkbox | Leave this checkbox selected | | Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. | We'll click `Add` to save. The way we configured the field validations to match a URL pattern will ensure that users will complete this field with a valid URL pattern, preventing errors. If their input does not match the expected pattern, the custom error message will inform them. Next, we're going to ensure Editors can create internal links to content entries from the models that we created at the start of this tutorial. To achieve this, we'll add a `Reference` field. We'll find it on the **Add fields** right sidebar and use the following information: | Tab | Field | Input | | ------------------- | ------------------- | ------------------------------------------------------------ | | Define | Reference type | Select `Allow multiple models to be referenced (Union Type)` | | Define | Models to reference | Use the dropdown menu to select `Author`, `Book`, and `Shop` | | Define | Reference direction | Select `One-way reference` | | Configure reference | Display Name | Internal link | | Configure reference | API ID | internalLink | We'll click `Add` to save. Finally, we'll add a `Boolean` field that users can toggle to indicate if the link should open on a new tab. We'll find the `Boolean` field on the **Add fields** right sidebar and use the following information: | Field | Input | | ------------ | ------- | | Display Name | New tab | | API ID | newTab | We'll click `Add` to save. This is how you build a link component in Hygraph. You can add this component to different models in your schema. We will add this to our simple banner later on. ![Link component](https://hygraph.com/images/docs/recipes/banners/components-link-done.png) Next, we'll create our theme enumeration. ### Create an enumeration The next step is to create the theme enumeration that we can later add to our simple banner as a dropdown menu. [Video](https://www.youtube.com/watch?v=tbKtE6SRdKk) Let's navigate to our project schema and click `+Add` next to **Enumerations**. We'll use the following information: | Field | Input | | ------------ | ----- | | Display Name | Theme | | API ID | Theme | Next, we need to add enumeration values. These are the options we will get when using this later as a dropdown menu. For this example, we'll use two theme options - light and dark. For every enumeration value, we need to enter a `Display name`, an `API ID`, and click `Add`. We'll add the following values: | Display name | API ID | | ------------ | ------ | | Light | light | | Dark | dark | Finally, we'll click `Add enumeration` to save. Now that our theme enumeration has been created, we can finally start building our simple banner component. ### Create the simple banner component [Video](https://www.youtube.com/watch?v=u89p0CMrlXo) To start building our simple banner component, we'll click `+Add` next to **Components** and use the following information to create one: | Field | Input | | ------------- | -------------- | | Display Name | Simple banner | | API ID | Simple banner | | API ID Plural | Simple banners | Click `Add component` to save. We can now start adding instances to this component. Let's start with a `Single line text` field, which will be our banner title. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. We'll use the following information: | Tab | Field | Input | | ----------- | ------------------------------ | ---------------------------- | | Settings | Display Name | Banner title | | Settings | API ID | bannerTitle | | Settings | `Use as title field` checkbox | Leave this checkbox selected | | Validations | `Make field required` checkbox | Select this checkbox | We'll click `Add` to save. Next, we'll add a `Rich text` field, which will our banner description. We'll select the `Rich text` field from the right sidebar and use the following information to create it: | Tab | Field | Input | | -------- | ------------ | ------------------ | | Settings | Display Name | Banner description | | Settings | API ID | bannerDescription | We'll click `Add` to save. Earlier, we created a link component. We will now add it as a `Basic component` field so users will be able to add multiple links to their content entries. We'll find the `Basic component` field on the **Add fields** right sidebar, click on `Add` to add it, and use the following information: | Tab | Field | Input | | -------- | -------------------------------- | ----------------------------------------------- | | Settings | Display Name | Links | | Settings | API ID | links | | Settings | `Allow multiple values` checkbox | Select this checkbox | | Settings | Select allowed components | Use the dropdown to select the "Link" component | We'll click `Add` to save. The final step is to add an enumeration field so the users can select a banner theme. We'll select `Enumeration` on the **Add fields** right sidebar and use the following information: | Tab | Field | Input | | -------- | ------------ | ------------------------------------- | | Settings | Display Name | Banner theme | | Settings | API ID | bannerTheme | | Settings | Enumeration | Select "Theme" from the dropdown menu | We'll click `Add` to save. This is how you build a simple banner component in Hygraph. You can add this component to different models in your schema. ## Useful links - [Components documentation](https://hygraph.com/docs/developer-guides/schema/components) **Would you like to know more?:** We have more resources for you! This is one way of creating a banner using Hygraph. If you want to try out more banner configurations, we have a [banner slider](https://hygraph.com/docs/recipes/banners/banner-slider), a [references banner](https://hygraph.com/docs/recipes/banners/banner-references) and an [image banner](https://hygraph.com/docs/recipes/banners/banner-image) for you to look into! **Do you have suggestions?:** [Join our community](https://hygraph-community.slack.com) to suggest new recipe ideas!