Page MenuHomePhabricator

Convert Phurl to use EditEngine
Closed, ResolvedPublic

Description

Phurl currently uses an older EditController style for editing URLs. It should be converted to use EditEngine instead, which is a newer mechanism that can, e.g., automatically generate a Conduit API endpoint.

D14771 has a good example of doing this conversion in Badges. T10672 has a couple of pointers at things that doesn't fully cover (also in badges).

Revisions and Commits

Event Timeline

eadler added a project: Restricted Project.Mar 28 2016, 8:19 PM
eadler moved this task from Restricted Project Column to Restricted Project Column on the Restricted Project board.Mar 28 2016, 8:29 PM
eadler moved this task from Restricted Project Column to Restricted Project Column on the Restricted Project board.Jul 4 2016, 9:18 PM

EditEngine is a slightly different way to build forms that look the same as other forms, introduced circa January 2016. Some applications have moved to it, while others have not yet. It seems pretty reasonable and stable, though, so we're in the process of moving everything over.

Roughly an EditEngine is a class that defines the UI and API for editing a particular type of object (like a task, or a short URL in this case). This definition of the edit UI then automatically generates:

  • the actual web form ("Edit Thing"),
  • a modern Conduit API (thing.edit),
  • HTTP prefilling (/edit/thing/?title=x),
  • the comment form, comment workflow, previews, drafts, and comment actions,
  • customizable variants of the form with different instructions/fields/defaults, like the "New Bug Report" and "New Feature Request" forms on this install.

Previously, most of these things were done more manually. EditEngine replaces the more manual versions with a unified definition which can generate all this other stuff.

EditEngine does not define how to apply edits, nor does it define which edits are possible. That stuff is done by TransactionEditor.

One way to think about it is that TransactionEditor is defining an internal API (a way to mutate objects by applying transactions to them) and EditEngine is defining an external API (forms and conduit API methods so users can apply those mutations).

To move an application EditEngine, you'll roughly do this:

  • Subclass EditEngine, and fill in things with your best guess to start with, based on existing EditEngine subclasses and how the EditController is written.
  • Replace the existing EditController with one that calls your new EditEngine, which will let you interact with it. Tweak stuff until things seem to be working.
  • Clean up leftover stuff in the UI -- commonly stuff like breadcrumbs, "Create New Thing" links, sometimes routing is a little weird. For applications with comments, replace them with EditEngine comments.
  • Optionally, expose the engine over Conduit (see T10681 for the task here), depending on how stable it is.

D14771 is an example of this process in Badges, and T10672 has some cleanup. You can also git log any other EditEngine class and probably find an initial conversion whenever it was introduced, although some of them are complex and probably not good examples. I think Almanac and Phame are probably fairly good as references, though.

The net effect of this should be essentially no change in the UI, but less code, and the option to implement consistent Conduit APIs in a few lines of code instead of copy/pasting a pile of junk into separate classes.

epriestley moved this task from Backlog to Intermediate on the Contributor Onboarding board.
epriestley added a subscriber: lpriestley.