XF 2.0 Resource Standards & Naming Conventions

[Kirby]

As far as I can see there are no explicit naming conventions for various entities:

Add on data which requires unique IDs or keys (such as template modifications) must be prefixed in a way that can identify the add on or developer.

This isn't quite that detailed and leaves room for interpretation.

Class Extensions
Assuming there is a class extension for XF\Entity\Post, what would be the recommended class name

Should the extension class be named

1. [VendorID\]AddonID\Entity\Post
2. [VendorID\]AddonID\XF\Entity\Post
3. [VendorID\]AddonID\Extend\XF\Entity\Post

Or even another variant?

Code Event Listeners
Should all listeners be in one class [VendorID\]AddonID\Listener with camelCase methods named after the event and hint?

Keyed Entities (Phrases, Templates, etc.)
Should all phrases, templates etc. be prefixed with [vendorid_]addonid_?

Would be nice to get some info on how the community is handling this, maybe even official recommendations by @Chris D

Btw: XenForo Media Gallery does not seem to fully follow these guidelines
Templates like alert_user_xfmg_album_delete and the administrator permission mediaGallery are not prefixed.
Are theere any plans to change this?

 

[Snog]

Using your example, the file that extends an XF Post entity should be in..
\src\addons\Author\AddOnName\XF\Entity\Post.php

The name of the class should be the same as the class it's extending (IE: class Post extends XFCP_Post)

IMHO, Code event listeners are subjective and up to the author where they are an what they are named.

IMHO phrases at the very least should be prefixed with the add-on name (IE: flags_country), however I take it one step farther and in most cases that phrase would be snog_flags_country.

Some templates, such as the one you used as an example (alert_user_xfmg_album_delete) are required to have the alert_user portion first due to automatic processing by XenForo that builds the template name by it's function, in this case alert_user.

 

[Chris D]

That particular point only applies to what you refer to as “Keyed entities”.

There’s no strict rule for the format as long as it identifies the add-on or developer (or both).

There are some special cases, such as alert templates, where the code has a particular format for the naming which may mean they are automatically prefixed by something else, in that example “alert_[content_type]_[action]” is the default format. It can be overridden but as long as the action is prefixed with some sort of identifier (such as “xfmg_” in that example) it is acceptable.

The Admin permission still identifies the add-on so it is also acceptable.

Even so, those standards specifically relate to resources listed in the Resource Manager. Official add ons will be most likely compliant with all of the standards anyway, but where that isn’t the case there are likely specific reasons for it.

 

[Kirby]

Some templates, such as the one you used as an example (alert_user_xfmg_album_delete) are required to have the alert_user portion first due to automatic processing by XenForo that builds the template name by it's function, in this case alert_user.

I know, but that conflicts with the quoted standards rule which states that addon data must be prefixed - hence why I am asking here.

 

[DragonByte Tech]

[...]

Agree 100%.

Using your example, the file that extends an XF Post entity should be in..
\src\addons\Author\AddOnName\XF\Entity\Post.php

If everyone followed this convention, putting their own original services in the "root addon folder" and any extensions under the Extended\Addon\Entity\EntityName.php folder(s), it would be so much easier to look over others code and see the distinction between extensions and original work.

I follow this convention even in DBTech's extensions to our own products for our own purpose, leading to this glorious folder structure:

/src/addons/DBTech/Custom/DBTech/eCommerce/Service/DownloadVersion/Generator.php - try saying that five times fast

IMHO, Code event listeners are subjective and up to the author where they are an what they are named.

Personally, I've grown to love the "single Listener.php file" approach, since I don't tend to have a whole lot of event listeners now that the Class extensions system exists.

But that's just my personal preference of course

IMHO phrases at the very least should be prefixed with the add-on name (IE: flags_country), however I take it one step farther and in most cases that phrase would be snog_flags_country.

It obviously depends on the type of modification, but to be safe it's best to use the vendor prefix as well as the addon prefix in phrases and DB columns.

For instance, it wouldn't be a stretch to imagine that if another eCommerce mod appeared and we both slacked on phrases, the site owner couldn't run them side by side because both products used ecommerce_product as a phrase name


Fillip

 

[DragonByte Tech]

I know, but that conflicts with the quoted standards rule which states that addon data must be prefixed - hence why I am asking here.

No, it doesn't.

public function getTemplateName($action)
{
    return 'public:alert_' . $this->contentType . '_' . $action;
}

xfmg_ is the prefix.

Allow me to dissect the alert template for you: alert_user_xfmg_album_delete

alert - Prefix added by the AbstractHandler, see above.
user - The content type ($this->contentType).
xfmg_album_delete - The action ($action).

Here's one of our mods' templates: alert_dbtech_ecommerce_download_delete

alert - See above
dbtech_ecommerce_download - The content type
delete - The action

Both ourselves and the XFMG follow the standard, we just took slightly different approaches for naming the content type and naming the action.


Fillip

 

[Snog]

Personally, I've grown to love the "single Listener.php file" approach, since I don't tend to have a whole lot of event listeners now that the Class extensions system exists.

But that's just my personal preference of course

Same here. I don't use them a lot, but in most cases, listeners are in a single file.

 

[Snog]

My structures look like this....



Anything NOT in the XF directory is related strictly to the add-on. Anything IN the XF directory is an extension of an XF class.

 

[Snog]

Something I'll comment on in relation to my structure....

You'll notice a "defaultdata" folder that normally wouldn't be there. But a while back Chris mentioned something about anything using the "data" folder should be written to the abstract data path, not directly to the "data" folder. I took that to heart and during install, the contents of the defaultdata folder are copied to the abstract path for "data". This ensures the add-on uses the correct location of the externalDataPath.

 

[Xon]

Using your example, the file that extends an XF Post entity should be in..
\src\addons\Author\AddOnName\XF\Entity\Post.php

This. actually being able to find what the heck is being extended is fairly important. Folders are cheap. Most sane IDE's let you type in a full path + filename in the create file dialog and create the folders for you.

I've got a script called xf-addon-create-extension which creates the relevant entry via CLI and creates a placeholder empty file to extend. I have a xf-addon-build script which calls; upgrade, sync, build with the various debug & verbosity flags to ensure everything is imported and synced before building.

Personally, I've grown to love the "single Listener.php file" approach, since I don't tend to have a whole lot of event listeners now that the Class extensions system exists.

Even in XF1, I just used a single listener with a single method called "load_class" for all the code event listeners which extended another class (event hints are awesome). It just pre-pended the add-on prefix and automatically mapped to the something like; \library\Author\AddOnName\XenForo\DataWriter\DiscussionMessage\Post.php

 

[DragonByte Tech]

Even in XF1, I just used a single listener with a single method called "load_class" for all the code event listeners which extended another class (event hints are awesome). It just pre-pended the add-on prefix and automatically mapped to the something like; \library\Author\AddOnName\XenForo\DataWriter\DiscussionMessage\Post.php

In XF1 (and actually, currently in all older XF2 mods, but it's being changed in the Resource Guidelines Rework), I had an EventListeners folder with 1 class per event (so LoadClass.php and InitDependencies.php etc), but it's a wee bit messy.

Generally speaking, I remember "It's in an event listener" more than I remember "It's in init_dependencies so I should go to this file"


Fillip

 

[Snog]

I've got a script called xf-addon-create-extension which creates the relevant entry via CLI and creates a placeholder empty file to extend.

So you're the one responsible for the seemingly new tradition of empty classes I've run across!

<?php
/**
* Created by PhpStorm.
* User: Zzz
* Date: 25/09/2017
* Time: 16:31
*/

namespace Zzz\AnAddOn\XF\Entity;

class User extends XFCP_USER
{

}

They drive me nuts!

 

[Kirby]

No, it doesn't.

It does, at least in the way I interpret this rule.

The resource standards rule (# 25) I quoted in in the first post says that add data (a template is addon data) which requires unique keys (a template name must be unique within the type scope) must be prefixed in a way that can identify the add on or developer.

Taking alert_dbtech_ecommerce_download_delete as an example, my understanding is that this template doesn't have an add-on related prefix at all while you consider alert_dbtech_ecommerce_ to be the prefix (which would indeed be compliant).

My point is that this interpretation (at least to me) is a bit too vague, as it allows developers to place an add on / author identifier pretty much anywhere:
Imagine xfmg_base_batch_update_confirm was instead named base_batch_update_xfmg_confirm, don't you think it would be a bit more difficult to spot this template as belonging to XFMG when looking a a list of template names?

If this is acceptable, it might be more clear to rephrase rule # 25 as "must contain a key part that can identify the add on or developer".

If this would not be acceptable, IMHO it would be better to change the rule to smth. like

Add on data which requires unique IDs or keys (such as template modifications) must be prefixed in a way that can identify the add on or developer unless the key is usually required to adhere to a certain format in which case it must contain a key part that can identify the add on or developer at the first possible leftmost position

 

[S Thomas]

I think most, if not all, developers can understand that there are certain types of naming schemes which supersede others. There's no need to change the rule.
dbtech_ecommerce_download_delete_alert for example wouldn't even work, hence superseded.
Other examples are option_template, widget_, and so on.

 

[DragonByte Tech]

It does, at least in the way I interpret this rule.

Well I'm sorry, but your interpretation is wrong. The meaning of the rule is that each template needs to contain addon specific naming, so that two mods with similar functionality do not end up using the same template name.

Therefore, if I name my template delete_product_ecommerce_dbtech (the exact reverse of what I'd actually name it), guess what, I'm still not in violation of the guidelines.

While you are technically correct that the word "prefix" means "in front of", I think you would do well to not be obtuse about this. It's fairly obvious that the spirit of the rule is "make sure that all your unique keys have some part of it that is unique to you as a developer and also some part of it that is unique to this modification".

The reason why it uses the word "prefix" is that it does look nicer if it's actually prefixed by vendor then addon ID, but I doubt Chris would report me to the police if I decided to flip my template names around like in my example above.

don't you think it would be a bit more difficult to spot this template as belonging to XFMG when looking a a list of template names?

No, I don't, because I have eyes with which to see, and I use those eyes to see that the template you're referring to has "xfmg" in the name, so I know it belongs to the XenForo Media Gallery.

If this would not be acceptable, IMHO it would be better to change the rule to smth. like

So you're suggesting we take a perfectly clear rule and add sub-clauses, doubling the length of the rule and making it 3 times more confusing?

I'm sorry, but what?

Look, I get wanting to cover all the angles and be as specific as possible, I feel that way too sometimes, but thankfully these resource guidelines were written by people who are better at writing than I am. They wrote something that's clear, easy to understand and leaves no room for confusion.

Let's just leave it as it is, shall we?

dbtech_ecommerce_download_delete_alert for example wouldn't even work, hence superseded.

Technically it could work, I could override getTemplateName in my mod's implementation of the Alert handler (and I did do that in the Credits mod because I was using a sillier alert implementation than I am in v5.1), but it's pretty pointless to do so unless you have an actual need to do so, or you just like the consistency of the template names or something.

Personally I prefer to follow the standards, rather than what looks prettier in a list


Fillip

 

[Chris D]

Therefore, if I name my template delete_product_ecommerce_dbtech (the exact reverse of what I'd actually name it), guess what, I'm still not in violation of the guidelines.

Well...

The only real exception to the rule is where XF might automatically expect a certain naming convention, such as alert, like and news feed templates. Another exception would be phrases that need to belong to a core phrase group. So, unfortunately, that would violate the standards.

We will change the wording to clarify the part about XF expected prefixes being acceptable as long as there is some other identifier in the string.

 

[DragonByte Tech]

So, unfortunately, that would violate the standards.

Personally I'm of the opinion it should be acceptable as long as the important information is there (the identifier(s) that contain dev / addon info) but I'm not going to cause a stink about it since it was only a hyperbolic example anyway


Fillip

 

[Kirby]

Getting back to this again:

While taking @Xon https://xenforo.com/community/resources/alert-improvements-by-xon.6398/ as an example, is it within the rules to use templates names like

• option_template_registrationDefaults_alerts
• account_alerts_extra
• acount_alerts_extra_controls
• account_alerts_summary

Those look pretty generic to me, thoughts @Chris D ?

We will change the wording to clarify the part about XF expected prefixes being acceptable as long as there is some other identifier in the string.

This does not seem to have happened yet?

 

[Chris D]

They do not appear, IMO, to accurately reflect at-a-glance which add-on they belong to so we would encourage some changes to be made in that case.

The addition of a vendor prefix makes a significant difference. While, strictly speaking, the following example doesn't contain a "prefix" simply changing to e.g. account_sv_alerts_extra or similar would probably be sufficient.

Primarily this rule is to avoid naming collisions.

In my view it's certainly possible another add-on could come along and create an account_alerts_extra template but clearly it's much more unlikely someone will come along and create an account_sv_alerts template (or similar).

Clearly sv_alertimprovements is fairly lengthy hence shortening to sv_alerts_ is reasonable.

Prefixes are better but as long as it is a reasonable identifier it should be ok.

 

[Xon]

Alert Improvements is a fairly old add-on with the first XF2 release in 2018-04 (ported nearly as-is from an even older 2015 XF1 add-on), so I'm not surprised it is missing prefixes as I was a lot less rigorous about it.

The just released version should fix this issue for Alert Improvements

If any of my other (XF2) add-ons have this issue, do report it to me so I can release updates. Be aware I've got a large number of add-ons, often fairly complex. So updates may not be that simple or quick.