| Project: | Drupal core |
| Version: | 8.x-dev |
| Component: | token system |
| Category: | task |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | active |
| Issue tags: | API clean-up, D7UX, microproject, token |
Issue Summary
Many different parts of the Drupal admin interface use placeholder tokens inside of a longer stretch of text to represent "some value that will be replaced later." Sending out welcome emails to users is a common case: core allows admins to enter the text of the mail, with placeholder tokens like %user-name and %site-url.
Token module is a popular contrib module that offers similar functionality to modules that need placeholders/wildcards for other purposes. Modules can provide new tokens, like "[og-name]" for "The name of the organic group that a node belongs to" or [site-slogan] for "The site slogan the admin entered on the site settings page. Users can then use those placeholder tokens in any token-enabled field (like pathauto's configuration page). Token module is being proposed for inclusion in Drupal 7 core, because its centralized 'registry' of placeholder tokens is useful all over core and contrib.
The challenge (and it's a tricky one) is how to properly explain to users what tokens are available to be used and what they mean when they are presented with a field that can "accept" tokens. Several solutions to this exist right now, and some brainstorming has been going on for the Pathauto module, but ironing it out for core would be very beneficial.
Right now, in Drupal 6, token module provides a helper function that just spits out a table of all the tokens that are available. This is less than ideal, because with a number of token-providing modules installed, the list can get really really long. Some modules (like pathauto) manually build their own lists of tokens broken up by the 'kind' of token. (Node related tokens, user related tokens, etc.)
Some existing links include:
http://groups.drupal.org/node/19500
http://www.flickr.com/photos/mverbaar/3595675392/in/set-72157619245872526/
What are the essential 'bits of information' that might be conveyed for tokens?
1) The 'token type' -- node, user, etc.
2) The token as it is used by a module -- for example 'title' or 'uid' or 'mail'
3) The user-friendly name of the token -- for example "Node title" or "User ID"
4) An optional extended description of the token -- for example, a fully formatted date demonstrating how the 'date' token will appear
5) The token as it can be entered by a user -- for example [user:name]
6) The token as it can be entered if chained with another token -- for example [node:author:name] instead of [user:name]
In the quick omnigraffle mockup below, I've listed an example of the sort of things that might be commonly entered into token-enabled fields. The fields themselves don't have to do anything special with the tokens -- they just need to have some way of presenting the 'possible' tokens. Some existing ideas include: a collapsible browsable list of tokens, grouped by token type (like 'node' and 'user' and 'site'). Auto-complete in the text fields themselves. A popup. Something made of magic.
Any thoughts? Anyone? Beuller?
| Attachment | Size | Status | Test result | Operations |
|---|---|---|---|---|
| tokens.png | 24.99 KB | Ignored: Check issue status. | None | None |
Comments
#1
Whoops. Should have titled this properly.
Also, the existing issue for adding tokens to core lives at #113614: Add centralized token/placeholder substitution to core
#2
Placeholder for an actual comment. Or Subscribing
#3
Popup modal dialog FTW.
#4
After chatting with Bojhan, here's one proposal for how tokens could be presented in the UI...
#5
So a update, I think one problem I did find is that - with descriptions (which is fine), is this interaction is unprecedented - so one behavior we should try to mimic is that of collapsing. I see a certain problem, with beign able to drill down but not beign able to move up quickly, so I think exposing the other tokens might be valuable - but this is by no means a set opinion.
#6
So it's basically a generic combined tree/table control? How many levels we need? Can we do it based on existing fieldsets http://groups.drupal.org/node/19500#comment-76033 or should we create a new UI element?
#7
kika, the tricky parts are:
Together, those pieces make it a bit of a doosie. The following rough mockup also reflects some of the stuff Bojhan and I were discussing...
#8
- Correct, this is hybrid "tree/expandable table" control then. It would be nice to have it as genric UI element.
- what are the proposed actions user can to with this widget? Perhaps I am mis-reading the mocks but the tokens 1.0-style guidance "here are the codes you can insert into a text field: [author-name], [node-title] ..." are lost in the new UI. How the user should know he needs to mash together active tree elements [node:author:last-login:short] in order to get the preferred token code? Or is there a planned JS trick to automatically paste the complete token code to the textfield from the active row?
#9
That's what I was thinking.
If we want to take a brutal shortcut route, we can just ignore any token 'chaining' entirely and only show top-level tokens, using a display style that mirrors token 1.x. ultimately, something like this is necessary to support the chaining...
#10
subscribing
#11
Introducing a new tag for feature freeze: API clean-up.
#12
Yeah the mockup in #7 is heading down the right path. If we take a shortcut and don't provide a way to see chaining it will drastically decrease the number of users who will realize this new ability exists.
#13
Wondering if there is any movement on this? / subscribing.
#14
Task #1: #675492: Allow exchangable ACDBs for autocomplete. Please review!
#15
Why not do it like Facebook's @mention UI? No list below the text field at all -- just start typing and it autosuggests.
#16
subscribe
#17
Moving on up.
#18
#19
@#8 "Or is there a planned JS trick to automatically paste [...] to the textfield [...]?"
@#9 "That's what I was thinking."
two points:
1- downgrade gracefully when JS is disabled (therefore design without entirely relying on JS: autocompletion, onclick events, etc)
2- if a page with 10-15 textfields/textareas provided by the same module wishes to show up only ONE table of tokens (since it might be huge):
2a-- to which textfield/textarea will be the token pasted?
2b-- forced to use one huge table for each tiny textfield?!
another important point:
3- Note that collapsible fieldsets lost their collapsibility within vertical tabs (and BTW lost their titles as well)
I truly believe that the better approach should be find out a logical (human readable) way to display that bunch of data
I also believe that it can be implemented in contrib (kind of
token_uiortoken_helpermodule) AND IF it is ready before D7 release it might even get into core (a couple of theme functions won't hurt anyone IMO, otherwise long live in contrib apply for D8)#20
Currently I have no solution for this
but this was my first shot
the algorithm to build this table was:
1- in this case the consumer module only matters about [comment:*] and [site:*] tokens (the old D6 scopes for 'comment' and 'global')
2- fetch all the tokens
3- pick selected types and bundle them in an array ready for theme('table', ...)
4- for each one see what chains they have and take note of the type and the key of the chain (i.e. for [comment:parent:*] take note that the chain is 'parent' but its type is 'comment')
5- pick those chains and bundle them in another array ready for theme('table', ...)
6- for the current chains at hand repeat 4-5-6 until all chain's keys have been marked as considered
7- output the table of 'Tokens' with token like this [comment:cid], [comment:parent:*] to remark what is a chain an what's not (also prepend to chain descriptions the bold word 'chains')
8- output the table of 'Chains' with chain fragments like this *:parent:cid, *:node:created:*
the result is that chains that appeared first are nearest the top while, lets say for instance, date chains appear bellow node chains (depending on the case they might be even, but it is just an example)
#21
I think the planned jQuery UI 'Tree' element would be good for us here. :)
#22
#735354: User token types should *not* be nested is a big blocker for any kind of token UI or browser so it could use a quick review.
#23
temporary you may use the type name as the group name, e.g "Comment tokens", "User tokens", and would have "Current-user tokens"
that's how I didn't hit that one
<?phpforeach ($token_list as $type => $tokens) {
$rows[] = array(array('data' => drupal_ucfirst($type) .' '. t('tokens'), 'class' => 'region', 'colspan' => 3));
?>
so, it is not so blocker that issue, you may work and enhance the section header later on
#24
Here's a *working* token UI I'm developing for Token D7. Work in progress of course, but feedback is welcome. :)
#25
Here's a *working* token UI I'm developing for Token D7. Work in progress of course, but feedback is welcome. :)
EDIT: Thanks Guru Mediation. :P
#26
Live demo up at http://www.davereid.net/d7/examples/token, will post a token issue patch shortly. It's currently blocked since there isn't any good jQuery tree/table plugin that is also licensed with GPLv2. I contacted the author of the one I liked best to see if he would dual-license MIT/GPLv2.
#27
Really like this, it'd look great with a slide effect similar to the default way we display fieldsets.
#28
I really like how TreeTable looks and functions. As an added bonus, it's actually not that bad when JavaScript isn't available too. Can't click on the text to copy in the token, obviously.
I looked for a similar solution that uses jQuery UI and found jQuery UI Tree, which unfortunately doesn't look as nice. But, it would be nice to have something that is future proof through the upgrade to jQuery 1.4 and jQuery UI 1.8.
..... What does SimpleTest use? We have something similar to this effect there, don't we?
#29
Dave Reid is my hero.
I think there's a lot of polishing that can be done with the UX here, but this kind of browser interface is a huge boost.
#30
Ehh, how is it diffrent from what I purposed in #5? Eitherway, this is not Drupal 7 stuff obviously.
#31
Bojhan: The difference is that Dave made an implementation of it.
#32
Got a response from Ludo, the author of the treeTable jQuery plugin and he's open to dual licensing his plugin with MIT/GPLv2.
#33
By the way, you're free to relicense MIT to GPLv2 yourself, MIT is fully compatible with the GPL and specifically allows you to sublicense work covered by MIT (IANAL).
Great work! The tree table looks very smooth in the demo and perfectly suited.
#34
Didn't know that, but I'd also feel much better just having the authors permission and approval, plus its fun to let someone know that you really like and appreciate their work. :)
#35
@Rob Loach : Well if I could, I would :). Eitherway good work, I do think putting the arrows inside the table will make more sense.
#36
I've made an official patch against the Token module for D7 and it wouldn't be too hard to do the same against core, although I want to know for sure before I put effort into that.
Follow #738372: Token UI browser + jQuery treeTable for all the patchy token UI goodness.