Create a Board Games section in Craft CMS

Alex Aguilar, Partner, Software Engineer Alex Aguilar β€’ β€’ Craft CMS

This article is part of a series on building a favorite board games library in Craft CMS. In this lesson, we’ll create the Board Games section.

πŸ’‘ I’m using Lando for local development. See install Craft CMS using Lando.

Board Game card design #

Eventually, we’ll build a board game card that looks like this:

https://cdn.eaglepeakweb.com/img/projects/blog/boardgame-card-mockup.jpg?mtime=20200909135437&focal=none

There’s a fair amount of data packed on that little card. Let’s break down the fields & data types we’ll need.

Board Game fields #

https://cdn.eaglepeakweb.com/img/projects/blog/boardgame-fields.png?mtime=20200909150431&focal=none

🎲 I have a Notion spreadsheet with sample data β€” My favorite board games.

Create Category #

Let’s start by creating the Category for our board games. The Notion spreadsheet shows that it only has 3 values: Strategy, Family & Abstract.

  1. Go to Settings.
  2. Click on Categories.
  3. Click the New category group button.
  4. Fill out the Name field with “Board Games”.
    Craft CMS automatically fills in the Handle and URI format. The Handle value boardGames is fine but I’m going to change the URI format to category/{slug}.
    If our site also had Video Games it might make sense to make the category URLs more specific. But here I prefer a generic category URL to avoid confusion with board game listing or detail pages.
  5. Click Save.
  6. Click Manage categories.
  7. Click the New category button.
  8. Enter “Strategy”.
    From the drop-down select Save and add another Shift-Command-S.
    Enter “Family”. Shift-Command-S.
    Enter “Abstract”.
  9. Click Save.

We now have the Board Game category with 3 values.

Create Board Game Section #

A Craft CMS Section is similar to a content type in other CMSs. Craft has 3 types of Sections: Singles, Channels and Structures. 1

In our case either a Channel or Structure would work. But I’m going to go with Channel since a Structure is more appropriate for content with hierarchy like Book Chapters.

  1. Go to Settings.
  2. Click on Sections.
  3. Click the New section button.
  4. Fill out the Name field with “Board Games”.
    The default Handle value boardGames is fine. And I’ll leave the Section Type as Channel. The only change I’ll make is to the URI Format where I’ll remove the hyphen boardgames/{slug}.
  5. Click Save.

Create an Asset Volume #

We need a place to store our board game cover image, which means we need to create an asset volume.

  1. Go to Settings.
  2. Click on Assets.
  3. Click New volume button.
  4. Fill out the Name field with “Board Games”.
  5. Enable Assets in this volume have public URLs
  6. In Base URL enter @web/uploads/images/boardgames
  7. Leave Volume Type as Local Folder.
  8. In File System Path enter @webroot/uploads/images/boardgames
  9. Click Save.

To mitigate a security concern, it’s best to explicitly set the @web alias in config/general.php 2

'aliases' => [
'@web' => getenv('DEFAULT_SITE_URL'),
],

To ensure we’ve setup our asset volume correctly, let’s upload a test image.

  1. Go to Assets.
  2. Click on Board Games.
  3. Click Upload files button.
  4. Select a test image from your local files.
☝️ If you encounter an issue uploading a test image, you may need to create the web/uploads/images/boardgames directory.

Create the Board Game Fields #

We can finally start adding fields to our Board Games channel. We start by creating a Field Group.

Create Field Group #

  1. Go to Settings.
  2. Click on Fields.
  3. Click on + New group button.
  4. Enter “Board Games” in the alert dialog.
  5. Click OK.

Add Image field #

  1. Go to Settings> Fields.
  2. Click on Board Games field group.
  3. Click on New field button. Notice how the Board Games group is pre-selected.
  4. Fill out the Name field with “Board Game Image”. The default Handle value boardGameImage is fine.
  5. In Field Type select Assets. Check Restrict uploads to a single folder And leave the default value.
  6. Also check Restrict allowed file types and select Image.
  7. Set Limit to 1.
  8. For View Mode select Large Thumbnails.
  9. In Selection Label enter “Add a board game image”.
  10. Click Save.

Add Category field #

  1. Go to Settings> Fields.
  2. Click on Board Games field group.
  3. Click on New field button.
  4. Fill out the Name field with “Board Game Category”. The default Handle value boardGameCategory is fine.
  5. In Field Type select Categories.
  6. In Source select Board Games
  7. In Branch Limit enter “1” so that only one category be assigned to board games.
  8. Click Save.

Add Number of Players fields - Min, Max & Best #

The next 3 fields are basically the same, a whole number for the minimum, maximum and best number of players.

For the following steps, you should already in the Board Games field group.

  1. Go to Settings> Fields.
  2. Click on Board Games field group.

Minimum

  1. Click on New field button.
  2. Fill out the Name field with “Minimum number of players”. Shorten the Handle value to minNumPlayers.
  3. In Field Type select Number.
  4. Enter the following values in corresponding fields.
    Default: 1
    Min: 1
    Max: 2
  5. Click Save.

Maximum

  1. Click on New field button.
  2. Fill out the Name field with “Maximum number of players”. Shorten the Handle value to maxNumPlayers.
  3. In Field Type select Number.
  4. Enter the following values in corresponding fields.
    Default: 4
    Min: 2 
    Max: 10
  5. Click Save.

Best

  1. Click on New field button.
  2. Fill out the Name field with “Best number of players”. Shorten the Handle value to bestNumPlayers.
  3. In Field Type select Number.
  4. Enter the following values in corresponding fields.
    Default: 2
    Min: 2
    Max: 10
  5. Click Save.

First glance at Board Game entry form #

Let’s take a break from adding fields and check how the admin form to create a board game is coming along.

  1. Click on Entries.
  2. Click on Board Games.
  3. Click New entry button. And you’ll see a screen like this:

https://cdn.eaglepeakweb.com/img/projects/blog/create_a_new_entry_-_only_a_title.jpg?mtime=20200915094334&focal=none

That’s strange… we only see a Title field. πŸ€”

Well there’s an additional step to make fields available on this admin entry form.

Field Layout #

  1. Go to Settings.
  2. Click on Sections.
  3. Click on Edit entry types (1).
  4. Click on Board Games.
    Welcome to Craft’s Field Layout builder, a drag-n-drop interface to build your admin entry forms.

  5. From the right sidebar, drag Category and put it underneath Title.

  6. Put the 3 number of player fields underneath Category. In this order: Min, Max and Best.
  7. Set the width for each player field to 25%.
  8. Click Save.

Refresh the create an entry form and it should now look like this:

https://cdn.eaglepeakweb.com/img/projects/blog/create-an-entry-with-player-fields-but-long-labels.jpg?mtime=20200917102145&focal=none

Pretty good. But I don’t like how number of players is repeated on the 3 player fields. So I’m going to use Field Layout’s UI tools to clean this up a bit.

Field Layout - UI Elements #

  1. Return to the Field Layout for Board Games.
  2. Click on the UI Elements tab.
  3. Drag a Heading element under Category.
  4. Click on the gear icon βš™οΈ and enter “Number of Players” Click Apply.
  5. Click the gear icon βš™οΈ for Minimum number of players. In the Label field enter “Minimum”. Also, make it Required.
  6. Click Apply.
  7. Click Save.

Repeat for Maximum number of players and Best number of players.

Return to the create an entry form and it should now look like this:

https://cdn.eaglepeakweb.com/img/projects/blog/number-of-player-fields-after-UI-elements.jpg?mtime=20200923145659&focal=none

I think that looks a bit cleaner. Let’s add the remaining fields.

Duration fields #

Once again for the following steps, you should already in the Board Games field group.

  1. Go to Settings> Fields.
  2. Click on Board Games field group.

Add Minimum Duration #

  1. Click on New field button.
  2. Fill out the Name field with “Minimum Duration”. Shorten the Handle value to minDuration.
  3. In Default Instructions enter “in minutes”.
  4. In Field Type select Number.

  5. Enter the following values in corresponding fields.
    Default: 30
    Min: 5
    Max: 180

  6. Click Save.

Add Maximum Duration #

  1. Click on New field button.
  2. Fill out the Name field with “Maximum Duration”. Shorten the Handle value to maxDuration.
  3. In Default Instructions enter “in minutes”.
  4. In Field Type select Number.

  5. Enter the following values in corresponding fields.
    Default: 60
    Min: 30
    Max: 600

  6. Click Save.

Duration - Field Layout #

  1. Return to the Field Layout for Board Games.
  2. Add the Duration fields similar as how we added the Number of Player fields.

The entry form should now look like this:

https://cdn.eaglepeakweb.com/img/projects/blog/added-Duration.jpg?mtime=20200917120344&focal=none

Time to add the Difficulty field.

Add Difficulty field #

  1. Go to Settings> Fields.
  2. Click on Board Games field group.
  3. Click on New field button.
  4. Fill out the Name field with “Difficulty”. The default Handle difficulty is fine.
  5. In Field Type select Dropdown.
  6. In Dropdown Options> Option Label column, enter “Easy”, “Medium” and “Hard”. Set Easy as the default.
  7. Click Save.

Difficulty - Field Layout #

  1. Return to the Field Layout for Board Games.
  2. Drag Difficulty below Category.
  3. Set the width for both to 25%.
  4. Click Save.

The entry form should now look like this:

https://cdn.eaglepeakweb.com/img/projects/blog/added-Difficulty.jpg?mtime=20200917123859&focal=none

Now let’s add the Play Online field.

Add Play Online field #

  1. Go to Settings> Fields.
  2. Click on Board Games field group.
  3. Click on New field button
  4. Fill out the Name field with “Play Online”. The default Handle playOnline is fine.
  5. In Default Instructions enter β€œEnter URL where game is available to play online.”.
  6. In Field Type select URL.
  7. Click Save.

Play Online - Field Layout #

  1. Return to the Field Layout for Board Games.
  2. Drag Play Online below Maximum Duration.
  3. Click Save.

The entry form should now look like this:

https://cdn.eaglepeakweb.com/img/projects/blog/added-Play-Online.jpg?mtime=20200917130654&focal=none

1 more field left! We just need to add the board game cover image to the field layout.

Add Image to Field Layout #

  1. Return to the Field Layout for Board Games.
  2. Drag Board Game Image below Title.
  3. Set the width to 25%.
  4. Click Save.

The entry form in its final glory should look like this:

https://cdn.eaglepeakweb.com/img/projects/blog/added-board-game-Image-to-Field-Layout.jpg?mtime=20200917131013&focal=none

Create our first board game entry #

Let’s add our first board game!

We’re going to add the excellent card game β€” Race for the Galaxy.

  1. Click on Entries.
  2. Click on Board Games.
  3. Click the New entry button.
  4. Enter “Race for the Galaxy” for the Title
  5. Download and use this image for the Board Game Image.
  6. Select Strategy for Category.
  7. Select Medium for Difficulty.
  8. For Number of Players enter: 2, 4, 2 (min, max, best).
  9. For Duration, the default values work (min 30, max 60).
  10. In Play Online enter: https://boardgamearena.com/gamepanel?game=raceforthegalaxy
  11. Click Create.

Nice! We have our first board game entry created.

https://cdn.eaglepeakweb.com/img/projects/blog/First-board-game-created.jpg?mtime=20200917134817&focal=none

In the next lesson, we’ll import the rest of our board games using Craft’s first party import plugin β€” Feed Me.

✨ This series is in development. Sign up or follow me @AlexAguilar18 to learn when new lessons are released.

  1. Craft 3 Documentation: Sections. ↩

  2. Github source code: config/general.php. ↩


Alex Aguilar, Partner, Software Engineer

Alex Aguilar

Partner, Software Engineer