Starting with Grouper v2.4, the Lite UI is no longer available in the standard setup, and the subject picker UI is not available.
Grouper Subject Picker
The Grouper subject picker picker is a lightweight embeddable UI component which can help external applications (or Grouper itself) to find subjects to put into textfields or hidden fields or drop downs or whatever. This is available for Grouper v.1.6+.
Here is a simple app screen. The URL says grouper, but it could be any URL.
There are two fields which need subjects selected, one just goes to a label on the screen, one to a textfield. When clicking on find person, this screen appears as a popup
This screen above is hosted in the Grouper UI. It is assumed there is singlesign on between the two applications for good usability. If there isnt, then the user would need to login to Grouper (I dont think the subject picker can be used anonymously). Since it is a popup there should be fewer problems with cross site browser plugin blockers (e.g. for ajax)
Now a subject can be searched for. Its results will populate with ajax. Note: there is a subject picker "name" that links the picker with a config file. That config file specifies which sources are to be used for searching, and if there is a group the results need to be in (e.g. only people who are active employees should be returned).
Subject pickers (you can have multiple at your site, customized for each application), have a lot of settings which are available. So to avoid having to set common settings in each subject picker instance, there are default settings. In the media.properties you can configure defaults for any of the subject picker settings. Note, since this is the media.properties, Grouper has defaults built in, and you can override those defaults:
In the media.properties, you need to specify if you are putting your configs for each subject picker in the classpath or in a hardcoded director. Also you can say what group by default can use subject pickers
Then for each subject picker, assign a subject picker name, some alphanumeric or underscore that will tie the subject picker in the URL to the property file. Make a file in the directory above or on classpath: /subjectPicker/subjectPickerName.properties
This file can be blank, or could have any of the default settings above overridden:
Not only the settings can be configured, but also the text. This is in the nav.properties so it can in different languages or locales based on browser preferences. Also this means Grouper has defaults, institutions can override those defaults (globally), and also further customize per subjectPicker. Here are the defaults in the nav.properties:
Based on the subject picker name, you can customize per subject picker in your local nav.properties
Note that the same rules apply in the nav.properties as other apps, you can use the same syntax to make infodot help icons appear
Once you have the subject picker configured in the Grouper UI, you can use it from an application. Note, with this setup with Grouper as an external application, there is no way to tell that the user is coming from the application you think it is coming from. This is one reason why authentication is required, and you can clamp down on who can use the service (e.g. active members of the community). If we want more security we could pass tokens with web services or something. In the HTML of the web app that needs a subject picker, make a button with an onclick that opens the picker. You also need to pass in the element name on the screen which had its button pressed (since multiple elements could need a subject picker).
Note, you could use a library like Jquery to make this easier. Also, it is nice if the elements you are putting the subjects into have id's (not just names), since it is more browser neutral (IE has issues with names).
There is a max number of subjects to display, which is configurable. Sources also have a max. Regardless if you search for someone's subject id or net id, that result will be at the top (by subjectId and subjectIdentifier). So if the netId is "a", and that throws an exception in the source for too many results, the subject with netId "a" will still be in the results to choose. the subjectId or sourceId match will always be at the top. The results are sorted by display label.
If the number of results is less than the max results by source (i.e. no exception thrown), but more than the max for the subject picker, then an alert will display to the user, and a partial listing of results will show on the screen.
Since subjects can be limited by group, the max number of results should be less than 1000 (I think 200). This is because finding a subject who is a member of a group is an expensive operation since the matching subjects need to be returned from the source, then the subejcts need to be queried (in batches) to the grouper registry to see which are in the group. You can test it out for yourself to see what a reasonable limit is.
"opener". So if Grouper and the application have different domain names or ports, then you need to workaround this. Set this in the settings to an HTML file which resides in the application:
That HTML page (or servlet or whatever) will be submitted to with an HTTP GET with the results of the picker. An example of the HTML page is attached, it just gets the args from the URL, and calls the opener function which will work since it is the same domain and port, and closes itself.
- Note that there is no sorting or paging here. This is because it is hard to sort and page across multiple sources, and even with a single source the subject API doesnt support it. The admin UI handles this by retrieving a lot of results and sorts and pages in Java. For the screen the initial hope is that if there are 200 results on the screen, hopefully the person can be found. Also, there are other tricks of bringing the netId and subjectId to the top