Lookup Data
Most business applications have some enumerated data that is used to populate selection items, as well as to look up the item by ID during validation or for any other purposes. Also, this data is typically fairly static, which lends itself to caching it globally, or at least for the current work session, to avoid unnecessary trips to the database or returning the full data for each result row versus just an ID.
For example, suppose that you have an Order Status
field that can be one of the predefined code values for each status, e.g., N for New, C for Complete, etc. When you have a screen for searching orders, the filter field for the status should provide a selection of statuses that shows status descriptions, but store the internal status codes, so you need a way to get a list of statuses with both codes and descriptions.
The backend service will need to validate that each provided status code is one of the valid statuses, especially when the service is called via a remote API, e.g., REST, where you don't want to rely on the UI validations alone. So it will need a way to quickly check if the provided status code is valid.
Similarly, when you display the order status in the results grid, you may want to show the full status description, whereas the backend service would return only the status code to make the structure of the result more simple and compact. In this case, the UI will need a way to quickly look up the status with its description by the status code without making external calls.
Xomega Framework defines a flexible common structure for storing, loading, and caching the lookup data on the client or on the server side, as described in the following sections.
Headers
When you want to display a list of entities in a selection control, you typically don't need all the fields for each entity. Normally you need an internal ID, display text, and possibly a few other attributes, which constitute the key information about the entity. For such information, Xomega Framework defines a generic class Header
that represents the key header data for an entity.
The Header
class has the following primary attributes.
Type
- a string that determines the class of objects it represents.Id
- string-based ID that should be unique for all headers of the given type.Text
- a user-friendly text that identifies this header.
Invalid headers
Normally, headers are constructed with all three of the above parameters. However, when you have an invalid Id
that was entered by the user or received from somewhere, then it's possible to construct a Header
from just the type and that Id
, which will mark it as invalid by setting the IsValid
flag to false
, as illustrated below.
Header h = new Header("type", "Valid ID", "Display Text"); // h.IsValid is true.
h = new Header("type", "Invalid ID"); // h.IsValid is false.
This allows you to store an invalid entered ID as a Header
in data properties, which makes it easier to work with when all the property values are of the same type.
Inactive headers
As your system is used and evolves with time, some of its entities may get retired and should no longer be used, but they may not be physically deleted to maintain the integrity of the other entities that use them. For example, when users are deactivated, they should no longer appear in the selection controls for new entities, but you still want to display their full names on the older entities that use them.
To support this, the Header
class also has an IsActive
flag, which is set to true
by default for valid headers, but you can manually set it to false
for inactive values. Inactive headers will not be available for selection, but you can still look them up by ID as needed.
Additional attributes
In addition to the basic Id
and Text
, a Header
can have any number of named attributes that are stored as an object
. You can get or set them using the header's indexer, as follows.
Header hdr = new Header("type", "ID", "Display Text");
hdr["my attribute"] = 4;
object attr = hdr["my attribute"]; // 4
You can also store multiple values in the attribute using List<object>
. To add a value to an attribute, you can use the AddToAttribute
method, which will either set the initial scalar value for the attribute or add the value to the existing list if it's not a duplicate (it will construct a new list if the current value is not an IList
), as illustrated below.
Header hdr = new Header("type", "ID", "Display Text");
hdr.AddToAttribute("attr", "a"); // hdr["attr"] -> "a"
hdr.AddToAttribute("attr", "b"); // hdr["attr"] -> List<object>() { "a", "b" }
hdr.AddToAttribute("attr", "a"); // duplicate, hdr["attr"] -> List<object>() { "a", "b" }