Categories
This article explains how to configure, add content to, and publish categories in Hygraph.
Creation
Categories must first be created in commercetools. See Create a Category. They cannot be manually created in Hygraph.
Only after the category has been created in commercetools does it become visible in Hygraph, where content can be added, localized, and where it must then be published from.
How to configure
To navigate to the Category section, via the left menu pane select Content, and in the secondary left menu pane under the DEFAULT VIEWS section, select Category.
A list of all existing categories, from all tenants, in the selected Environment, will be displayed. Click on category row to edit/remove it.
It is prudent to first filter categories for the relevant tenant, so you don't mistakenly select an equally named Category from another tenant.
Components
Like most objects in Hygraph, a Category is made up of multiple components. The nature of the components vary between objects, and is determined by the configurations in the Schema sections. You cannot simply add components; this must be done in consultation with the development teams and may even require a feature request to be submitted.
The available components for a Category are displayed on the left pane (next to the main navigation pane), and by clicking them they can be navigated to.
Tenant
As Hygraph is multi-tenant, the first and most important selection is the tenant. Selecting a different tenant than the one that category was created in is not recommended. Only make changes in this field if you are instructed to, and otherwise leave it as is.
URL Path
Autogenerated field based on the URL identifier in the SEO component and, if applicable, the relation with parent or child entities. However, when the category is first created and synced from commercetools there will be a system generated URL automatically populated in this field.
Here is an example of how the VEX category “Superfoods” looks on the shop: https://www.vitaminexpress.org/en/superfoods-supplements The URL path is determined by what is entered in the URL identifier field in the SEO section.
SEO
The Search Engine Optimization (SEO) component is made up of multiple sub-components. The same fields are documented in more detail in SEO.
URL Identifier
This is a required field. The part of the URL placed after the domain name and locale (i.e. the slug). For example: hilife-kids-multivitamin. It has to be unique, meaning that it cannot be the same as the urlIdentifier of another blog, brand, category, product etc. This is what will be displayed to the customer in the website, and how the URL link will look that can be provided to customers.
It is important that the default locale field has a value, it serves as a fallback in certain scenarios.
URL Path
The URL path is autogenerated based on the URL identifier and relation with parent or child entities.
SEO Title
Meta title for this page in search engines. Google typically displays the first 50-60 characters of a title tag.
SEO Description
Meta description for this page in search engines. Google generally truncates snippets to ~155-160 characters.
No Index
Use this field to determine whether to show this category page in search results. By default, this should be on False. Only when you are creating a temporary page, for instance for a campaign, should this be set to true.
No follow
Use this field to allow search engines to index this category page, but ask crawlers not to follow links on the current page. By default, this should be on False. Only when you are creating a temporary page, for instance for a campaign, should this be set to true.
Canonical URL
Optional. Only use in case of duplicate page content. A canonical URL is the URL of the page that Google thinks is most representative from a set of duplicate pages on your site.
Keywords
Use this field for keywords that are not allowed to be displayed on the page, but a user might use in the search bar to find this category on the website. Add keywords by clicking + Add to list and remove them by clicking the three dots on an existing one and then clicking remove.
Exclude from search
This field is required. Exclude this page from Algolia search results and recommendations. This is useful for pages that are not meant to be indexed, such as a certain tryout product. By default this should be on False. Only when you are creating a temporary page, for instance for a campaign, should this be set to true. This flag is also honoured for Pages, Content pages, and Authors.
Open Graph Image
Please provide an image with the size 1200 x 630px. Fallback to main image of the page if existing.
Title
This field is required. The title of the category is managed in commercetools and is displayed at the top of the page. This Hygraph title field is for search-purposes only and always reflects the category name in commercetools.
Top Content
Shows right under the title of the category page, typically used for a short description or a banner. Putting content here will push the products down so avoid using big banner or a large amount of text.
The Category Multicomplexes utilizes the Top content section where only Text is displayed: https://www.vitaminexpress.org/en/multi-complexes-buying For Desktop a little bit of text displays with no issues. Take note that on mobile devices, even a little bit of text will push the product displays down considerably.
Make sure that you test the page in mobile as well as Desktop view.
Hero
Hero (hero) and Hero for mobile (heroForMobile) sit on the listing.
Main Content Section
Below the product section on a category page is where the Headline, Image, Introduction, Description and bottom content is located.
Headline
The Title of the content displayed directly under the products of the category. This is the headline field. In Hygraph no formatting option can be applied to this field.
Image
Directly under the Headline and part of the main body of the content underneath the product, an image may be uploaded. This is the Image component in Hygraph.
Caption
The text directly underneath the image displayed on the website. Is determined by the Caption field in Hygraph.
Introduction
A section of text before the main body of content, written in larger text, and intended as a summary of the category. Comes from the Introduction plain text field.
Description
There under the main body of content from the category page is displayed. This is the Description field in Hygraph, which supports rich text and has a built in text editor. There are also a number of placeholders that can be entered here, as well table functionality that can be used.
Bottom content
Displayed underneath the main content section of the category page. Typically used to note references from the description.
It appears much the same as the description on the website, here is an example from Baerbel Drexel: https://www.baerbel-drexel.de/nahrungsergaenzungsmittel/algenprodukte
Use Bottom content components (bottomContentComponents) to stack blocks. Typical use is still references.
Related Categories
Link existing categories to this one, which will be displayed in a carousel on the bottom section of the category page. An example of a category that makes use of the Related Categories section is Beauty: https://www.vitaminexpress.org/en/beauty-supplements Any number of pre-existing categories can be connected and in turn displayed in dedicated section.
Even though the button exists, it is still best practice to create categories in commercetools, as opposed to using the button + Create new Category.
Related Blog Pages
Link existing Blog pages to the category page, which will be displayed in a carousel on the bottom section of the category page.
Here is a Baerbel Drexel page that displays Related Blog Pages on Algenprodukte: https://www.baerbel-drexel.de/nahrungsergaenzungsmittel/algenprodukte Similar to related categories, Related blog posts allows the user to specify existing blog posts to be displayed on the category page.
Clicking the Add existing Blog button opens a searchable pop-up screen where the selection can be made.
Short Description
The text that is shown on other pages where the category tile of this category is displayed. This is typically only used for Articles/Blog posts. But should you want a category tile to display text, you would fill this field in. Leaving it empty, like above, displays only the image of the category, like below.
Show in Slider
If true, then this category shows in category sliders on other pages (like on the homepage). By default, this should be on True. Only when you are creating a temporary category, for instance for a campaign, should this be set to False.
CTA Image
Insert a Call to action image, which can be used to bring attention to specific products or discounts relevant to the category.
Icon
Icon (icon) is optional.
Filtersets
Add existing filtersets or Create new filtersets using the buttons in this component. These filtersets are shown on the corresponding category page. If no filtersets are selected, then the default filtersets from the Settings model are shown. See Filtersets.
Category Key
Generated from the Category’s creation in commercetools. The Category Key is the unique identifier shared between commercetools and Hygraph categories. Upon category creation in commercetools, categories are automatically synced to Hygraph with a Category Key.
Recommended Products
Allows specific products to be marked with a Recommended tag only on this category’s page.
Bestseller Products
Allows specific products to be highlighted with a Bestseller tag only on this category’s page.
Category for interest Survey
If linked to the website's Setting, then the user can choose this category as their interest in the Category Interest survey on the confirmation page after checkout. That Settings field is Interest Categories (interestCategories).
Category labels
Category labels (categoryLabels) — tags used as labels for products in this category. See Tags, Product Badges and Labels.
Listing behaviour
- Hide default listing content (
hideDefaultListingContent) - Disable personalization (
disablePersonalization) - Disable reranking (
disableReranking) - Hide side menu subcategories (
hideSideMenuSubcategories) / Hide side menu sibling categories (hideSideMenuSiblingCategories)
Save & Publish
When a Category is created in commercetools, it will not be visible on the website until it has been manually published. Furthermore, after publishing a Category in Hygraph for the first time, a build must run before it will be visible on the live website for customers.
Whereas updating a Category after it has already been published previously does not require a build, any changes that are made will become visible after the category is published. You may save, and publish later, or concurrently save and publish using the buttons on the top right section of the screen. A pop-up will appear where specific stages or localizations can be selected and toggled.
Builds will run automatically at night, and if needed it can be requested via the Slack channel: #help-commercetools-hygraph You need to specify specifically if it’s for staging, otherwise the dev team will assume the build request is for production. You may also configure a schedule event to publish the category by clicking the drop-down arrow on the right of the Save & publish button.
A pop-up will appear where you can toggle to either only schedule the category or add it to an existing release. A secondary pop-up will be displayed where you must configure the schedule entry. Once configured it will be visible in the info panel on the right-hand side of the screen. See also Save, Publish & Schedule and Page revalidation.