:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

When a collection of entities are rendered by the viewer, the table will by default have one column for every property that is not otherwise universally hidden (eg using `@Property(hidden = Where.ALL_TABLES`).

Sometimes though the columns to be shown will vary depending upon the use case with which the entity is being interacted.
One way to fine-tune the columns shown is to implement the `TableColumnOrderService` SPI.
An alternative is to define a view model as a projection of that entity, and return a collection of that view model instead.
However, this view model requires the end-user to have to click first to the view model, and then to the backing entity instance that it wraps.
The `projecting` element allows this extra hop to be eliminated.

The `projecting` element can only be used on a view model, and only on a single property of that view model,  and that property must return a reference to an entity (the backing entity).

Rather than render links to the view model, the viewer instead renders links directly to the entity.

== Demo Domain

The diagram below shows how the domain objects of the demo app are related:

ifndef::dev-mode[]
image::/demoapp/dom/annotDomain/Property/publishing/uml-class-diag.png[]
endif::dev-mode[]

ifdef::dev-mode[]
[plantuml,property-projecting-uml-class-diag,png]
----
@startuml(id=Commons)

hide empty members
skinparam {
  shadowing false
  arrowFontSize 10
  defaultTextAlignment center
  wrapWidth 200
  maxMessageSize 100
}
hide stereotype
skinparam rectangle<<2>> {
  BackgroundColor #438dd5
  FontColor #fffffe
  BorderColor #2E6295
}

class PropertyPublishingVm {
}
class PropertyPublishingChildVm {
}
class PropertyPublishingChildJdo {
}

PropertyPublishingVm -r-> "1" PropertyPublishingChildVm : firstChild
PropertyPublishingVm -r-> "1..*" PropertyPublishingChildVm : children
PropertyPublishingChildVm -d-> PropertyPublishingChildJdo : backingEntity

@enduml
----
endif::dev-mode[]

The property from `PropertyPublishingChildVm` to `PropertyPublishingChildJdo` is annotated as a projecting property:

[source,java,indent=0]
----
include::child/PropertyProjectingChildVm.java[tags=projecting]
----
<.> projecting property
<.> it is _not_ necessary for the property to be visible

The "parent" `PropertyPublishingVm` has both:

* a collection of child view model objects:
+
[source,java,indent=0]
----
include::PropertyProjectingVm.java[tags=children]
----

* a property referencing a single child view model:
+
[source,java,indent=0]
----
include::PropertyProjectingVm.java[tags=property]
----

In both cases, following the link to the view model instead navigates to the backing entity.

[TIP]
====
As it isn't possible to access the projection view model at all, there's little need to define a `layout.xml` file.
====



