Differences

This shows you the differences between two versions of the page.

--- newdevs:db:fm [2025/02/22 10:24] – [oils_persist:cardinality] sandbergja
+++ newdevs:db:fm [2025/10/11 10:04] (current) – [options] sandbergja
@@ Line 18: / Line 18: @@
   * [[evergreen-user:reporting_data_dictionary|Reporting data dictionary]]
+While it was written for the old desktop client, [[xul:birds_eye_view|this page is a good starting place to learn about the Fieldmapper and API calls]]:
-===== Things to Add to This Page: =====
+{{METATOC >:xul:birds_eye_view}}
-  * Information about the main fieldmapper classes
-  * Example of how to navigate the fieldmapper
-  * Relationship of the fieldmapper to reports
-  * Relationship of the fieldmapper to the PostgreSQL database schemas
@@ Line 94: / Line 91: @@
 === reltype ===
-These distinctions are to indicate key directionality. They are not to indicate nullability.
-  * has_a
+There are 3 reltypes:
-  * has_many
+  * has_a -- the field physically exists as a column (as in, does not have the @oils_persist:virtual="true" attribute) on the SQL relation being described, and points to a unique key column (usually the primary key) of another SQL relation represented by another IDL class.
-  * might_have
+  * has_many -- the field is does NOT physically exist on the described SQL relation, but instead exists as a class property that will be filled with a LIST of zero or more objects built from rows on another SQL relation, described by the <link>'s @class attribute, which have a field that contains the local SQL relation's (effective) primary key.
+  * might_have -- the field does NOT physically exist on the described SQL relation, and there is exactly one row on another SQL relation described by the <link>'s @class attribute that contains the local SQL relation's primary key.
+In other words, "might_have" is EXACTLY THE SAME as "has_many", but is guaranteed to always hold exactly one object, or NULL, rather than always hold a LIST of zero or more objects.
+Here's how to decide which reltype attribute to use:
+  * If the field is not virtual, but backed by a real column: ALWAYS use "has_a"
+  * If the field is virtual, but there's only ever going to be, at most, one row on the other end of the join: ALWAYS use "might_have"
+  * If the field is virtual, and there can be any number of rows on the other end of the join: ALWAYS use "has_many"
 === key ===
@@ Line 113: / Line 123: @@
 === permacrud xmlns ===
 <code><permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"></code>
-This should be the opening tag for your peramcrud area.
+This should be the opening tag for your permacrud area.
 === actions ===
@@ Line 125: / Line 135: @@
 If using the create/update/delete actions, the class must also be mapped to an **[[newdevs:db:fm#oils_persist:tablename|oils_persist:tablename]].**
+If you specify a permission, you must also include a ''global_required'' or ''context_field'' attribute or a ''context'' element.  Otherwise, you will get the error message "Invalid object or insufficient permissions".
+You can specify multiple permissions at once by separating them with a space.  If you specify multiple permissions, a user would need at least one of the listed permissions to perform the action in question.
 == context_field ==
@@ Line 135: / Line 148: @@
 == owning_user ==
+===== Things to Add to This Page: =====
+  * Information about the main fieldmapper classes
+  * Example of how to navigate the fieldmapper
+  * Relationship of the fieldmapper to reports
+  * Relationship of the fieldmapper to the PostgreSQL database schemas