Improve Text Format Admin Description

+      $output = '<p>' . t("Text formats control which Html tags are allowed. You can add a new one by clicking on 'Add text format' above. Define which user roles can use which text format; the default format is available to all users. The formats are presented in the order you arrange them below.") . '</p>';
+      $output .= '<p>' . t('Take care not to allow too many tags to users, since this may cause a security threat. Be especially careful when allowing PHP code.') . '</p>';

We always use 'HTML', not "Html".
"You can add a new one by..." => "Add a new one by..."
"Define which user roles can use which text format; the default format is available to all users." ? That first clause feels like a sentence fragment, at the least, you have to read it several times to parse.

I'm not sure the security warning is useful here and will be difficult to do in a way that is applicable to all situations. In particular, it is not allowing too many tags that may be dangerous; it is more a danger caused by the specific tags that are allowed. Quantity of tags is not all that applicable. And, that last sentence regarding PHP code may not be applicable to a site that has not enabled that module.

All that said, though, there certainly is room for improvement.

What about something like:

Use the list below to review the text formats available to each user role, to select a default text format, and to control the order formats are listed in the Text format fieldset, The text format selected as default is available to all users and is applied to new posts unless the author chooses another available format. All text formats are available to users in roles with the "administer filters" permission.

Looking at the page without making any changes is "reviewing" the changes. That's a very necessary thing to do considering this page has security implications (you'd review this page to determine what roles have access to what formats, for instance).

This is an important page, and while it may be true that people don't understand text formats, not mentioning the phrase "text format" does not explain what they are, and actually makes it harder to find out. You don't know what to Google, for instance.

In my opinion, trying to "dumb down" a concept is the wrong way to go. That's kinda' what we saw with moving "Taxonomy" to "Category".

But, that said, yeah, it's very hard to really nail the audience we're aiming at here.

FYI: the location for this is now

/admin/config/content/formats

We attempted to test this, but only scratched the surface. We found this text, in the larger context, is part of a work-flow that needs revision/changes.

- User is unclear what "text format" means in the title.

- On configuration page, there is a loss of the prior context

- "More information about text formats' /filter/tips is not styled the same, and is completely out of the context of 'Text Format' area.

- The link to more information should be on the start page, in addition to configuration page

- The listing of text formats "name" column- the word "name" confusing

Many of the problems with the initial text are also part of a wider issue with the work-flow of this task.

Rebecca and I initially thought we could 'fire through' a few of these long-neglected ui-text issues. But we realised it was a bit more than we could handle in the time we had. I wanted to contribute the notes in case they were of use.

But this was like pulling one string on a larger knot that needs unraveling.

I would like to sit down and try a user test again on this. In fact, I am preparing a proposal for a UX testing in Belfast 26-27 Sept: DrupalCamp Ireland. Talked with Yoroy who is advising me. Should be of use, I hope! We might be able to come up with some simple/effective things to ease some of the problems... (i hope :)

Can 'Text Format' be renamed to 'Text Display' since that is what people will need to understand when setting these?

As for the copy, how about:

"Text formats control which HTML tags can be used in a node once the content is saved. People creating content may need to use additional HTML tags; configure their role to use Full HTML if needed. Anonymous users should be restricted to Filtered HTML or plain text for security reasons.

If you want to create a custom text format, add a new one by clicking on 'Add text format' above. "

Edited: I removed references to PHP since it's not handled on this screen by default (admin needs to enable it first)

Taking this on to try out revising the patch as per comments.

Hi! So - my first post seems to have vanished - trying again.

I've created a new patch to reflect the conversation and lisarex's final suggestion - as well as with a few edits of my own. Please review and see if it meets all of our expectations.

People creating content may need to use additional HTML tags; configure their role to use Full HTML if needed.

We should not advice to switch to full HTML in this case for security reasons. It's best to either modify the set of allowed tags of the "Filtered HTML" filter at config/content/formats/1/configure or create a new filter with an extended set of allowed tags. It should be mentionned that the Full HTML filter, if granted to any role, should only be used for trusted users.

Anonymous users should be restricted to Filtered HTML or plain text for security reasons.

agreed.

+++ modules/filter/filter.module	2009-10-21 17:32:31 +0000
@@ -18,8 +18,8 @@
+      $output = '<p>' . t('Text formats control which HTML tags can be used in a node to enter content. Administrators or people creating content may need to use additional HTML tags and configure their role to use Full HTML as needed.  Anonymous users should be restricted to Filtered HTML or plain text for security reasons.  Access to the defined text formats can be assigned using the <a href="@url">permissions page</a>.', array('%fallback' => filter_fallback_format_title(), '@url' => url('admin/config/people/permissions', array('fragment' => 'module-filter')))) . '</p>';

Text formats do not only apply to nodes, but to any fieldable entity type in D7 (users, comments, terms...) and possibly more (in contrib), so the first sentence should be made more generic.

I agree that the current text on this page is a disaster and that it is very important to make it better :) I think the most recent rewrite definitely does that. Here are some comments, though:

1. "Anonymous users should be restricted to Filtered HTML or plain text for security reasons."
   

   I'd suggest something like "untrusted users" here. On most sites, anonymous users aren't the only ones who should be restricted (and theoretically, it's even possible to have a site where anonymous users are trusted, although that's probably the 0.01% use case).

2. Overall, I'm not sure we want so much detail about security specifics on this page. A general comment about security would definitely be good, but like a few people said above, this isn't the right page to go into details - you can't actually do anything dangerous from this page itself anyway. (In Drupal 6 you could via the horrendous "default" radio button, but in Drupal 7 that is now gone.)

   If you want to give people proper detailed warnings about security, the issue to look at is #275811: Warn about potentially insecure filter configurations. It is really, really, really, really important to get that into Drupal 7 - that allows us to (dynamically) detect exactly which text formats on the site are configured insecurely, and to provided specific information about what makes it insecure (e.g., "The HTML filter is configured to allow the following unsafe tags: <script>, <object>, etc").

   If you care about security warnings, please review that patch - time is short :) There is also a corresponding design issue at #618902: Design and implement a user interface for warning about insecure text formats that needs lots of help from UX folks to figure out exactly how best to present the information from that to the site administrator.

3. I think we need to retain at least some explanation of reordering text formats and why you would want to do that, since that's the main thing you can actually do while on this page.

4. "A new custom text format can be created by clicking the link below."
   

   For accessibility reasons, let's try to avoid the word "clicking" (even though it was there already)... and we don't need to say this sentence at all anymore anyway, since due to recent D7 changes, the "Add text format" link now (happily) appears right underneath the help text.

***

Putting it all together, here's a stab at what I'd suggest:

Text formats control the HTML tags, code, or other formatting that can be used when entering text. Administrators may choose from a variety of text formats that allow them to create rich content, while untrusted users should be restricted to more limited formats that do not present a security risk.

From this page, you can review and configure the text formats on your site (access to the defined text formats can also be assigned using the <a href="@url">permissions page</a>). When creating content, the available text formats will be presented in the order you arrange them below.

@ David Rothstein

Well done! That looks like a really good, clear and concise description. You've incorporated all considerations.

Thanks also for the heads-up about the two patches which need reviewing, (your point #2)

Dcor, you want to re-roll this?

I'll be glad to review it.

Great, thanks!

As long as I'm here now, I'll just roll it into a patch...

Applied the patch and it looks good to me!

@eigentor - I see you're trying to improve David's patch #22 according to the guidelines for UI best practice.

However, I am wary it might be too brief in this case.

This is the one location where a novice site admin can introduce serious security threats to their site, and the latest patch does not explain how this page works. (and it's not obvious, in my experience).

David's 4 points in #20 are very clear. I think we can hit on his 4 points, more concisely, without introducing further confusion.

The text on this page should refer mainly to the functionality of this page alone; should not try to explain text formats & filters in general; and should alert the user to the security threat clearly.

His point 3) is that we should explain the ordering of the formats on this page(!) I, um, for one had trouble with that.

And generally:
We do not need to tell the user to add formats, right below there is a link to add.

Also my other issues with patch #26...

They don't get referred to anywhere else as configuration sets. We should not introduce new language here. They are text formats (filter sets would have been nice, but it didn't happen). We do not need to define it in this case, as the user is learning this notion through the interface.

When someone clicks 'configure' the list of options is referred to as filters. I think it's important not to lose this language. Look to the existing, very clear, documentation on this. http://drupal.org/node/213156

The conceptual model of 'filter' fits here, as any text, code or string can be input and uploaded to the site. Yet the filter controls what is displayed or executed either on the server or client side.

So I'm giving this a roll...

Cute. I forgot how to make a patch.

I need tea.

Yeah, I agree with making it more concise. However:

• Like @heather said, we do indeed still want to explain what you can do on the page itself :) Sounds like we now have two suggestions:
  1. "When creating content, the available text formats will be presented in the order you arrange them below."
  2. "Arrange the order of text formats presented to your users, in descending order of preference for use. The default format for each user role is the first one on this list in which their role appears."

  The first one is shorter, and I still like it better... does it explain things well enough? I am not sure there is an advantage of using the term "default format" here anymore - IMO that is something of a relic of Drupal 6.

• The goal of adding a (meaningful) security warning might conflict with the goal of brevity. The only reason to add a security warning on this particular page is because they can review which roles have which formats - but with #618902: Design and implement a user interface for warning about insecure text formats we could explore the possibility of adding some kind of warning inline (in the table), only for the particular formats that are actually security risks - and therefore maybe not mentioning it in the help text at all. Not sure if there is a good way to do that which doesn't look repetitive, though.
• If we don't want to define "text formats" on this page, we shouldn't mention that they are made up of filters either - that is kind of a definition in disguise :) Also, you can do a fair amount of configuration of text formats in Drupal 7 without even knowing or caring that they are made up of filters.

  Given that this page is the main overview page for all text format administration (and that the overall "more help" page for the filter.module is a wall of text), I wonder if a one sentence definition is maybe still a good idea? If so, I'd prefer to aim for 100% here, not 80% :) Besides, stuff like Markdown and BBCode is (I'm guessing) much more common than 20% - typing HTML tags into a textarea is pretty old-school, and one of the main purposes of the text format system is to allow people to avoid that. We can probably remove the word "code", though... since if you can be trusted to type PHP code, you hopefully don't need the help text here :)

So, trying to put it all together again, I'd suggest maybe something like this:

Text formats control the HTML tags and other formatting that can be used when entering text. They are central to a site's security, so untrusted users should be restricted to limited formats.

When creating content, the available text formats will be presented in the order you arrange them below.

If we're bold, delete the second sentence:

Text formats control the HTML tags and other formatting that can be used when entering text. When creating content, the available text formats will be presented in the order you arrange them below.

If we're really bold, delete the whole first paragraph :)

When creating content, the available text formats will be presented in the order you arrange them below.

+++ modules/filter/filter.module	21 Nov 2009 18:17:31 -0000
@@ -18,8 +18,8 @@ function filter_help($path, $arg) {
+      $output = '<p>' . t("Control which HTML Tags and other formatting can be used for text input. Don't allow too much formatting for untrusted users. This can be a serious security risk.") . '</p>';

Tags in HTML Tags should be all lower case, i.e. HTML tags.

OK, like all the changes :) .. Fixed this minor issue pointed out by scor. Should be RTBC.

I changed "behaviour" to "behavior" (not sure if there is an official style guide for American vs British English, but "behavior" is what is used elsewhere in Drupal).

Otherwise, looks good. I think the "Don't allow too much formatting" phrasing is a little strange, but don't have any great ideas for anything better at the moment.... Maybe we can improve it later, depending on how other issues go.

A big improvement overall.

Regarding the last point: one try at rewording it. We want to try and not use "don'ts". Does it help to give examples of risky tags or is that a can of worms we don't want to open now?

"Allowing too many HTML tags (like x? y? or z?) for untrusted users can be a serious security risk."

Committed to CVS HEAD. Thanks!

Re #35, mentioning individual tags is indeed a can of worms... but even without that part, your suggestion sounds like an improvement to me. We can also say "tags" rather than "HTML tags" because it's more general and also because "HTML tags" was already used in the sentence right before it.

Also at http://drupal.org/node/558666#comment-2353956 Bojhan suggested killing the sentence about configuring text formats, which sounds reasonable (the "configure" links in the table ought to be self-explanatory).

Made those changes in the attached patch.

+++ modules/filter/filter.module	10 Dec 2009 05:31:31 -0000
@@ -26,8 +26,8 @@ function filter_help($path, $arg) {
+      $output = '<p>' . t('Control which HTML tags and other formatting can be used for text input. Allowing too many tags for untrusted users can be a serious security risk.') . '</p>';

This will be very hard to translate.

Additionally, I seriously request to go at least partially back to #20. The second sentence in there was very important, and since this is the first page that site admins see + read about text formats, we want to precisely state that this entire thingy is about security. Every filter is about security, regardless of whether it's a security filter, markup filter, or a macro filter.

I have very strong feelings about this.

David put it this way in #20:

Text formats control the HTML tags, code, or other formatting that can be used when entering text. Administrators may choose from a variety of text formats that allow them to create rich content, while untrusted users should be restricted to more limited formats that do not present a security risk.

1) The first sentence was much more clear than the half-baked sort of sentence that's in there now.

2) The second sentence is required. But we want to flip the phrases to prioritize the "untrusted".

Text formats control the HTML tags, code, or other formatting that can be used when entering text.  Untrusted users should be restricted to more limited text formats that do not present a security risk, while administrators may choose from a variety of text formats that allow them to create rich content.

We can revise this, perhaps especially 1), but 2) I must insist on.

http://twitter.com/tha_sun/status/7538684384

I don't think that tweet makes for a better description. Nor will any amount of help text ever fix a broken ui.

re: sentence 1.
There's no substantial difference between the two sentences there. Same information is given in the current, shorter sentence. There is no reason to add more words without giving extra information.

re: sentence 2.
- Too long.
- Don't use 'should'.
- 'more limited' is weird.
- 'may choose': oh really? how nice of you Drupal… Also, not necessary to say admins can do this when you already pointed out that untrusted users should not.

Restrict input by untrusted users to text formats that do not present a security risk.

That captures what you're trying to communicate I think.

This issue already started completely wrongly. What's wrong here, and, what's the help text to prevent it?

And what's wrong here?

And here?

(Hint: This only looks safe.)

Sun, making things a riddle is not constructive. If you know better, tell us, show us, but don't make people guess. This way no-one can help.

So we are writing help texts for stuff we do not understand?

sun: Your sarcasm is not needed. Please just state in plain English what is wrong rather than making people guess. It's not that they don't understand the issues, it's that they aren't aware of the particular issue you are trying to bring up. There's a lot of stuff in those screen shots...

While I do not agree with @sun's railroad approach at the end of this issue (because I suppose I am also not able to decipher his screen shot riddle), I like the concept of reversing the importance of the second sentence (in #38). It's a case of UI glaze where if I'm not prompted in some way or feel like it's important somehow implicitly to continue reading, I won't.

The word "Untrusted" as the first makes me feel as a site administrator that I might care about what that has to say. However, I think @yoroy in #40 did the best job by leading with "Restrict" - Now, I know I need to read that.

Just two linguist pennies. Otherwise I am a big +1 on this rework of the copy. My favorite combination so far is some from @David_Rothstein and some from @yoroy.

Text formats control the HTML tags, code, or other formatting that can be used when entering text.  Restrict input by untrusted users to text formats that do not present a security risk.

I guess the only real concern with that would be leaving it totally up to the end user what formats do present a risk. To an average site builder, they may not be familiar with XSS and the fact that the <script> tag can present that risk.

(Also, not sure if this is really "critical", so I'm changing it back to normal)

This week alone, I saw 3 Drupal sites with improperly configured text formats. Anonymous visitors were able to post too much, sometimes even without any restrictions at all.

While the D6 help text wasn't very concise, the new help text does not make the site admin aware of how horribly important this configuration is.

Repeat: This configuration is the most important configuration on your Drupal site in terms of security.

Let's solve the riddle.

Here, "Full HTML" is the default text format for all users that are able to access it. Normally, this means that users can post arbitrary content, including XSS attacks. Look closely. Who can access Full HTML?

By default, the "Plain text" format is accessible as fallback text format for everyone and anyone. This configuration in itself isn't dangerous, it just means that you'll always have to switch to a more permissive when trying to post a new node with regular HTML styling. However, let's think users. This format only looks like "Plain text". It can be configured like any other, and you can disable all filters in this text format. Therefore, this configuration makes sense if you want to shortcut the entire filter system by disabling all filters in the fallback format, and therefore allow everyone to post arbitrary content, including XSS attacks. Users don't care about security, they care about whether something works or not. This works. Only.

Similar real-life scenario here: "Filtered HTML" is only so long "Filtered" as long as you do not disable its filters or make them more permissive. This does not mean that the title of this text format is wrong. It simply means that this system is highly configurable, so that you can customize it to your particular needs.

Important facts:

- Users don't understand text formats.
- Users don't understand filters.
- Users don't care about security, as long as something works.
- Users are not aware that this configuration is responsible for allowing malicious, anonymous users to entirely wreck your site, which may happen through XSS, CSRF, or plain PHP.
- Users are not aware that malicious users can take over their user account on their own sites, if this is improperly configured.

Apologies if this needlessly repeats a suggestion -- I skimmed this and related issues but didn't read them that closely. Since Drupal's default settings are secure, how about adding something along the lines of, "Don't change these settings unless you know what you're doing." I know every time I see that in a piece of software it usually scares me from changing anything -- or at least makes me think twice.

#46 summarizes very well the problem with setting up the texts formats (thanks sun for highlighting it): the name of each text format (e.g. plain text) gives a false sense of security, which has to be corrected. I see 2 options:

- make it clear in the text format name that that its settings have been overridden and might not reflect "Plain text" anymore, either using a strikethrough the name, or add a red flag next to it.
- do not allow users to modify the default secure settings of the "plain text" and "filtered HTML" text formats, forcing users to create their own new text formats and making them responsible for potentially setting up a insecure text format (further security education measure should be implemented on a per filter basis).

Not allowing users to modify the default filtered HTML would be annoying. It never has exactly the tags you want available on a particular site (i.e. there are additional tags that are not security risks, but that are not included in the default). So please don't chose that option.

I don't think a strikethrough or a flag is a clear user interface. Putting the word "modified" next to the name would be clear, and sounds like a good idea to me.

I am also in favor of making a detailed help text for this screen that explains the issues outlined by sun (and thanks for writing out the answer to your riddle). There should also be a detailed help text on the modify the filter and modify who can use your filter screen that explains what would be safe and what wouldn't.

I like "Modified" because it stays in line with another huge part of Drupal that does overrides to its settings. (Views) - Sun, thanks for the explain. I understand the point. They need visual cues for it to be fully discoverable. Makes perfect sense to me.

At this point there's little we can do other than improving help texts to ensure the user is aware of the critical security implications. Furthermore, this issue is about help texts only, no functional changes.

just skimming this, and just wanted to suggest, if something is used to denote whether the filter has been changed, maybe make it consistent with the language used in Features module's interface? it seems pretty intuitive: "overridden", "default", "revert"

ps. just in case, since this hasn't been updated in a bit - http://drupal.org/node/394466 is also about the formats

#275811: Warn about potentially insecure filter configurations is the critical issue for warnings, no amount of help text is going to stop people giving people wrong permissions. Let's leave this as help text cleanup and keep the self-pwnage fixing to the other issue.

heh. sounds good to me, thanks catch.

I disagree. #275811: Warn about potentially insecure filter configurations deals with warnings for user permissions and does not touch the text format configuration at all (and additionally I'm not convinced by that patch yet). The actual issue for adding any warnings or notices to the text format configuration pages is #618902: Design and implement a user interface for warning about insecure text formats, but there's not even a sense of a patch or way forward.

"Don't change these unless you know what you're doing." Something to this effect seems like the way to go. It would need a link to a page that teachers you to know what you are doing…
It's important to warn about potential security holes, but equally important to not make the impression the defaults are already unsafe.

Enough reviewing.

#45 has the review and summary of best option so far:

Text formats control the HTML tags, code, or other formatting that can be used when entering text.  Restrict input by untrusted users to text formats that do not present a security risk.

- Is there a help or handbook page we can link to?
- Not sure this needs the 'don't change unless" bit still, but if we have a help page to link to we could make it say

Text formats control the HTML tags, code, or other formatting that can be used when entering text.  Restrict input by untrusted users to text formats that do not present a security risk. Read and understand [link]this help page[/link] before configuring your own.

Can we maybe just link to the main Filter module help page (i.e., admin/help/filter)? It seems like that would be the place to have any links to outside resources (if there are any).

That's an excellent idea. And the main filter help page would be a good place to describe the pitfalls in a bit more detail. It does already have a link to the Handbook page on the filter module (which may currently just be a stub, but the plan is to flesh out all of the core module help pages before release).

Here's a suggested patch. Screen shots show the help text shown on the Text Formats page, as well as the module-level help page.

Before:

After:

proposed new text:

Review:
• I think this almost there now and definately an improvement over the existing text.
• Using strong tags is ok here.
• "…be a security risk" was changed to "present a security risk". Is the latter more correct? It's a bit harder to translate.
• Any specific reason to use the "…; learn more…" instead of two seperate short sentences?
• "below" could be removed

New proposal:

I could patch it but then I couldn't RTBC :)

Oh well…

I forgot to mention that this patch also adds a bit about this to the actual Filter help page, which looks fine to me as well.

This is a big improvement, RTBC.

Thanks!

+++ modules/filter/filter.module	28 Jan 2010 13:21:33 -0000
@@ -17,6 +17,8 @@
+      $output .= '<dd>' . t('Configure text formats on the <a href="@formats">Text formats page</a>. <strong>Improper configuration of text formats can present a security risk</strong>. To ensure security, untrusted users should always be restricted to using text formats that restrict them either to entering plain text or using a safe set of HTML tags, since certain HTML tags can allow embedding malicious links or scripts in text. Fully trusted users can be granted permission to use less restrictive text formats, in order to create rich content.', array('@formats' => url('admin/config/content/formats'))) . '</dd>';

To ensure security, untrusted users should only have access to text formats that restrict them to either plain text or a safe set of HTML tags, since certain HTML tags can allow embedding malicious links or scripts in text. More trusted registered users may be granted [permission] to use less restrictive text formats in order to create rich content.

+++ modules/filter/filter.module	28 Jan 2010 13:21:33 -0000
@@ -27,8 +29,8 @@
+      $output = '<p>' . t('Text formats determine the HTML tags, code, and other formatting that can be used when entering text. <strong>Improper text format configuration can be a security risk</strong>. Learn more on the <a href="@filterhelp">Filter module help page</a>.', array('@filterhelp' => url('admin/help/filter'))) . '</p>';

s/determine the/define/

Powered by Dreditor.

+++ modules/filter/filter.module	28 Jan 2010 13:21:33 -0000
@@ -27,8 +29,8 @@
+      $output = '<p>' . t('Text formats determine the HTML tags, code, and other formatting that can be used when entering text. <strong>Improper text format configuration can be a security risk</strong>. Learn more on the <a href="@filterhelp">Filter module help page</a>.', array('@filterhelp' => url('admin/help/filter'))) . '</p>';

In order to be consistent with first hunk: "Improper text format configuration can be a security risk" should read "Improper text format configuration can present a security risk"

Let's just say "Improper text format configuration is a security risk".

Here's a rework of the patch from #63, addressing #66, #67, #68.

Attached are screen shots of the filter module help and the filters screen, with this patch applied.

Thank you jhodgon. +1.

Although this changes strings, I think it's worth doing. This is the most sure way to totally screw up your Drupal site, and we catch big-name sites and Drupal shops with problems like this all the time.

Committed to HEAD.

Seems like we need to continue in #717176: Clarify relationship between order and selected status of text formats