@SquizyField

The @SquizyField annotation customizes the behavior and appearance of individual fields within a Squizy entity. It controls how a field is displayed in forms and tables, whether it can be sorted, filtered, or edited, and more.

Basic Usage

@Entity
@SquizyEntity
public class Product {

    @Id
    private String reference;

    @SquizyField(placeholder = "Enter product name", helpText = "The public display name")
    @NotNull
    private String name;

    @SquizyField(scale = 4)
    private BigDecimal price;

    // ...
}

Attributes

placeholder

Text shown as placeholder in form inputs:

@SquizyField(placeholder = "Enter product reference")
private String reference;

helpText

Displays a tooltip with help text for the field in forms. Supports both plain text and i18n bundle references using {key} syntax:

@SquizyField(helpText = "Unique identifier for the product")
private String reference;

// Or with i18n
@SquizyField(helpText = "{product.reference.help}")
private String reference;

section

Groups fields into form sections. Fields with the same section value are grouped together:

@SquizyField(section = "Basic Info")
private String name;

@SquizyField(section = "Basic Info")
private String description;

@SquizyField(section = "Pricing")
private BigDecimal price;

Use SquizyField.NO_SECTION to explicitly place a field outside any section.

displayFormat

Overrides how a related entity field is displayed. Only applies to entity-type fields. This is equivalent to placing the @DisplayFormat annotation on the field:

@SquizyField(displayFormat = "${id} - ${name}")
@ManyToOne
private City city;

This overrides the displayFormat defined on the City entity only when displayed as a field of the parent entity. See @SquizyEntity(displayFormat) for entity-level configuration.

sortingExpression

Custom sorting expression for this field. If not set, the display format is used for sorting. This is equivalent to placing the @SortingExpression annotation on the field:

@SquizyField(sortingExpression = "${name}")
@ManyToOne
private City city;

customComponent

Overrides the default UI component used to render the field:

@SquizyField(customComponent = ComponentType.SWITCH)
private boolean active;

@SquizyField(customComponent = ComponentType.TEXT_AREA)
private String description;

Available component types:

ComponentType	Compatible With	Description
DEFAULT	All types	Framework decides the best component
TEXT_INPUT	String	Standard text input
TEXT_AREA	String	Multi-line text area
CHECKBOX	Boolean	Checkbox (default for booleans)
SWITCH	Boolean	Toggle switch

Automatic textarea

When customComponent is set to DEFAULT (or not specified), String fields with a maximum length of 500 characters or more (e.g., @Size(max = 500)) are automatically rendered as a TEXT_AREA instead of a standard text input. You can always override this behavior by setting customComponent explicitly.

sortable

Controls whether the field appears in sort options:

// Explicitly sortable (even if framework would exclude it)
@SquizyField(sortable = SortableMode.SORTABLE)
@SensitiveField
private String secret;

// Explicitly not sortable
@SquizyField(sortable = SortableMode.NOT_SORTABLE)
@OneToMany
private List<Account> accounts;

Values: DEFAULT (framework decides), SORTABLE, NOT_SORTABLE.

filterable

Controls whether the field appears in filter options:

@SquizyField(filterable = FilterableMode.NOT_FILTERABLE)
@OneToMany
private List<Account> ignoredAccounts;

Values: DEFAULT (framework decides), FILTERABLE, NOT_FILTERABLE.

ignored

Controls field visibility. By default, the framework hides auto-generated IDs and optimistic lock fields (@Version):

// Force show a generated ID
@SquizyField(ignored = IgnoredMode.NOT_IGNORED)
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// Force hide a regular field
@SquizyField(ignored = IgnoredMode.IGNORED)
private String internalCode;

Values: DEFAULT (framework decides), IGNORED, NOT_IGNORED.

frozen

Freezes a table column to the left or right side:

@SquizyField(frozen = FrozenMode.LEFT)
private String reference;

Values: NONE, LEFT, RIGHT.

wrappedMode

Controls text wrapping in table cells:

@SquizyField(wrappedMode = WrappedMode.Mode.WRAPPED)
private String description;

updatable

Controls whether the field can be edited after creation. Setting to false makes the field read-only on updates:

@SquizyField(updatable = false)
private String reference;

WARNING

This only opts out of updatability. Setting it to true does not guarantee the field will be updatable — other factors (like @SensitiveField) may still prevent updates.

bulkUpdatable

Controls whether the field can be edited in bulk update operations. Requires updatable to also be true:

@SquizyField(bulkUpdatable = false)
private String name;

scale

Defines the number of decimal places for decimal fields. Only applies to BigDecimal and similar types. Defaults to 2:

@SquizyField(scale = 4)
private BigDecimal exchangeRate;

// Default scale (2 decimal places)
private BigDecimal price;

Scale via @Column

The scale attribute on @SquizyField controls the UI display of decimal places. For database-level precision, use the standard JPA @Column annotation:

@Column(precision = 10, scale = 4)
@SquizyField(scale = 4)
private BigDecimal exchangeRate;

It's good practice to keep both values aligned.