[[usability]]
= Usability

: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.
:page-partial:


== Property

By default properties cannot be edited, as specified by the
xref:refguide:config:sections/causeway.applib.adoc#causeway.applib.annotation.domain-object.editing[causeway.applib.annotation.domain-object.editing] configuration property.

This policy can be overridden for an individual property using the xref:refguide:applib:index/annotation/Property.adoc#editing[@Property#editing] annotation; this makes sense for properties where there are no business rules governing their content, for example "notes" or "comments" fields.

For example:

[source,java]
----
import lombok.Getter;
import lombok.Setter;

@Property(editing = Editing.ENABLED)    // <.>
@Getter @Setter
private String notes;
----
<.> Allows the property to be enabled (even if property editing is disabled globally).

It's also possible to make all properties of a domain object editable using xref:refguide:applib:index/annotation/DomainObject.adoc[@DomainObject], though use cases for this are rare.

For very simply "CRUD-y" like applications, you might wish to switch the global policy, so that all properties are enabled by default, then selectively disable them.

To disable an otherwise property (so that it cannot be edited):

[source,java]
----
import lombok.Getter;
import lombok.Setter;

@Getter @Setter
private String notes;

public String disableNotes() {                                  // <.>
    return isArchived()
            ? "The notes of archived objects cannot be modified"
            : null;
}
----
<.> "disable" prefix, suffix matches property name, returns String.
A non-`null` return string is taken as the _reason_ why the property cannot be edited.

To make _all_ of the properties of a domain object unmodifiable, use:

[source,java]
----
@DomainObject(
    editing=Editing.DISABLED
)
public class Customer {
    // ...
}
----




== Collections

Collections are always read-only; there is no notion of adding or removing from a collection implicitly.
To add to or remove from a collection, an action should be defined.



== Actions

To disable an object action:

[source,java]
----
public Customer placeOrder(Product p, int quantity) {
    // ...
}
public String disablePlaceOrder() {                     // <.>
    // ...
}
----
<.> "disable" prefix, suffix matches action name, and takes no parameters.
A non-`null` return string is taken as the _reason_ why the action cannot be edited.



== Action Parameters

It is also possible to disable an action parameter, so that it is disabled (greyed out) based on the value of earlier parameters.
For example:

[source,java]
----
public Product categorize(
                    Category category,
                    Subcategory subcategory) {
    // ...
}
public String disable1Categorize(                           // <.>
                    Category category) {
    return category == null || category.hasSubcategories()
            ? null
            : "The selected category has no subcategories"
}
----
<.> "disable" prefix, N-th param, suffix matches action's name, parameters are subset up to Nth, same type.
A non-`null` return string is taken as the _reason_ why the action argument cannot be changed.

[TIP]
====
If the action is implemented as a xref:mixins.adoc[mixin], then the `disableXxx` supporting method can be matched to the action parameter xref:mixins.adoc#using-the-parameter-name[by name] and also using xref:mixins.adoc#using-a-parameters-class[Parameters] class.
====

== For more information

For more information, see  xref:refguide:applib-methods:prefixes.adoc#disable[disable...()] section in the appropriate reference guide.

It's also possible to return locale-specific strings, by returning xref:refguide:applib:index/services/i18n/TranslatableString.adoc[TranslatableString] instead of `java.lang.String`.

