Publish to the Web plugin

[mbastian]

The existing Sigma exporter is maintained by @computermacgyver. You can see the branches on their fork. We need to decide first if we want to update this plugin or to write a new one. If we decide to extend the existing one, I've already created an up-to-date branch on this repository at sigmaexporter-plugin.

[jacomyal]

At OuestWare, many people have asked us a solution to share networks online, using sigma v2. Our solution is Retina (source page). Its current functional scope is to allow sharing online a GEXF graph, but with custom filtering, coloring and sizing.

It is still in beta version, but ultimately:

• It reads any graph available online, as long as there is no CORS restriction (and Gist applies)
• The state (sizes, colors, filters...) are stored in the URL
• All Retina versions will coexist so that permalinks are persistent

One solution to provide a solution to share GEXF online using sigma v2 would be to have a wizard in Gephi that uploads the GEXF graph somewhere online (maybe on Gist, if we can allow users to login from the wizard itself), and then give them a URL to use.

We could also make something similar (exporting a .zip that contains Retina code and the graph file), but I'm afraid it will be harder to maintain.

[jacomyal]

Here is a list of things that the plugin must do, if we go that way:

1. We must register Gephi (or this plugin) as a GitHub app, to enable saving Gists

The doc is here. This is not the biggest topic, but we must store the registered app ID somewhere.

Also, to prevent having to deal with displaying a web page inside Gephi, the Enable Device Flow option must be checked.

2. The plugin should allow user to log into GitHub Gist

This will allow uploading the GEXF graph file onto Gist, to share it online with Retina. The process to authenticate a user (ie. retrieving a usable API token) is the following (as described here):

1. Gephi will ask for a user verification code to GitHub, and display to the user the code and a URL. The API call contains the app ID and the required scope (gist, in our case). More information here.
2. The user opens the URL in a browser where they log into GitHub, and then they give the code to GitHub.
3. During that time, Gephi will poll GitHub API to know when the user has effectively been verified. When it's done, Gephi will have a proper access_token. This token must be saved into the plugin

3. A logged in user can share their graph online

To share a graph with Retina, here is the list of things to do:

1. The graph is serialized in GEXF
2. A new public Gist is created with the GEXF file (doc here), with given file name, such as shared-graph.gexf
3. The API call response should provide the raw GEXF file URL under response.files["shared-graph.gexf"].raw_url. This is the URL that will be used to share the graph with Retina.

At this point, Gephi just has to share with the user the URL:

• To open Retina with the editor interface (to allow the user to pick what graph viewers will be able to do): https://ouestware.gitlab.io/retina/beta/#/graph/?url={ ENCODED_GRAPH_URL }&r=d
• To open Retina as a viewer with the default settings (ie. GEXF nodes and edges colors, no viewer option): https://ouestware.gitlab.io/retina/beta/#/graph/?url={ ENCODED_GRAPH_URL }

Please note that the graph URL must be properly URL-encoded before being put into the Retina URLs.

[jacomyal]

Additional attention spots

1. We must properly handle authentication failure:
   • Authentication token can be invalid, in which case the process at 2. must be rerun
   • During 2., a timeout (a long one, maybe 5 minutes or something) should be set before considering that something went wrong and asking for a new GitHub verification code
2. At this point, if Retina is updated from beta to v1 for instance, this plugin will have to be updated as well. This is an issue that must be addressed on Retina's side.