IO Base Component

📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.

⚠️

*Condition Layout app v1 has been deprecated in favor of Condition Layout app v2. Although support for the former version is still granted, we strongly recommend you to access the Migration Guide and update your store theme with the app's newest version in order to keep up with the components' evolution. If you’re still using the former version, you can find its documentation here.

Condition Layout

The Condition Layout app allows a component to be rendered in your store if predefined conditions are met.

Screen-Recording-certo

Configuration

Step 1 - Adding the Condition Layout app to your theme's dependencies

In your theme's manifest.json, add the Condition Layout app as a dependency:

  "dependencies": {
+   "vtex.condition-layout": "2.x"
  }

You are now able to use all blocks that are exported by the condition-layout app. Check out the full list below:

Block name	Description
condition-layout.product	Defines the condition logic on the product context and the children blocks that are going to be rendered in case the predefined conditions are met.
condition-layout.binding	Defines the condition logic on the current binding and the children blocks that are going to be rendered in case the predefined conditions are met.
condition-layout.category	Defines the condition logic on the current category page or department page and the children blocks that are going to be rendered in case the predefined conditions are met.
condition-layout.user	Define condition logic on current user and the children blocks that are going to be rendered in case the predefined conditions are met.
condition-layout.urlParam	Define condition logic on current page based in url parameters and the children blocks that are going to be rendered in case the predefined conditions are met.

Step 2 - Adding the condition-layout.product block to your theme's templates

In the product theme template, add the condition-layout.product block as a children. For example:

{
  "store.product": {
    "children": ["condition-layout.product"]
  },
}

Or the condition-layout.binding block, for example:

{
  "store.product": {
    "children": ["condition-layout.binding"]
  }
}

Or the condition-layout.category block, for example:

{
  "store.search#my-category-page": {
    "children": ["condition-layout.category"]
  }
}

⚠️ Never use condition-layout directly. Make sure to always use it with the context variant, such as condition-layout.product.

Step 3 - Defining the desired conditions

Now it is time to configure the condition-layout.product block!

Use the block's props to define your layout condition. You can also declare as the children the condition-layout.product's children some blocks of your choosing to be rendered if the condition is met.

For example:

{
  "store.product": {
    "children": ["condition-layout.product#cond1"]
  },
  "condition-layout.product#cond1": {
+   "props": {
+     "conditions": [
+       {
+         "subject": "productId",
+         "arguments": {
+           "id": "12"
+         }
+       }
+     ]
+     "Then": "flex-layout.row#custom-pdp-layout-12",
+     "Else": "flex-layout.row#default"
+   }
+ }
}

Or for condition-layout.binding:

{
  "store.product": {
    "children": ["condition-layout.binding#cond42"]
  },
  "condition-layout.binding#cond42": {
+   "props": {
+     "conditions": [
+       {
+         "subject": "bindingId",
+         "arguments": {
+           "id": "13fb71d0-binding-code-here-87h9c28h9013"
+         }
+       }
+     ]
+     "Then": "flex-layout.row#just-for-this-binding",
+     "Else": "flex-layout.row#for-other-bindings"
+   }
+ }
}

Or for condition-layout.category:

{
  "store.product": {
    "children": ["condition-layout.category#cond42"]
  },
  "condition-layout.category#cond42": {
+   "props": {
+     "conditions": [
+       {
+         "subject": "department",
+         "arguments": {
+           "ids": ["1", "42"]
+         }
+       }
+       {
+         "subject": "category",
+         "arguments": {
+           "ids": ["301", "304"]
+         }
+       }
+     ]
+     "matchType": "any",
+     "Then": "flex-layout.row#just-for-this-category-or-department",
+     "Else": "flex-layout.row#for-other-category-or-department"
+   }
+ }
}

ℹ️ According to the example above, whenever users interact with a product whose ID is equal to 12, the block flex-layout.row#custom-pdp-layout-12 is rendered. If users interact with a product whose ID is not equal to 12, the rendered block is the flex-layout.row#default.

Prop name	Type	Description	Default value
conditions	object	List of desired conditions.	undefined
matchType	enum	Layout rendering criteria. Possible values are: all (all conditions must be matched in order to render the layout), any (at least one of the conditions must be matched in order to render the layout) or none (no conditions must be matched in order to render the layout).	all
Then	block	Name of the block to be rendered if the conditions are met. If no value is defined, the blocks declared as children of condition-layout.product will be rendered instead.	undefined
Else	block	Name of the block to be rendered if the conditions are not met.	undefined

• conditions object:

Prop name	Type	Description	Default value
subject	string	Defines, according to the product context where the block in declared in, which data is needed from the UI to validate the value chosen in the object prop. Check below the possible values for this prop.	undefined
arguments	object	Defines the condition parameters. Notice: this prop value varies according to the value set to the subject prop. Check below the table for the subject's possible values and their expected arguments.	undefined
toBe	boolean	Whether the data fetched in the subject prop must met the predefined conditions to render the new layout (true) or not (false).	true

Possible values for the condition-layout.product's subject prop:

Subject	Description	Arguments
productId	Product's IDs currently displayed on the UI.	{ id: string }
categoryId	Category's IDs currently displayed on the UI.	{ id: string }
brandId	Brand's IDs currently displayed on the UI.	{ id: string }
selectedItemId	ID of the item currently selected by the user.	{ id: string }
productClusters	List of product clusters currently displayed on the UI.	{ id: string }
categoryTree	List of categories currently displayed on the UI. Note: only available in the Product Detail Page.	{ id: string }
specificationProperties	List of product specifications currently displayed on the UI.	{ name: string, value: string }. Notice: value is an optional prop. If omitted, only the specification name (name) will be checked.
areAllVariationsSelected	Whether all product variations currently available on the UI were selected by the user (true) or not (false).	No arguments are expected.
isProductAvailable	Whether the product is available (true) or not (false).	No arguments are expected.
isBestPrice	Whether the current product has the best price	No arguments are expected.
hasMoreSellersThan	Whether the quantity of sellers for the product is more than argument passed.	{ quantity: number }
isUniqueSku	If the product has no variations	No arguments are expected
hasVideo	If the product has video	No arguments are expected
hasListPrice	If the product has list price	No arguments are expected
description	If the product has description	No arguments are expected
specificationGroups	If the product has specification groups	{ name: string}

Possible values for the condition-layout.binding's subject prop:

Subject	Description	Arguments
bindingId	ID of the desired store binding.	{ id: string }

Possible values for the condition-layout.category's subject prop:

Subject	Description	Arguments
category	Category's IDs currently displayed on the UI.	{ ids: string[] }
department	Department's IDs currently displayed on the UI.	{ ids: string[] }
categoryTree	Department's or Category's IDs that are parent of the currently displayed on the UI.	{ ids: string[] }

Possible values for the condition-layout.user's subject prop:

Subject	Description	Arguments
isAuthenticated	Check if user is authenticated	no argument are expected
priceTables	Check if user has a specific price table (on Client Entity)	{ value: string }

Modus Operandi

The condition-layout.product mainly uses the matchType and conditions props to set, respectively, the criteria and the conditions that blocks must meet to be rendered or not.

The conditions prop, in turn, does not rely on any automatic grammar to define the desired conditions. Instead, it relies on its two props, namely subject and arguments, that together define which condition must be met by using an underlying data validation method (with specific arguments) according to the UI behavior.

Lastly, the matchType prop has the responsibility for deciding the necessary number of valid conditions for the layout rendering to actually occur.

Customization

The Condition Layout merely establishes a logic to render other blocks. Therefore, the app doesn't have CSS Handles for its specific customization.

Instead, you should use its child block's Handles.

Contributors ✨

Thanks goes out to these wonderful people:

LucasCastroAcctGlobal 💻

vini-lima-acct 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!