Replace emit/bind as plugin api

[WardCunningham]

The plugin api evolved to solve one not-to-interesting problem: distinguishing startup code required for static(html) and dynamic(json) wiki pages. Weaknesses have emerged:

• some doubt the utility of static html -- we preserve it mostly for seo
• a carelessly assembled collections of utilities have emerged in the wiki object
• the api has been converted to one using callbacks to deal with issues loading dependencies
• story item types with text have to repeat the binding of the textEditor

We've also bastardized the plugin/factory interface to suggest how factories might work

• the factory plugin has been split into a meta-factory which is converted to a factory plugin by the server
• the server inserts a plugin menu as part of this conversion
• the conversion menu has been hardwired since it is not easy for the server to tell what plugins it hosts
• the drop handling in the factory plugin could delegate some case analysis to plugins
• it is left as an exercise for the site owner to figure out how to add new plugins

Finally, Adam points out that plugins know way too much about how the mouse works to make it work well with touch.

• https://github.com/WardCunningham/Smallest-Federated-Wiki/issues/100#issuecomment-3724031

He goes on to say, "The net step, it seems to me, will be to rewrite the way editing works. Because the current plugin implementations are not ideal for touch-based clients, I would like to suggest that we rewrite them but I'm not sure how much opposition there is to that idea. Specifically, instead of allowing plugins to arbitrarily bind events, I'd like to expose a handful of hooks they can use (to specify different allowed user actions) and that way we can have a single implementation for how those actions are displayed in the UI. That way we can change the UI in one place and have all plugins change to match."

In this issue I'd like to hear some suggestions as to a good path forward. Hopefully we can continue to work in smallish increments.

[asolove]

I want to put in a word for some form of static html. It is necessary for some search engines, and those who do not or are not permitted to use javascript. Of course we don't have to provide the complete plugin in a static html format. I suggest that all plugins maintain an "alt" property that represents how they should be rendered as static html. For text modules, this would simply be the text content. For an image it might be the img html tag and its alt tag description. A chart might simply say "A chart of" followed by the content of the caption property. This way, servers only have to load the json data and spit out the alt attributes, rather than having to make the plugins or their templates run on all the different servers.

[WardCunningham]

Seems like each plugin could benefit from its own directory. Static html and other metadata could go in files with standard names.

[dvberkel]

I have a question regarding the cloning of wiki in relation to the plugins available on the original wiki. Will the plugins be cloned as well?

When you are federating a wiki on a specific subject e.g electrical engineering or mathematics, it is not unlikely that you will develop a custom plugin to render some data relating to the subject. In a sense the wiki relies on the plugin. When I clone your wiki I would like to benefit from the plugin you created. Are plugins cloned automatically? Is it a mechanism which should receive some attention in this discussion?

[WardCunningham]

It is a good question. We have to be careful to not distribute viruses throughout the federation. We have to jump through some hoops just to pull inert json from remote sites. Pulling active code automatically will require even more care. Some form of sandboxing is required. Here is one that depends on source-to-source transformation:

• http://code.google.com/p/google-caja/

Another suggestion is to include the address of a git repository in plugin metadata. That would leave it to individual server operators to decide how automatic they want to make installation. Perhaps good practice would be to clone your own repo into a DMZ version before browsing too widely when plugin installation is automatic.

[dvberkel]

Both suggestions are interesting albeit a bit technical. I am not sure that all intended user that would want to host their own wiki are up to the task of configuring the plugins in the suggested ways.

Like you said, we have to be alert on the possibility of spreading ill-intent viruses (I think that virus memes should be encouraged), but I think it should possible to manage plugins without a deep understanding of any technology like google-caja or git.

Ideally one would enable users to manage plugins (and maybe more) from within the wiki. I am thinking out load, when a wiki is cloned all "custom" plugins will be cloned as well, but signaled to be dirty. For example be prefixing the file-name with "dirty-". We then could add a menu only visible for the owner of the wiki with a command to clean up dirty plugins.

[asolove]

I would like to start tackling this issue in an organic way rather than the one-shot refactoring that has now failed twice.

My idea is to start by only allowing drag refactoring from a drag rail on the border of each item that appears when it is hovered.

Then I propose introducing an alternate API while still allowing modules to use the old one and just detecting which they use. Then we can move them over one by one (starting with text) to get a feel for what the new API should be.

[asolove]

I create a demo of the first step, the drag rail, this evening. It is done hackily and only works for paragraphs, but is worth playing with. The code is in my drag-rail branch.

For the chronically impatient, I uploaded a short screencast.

The primary upshot is that you can now click and drag within an item (to select text or move a map) without actually picking the item up and reordering it within the story. The handle also begins to move us toward a UI with more visible affordances for user action. It will be a good place to hang other items, like icons for edit and other plugin-specific features.

[WardCunningham]

Hey, thanks for the video. I was scratching my head wondering what a drag-rail might be until I saw the screencast.

[WardCunningham]

I can see how it avoids entering a mode when ever you want to see something a little more detailed. If you could also rearrange pages, would you use a similar bar at the top of a pages to drag it left or right?

[asolove]

Yes, I would think so. And whatever pattern we find for entering the edit state or doing other item actions could also be available for changing the page title or other page-level actions.

[WardCunningham]

Warning: I did not fully understand the completeness of your thoughts until I had completed writing the following analysis. Please forgive me for going on and on when you had already said most of this. You can now watch me come to understand and maybe even contribue.

If a "mode" is a state where inputs are given an alternative meaning, then the most evil version of mode is when each mode demands of a user a different input to be released from the mode. Unix is notorious for this: "ctrl-d" here, ":wq" there, "bye" somewhere else. Things got better for users when pointing joined typing as a possible input.

In the case of the map we have several distinctions to make: are we dragging the map because we want to see past the edge (a temporary change), or, are we dragging the map because we want others to see a different view (a permanent change). The TextEditor uses double-click to enter edit mode, a declaration that changes to be permanent. Loss of focus or command-s is our way out now, though a universal way to 'cancel' would be handy.

The TextEditor has a similar conflict as the map: If we're not editing, then drag could mean "select", not move the paragraph as it is currently interpreted.

The drag bar nicely avoids a third interpretation: we are dragging the map because we want the map to appear somewhere else. Other possible interpretations of a drag motion include: moving one page within the arrangement of pages, and, moving the collection of pages together.

As I write this I'm coming to believe we need (dare I say it) a hierarchy of modes. We start in mode "reading" where swipes scroll and taps hyperlink. Then, somehow, we enter mode "organizing" where we move pages with respect to each other and adjust map views to see what we want to see. Neither reading or organizing are persistent beyond a session. Editing is the third and deepest mode. While editing we will want some access to gestures that allow us to continue reading and organizing while we edit.

If we were to offer a read-only site then we would fix it so that one couldn't get into editing mode. Today we say, anyone can edit but changes don't any further than one has permission to write.

[asolove]

Your comments are very helpful and actually straighten out a few things that were jumbled together in my mind.

I think a good model for this is a spreadsheet. You can read and move around a spreadsheet without any UI elements in the way. You can click on a cell once to change its properties or drag it around. And you have to click one more time (or double-click, or press enter) to actually get the line editor to change the cell's contents.

I haven't played around with Numbers or other spreadsheet programs on the iPad, but I imagine they would be a good place to look for inspiration.

[WardCunningham]

I use keynote on osx and ios. I consider both to be good models for manipulation of structured content. Sometimes recognizing useful analogies between presentation slide and wiki page requires understanding the why behind each of apple's decisions. (If we understand the why, but not copy the what, maybe we can stay out of court.)