API:Working with Lists
THESE ARE JUST NOTES - more work is needed
So ca_lists and ca_list_items together model hierarchical lists. ca_lists records represent the list itself, and each has one or more rows in ca_list_items that represent items in the list. List items can assemble into hierarchies, so you can have lists that are flat (all items attached to the list root) or hierarchical (items attached to the root or to each other)
Both lists and list items take labels, just like any other first class CA database entity.
Lists are used in several ways in CA:
- They can define values to be used in a "list" metadata element. In this way you can associate one or more values from a list with a record (object, entity, place, etc.) in an editing form.
- List items can be related to other records via relationships, in the same manner that other first class database entities are (Eg. objects related to entities via the ca_objects_x_entities table
- Specific lists are used to by CA to define how the system works. For example, available object types in an installation (eg. the list of types appearing in the New > Object > submenu) are defined in a list with list_code = "object_types"; there are two or three dozen lists that serve some role in system configuration
- There are a handful of hardcoded drop-downs in the data model - fields baked into the record structure for objects, lots, entities, and friends – for which a specific list defines the values. Examples are ca_objects.source_id (object_sources), ca_objects.access (access_statuses), and ca_entities.status (workflow_statuses). lot_status_id in lots is one of these fields.
There are a bunch of method that will let you get at list data in the ca_lists model. Just instantiate ca_lists and then call the methods. Most take an alphanumeric list_code or a numeric list_id to identify the list. You can use list_id or list_code interchangeably for the most part. List_code's are preferred because they are set in the profile and do not change across installations of the same profile. Because of the way MySQL allocates list_id's, here is no guarantee list_ids will be the same across various installations, even if they're using the exact same profile.
Lists and vocabularies are stored in the following database tables:
Other items in the database can be related to list items in two ways:
- Many-to-many relationships using *_x_vocabaulary_terms tables:
- Using attributes of data type list: