Merge obj2href() and as_summary_row() to as_summary_item()

Written between 2024-06-12 and 2024-06-14.

I merged the obj2href() and as_summary_row() methods of Model into a single method named as_summary_item.

They did almost the same, both returned a link (an <a href="...">...</a> fragment) that opens the detail window of this object. One difference between them was that obj2href() returned an ElementTree element while as_summary_row() returned a safe string. The as_summary_item() method returns an ElementTree element. ElementTree is better than safe HTML for specifying small HTML chunks because it is more flexible and more fool-proof (and thus actually safer). And at this level we won’t use any templating nor store the result in a database, so there is no advantage of using safe html. So I converted the as_summary_row() methods from generating safe html to using ElementTree.

The as_summary_item() method expects the text of the link as an optional positional argument after the ar.

Note: We should also rename the obj2html() method. But this is another topic because application developers aren’t supposed to override it. obj2html() just returns a link to

Documentation about this is still poor. I started to move docstrings from lino.core.requests to lino.api.core.Request, but then stopped because this is yet another huge set of changes. I prefer to do this another time.

Usage examples:

  • lino_xl.lib.cal.Event customizes the title of the link

  • Polymorphic.obj2href() potentially loops over navigatable MTI models (_mtinav_models)

  • Voucher.obj2href() finds the MTI leaf (the implementing document type) before linking to it.

  • Note.obj2href() customizes the default text to use.

  • Ticket.obj2href() customizes both title and default text.

  • ProjectRelated.as_summary_row() adds, between parentheses, a clickable link to the related project.

  • coachings.Coaching.as_summary_row() adds, between parentheses, a clickable link to the related client.

  • comments.Reaction.as_summary_row()

  • publisher.Page.as_summary_row()

  • cal.Component.as_summary_row() adds a bit more information (the start_time, state and summary).

  • notes.Note.as_summary_row() adds a bit more information (the subject).

Calls:

as_summary_row() is called by

  • Actor.row_as_summary()

  • Request.row_as_summary()

obj2href() is called by

  • TableRow.as_summary_row and get_overview_elems() and as_paragraph()

Changes

  • converted every as_summary_row() to use ElementTree instead of safe html.

  • Renamed all as_summary_row() and obj2href() to as_summary_item().

  • as_summary_item() supports a second optional positional argument text

  • As a consequence, row_as_summary() (on both Actor and Request) now returns an ET element instead of safe html.

TODO: Rename obj2href() to as_summary_item() or something similar, and row_as_summary() to row_as_summary_item(). I leave these renames to a later commit to keep the changes as transparent as possible.