Coding guidelines for template event names

These requests for comments/change have lead to an implemented feature that has been successfully merged into the 3.1/Ascraeus branch. Everything listed in this forum will be available in phpBB 3.1.
Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Coding guidelines for template event names

Post by Oleg » Tue Dec 11, 2012 2:03 am

See the current template event PR: https://github.com/phpbb/phpbb3/pull/765

Similarly to coding guidelines we should have guidelines for naming template events. I can think of the following two bullet points currently:
  • Whether events have before/after or prepend/append to indicate relative position
  • What is used for prefixes (currently template file name seems to be popular)

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: Coding guidelines for template event names

Post by imkingdavid » Tue Dec 11, 2012 2:59 pm

Another guideline should be that template events go on their own line when possible. In other words, if it is being inserted before or after a complete line of code, it should be moved to the following line. If it is being inserted within a line of code, that is fine.

As for before/after, I vote for prepend/append.

In regards to prefix, filename, and if necessary, a word to describe where in the filename. So for adding to the front of the navigation links (faq, members, etc.), I would suggest overall_header_navigation_links_append.
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: Coding guidelines for template event names

Post by EXreaction » Tue Dec 11, 2012 5:13 pm

before/after should be used on blocks

prepend/append should be used if inline

Example:

Code: Select all

<!-- EVENT before navlinks -->
<ul class="linklist navlinks">

Code: Select all

<ul class="linklist navlinks">
<!-- EVENT prepend navlinks -->

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: Coding guidelines for template event names

Post by Oleg » Thu Dec 13, 2012 10:03 am

How about this.
  • Event name should be formed as follows
    • File name where the event is located, or a prefix
    • Location of the event
    • Indicator of where the event is relative to the location's container
      • For block level events: begin/end
      • For inline events: prepend/append
  • Events that add to content generated by phpbb should either come at the beginning or end of a container. In other words:
    • Event names should have begin/end or prepend/append in them.
    • There should be no events in the middle of a container. If that is where the event really needs to be, there should be a logical container that can be described in prose even if there is no corresponding tag in the markup.
  • Events that are placeholders for content that phpbb itself has no equivalent of do not need begin/event indication. Names of such events should reflect that they are for content that phpbb does not have.
Common prefixes:
  • acp - anything in adm style, even if the file name does not have acp prefix
Examples:
  • acp_main_notice - event in acp_main.html in adm style, where a notice would go.
  • acp_simple_header_head_end - event in simple_header.html in adm style, located in <head>, after all other content.
  • overall_footer_copyright_prepend - event in overall_footer.html, not style specific, where copyright is, before the copyright
  • overall_header_head_end - same thing for non-acp overall_header; applies to all styles

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: Coding guidelines for template event names

Post by EXreaction » Thu Dec 13, 2012 5:08 pm

Begin/end still sound inline to me, which would be the same as prepend/append.

overall_header_head_append would be the same as overall_header_head_end in your example.

before/after are just outside of the elements they name, overall_header_head_after would be after </head> (although there is not a reason for this particular case to exist).

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: Coding guidelines for template event names

Post by imkingdavid » Thu Dec 13, 2012 8:00 pm

I am fine with the guidelines in Oleg's post.
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: Coding guidelines for template event names

Post by Oleg » Thu Dec 13, 2012 8:10 pm

EXreaction wrote: before/after are just outside of the elements they name, overall_header_head_after would be after </head> (although there is not a reason for this particular case to exist).
This is why before and after are not right. The event is inside the container.

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: Coding guidelines for template event names

Post by EXreaction » Thu Dec 13, 2012 8:48 pm

Then what is the difference between append and end or prepend and begin?

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: Coding guidelines for template event names

Post by imkingdavid » Thu Dec 13, 2012 9:45 pm

append is when you're adding to a list or something. For instance, if you want to append a forum row to the forum block on the index page so that you have another row that looks like a forum but may be an advertisement or something.

end is when you are adding something directly after the list, but not in the list.

And same idea for begin/prepend
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: Coding guidelines for template event names

Post by Oleg » Thu Dec 13, 2012 10:06 pm

I am not sure there needs to be a distinction between inline and block level events. A container is one or the other so technically begin/end will work everywhere.

Post Reply