Documentation HomeBack to Cnidarity
Documentation HomeBack to Cnidarity

Managing Attributes

Learn how to create, configure, and organize attributes for your research data models.

Introduction

Attributes are the building blocks of your data models in Cnidarity. They define the specific fields that will be available when creating records. Each attribute has a type (e.g., text, number, date) and various settings that control how the data is stored, validated, and displayed.

Well-designed attributes are crucial for effective data management. Take time to plan your model's attributes to ensure they align with your research methodology and data collection needs.

Creating Attributes

You can add attributes to your model during the model creation process or add them later to an existing model.

Adding Attributes to a New Model

  1. During model creation, navigate to the "Attributes" section
  2. Click the "Add Attribute" button
  3. Fill in the attribute details (name, type, settings)
  4. Continue adding attributes as needed
  5. Complete the model creation process by clicking "Create Model"

Adding Attributes to an Existing Model

  1. Navigate to the model in your project
  2. Click on the "Attributes" tab
  3. Click the "Add Attribute" button
  4. Fill in the attribute details and click "Create Attribute"

Required Attribute Information

When creating an attribute, you'll need to provide the following information:

  • Name: A unique identifier for the attribute (e.g., "sample_id")
  • Label: A human-readable label that will be displayed in forms (e.g., "Sample ID")
  • Type: The data type for the attribute (e.g., text, number, date)
  • Description: Optional guidance text that explains the purpose of the attribute
Create attribute form

Understanding Attribute Types

Cnidarity offers various attribute types to accommodate different kinds of research data. Selecting the appropriate type ensures proper validation, storage, and querying capabilities.

Text

For short text values like names, codes, or identifiers.

Text Area

For paragraphs of text like descriptions, notes, or observations.

Number

For integer or decimal values with optional min/max constraints.

Date

For storing calendar dates with optional time components.

Boolean (Yes/No)

For true/false or yes/no values.

Select

For choosing a single option from predefined choices.

Multi-Select

For choosing multiple options from predefined choices.

Email

For email addresses with built-in format validation.

URL

For web addresses with built-in format validation.

For detailed information on each attribute type, including specific settings and use cases, see the Attribute Types Reference.

Attribute Settings

Each attribute has several settings that control its behavior. Common settings include:

Common Attribute Settings

  • Required:

    If enabled, users must provide a value for this attribute when creating a record. Use this for essential data points.

  • Unique:

    If enabled, each record must have a unique value for this attribute. Use for identifiers like sample IDs.

  • Indexed:

    Improves search and filtering performance. Enable for attributes you'll frequently search or filter by.

  • Default Value:

    A value automatically pre-filled when creating new records.

  • Help Text:

    Guidance displayed to users when filling out this field. Use for explanations or instructions.

Type-specific settings provide additional control over attributes. For example:

  • Text attributes: Maximum length, validation pattern
  • Text Area attributes: Number of rows, maximum length
  • Number attributes: Minimum/maximum values, decimal places, step increment
  • Date attributes: Minimum/maximum dates, date format
  • Select/Multi-Select attributes: Available options, display mode
  • Email attributes: Automatic email validation
  • URL attributes: Automatic URL format validation

Conditional Validation Rules

Conditional validation rules allow you to make fields required based on the values of other fields in your model. These rules are evaluated when forms are submitted, ensuring data integrity while providing flexible validation logic.

Conditional validation rules are particularly useful for creating smart forms where certain fields become required only when relevant, reducing validation complexity and improving data quality.

Creating Conditional Validation Rules

When creating an attribute, you can add conditional validation rules in the "Conditional Validation Rules" section. These rules can only be set during attribute creation and cannot be modified afterward.

  1. Navigate to the attribute creation form
  2. Scroll down to the "Conditional Validation Rules" section
  3. Click "Add Conditional Rule" to create your first rule
  4. Select a Rule Type from the dropdown (e.g., "Required If", "Required With")
  5. Choose the Reference Field(s) - the field(s) whose values will trigger the validation
  6. Enter a Value if required by the rule type (for "Required If" and "Required Unless" rules)
  7. Save the attribute to apply the conditional validation rules

Example: Simple Conditional Validation Rule

For a "Lab Equipment" field that should be required only for laboratory studies:

  • Rule Type: "Required If"
  • Reference Field: "Study Type"
  • Value: "Laboratory Study"

The "Lab Equipment" field will be required when users select "Laboratory Study" from the Study Type dropdown.

Types of Conditional Validation Rules

Cnidarity offers several types of conditional validation rules that can make fields required based on other field values:

Required When Field Equals Value

Makes the field required when another field equals a specific value.

Example:

"Lab Equipment" field is required if "Study Type" equals "Laboratory Study"

Required Unless Field Equals Value

Makes the field required unless another field equals a specific value.

Example:

"Field Notes" field is required unless "Study Type" equals "Data Analysis Only"

Required When These Fields Have Values

Makes the field required when any of the specified fields have a value.

Example:

"Measurement Method" field is required if either "Temperature" or "Humidity" fields have values

Required When These Fields Are Empty

Makes the field required when all of the specified fields are empty.

Example:

"Alternative Identifier" field is required if both "Sample ID" and "Barcode" fields are empty

Numeric Comparisons

For number fields, you can create validation rules based on numeric comparisons with other number fields.

  • Must be greater than: Field must be greater than another field's value
  • Must be greater than or equal to: Field must be greater than or equal to another field's value
  • Must be less than: Field must be less than another field's value
  • Must be less than or equal to: Field must be less than or equal to another field's value

Example:

"Maximum Temperature" field must be greater than "Minimum Temperature" field

Date Comparisons

For date fields, you can create validation rules that compare dates with other date fields.

  • Must be a date before: Date must be before another date field
  • Must be a date after: Date must be after another date field
  • Must be the same as: Date must be the same as another date field
  • Must be different from: Date must be different from another date field

Example:

"Completion Date" field must be after "Start Date" field

Mutual Exclusion with Regular Required

When setting up conditional validation rules, it's important to understand that conditional required rules are mutually exclusive with the regular "Required" setting:

How Mutual Exclusion Works

  • When "Required" is checked: Conditional required rule types (Required When Field Equals Value, Required Unless Field Equals Value, Required When These Fields Have Values, Required When These Fields Are Empty) are unavailable in the dropdown
  • When a conditional required rule is selected: The "Required" checkbox becomes disabled and shows "Unavailable - conditional requirements are active"
  • Smart conflict prevention: The system automatically prevents conflicting validation rules to maintain data integrity

This mutual exclusion prevents logical conflicts and ensures your validation rules work predictably. You can use either a field is always required OR conditionally required, but not both.

How Conditional Validation Works in Record Forms

When users fill out record forms, conditional validation rules are evaluated when the form is submitted. If conditional validation rules are not met, the form submission will be blocked with clear error messages.

Conditional validation in record form

Dynamic Required Indicators

  • Real-time Updates: Required asterisks appear and disappear instantly as form values change
  • Validation on Submit: Form submission is blocked if any conditionally required fields are empty
  • Clear Error Messages: Users receive specific validation messages explaining which rules make a field required
  • Visual Consistency: Conditionally required fields use the same styling as regularly required fields

Example: Dynamic Required Behavior

For a "Lab Equipment" field with a "Required If" rule where "Study Type" equals "Laboratory Study":

  1. Initially, "Lab Equipment" shows no required asterisk
  2. User selects "Laboratory Study" from "Study Type" dropdown
  3. Immediately, "Lab Equipment" label shows a red asterisk (*)
  4. If user tries to submit without filling "Lab Equipment", validation prevents submission
  5. If user changes "Study Type" to something else, the asterisk disappears

Limits and Performance

To maintain form performance and usability, conditional validation rules have some practical limits:

System Limits

  • Maximum Rules per Attribute: 10 conditional validation rules per attribute
  • Creation Only: Conditional validation rules can only be set during attribute creation
  • Server-Side Validation: All conditional rules are validated on form submission for security and reliability
  • Performance Optimized: The system uses efficient validation processing to handle complex rule combinations

Best Practices for Conditional Validation Rules

  • Plan Ahead: Since validation rules cannot be changed after creation, carefully plan your conditional logic before creating attributes
  • Start Simple: Begin with basic conditional rules and avoid overly complex dependencies
  • Test Thoroughly: Verify all rule combinations work as expected during testing
  • Consider User Experience: Avoid creating confusing validation scenarios that might frustrate users
  • Use Descriptive Field Names: Clear field labels make it easier to understand which fields trigger validation
  • Document Complex Rules: Use the attribute description field to explain complex conditional logic

Important: Conditional validation rules cannot be modified after attribute creation. If you need to change validation logic, you'll need to create a new attribute with the desired rules.

Display Rules

Display rules allow you to show or hide attributes based on the values of other attributes in your model. This creates dynamic forms that adapt to user input, making data collection more efficient and user-friendly.

Display rules are particularly useful for creating branching forms where certain fields only appear when relevant, reducing form complexity and improving data quality.

Creating Simple Display Rules

When creating or editing an attribute, you can add display rules that control when the attribute should be visible.

  1. Navigate to the attribute creation or edit form
  2. Scroll down to the "Display Rules" section
  3. Click "Add Display Condition" to create your first rule
  4. Select the Control Attribute (the field whose value will determine visibility)
  5. Choose a Condition (e.g., "equals", "contains", "is not empty")
  6. Enter a Value to compare against (if required by the condition)
  7. Save the attribute to apply the display rule

Example: Simple Display Rule

Imagine you have a "Study Type" field with options like "Field Study" and "Lab Study", and you want to show a "Lab Equipment" field only for lab studies:

  • Control Attribute: Study Type
  • Condition: Equals
  • Value: "Lab Study"

The "Lab Equipment" field will only appear when a user selects "Lab Study" from the Study Type dropdown.

Available Condition Types

Different attribute types support different condition types. Here's a comprehensive list:

Universal Conditions

  • • Is Empty
  • • Is Not Empty

Text & Select Conditions

  • • Equals
  • • Doesn't Equal
  • • Starts With
  • • Ends With
  • • Contains
  • • Doesn't Contain

Number Conditions

  • • Less Than
  • • Less Than or Equal To
  • • Greater Than
  • • Greater Than or Equal To

Multi-Select Conditions

  • • Selected Options Include
  • • Selected Options Don't Include
  • • Any Selection Contains
  • • Number of Selections >
  • • Number of Selections =

Creating Complex Display Rules

For more sophisticated scenarios, you can create complex rules using multiple conditions with AND/OR logic.

Adding Multiple Conditions

  1. Start with a simple condition as described above
  2. Click "Group with New Condition" to create a grouped rule
  3. Select the operator (AND or OR) for how conditions should be combined
  4. Add additional conditions using the "Add Condition" button
  5. For even more complexity, use "Group with New Condition" on individual conditions to create nested groups

Example: Complex Display Rule

Show a "Specialized Equipment" field when:

  • Study Type equals "Lab Study" AND
  • (Sample Size is greater than 100 OR Funding Source contains "NSF")

This creates a nested rule structure: Study Type = "Lab Study" AND (Sample Size > 100 OR Funding Source contains "NSF")

The system supports up to 3 levels of nesting for display rules. For most use cases, 1-2 levels provide sufficient flexibility while maintaining clarity.

How Display Rules Appear in Record Forms

When users fill out record forms, conditional attributes provide visual feedback about why they're being displayed.

Conditional attribute in record form

Visual Indicators

  • Toggle Icon: Conditional attributes display a small toggle icon next to their label
  • Conditions Drawer: Clicking the toggle reveals a drawer showing which conditions are currently satisfied
  • Green Checkmarks: Each satisfied condition is marked with a green checkmark
  • Condition Description: Human-readable descriptions explain exactly why the field is visible

Example: Conditions Drawer

When a conditional field appears, users can click the toggle icon to see:

This attribute is visible because:
Study Type equals "Lab Study"

This transparency helps users understand the form's behavior and ensures they provide the correct information.

When conditional fields become hidden due to changed values, any data they contained is automatically cleared to maintain data integrity.

Best Practices for Display Rules

  • Start Simple: Begin with single conditions and add complexity only when needed
  • Test Thoroughly: Verify all condition combinations work as expected before deploying
  • Consider User Experience: Avoid overly complex rules that might confuse users
  • Use Descriptive Attribute Names: Clear attribute labels make condition descriptions more readable
  • Document Complex Rules: Use the attribute description field to explain complex conditional logic

Be cautious when modifying display rules for attributes with existing data. Changes to rules might affect the visibility of fields that users have already filled out.

Ordering Attributes

The order of attributes affects how they appear in record creation forms and record listings. You can arrange attributes in a logical order that makes sense for your data collection workflow.

Changing Attribute Order

  1. Navigate to the "Attributes" tab of your model
  2. Drag and drop attributes in the list to rearrange their order
  3. The new order is automatically saved as you make changes
Attribute ordering interface

Changes to attribute order take effect immediately without requiring a separate save action. You'll see an indicator while the changes are being processed.

The attribute order applies to both the record creation form and the default view in record listings. Consider which attributes are most important for both creating and viewing records.

Managing Existing Attributes

After creating attributes, you can edit, hide, or delete them as your research needs evolve.

Editing Attributes

You can modify most attribute settings after creation, although some changes may have implications for existing data.

  1. Navigate to the "Attributes" tab of your model
  2. Find the attribute you want to edit
  3. Click the "Edit" button (pencil icon)
  4. Modify the attribute settings as needed
  5. Click "Update Attribute" to save your changes

Changing an attribute's type may result in data loss if the existing values cannot be converted to the new type. Always back up your data before making significant attribute changes.

Hiding Attributes

Instead of deleting an attribute, you can hide it from forms and listings while preserving the existing data.

  1. Edit the attribute
  2. Toggle the "Hidden" setting to "Yes"
  3. Update the attribute

Hidden attributes still exist in the database but won't appear in forms or default record views. You can unhide them at any time.

Previous Creating Models Next Attribute Types