Page MenuHomePhabricator

Templates in Phriction
Open, NormalPublic

Description

I would like a feature allowing an admin to add wiki templates, which can be used to quickly create wiki pages by anyone in the team.

Templates in Phriction Wiki will allow users to quickly create a wiki page with some specific base content.

Use Case Examples:

  1. A template for a requirements document which should include mockups and collection of user stories.
  2. A template for meeting notes will help remember things to note (make the interns' life easier) .

Benefit:

Saves time, and brings in more consistency.

Event Timeline

skyronic created this task.Oct 15 2013, 5:05 PM
skyronic raised the priority of this task from to Needs Triage.
skyronic updated the task description. (Show Details)
skyronic added a project: Phabricator.
skyronic added a subscriber: skyronic.
chad edited projects, added Phriction; removed Phabricator.Oct 15 2013, 6:07 PM
chad triaged this task as Normal priority.Dec 5 2013, 5:23 AM
svemir added a subscriber: svemir.Jun 24 2014, 12:28 PM

T4029 has some discussion about this. The major open question is how powerful to make templating.

eadler added a subscriber: eadler.Apr 28 2015, 3:20 AM
chad added a comment.Aug 14 2015, 5:17 PM

I am presuming this should work like wiki templates:

https://en.wikipedia.org/wiki/Help:A_quick_guide_to_templates

I understand that the original reporter actually wanted "page templates", not "macros".

chad added a comment.Aug 14 2015, 5:31 PM

From https://secure.phabricator.com/book/phabcontrib/article/feature_requests/#describe-problems

Often, your problem may have a lot in common with other similar problems. If we understand your use case we can compare it to other use cases and sometimes find a more powerful or more general solution which solves several problems at once.

chad added a comment.Aug 14 2015, 5:47 PM

(I would like remarkup macros)

If macros really shall solve T9153 (updating of links to files):

  • Wiki pages were just one example. How do wiki page templates apply to other things, like project pages, tasks, events and so on?
  • I can already imagine the faces, when I tell someone who wants to "update" his file that is linked in several locations, he should have created a macro and used that right from the start...
chad added a comment.Aug 14 2015, 6:19 PM

I can already imagine the faces, when I tell someone who wants to "update" his file that is linked in several locations, he should have created a macro and used that right from the start...

This is a hypothetical. Even if it was needed once, by one install, it's not likely to get any prioritization. My concern here is you seem to have unrealistic expectations on the upstream. Maybe it's helpful if I clarify his a bit?

  • The upstream has 2 full time developers.
  • The upstream prioritizes based on contracts, and then impact / desire.
  • Free support consumes more upstream time than development.
  • Free support to every customer question this week alone consumed probably 70% of upstream time.

We are actively trying to reduce "free support" so we can build a real business, solve more customer problems, and maybe even someday afford additional full time developers.

Companies that have more needs than can be covered by "free support" should strongly consider paid prioritization / consulting. This is a generally a win for everyone involved. Features paid for by one company benefit every install, this distributes costs and reduces strain on the upstream.

Please don't get me wrong. I am doing my best to provide as much helpful feedback as possible, so the product becomes most useful and easy to use in the end.

In this case, I tried to clarify that the solution might not solve the original problem and instead complicate things. I didn't realise that there is no widespread need to update files linked into texts (like wiki pages, tasks, ...).

chad added a comment.Aug 14 2015, 7:13 PM

There are two things that come to mind.

  • You have a piece of Remarkup that you want to apply to many different content areas, that update when the parent updates. That should be this task, or a use case of this task.
  • You want to perform a bulk action in an application. T9132 is the task to track abstraction of bulk tools so they can be implemented in more applications, but it only would update one application. I also don't know if it will include find/replace, but seems reasonable to ask for that.
chad renamed this task from Templates in phriction wiki to Remarkup Templates.Aug 14 2015, 7:28 PM
chad updated the task description. (Show Details)

I can create a "weekly_changelog" template which I use in Phriction to quickly apply the common markup I use when building a new Changelog page.

Can you walk me through how you'd expect this to work when writing our weekly changelogs? I can't think of a way to implement this that both is:

  • useful for changelogs; and
  • updates when the parent updates (e.g., "please_please_please").

That is, for the first case, having a way to quickly start with a page with a bunch of markup on it might be helpful (basically, "start with a copy of this page..." for some other page), but then I'll edit that markup and there will be no way to automatically update it if the template changes.

In the second case, the templated text can change when the parent updates, but I probably can't edit it.

Is there a way to write this as one feature that I'm just not seeing?

chad added a comment.Aug 14 2015, 7:34 PM

My thought was "here is a block of Remarkup I want to re-use occasionally", that that ends up being either applied as a rough template when creating something or inline rendering the output when used as a macro. Or is this really two systems?

Well, what would the changelog one look like? If it looks like this:

Summary of changes from XXX to XXX.

| Codebase | Repository | HEAD | Activity |
|-----|-----|-----|-----|
| Phabricator | rP | rPXXX | XXX commits |
| Arcanist | rARC | rARCXXX | XXX commits |
| libphutil | rPHU | rPHUXXX | XXX commits |

These changes were promoted to `stable`.

General
=======

  - 

Upgrading/Compatibility
=======================

  - 

Security
========

  -

...that (say, a "template") might be helpful for writing the next changelog if I had some way to quickly "paste this template" into the box, but once I go through and edit it there's no way we can realistically update it if the original thing changes, since all of the text will be completely different.

We could take specific snippets, like:

These changes were promoted to `stable`.

...and then I could write:

{{stable}}

If that (say, a "macro") changed a lot it might be helpful in the general case, but that would save me almost no time, at least in Phriction when doing the changelogs, as they work today.

(What I actually do today is start by copy/pasting the previous week's changelog, so that minor updates to layout or formatting -- like the introduction of the stable branch -- come along over time; it wouldn't even be appropriate to update old changelogs since the stable branch didn't exist at the time.)

Like, there's no useful {{changelog}} macro I can define, since tons of the internal text is different from page to page.

I could theoretically define a {{changelogtable, phabricator=abc, phabricator.count=3, arcanist=def, arcanist.count=4, libphutil=a2b, libphutil.count=9}} macro/function (which takes parameters) and renders this:

| Codebase | Repository | HEAD | Activity |
|-----|-----|-----|-----|
| Phabricator | rP | rP{$phabricator} | {$phabricator.count} commits |
| Arcanist | rARC | rARC{$arcanist} | {$arcanist.count} commits |
| libphutil | rPHU | rPHU{$libphutil} | {$libphutil.count} commits |

But this is straying rapidly into a huge amount of complexity. For example, if the count is 1, it should say "commit", not "commits". And what if this macro/function contains other macros/functions? What if it wants to pass its parameters to them? And so on.

chad added a comment.Aug 14 2015, 7:44 PM

Ah, sorry, no I'm not suggesting when used as a template that it updates, only when used as a macro. The "reusable remarkup" seemed to fall into two use cases, but could be built into one application.

chad added a comment.Aug 14 2015, 7:46 PM

If this should be two separate tasks, that's fine, I assumed we could just build one thing.

epriestley added a comment.EditedAug 14 2015, 7:54 PM

So the idea is that you can either invoke a snippet as a macro, like:

{{please}}

...or click a "Start with Template" button, select "please" from that, and it fills in the box as though you'd copy/pasted the text?


Personally, I guess I'm generally not sure the "template" use case has much value over making it easier to "copy this document" in Phriction (I think ~100% of use cases are in Phriction?).

I'm not sure the "macro" use case has much value if we have Nuance and a builtin "Common Response" system there, since the primary use seems to be support stuff.

It seems vaguely bad/confusing to me that a comment or description on a task could say "Yes, this is a great idea." and then change to say "No, don't do that, it is a bad idea." without a comment edit / task edit too.

Even setting aside the intentional "Yes" -> "No" template edit, subtle changes to macro text over time could render it meaningless/confusing on old tasks.

chad added a comment.Aug 14 2015, 8:00 PM

How do you want to solve @devurandom's use case then?

I don't want to solve it anytime soon (and don't actually understand it, see bottom).

In the long run, I think having a proper directory structure for storing files is the best attack on this and a class of similar issues. I'd either turn Phragment into a user-friendly filestore or add the capability directly to Files, so you can browse through folders and upload files to specific places.

Then he:

  • Goes to Phragment.
  • Creates a new folder.
  • Adds files there.
  • Embeds them as {!common/headers/rainbow_header.jpg, size=full} or something.

Basically, Phragment (or files) starts looking like your Dropbox web UI or Google Drive in the future, and then you have a way to embed stuff from it in different places.

(I don't actually know what the original use case is, since I can't think of why I'd upload the same file to multiple pages except if it's a logo or background or splash image, which we can probably tackle better with CMS features. If it's something like "the PDF for requesting vacation", put it on a page by itself somewhere and link to it.)

chad added a comment.Aug 14 2015, 8:08 PM

Even setting aside the intentional "Yes" -> "No" template edit, subtle changes to macro text over time could render it meaningless/confusing on old tasks.

My argument here is that a text macro would keep correct information more in sync than static content. Certainly it could be abused, but the overall point is to improve the correctness of content with less effort.

I suppose an example from the original ticket was:

an image that is used to explain something in the documentation

I don't think this is worth solving. It seems rare, not-much-used, and you can go sort it out manually by going to FilesAttached to find all the places a file is used. If a screenshot explaining some documentation is used in more than a handful of places things should probably be consolidated anyway?

chad added a comment.Aug 14 2015, 8:12 PM

Well I've made a mess of this task.

chad renamed this task from Remarkup Templates to Templates in Phriction.Aug 14 2015, 8:13 PM
chad updated the task description. (Show Details)

The primary use case I see for {!bigproject/presentations/pitch.ppt} or {!design/mocks/notifications.pdf} is non-version-controlled resources which are potentially shared between users and updated a lot of times. But basically the same value as Drive or Dropbox: sharing files with familiar filesystem semantics so you can go look in a folder and see stuff with sensible names and non-technical users have a reasonable shot at figuring it out, too.

It's pretty hard to link to the latest version of a presentation or update a PDF a bunch of times right now, since you'd have to go edit the task description every time and update the reference to the new version. And no automatic versioning or nice browsing, which we'd get for ~free if you were just uploading to bigproject/presentations/pitch.ppt to update it.

I don't think macros are necessarily a bad idea or anything, and they'd be an OK fix here, they just seem potentially really complicated and involved and like they're only-an-ok-fix for a handful of not-too-important issues.

(I think batch find/replace is interesting, too.)

devurandom added a comment.EditedAug 15 2015, 9:29 AM

Thanks for the hints and ideas.

I assume the "Attached" tab works well enough. In addition, the find-and-replace function for batch edits (T9132) seems very useful.

Regarding the filesystem-like structure: I am trying to get my users used to using Phriction to create this structure instead. In my eyes it is superior to an actual filesystem (you can add descriptions inline and are free to use whatever form you like), as long as there are powerful search features (T9133) to find files that are not on any wiki page anymore or when you forgot which page the file was on (but remember related projects, e.g.).

When linking to a versioned file and then updating it - in my eyes it might be bad to just display the new file unconditionally everywhere. Maybe displaying "there are newer versions of this file available" might be better.

Disclaimer: We are still developing workflows with Phabricator as more users are joining.

P2028 is a really quick bookmarklet that will pull the content of a given Phriction document and insert it into the current Phriction edit page's textarea. Hopefully it'll save a few clicks for those of us who write lots of pages with a similar structure.

epriestley added subscribers: TafThorne, avivey, qgil.

T12511 discusses some possible use cases, but they are all in the form of {{name|123}} expanding to [[ something.com/123 | 123 ]] (external bug trackers, RFCs, etc).

T12511 is about a very different problem and use case. This request is about adding a feature that "will allow users to quickly create a wiki page with some specific base content.". T12511 is about adding a feature that lets users create a bit or markup that acts as a macro/function/template that generates a few lines of markup within a page.

MediaWiki does attempt to solve both T3963 and T12511 with a feature that it calls "Templates" but there is no need to say that the two would be implemented in the same way for Phriction.

See T12511#218328.

This task discusses both templates-as-functions (for example, {{math 2 + 2}} displaying as 4) and templates-as-starting-points (for example, some ability to select a common response like "Hi, Valued Customer! Thanks for getting in touch. This is a great question!" as a starting point when replying to a task).

Both flavors have significant technical and product complexity, and neither flavor of templates is currently supported by compelling use cases.

urzds added a subscriber: urzds.Jul 12 2017, 11:13 AM
ivo added a subscriber: ivo.Sep 13 2017, 10:03 AM

As for the templates-as-starting-points case: couldn't this be solved by implementing edit engine support for Phriction?

In Maniphest we have a number of custom forms with default values that contain template text for certain categories of tasks. If this were possible in Phriction, we'd be able to easily add default values for wiki pages as well.

epriestley moved this task from Backlog to Next on the Phriction board.Feb 14 2018, 2:41 PM