= Action Icons and CSS

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


Apache Causeway allows link:http://fortawesome.github.io/Font-Awesome/icons/[font awesome] icons to be associated with each action, and for link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to action rendered as buttons.
These UI hints can be applied either to individual actions, or can be applied en-masse using pattern matching.

It is also possible to specify additional CSS for an object's members (not just actions).


== Icons

Action icons can be specified in several ways.

One option is to use the xref:refguide:applib:index/annotation/ActionLayout.adoc#cssClassFa[@ActionLayout#cssClassFa].
For example:

[source,java]
----
@ActionLayout(cssClassFa="refresh")
public void renew() {
    ...
}
----

Alternatively, you can specify these hints dynamically in the xref:ui-layout-and-hints.adoc#object-layout[layout file] for the entity:

[source,xml]
----
<cpt:action id="renew" cssClassFa="refresh"/>
----

Rather than annotating every action with xref:refguide:applib:index/annotation/ActionLayout.adoc#cssClassFa[@ActionLayout#cssClassFa] and xref:refguide:applib:index/annotation/ActionLayout.adoc#cssClass[@ActionLayout#cssClass] you can instead specify the UI hint globally using regular expressions.
Not only does this save a lot of boilerplate/editing, it helps ensure consistency across all actions.

To declare fa classes globally, use the xref:refguide:config:sections/causeway.applib.adoc#causeway.applib.annotation.action-layout.css-class-fa.patterns[causeway.applib.annotation.action-layout.css-class-fa.patterns] configuration property (a comma separated list of key:value pairs).

For example:

[source,ini]
----
causeway.applib.annotation.action-layout.css-class-fa.patterns=\
                        new.*:fa-plus,\
                        add.*:fa-plus-square,\
                        create.*:fa-plus,\
                        renew.*:fa-sync,\
                        list.*:fa-list, \
                        all.*:fa-list, \
                        download.*:fa-download, \
                        upload.*:fa-upload, \
                        execute.*:fa-bolt, \
                        run.*:fa-bolt
----

Here:

* the key is a regex matching action names (eg `create.*`), and
* the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name

For example, "fa-plus" is applied to all action members called "newXxx"


== CSS

Similarly, a CSS class can be specified for object members:

* xref:refguide:applib:index/annotation/ActionLayout.adoc#cssClass[@ActionLayout#cssClass] for actions

* xref:refguide:applib:index/annotation/PropertyLayout.adoc#cssClass[@PropertyLayout#cssClass] for properties, and

* xref:refguide:applib:index/annotation/CollectionLayout.adoc#cssClass[@CollectionLayout#cssClass] for collections.

Again, this CSS class will be attached to an appropriate containing `<div>` or `<span>` on the rendered page.

Possible use cases for this is to highlight the most important properties of a domain object.


It is also possible to specify CSS classes globally, using the xref:refguide:config:sections/causeway.applib.adoc#causeway.applib.annotation.action-layout.css-class.patterns[causeway.applib.annotation.action-layout.css-class.patterns] configuration property.

For example:

[source,ini]
----
causeway.applib.annotation.action-layout.css-class.patterns=\
                        delete.*:btn-warning
----

where (again):

* the key is a regex matching action names (eg `delete.*`), and
* the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied


