45 lines
5.1 KiB
Markdown
45 lines
5.1 KiB
Markdown
# Metadata, Java ViewModels and new FXML forms
|
|
|
|
These are three separate operations: describe existing Java Models at compile time, optionally generate Java ViewModel classes, and interactively review a new editable FXML form. The Person desk enables the first, keeps its hand-written ViewModel, and provides examples for the third.
|
|
|
|
## Compile-time Model descriptions
|
|
|
|
Add `de.neitzel.fxdesigner:designer-model-processor:0.1.0-SNAPSHOT` to Maven compiler `annotationProcessorPaths`, preserving existing processors such as Lombok. Enable annotation processing and select Models with:
|
|
|
|
```xml
|
|
<compilerArgs>
|
|
<arg>-Adesigner.models=com.example.Person,com.example.Address</arg>
|
|
</compilerArgs>
|
|
```
|
|
|
|
The processor emits deterministic resources under `META-INF/neitzel-fx-designer/models/`. It describes eligible public read/write JavaBean Attributes, inherited properties and collection element types without constructing Models. Only types owned by the source compilation are emitted. Discovery prefers these descriptions and verifies them against compiled signatures; absent metadata uses compiled-signature fallback. Malformed, duplicate or stale metadata is an error, not silently ignored. Custom BeanInfo semantics and unsupported generics are not guessed.
|
|
|
|
Build and Refresh clean-builds the selected inputs. Outside the Designer, clean after removing/renaming properties or changing processor selections so obsolete generated files cannot survive. Generated metadata is not a runtime dependency or an alternative Model instance. [Full processor setup and format](../generated-model-metadata.md).
|
|
|
|
## Optional Java ViewModels and registry
|
|
|
|
Add the following compiler options when generated Java classes are desired:
|
|
|
|
```xml
|
|
<arg>-Adesigner.viewModels=true</arg>
|
|
<arg>-Adesigner.viewModelModels=com.example.Person,com.example.Address</arg>
|
|
<arg>-Adesigner.generatedPackage=com.example.generated</arg>
|
|
<arg>-Adesigner.viewModelDefaults=com.example.Person=com.example.CustomPersonViewModel</arg>
|
|
```
|
|
|
|
`viewModelModels` is an optional subset of `designer.models`; omission selects all. `viewModelDefaults` is optional. Generated classes in `target/generated-sources/annotations` expose typed stored properties and accessors, with nested ViewModels and observable collection values following NeitzelLib's existing identity/write-back rules. Do not edit generated Java. Put custom behavior in an ordinary subclass of the generated base and select it as the default. A pre-existing subclass of plain non-generic `ViewModel` cannot simply be registered as a generated-base subclass.
|
|
|
|
The generated registry supplies defaults without constructing registry objects. Classpath builds emit service metadata. Named modules need an explicit `provides de.neitzel.fx.view.ViewModelRegistry with ...GeneratedViewModelRegistry;` and appropriate generated-package exports/opens. A compatible explicit `@ViewModelClass` takes precedence before first creation; conflicts and incompatible defaults fail rather than splitting Model identity.
|
|
|
|
Use separate generated packages for participating modules. Unsupported generic Model declarations, reserved API collisions, unsafe narrowing and unresolved nested mappings are compile errors. Cross-module nested generation and arbitrary custom BeanInfo mappings are outside the qualified slice. Selection remains checked-in Maven configuration; there is no graphical Java-generation setup screen. See the [registry and JPMS reference](../generated-viewmodels.md) and matching NeitzelLib runtime guide.
|
|
|
|
## Review and create FXML
|
|
|
|
1. Build successfully, then choose **Bindings → Generate View**. Enter the qualified Model and optionally an existing Controller; **Load Model fields**.
|
|
2. Include fields, order them, edit labels, controls, directions and Converters. **Discover field choices** supplies compatible Components/Rows and Table information. Omitted fields need no valid configuration.
|
|
3. For nested Models choose an existing Component. For Model collections choose Repeat or Table and an existing Component/Row; Table Columns use ordered `attribute | header | optional width` lines. Open the selected source independently if it needs editing.
|
|
4. Enter a new sibling `.fxml` filename and **Review generated View**. Inspect both proposed layout and exact XML. Errors block creation; warnings remain visible.
|
|
5. **Create reviewed View** writes exactly the approved text without overwriting an existing file and opens it in the host. Subsequent edits have normal Undo/Redo. Rebuild to include the new resource; add a preview descriptor if it should run interactively.
|
|
|
|
Any relevant document, build or choice change invalidates review. File creation is not itself a text Undo command. Generation produces an independent editable document, not a managed file that later regeneration overwrites. The supported controls are TextField, Label, CheckBox, ListView, Component, Repeat and Table. Scalar defaults form a two-column GridPane; complex sections span it. A blank Controller uses the runtime's declarative fallback. The generator does not create Controllers, handlers, Components, Computed declarations or sample providers, and does not support arbitrary output directories. [Detailed creation contract](../reviewed-view-generation.md).
|