| | 62 | == Understanding The SPI == |
| | 63 | |
| | 64 | This section describes the SPI abstractions and operations that application writers will use. We are concerned with how to put the concepts into use and how they interrelate with each other. Below we describe the detailed interface. |
| | 65 | |
| | 66 | === Profiles === |
| | 67 | |
| | 68 | A profile is a collection of metadata attached to an abstraction instance, primarily to help users and administrators understand what the instance is bing used for. Users, projects, circles, experiments, and libraries all have profiles attached to them which describe those things. For example, a user profile includes the researcher's name and an e-mail address. |
| | 69 | |
| | 70 | Profiles are self-describing, so that applications have guidance is what is being presented and how to display it. Each of the abstractions above has an operation called `getProfileDescription` that returns an array of all the valid fields - called ''attributes'' - in that abstraction's profile. Each element of that array - each attribute - includes additional metadata that describes its purpose and presentation: |
| | 71 | |
| | 72 | ||= Metadata =||= Meaning =|| |
| | 73 | || Name || Descriptive name for the attribute, e.g. e-mail. All attributes have a name. || |
| | 74 | || Value || The contents of the attribute. When retrieving a profile description, every attribute's value is empty || |
| | 75 | || Description || Brief natural language description of the attribute, suitable for context sensitive help || |
| | 76 | || Access || Whether a user can modify the data. Valid values are `READ_ONLY`, `READ_WRITE`, `NO_ACCESS`, and `WRITE_ONLY` || |
| | 77 | || Optional || True if the field can be omitted in a profile. All non-optional fields must be present when creating an instance. Applications may expect these fields to be present. |
| | 78 | || DataType || How to interpret the data. Valid values are `STRING`, `Int`, `FLOAT`, and `OPAQUE`. || |
| | 79 | || Format || A regular expression describing valid field entries. Applications can use this to check user input locally. Applications are not required to do so, but values for this attribute that do not match the expression will be rejected. || |
| | 80 | || FormatDescription || A natural language description of valid input suitable for context sensitive help. The FormatDescription for a phone number field might be "10 digits, optionally separated by hyphens or parentheses." || |
| | 81 | || LengthHint || A hint at how much space an application should to reserve for input, in characters. Applications can obviously ignore this. || |
| | 82 | || OrderingHint || An integer that suggests to an application what order to display the field relative to others. Applications can ignore this || |
| | 83 | |
| | 84 | Each instance has an associated operation, `getUserProfile` (projects have `getProjectProfile`, experiments have `getExperimentProfile`) that returns the profile for that instance as an array of attributes, as above. This profile includes the values for all the (readable) attributes. |
| | 85 | |
| | 86 | Each instance supports a `changeUserAttribute` operation that allows the application to change the instance's attribute values. `changeUserAttribute` is used to change a user's phone number. Optional attributes can be deleted through this interface. |
| | 87 | |
| | 88 | An application will use the profile operations in the following ways: |
| | 89 | |
| | 90 | * When creating an instance that requires a profile, the application will request the profile description using `getProfileDescription`, fill in non-optional fields (probably based on user input) and include that profile data with the creation request. All abstractions that have profiles attached require a valid profile as a parameter to the operation that creates them. |
| | 91 | * When displaying an instance that supports a profile, the application may request the profiles for various instances using `getUserProfile` et al., and display all or some of the profile data. |
| | 92 | * Applications that manage abstractions with profiles may allow users to change the contents of the profile using `changeUserAttribute`, et al. |
| | 93 | |
| | 94 | |
