New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create a standard for naming keys of lexicons #14313

Open
Ruslan-Aleev opened this Issue Jan 27, 2019 · 5 comments

Comments

Projects
None yet
2 participants
@Ruslan-Aleev
Copy link
Contributor

Ruslan-Aleev commented Jan 27, 2019

Feature request

Summary

There is confusion in the keys of lexicons, for example, there are duplicate lines with different keys (for example, new_tv | tv_new | add_tv), there is also excessive terminology.

I propose to mark the standard of the name of the keys, and bring the current lexicons to the new standard (many duplicates will be deleted).

For example:

element - the name of the element, for example, template;
element_create - Creating an element (template_create);
element_edit - Editing an element (template_edit);
element_delete - Delete an element (template_delete).

It makes sense to link other elements through the key, if they are connected according to logic, for example in the system settings:

site_page_start, or page_index (instead of site_start);
site_page_error, or page_404 (instead of error_page);
site_page_unavailable, or page_503 (instead of site_unavailable_page).
...
default_hidemenu (instead of hidemenu_default);
default_template.

The key must clearly indicate its "essence" and "location" of the key, and only then the action or characteristic of the key:

mgr_source_icon
mgr_browser_sort_default (but not modx_browser_default_sort)

Using the example "mgr_browser_sort_default" key, we see what needs to be written:

  1. "mgr_" - because this prefix clearly gives an understanding that the key belongs to the Manager, the "modx_" prefix is wider and the "mgr_" prefix is already used in other keys.
  2. "mgr_browser_sort" - here we understand that the key refers to sorting in the browser, instead of "modx_browser_default" - here the key refers to the browser itself, which is confusing.
  3. "mgr_browser_sort_default" - here we understand what sorting state is needed, and in the "modx_browser_default_sort" variant we only now understand that this is sorting in the browser and its state.

There are many discussions, but there is no standard, it is necessary to designate it and always refer to it.
We need a discussion.

Perhaps it is worth making lexicons in a separate project on github and in the process of working with it, define the standard and the final changes (what has changed, what has been removed).
And after finishing work on this translation project, integrate the new version into MODX.

Related issue(s)/PR(s)

#13554
#1188

@JoshuaLuckers

This comment has been minimized.

Copy link
Collaborator

JoshuaLuckers commented Feb 2, 2019

Lexicon keys should be easy to group, sort, filter and describe their purpose.

A lexicon named setting_site_page_error can be open for interpretation because it does not clearly describe its purpose. For example is this key used in a situation where an error occurs if I edit a setting related to setting site page or does it used for something else?

@Ruslan-Aleev

This comment has been minimized.

Copy link
Contributor Author

Ruslan-Aleev commented Feb 2, 2019

About the sorting of the settings was also a thought - #14254
In this case, I gave an example with keys so that they are next to the list, perhaps more intelligently name, for example:

setting_site_index
setting_site_404
@JoshuaLuckers

This comment has been minimized.

Copy link
Collaborator

JoshuaLuckers commented Feb 2, 2019

To describe a key's purpose I think it would be better to name them like this:

  • setting_name_site_index_id
  • setting_description_site_index_id

Without context it's more clear for a translator that values for those keys should describe the name/description for something referring to an "site index identifier" setting.

@Ruslan-Aleev

This comment has been minimized.

Copy link
Contributor Author

Ruslan-Aleev commented Feb 2, 2019

In my opinion, "setting_name" is an unnecessary expression, just "setting" is already enough.
The current option, in my opinion, is better, because visuall connection between the settings is immediately visible:

setting_site_index_id
setting_site_index_id_desc

The problem is not so much in the writing of keys, but in the fact that there are too many variants for keys, for example, the section "Back-end Manager" in the "System Settings":

manager_week_start (more correct mgr_week_start)
mgr_source_icon (mgr_source_icon)
modx_browser_default_sort (mgr_browser_sort_default)
@Ruslan-Aleev

This comment has been minimized.

Copy link
Contributor Author

Ruslan-Aleev commented Feb 13, 2019

Related with - #12493

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment