| Author: | Michael JasonSmith |
|---|---|
| Contact: | Michael JasonSmith <[email protected]> |
| Date: | 2014-09-17 |
| Organization: | GroupServer.org |
| Copyright: | This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net. |
This product is concerned with the issuing of invitations to join an online group in bulk [1], using a CSV file submitted to a form. Most of the page is powered by JavaScript.
The admin_invite_csv.html form, in the Group context, takes a
CSV file and invites each person in the file (one per row) to
join the group. The work is done in two main steps — parsing and
inviting — which is controlled by JavaScript.
In the CSV file each row represents a person, and each column
represents a profile attribute. The form
gs-group-member-invite-csv.json, in the group context
[2], parses the information in the CSV file and returns a
JSON object: a list of profile data. The JavaScript then handles
the inviting.
The parsing form is a "JSON" form, as supplied by
gs.content.form.api.json [4]. The HTTP PUT parses in
a list of column identifiers and the CSV file, and a JSON object
is returned. If successful the object is a list of
profile-objects. If there is a problem then a JSON object is
returned with status set to one of the following error
numbers, and message set to a human readable message.
| Error | Name | Note |
|---|---|---|
| -1 | Form error | "Standard" gs.content.form.api.json error. |
| -2 | Unicode Decode Error | The entire file could not be parsed. |
| -3 | Column-count error | The column count was different to the ID count. |
| -4 | No rows | No rows could be found in the CSV. |
| -5 | Empty | The CSV file was empty |
The inviting is actually carried out by
gs.group.member.invite.json. If the CSV is fine then the
JavaScript fires off invitation notifications provided by
gs.group.member.invite.base. The invitation is responded to
using one of the two pages in the gs.profile.invite module
[3].
JavaScript is essential to the Invite by CSV system; without full
compliance the page simply will not work. I decided to make the
JavaScript a requirement because it drastically the system,
reducing errors in my code, and drastically improves the
usability. (The usability is far from good, but the earlier CSV
Invite system would only show a spinner and generally end up
showing a TCP Timeout error page.) The code, provided by the
resource /++resource++gs-group-member-invite-csv.js, controls
the marshalling of user-supplied data, a template
generator, the parsing AJAX and the inviting AJAX. All
are controlled by some connecting code.
There are two components to the user-supplied data:
- The CSV file (which we will ignore for now) and
- The columns.
The latter is supported by the JavaScript class
GSInviteByCSVOptionalAttributes. The page and code provide a
table at Twitter Bootstrap dropdown that allows the group
administrator to select the optional attributes in the page. The
same class can marshal the data out of the HTML-table (embedded
in the page) and into a list of profile attributes and
names. These are used by the template generator and parsing
ajax.
The template-CSV generator is provided by the
GSInviteByCSVTemplateGenerator class. It examines the
profile-attributes that have been specified by the group
administrator and then generates a data-URL. This URL is then set
as the href for a (hidden) anchor element that is then added
to a page. Finally, a click event is fired, which causes the
browser to "download" the CSV template.
The JavaScript that powers the parsing AJAX is one of the reasons
that only (relatively) new browsers support the Invite by CSV
page. The class GSInviteByCSVParserAJAX makes use of the
FormData [5] and File [6] APIs to marshal
the data out of the form and to the parsing`_ form.
The same code examines the return value from the parser. If a problem was encountered then the error message is shown. Otherwise the inviting AJAX is called.
The JavaScript code that actually invites each person is provided
by the GSInviteByCSVInviterAJAX class. It maintains the list
of people that are yet to be invited, updates the progress bar
when the inviting form responds, and (depending on the response)
updates the New, Ignored or Error lists.
As is fairly standard for GroupServer JavaScript the page uses
attributes of the <script> element to pass data (such as URLs
and element selectors) to the JavaScript. As is also fairly
standard, the JavaScript is only initialised after the
window has raised the load event. Events are used to
connect one sequence of events (parsing the file) with another
(inviting the people).
Finally, the connecting the code is also used to reset the entire form when the group administrator clicks on the Reset button.
The template generator code, like much that is tricky with the Web, is helped by Stack Overflow.
- Code repository: https://github.com/groupserver/gs.group.member.invite.csv
- Questions and comments to http://groupserver.org/groups/development
- Report bugs at https://redmine.iopen.net/projects/groupserver
| [1] | For issuing a single invitation see the base product
gs.group.member.invite.base:
<https://github.com/groupserver/gs.group.member.invite.base> |
| [2] | The form gs-group-member-invite-csv.json is
also available in the site context, for the day
that the site-wide invite and add systems exist. |
| [3] | See <https://github.com/groupserver/gs.profile.invite> |
| [4] | See <https://github.com/groupserver/gs.content.form.api.json> |
| [5] | See <https://developer.mozilla.org/en-US/docs/Web/API/FormData> |
| [6] | See <https://developer.mozilla.org/en-US/docs/Web/API/File> |