Computed Pseudofield
Computed Pseudofields, also known as calculated fields or computed fields, are fields that rather compute than store their value. Unlike other field types, like text fields, they contain a "formula" or script that describes the computation of the value instead of a user-entered value.
Use cases
Computed fields are mainly used to:
- Extract values from another field's value, e.g. the middle initial from a middle name field.
- Combine multiple fields, e.g. the display name is a combination of first, middle and last names.
- Calculations based on a value from one or more other fields, e.g. the grand total based on the VAT and the net price fields.
Features and Limitations
Let's have a look at their features and limitations:
- defined at design-time
- Calculated fields are entirely defined by the author of a class, that means standard users without programming rights cannot change anything about them. They don't have a value property and the script is defined by the author of the class.
- calculated at run-time
- Everytime a page containing a computed field is requested the value of the computed field is calculated. That means, that the computed field always shows current value, even if it is used to display something highly volatile like the current date and time. But that also means, that you should not overdo it with the number of computed fields and their complexity, else you wiki may decrease in performance
- read-only
- The standard display for view and edit mode of an calculated field is read-only. So users of your wiki cannot enter any data into the calculated field but only read the value of the calculated field. The value of the computed field will change if the user changes a value of a field that the computed field is based upon.
- not queryable
- Unlike other fields the value of the computed field is not stored in the database and therefore cannot be part of xwql or hql queries.
Usage
Now it's time to have a look into how you use computed fields. To be ready to start you should have some knowledge about defining and using an XClass.
If you create an XClass with a computed property you will see the following in the property editor:
The property we are most interested in is the script property. You can use any of the script languages in XWiki to create your script. If you use Velocity for your scripts you also have some "extras" at your hand (see Velocity Tools).
Let's start with the most basic example for a computed field:
Hello World
This example only displays the string "Hello World" in a computed field. This can be achieved in multiple ways, the most basic is to use the string "Hello World" as script.
The next version is to use Velocity scripting:
Hello world
{{/velocity}}
Echoing a field
For this example you need a class with a field "source" of type string and a calculated field "echo". Paste the following code into your script to see the value of the field "source" echoed in the "echo" field:
#set($source=$object.getValue('source'))
$source
{{/velocity}}
Getting a substring of a field value
Let's reuse the class from above and use the following code to get the first two letters of the "source" field:
#set($source=$object.getValue('source'))
$source.substring(0,2)
{{/velocity}}
But what happens if the source field is empty?
This is not good, so let's prepare for source being empty:
#set($source=$object.getValue('source'))
#if($source.length()>=2)
$source.substring(0,2)
#end
{{/velocity}}
