eLIFE tech discussion - 2017-09-05

elife-notes-2017-09-05.md

eLife tech discussion

Present

• chdorner
• dthompson
• robertknight

Agenda

Discuss implementation approaches for:

• Importing Disqus comments
• Allowing eLIFE to associate display names with users and rendering those in the client
• Allowing display names / usernames in annotation cards to link to eLIFE user profiles

Disqus comment import

• We'll create a tool for admins to bulk import annotations in the W3C annotation format. eLIFE will provide their existing comments in this format. See hypothesis/product-backlog#349 (comment)
• Replies to be handled as per the above comment
• dthompson had a question about whether eLIFE would submit textual bodies as markdown or HTML. robertknight said that client and service should support HTML in annotation bodies, but needs testing. One option is for eLIFE to convert HTML to markdown using something like https://github.com/thephpleague/html-to-markdown

Display names

• We have an API for creating users, this can be extended to support setting the display name. ie. POST /api/users will get support for a display_name field.
• We can add a PATCH /api/users/{username} API for modifying existing users.

POST /api/users

{
  "authority": "publisher.org",
  "username": "jimsmith",
  "display_name": "Jim Smith",
  "email": "jsmith@gmail.com"
}

PATCH /api/users/jimsmith

{
  "display_name": "James Smith"
}

The display name will then be rendered in annotation responses under a user key:

GET /api/annotations/123

{
  "userid": "acct:jsmith@publisher.org",
  "user": {
    "display_name": "Jim Smith"
  },
  ...
}

The client will then render these display names in place of the username in annotation cards, if present. Note that this will apply to both normal Hypothesis accounts and third party accounts.

Usernames

We talked through 3 approaches briefly:

1. Allow APIs for creating/updating users to associate a URL with the user, rendering these URLs in annotations and making usernames in the client open these URLs
2. Allowing the response for /api/links to be customized per-authority to override the default username templates
3. Allowing client configuration to override the default links set by /api/links

We don't have any of the infrastructure needed to support (2) yet and for (1) it wasn't clear that this is the right approach since the links that we currently have in the User data model are for users personal links, not their profiles on the annotation service.

We're inclined to opt for the third approach at the moment, since this is how other URLs are already configured in the context of third party accounts.

The client configuration might look something like this:

window.hypothesisConfig = () => {
  return {
    services: [
      apiUrl: "...",
      grantToken: "...",
      links: {
        user: "https://publisher.org/users/:user",
      },
    ],
  };
};

Update 2017-09-07 - During the eLIFE sync call Nathan suggested that a callback function, along the lines of how we handle the login and signup callback, would be another option.