Skip to content

Add conditionals to your field layouts

License

Notifications You must be signed in to change notification settings

JshGrn/Reasons-Craft3

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

42 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Reasons plugin for Craft CMS 3.x

Scrutinizer Code Quality

Supercharge your field layouts with conditionals.

What is Reasons?

Reasons adds simple conditionals to field layouts in Craft CMS – making it possible to hide or show fields on the fly, as content is being edited.

Using a Lightswitch to toggle between two different fields

Changes from the Craft 2 version:

  • Supports Project Config
  • Works with the new Drafts and Live Preview systems, and the new Asset edit pages in Craft 3.4
  • Support for plugins (including third party fieldtypes, Craft Commerce and Solspace Calendar) has been removed

Reasons for Craft 3?! But they said it'd never happen!

Yeah, I wasn't gonna do this.

Field layout conditionals were originally planned for core in a 3.x release. Currently, the feature is on the roadmap for Craft 4.0 - which may or may not release sometime in 2021. I figured, 3 years is a long enough wait (almost 5 years, if you count the original feature request!).

This plugin is not in active development; the primary purpose of this port is to make upgrading legacy Craft 2 projects using Reasons easier. I'm going to make sure the plugin continues to work on upcoming Craft releases until conditionals are in core, but I won't be adding any new features (read: no Matrix or Neo support incoming).

In short, consider Reasons on life support and as a stop-gap solution until Craft has conditionals in core.

Requirements

This plugin requires Craft CMS 3.5.0-RC1 or later.

Looking for the Craft 2 version?

Installation

To install the plugin, follow these instructions.

  1. Open your terminal and go to your Craft project:

     cd /path/to/project
    
  2. Then tell Composer to load the plugin:

     composer require mmikkel/reasons
    
  3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Reasons.

Updating from Craft 2

Existing conditionals in the database from the Craft 2 version should be migrated over automatically and continue to work as-is. Note that all third-party fieldtype and plugin support (including Solspace Calendar and Craft Commerce) has been removed, though.

Using Reasons

To create or edit conditionals for a particular field, edit the field layout for the appropriate element source (i.e. the Entry Type, Category Group, Global Set or Asset volume). Click the little cogwheel next to the field in the field layout designer and choose Edit conditionals.

Note that for element sources that support tabbed field layouts, Reasons is designed to work on a "per-tab" basis.

Setting up conditionals using the built-in field layout designer

What's a "toggle field"?

A toggle field in Reasons is a field that can be used to "toggle" other fields (in the same field layout tab) on or off (show or hide them, as it were).

These field types can be used as toggle fields:

  • Lightswitch
  • Dropdown
  • Checkboxes
  • Multi-select
  • Radio Buttons
  • Number
  • Plain Text
  • Entries
  • Categories
  • Tags
  • Assets
  • Users

Where does it work?

Reasons works for Entries, Global Sets, Categories, Assets, Users and Tags. It also works inside Live Preview, in element editor modals and for entry drafts and revisions.

A note on required fields

Be careful not to add conditionals to a required field. Even if the required field is hidden, it'll still be required by Craft, potentially making your content impossible to save.

What Reasons doesn't do - or a disclaimer of sorts

It's important to realize that Reasons is strictly about increasing authoring experience, by hiding the UI for fields that might be irrelevant based on other fields' current values.

Reasons works as a thin layer on top of Craft's Control Panel UI, using JavaScript to show and hide fields as content is being edited. Since the plugin is dependant on undocumented features, markup, CSS and JavaScript in the Control Panel, it's basically a big hack and may stop working at any time if certain aspects of the Control Panel is ever changed or redesigned.

The good news is that Reasons does absolutely nothing to your content, nor does it affect your fields or field layouts in any way. It also does absolutely nothing on the front end of your site. And if you ever uninstall it, your field layouts will simply render natively, i.e. with all fields visible regardless of their values.

My advice is to be smart about how you design your field layouts; always keep in mind that the layouts may render without conditionals one day. Use Reasons sparingly and with caution – if you find yourself creating a lot of complex conditionals, consider alternative approaches (e.g. Entry Types or Matrix fields).

About

Add conditionals to your field layouts

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%