CONTRIBUTING.md

Contributing to formmvc

For architecture and usage, see README.md. This document covers how to build, test, and extend the library.

Building

# Build and test
gradle build

# Tests only
gradle test

Key concepts

There are four moving parts:

Class	Role
Attribute<T>	A sealed interface. Each nested record is one HTML attribute. It owns HTML rendering and server-side validation.
IDomain<S, U>	Abstract base for a form field. Holds a value and a list of Attributes. Doubles as a JPA AttributeConverter.
IDedEntity<I>	JPA base class for entities. Discovers IDomain fields via reflection and coordinates validation.
AbstractEntityFormController<S, T>	Abstract Spring controller. Provides create, edit, update, and ids endpoints for any entity.

How to add a new Attribute

1. Add a record to the permits clause of Attribute in Attribute.java.
2. Implement name() and htmlValue().
3. Override validate(...) if the attribute has a server-side constraint; leave it as the no-op default if it is render-only.

// Example: a render-only "readonly" attribute
record ReadOnly() implements Attribute<Object> {
    @Override public String name()      { return "readonly"; }
    @Override public String htmlValue() { return "true"; }
}

How to add a new IDomain

1. Create a class that extends IDomain<S, U> where S is the Java/DB type and U is the class itself.
2. Implement getType() (returns the HTML input type string).
3. Implement convertToDatabaseColumn and convertToEntityAttribute for JPA persistence.
4. Annotate the class with @Converter(autoApply = true).
5. Implement whichever constraint interfaces apply (IRangeable, IStringControls, IPlaceHolder, etc.) by delegating to addAttribute(...).

@Converter(autoApply = true)
public class SearchDomain extends IDomain<String, SearchDomain>
        implements IPlaceHolder<SearchDomain> {

    @Override public String getType() { return "search"; }

    @Override public String convertToDatabaseColumn(SearchDomain d) { return d == null ? null : d.getValue(); }
    @Override public SearchDomain convertToEntityAttribute(String s) {
        SearchDomain d = new SearchDomain();
        d.setValue(s);
        return d;
    }

    @Override public SearchDomain placeholder(String text) { return addAttribute(new Attribute.Placeholder(text)); }
}

If your domain needs date/time types registered with Spring's ConversionService, they are provided automatically by FormmvcAutoConfiguration — no extra config needed.