Display Format

Squizy uses display formats to control how entities are represented as text throughout the application. Instead of showing raw IDs or object references, you can define a human-readable expression that combines entity fields into a meaningful label.

Why It Matters

When an entity appears in a dropdown, relationship column, search result, or anywhere outside its own detail view, Squizy needs a text representation. Without a display format, you'd see raw identifiers like 42 or a3f8-.... With a display format, you see something like "John Doe" or "ORD-2024-001 - Pending".

How It Works

Display formats use a simple placeholder syntax — ${fieldName} — to reference entity fields. The expression is evaluated at query time by concatenating the referenced fields into a single string.

@SquizyEntity(displayFormat = "${firstName} ${lastName}")
@Entity
public class Employee {
    private String firstName;
    private String lastName;
    // ...
}

This produces labels like "John Doe" wherever an Employee reference is displayed.

You can also reference nested fields to traverse relationships:

@SquizyEntity(displayFormat = "${address}, ${city.name}")
@Entity
public class Location {
    private String address;
    @ManyToOne
    private City city;
    // ...
}

Entity-Level vs Field-Level

The display format can be configured at two levels:

• Entity-level: Defines the default representation for the entity everywhere. Set via @SquizyEntity(displayFormat = ...) or the standalone @DisplayFormat annotation.
• Field-level: Overrides how a related entity is displayed for a specific relationship. Set via @SquizyField(displayFormat = ...) or @DisplayFormat on the field. This only affects the display within the parent entity — it does not change the related entity's own display format.

@Entity
@SquizyEntity
public class Order {

    // Show customer as "ID - Name" only in Order context
    @SquizyField(displayFormat = "${id} - ${name}")
    @ManyToOne
    private Customer customer;
}

Auto-Generated Format

When no display format is specified, the framework generates one automatically based on the entity's ID fields. See Display Format Guessing for details.

Reference

For annotation details and attributes, see @DisplayFormat.