[[disable]]
= `disable...()`

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



The `disable...()` supporting method is called for properties, actions and action parameters.
It allows the modification of the property to be vetoed (ie made read-only) and to prevent the invocation of the action ("grey it out").
For parameters, it disables the entry into the parameter; this is for actions with dependencies between the parameters.

Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).

The reason for vetoing a modification/invocation is normally returned as a string.
However, Apache Isis' xref:userguide:btb:i18n.adoc[i18n support] extends this so that reasons can be internationalized.

The signature of the supporting method is generally:

[source,java]
----
public String disableXxx() {
    // ...
}
----

where the returned string is the reason the property cannot be edited, or the action invoked.

For i18n, the supporting method returns a `TranslatableString`:

[source,java]
----
public TranslatableString disableXxx() {
    // ...
}
----

The returned string is then automatically translated to the locale of the current user.

To disable a property:

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

public class Customer {

    @Getter @Setter
    private boolean blacklisted;

    @Getter @Setter
    private BigDecimal creditLimit;

    public String disableCreditLimit() {
        return isBlacklisted()
                    ? "Cannot change credit limit for blacklisted customers"
                    : null;
    }

    // ...
}
----

Or, to disable an action:

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

public class Customer {

    @Getter @Setter
    private boolean blacklisted;

    @Action
    public Order placeOrder(
                    final Product product,
                    final int quantity) {
        // ...
    }
    public String disablePlaceOrder() {
        return isBlacklisted()
                    ? "Blacklisted customers cannot place orders"
                    : null;
    }

    // ...
}
----

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 class ToDoItem {

public class ToDoItem {

    @Action(semantics = SemanticsOf.IDEMPOTENT)
    @ActionLayout(
            describedAs = "Update category and subcategory"
    )
    public Product categorize(
                    Category category,
                    Subcategory subcategory) {
        // ...
    }
    public String disable1Categorize(Category category) {
        return category == null || category.hasSubcategories()
                ? null
                : "The selected category has no subcategories";
    }

    // ...
}
----



