Provide a description field

Yep, I've done away with generating human-readable labels in rules 2, so with the possibility with custom labels. But I agree with you that all the *general* data_set labels aren't helpful.

I thought about automatically generating better labels for them originally, but had no time for implementing it yet :/ E.g. instead of "Set a data value" the label could turn into "Set node:author" once it is configured - the same way for the data_is conditions and entity conditions/actions.
However, I'd not like to go with that pattern for all actions/conditions, but use it only for the generic ones. I really want to avoid ending with auto-generated sentences in rules 1.x - it's a mess and won't work in all languages anyway.

Also, I think we should add a rule description field somewhere, which allows for a human-readable description of the whole role (what the heck is it doing?).

Do you think both improvements would do it, or still custom labels would be better? I'm not in favour of custom labels as it is much work to input them for every action/condition and it's probably a bit inconsistent to have some custom ones + machine-generated ones?

Then let's do that!

That sounds great! Just to be clear... you're talking about a description field for each rule in addition to one for each element?

We definitely want a description field per rule/config. I'm not sure whether we need one per element too.

I'd be curious to see broader input on that. If not description fields for individual elements, how about an option to see all of the settings for all of the elements from the rule listing on the main rule page? I know the hover option is available for this but it only allows you to see the details of one at a time. With a long list of elements, I think it would be really helpful to see the details of each in the context of the whole.

@Itangalo: I vaguely remember some of the info on this subject from the BoF. Do you have notes on this?

Bumping priority because many people liked this idea.

Marked #1217582: improve component variable UI as a duplicate of this.

We spoke about generating descriptions per element at the BoF, and, afair, it was a very well liked idea. I forgot how we said it would look, so I haven't included it in the mockups at #1495552: [Meta] Improve overview page, but that should go in there next.

Cross referencing #1331556: Debug log: add component name for related "generating human-readable labels."
Marked #1149108: Add a documentation field as a duplicate of this issue.

Aside: Changing to feature request, because it involves new code. Tasks, to me, seem more like fix documentation, but just trying to be consistent.

Marked #1190034: Provide rulesets labels with translation option as a duplicate.

It will be very helpful as I have many rules with "Execute custom PHP code" and I use to be able to change it to a custom label in Rules 1 to make it readable.

Closed as duplicates:

• #1889434: Add description field to rule and components
• #1935556: Add custom description / comment / notes on each rule event / condition / action - to make rules more readable

Relevant information from these issues:

• There is a module for adding comments between actions/conditions: Rules Developer Comment Plugin

In the attached patch I've added a description field to the rules config entity.

I tried to find all the places in the Rules module where the description should be used. I altered the following:

• Database table 'rules_config': added a column called 'description'.
• Class RulesPlugin: added a public property called 'description'.
• Class RulesPlugin, method returnExport(): make sure description can be exported.
• Class RulesEntityController, method import(): make sure description can be imported.
• Class RulesPluginUI, method settingsForm(): added textarea field called 'description'.
• Class RulesPluginUI, method buildContent(): displays description.

This means the following is implemented:

• Descriptions can be entered when adding or editing a rule (or a rule component).
• Descriptions are shown on the rules overview page.
• When exporting a rule, the description is also exported.
• When importing a rule, the description is also imported.

The following is NOT implemented:

• Descriptions for conditions and actions.

From https://drupal.org/node/1181250

This is any completely new functionality added to core. Feature requests may be major in scope, but should not be marked as critical since a completely new feature should not block a release.

Feature requests are never critical.

Reroll of the patch in #15.

+1 for this issue. The current situation is really problematic because complicated rules are missing important documentation.

The failing test looks unrelated to the patch. The tests are failing because for some reason the testbot doesn't checkout the variable module, which is a dependency for the Internationalization module, used by the test "RulesI18nTestCase", so setting this back to "Needs review".

Patch #19 works well. It would be good to have the description displayed in the rules overview table though.

thx and cheers.

Confirming that Patch #19 works well and agree with #23. Is there a way to set the dependency for the Testbot? I have not read something like that yet.

#2650886: Reduce the likeliness of cache rebuilding locks also added rules_update_7215(), so here is a new reroll against dev. The update function is now called rules_update_7216(). (The patch from #19 can still be used for Rules 7.x-2.9.)

There is also a new testbot now, so hopefully this patch doesn't fail on the same error again.

@shortspoken, Anybody
I think the descriptions are displayed on the rules overview table? See screenshot. Or have I missed something on an other place in the UI?

@MegaChriz: You're totally right. The descriptions ARE showing in the overview table. Maybe a cache issue... weird. But great. Please get this commited soon!

Yes I can confirm that, the description appears. Seems to have been a cache issue. #25 RTBC!

Can the Description field be translated in other languages? I can't see any way to do so because the text (ex: You've deleted a content, therefore... etc) doesn't appear in the translation interface of i18 module...

Rules 7.x-2.9, D7
tnx

I tested the patch #26. It works for me, too.

I'd like to move this to RTBC but want to suggest to keep the line breaks in descriptions using the following one-line change to the patch.

         '#caption' => t('Description'),
         '#theme' => 'rules_content_group',
         'description' => array(
-          '#markup' => check_plain($this->element->description),
+          '#markup' => nl2br(check_plain($this->element->description)),
         ),
       );
     }

Since the input field for the description is textarea, people will expect line breaks are kept, I think.

@kinmen, it's too late and maybe your interest is off-topic but I'd like to answer your question. There's no way to translate description as well as the titles, I think.

that's too bad... in a multilingual website how can users understand those messages?

@kinmen
Why do you want the description of a rule to be translatable? They are meant to document what a rule does (because a rule configuration can get quite complex). The description of a rule is not shown to end users, only to users who may administer rules.

I agree with @MegaChriz, other things may be edge cases which would exists for many many Drupal administration pages etc... I think a translation would be too complex and better a separate module if someone needs it.

Maybe I didn't explain it well: I don't mean the description of a rule in the administrative interface but the description of the reason which caused the action, which is visible to the users. For example, if using the userpoint module, you get something like: "You've deleted a content, therefore 2 points have been taken away from you!"

@kinmen: I can't see a relation to this issue. This issue only handles the first thing you mentioned: An administrative description for rules to explain to site admins what the rule does and how.

Ok I didn't exlain well what I meant, I'll open a new issue

@kinmen
This issue is only about the description of a rule in the administrative interface, not about showing messages to users. I think you are talking about the Rules action "Show a message on the site". If the message set in that action appears to be not translatable, an option would be to write your own Rules action in a custom module. There you would have the freedom to make strings translatable with the t() function.

What I need is to translate, under the Action page, the value of the Description "Can contain the reason why the points have been granted." I think it just needs a "t" function in the form

@kinmen, thank you for the image.

As MegaChriz and Anybody told, "description" in this issue is the administrative description only for admin users who manage rules. And your "description" is actually a message which is shown to users as MegaChriz told. And this issue does target not all the "description" but only the former description. So it's better for you to ask your question in another issue (as you already noticed).

FYI, Userpoints - Rules integration is implemented in Userpoints module (see https://www.drupal.org/project/userpoints) and I recommend you to create an issue in Userpoints module issue queue, not Rules. I hope this helps.

@Anybody thank you for your review!

This seems good to me, but the patch does not apply any more. It needs a reroll.

@fago thank you for your comment! This is a reroll of the last patch.

If this feature is committed it should go into D8 as well.

hi i like this feature.

yes after applying the patch it does exactly what i expect..

hi

after more deep test i can confirm that description looks to be working .. however is it possible to have more/deep integration ? which means that inside rules any new row of areas: "any new Event..", "Any new condition", any new action etc (and so on)has their own description field to have a well documented rules steps..?

Thanks

@delacosta456

Description in "any new Event..", "Any new condition", any new action etc

That would be a nice idea for a follow-up, but let's keep the scope of this issue to just the description field for the whole rule. The module Rules Dev Comments might also fulfull this feature request.

@MegaChriz

Ok Many thanks for guidance .. i didn't know that sandbox project before .. That look to be solving my problem :

Description in "any new Event..", "Any new condition", any new action etc

Many thanks

After patching the patch in #42 it worked but after flushing the caches drush cc all I get this:
PDOException: SQLSTATE[42S22]: Column not found: 1054 Unknown column 'base.description' in 'field list': SELECT base.id AS id, base.name AS name, base.label AS label, base.description AS description, base.plugin AS plugin, base.active AS active, base.weight AS weight, base.status AS status, base.dirty AS dirty, base.module AS module, base.owner AS owner, base.access_exposed AS access_exposed, base.data AS data FROM {rules_config} base WHERE (base.status IN (:db_condition_placeholder_0, :db_condition_placeholder_1, :db_condition_placeholder_2)) ; Array ( [:db_condition_placeholder_0] => 3 [:db_condition_placeholder_1] => 2 [:db_condition_placeholder_2] => 6 ) in EntityAPIController->query() (line 187 of /Users/GraphicDesign/Sites/www.sandbox-D7.67.dev/sites/all/modules/entity/includes/entity.controller.inc).

And I am unable to revert. Whatever I do on the site leads to this.
What can I do?

@BassPlaya: Did you run update.php ?

I realize that when I commented on this in #43 over a year ago, I didn't understand what this issue was about. I thought the issue summary described the feature request here, but it doesn't. In fact, this issue seems to be entirely about adding a description field to reaction rules that will show up in the reaction rule overview at /admin/config/workflow/rules. I don't know why no-one ever re-wrote the issue summary to reflect this.

Drupal 8 Rules already has this description field, and has had it for many years. So this issue is now really about a backport of that feature. Thus, I removed the "Needs port to D8" tag that I put on this issue.

In D8 this feature is really useful so I'm not opposed to putting it into D7, but I AM worried about breaking some of the existing >200,000 D7 sites that are using Rules by making a schema change this late in the D7 development cycle. It would have been pretty simple to get this committed 6 or 7 years ago, but at this point I'm reluctant to do that because I will be the one who has to deal with the fallout if the patch breaks things and I don't have time to work on this myself because I am focused on the Drupal 8 (&9!) versions of Rules.

Moving to "Needs work" because we need a clear issue summary describing exactly what this patch is meant to do. I would also really like some test cases for this to help prevent disruption to established sites.

Regardless, the patch is here and available for anyone who wants to use it, but I don't think there are enough benefits at this point to risk the schema change.

I've added the "Needs issue summary update" tag.

@TR: I wasn't able to do anything, not even a update.php However, I fiddled around and added a table named "description" in the table named "rules_config" because clearly that one was missing. And that got me my site back. Phew!
So, to me, that patch in #42 worked but after clearing the caches broke my site.
I'll try to redo it again and see if it was a one-off or if it's always like that. But now that's not my priority.
I understand why you would not want to look into this at this moment and I appreciate that.
It's a minor thing to me at this moment. Thank you for the reply.

@MegaChriz yes, I've installed Rules Dev Comments and that seems to work partly.. I'll discuss that over there. Thanks

I wasn't able to do anything, not even a update.php

I think update.php should be run first, before drush cc all, because after the cache clear the next page request will run code without having fixed the DB schema ... But even with that order this may be causing a problem if you have active Rules that are trying to fire on Drupal init or something like that - executing a Rule before the schema update will also cause problems. So the patch MAY need to disable Rules execution until the update.php is performed, or something along those lines.

The big problem I see is that no one ever goes through the update process twice - they just do it once; if it works, great, if it fails, they struggle to fix it and then move on. No one is going to help develop a new patch to fix the update process, then revert their site and test to see if the new update patch fixes the update process. That means if I commit the above patch and is DOES cause problems for some fraction of sites, there won't be a good way to develop a new patch which fixes those update problems. And history shows that if there is an update problem, there will be repeated bug reports here in the issue queue for literally years after it has been solved ... this is true even for seemingly benign changes, and it will only be worse for a schema change. If there were support from the community then perhaps I would think differently, but nobody is helping out in the issue queue so it would be all up to me. I can't support any more of that for the D7 version.

hi
i have been using this nice patch for a moment . Now i just want to suggest a little css tweak

** Make the description field have it's own class ... this can help coloring the background and text from css.

Actually trying colors background by copying the selector structure may be coloring the next field (tags) if description is not present.

For the moment below is my css workround

table.rules-overview-table .description div:nth-child(2){
  background-color: oldlace;
}
table.rules-overview-table .description div:last-child{
  background-color: #d1f1a9 !important;
}

The above CSS helps having the screenshot in attached file

Thanks

Attched files: result of the above #54 comment