Page 1 of 2

General forum information/Events requests

Posted: Thu Nov 07, 2013 9:16 pm
by DavidIQ
3.1 is bringing about some radical changes to the entire phpBB MODification scene. What was known before as a Modification will soon be a thing of the past. 3.1 introduces extensions and with that the end to code modifications.

While this sounds like a dream it is something that can become a reality over a hopefully short period of time but that will only be possible if you, the MOD/Extensions writer community, request that events be added to the phpBB core. Here's how to do it:
How to request an event wrote:Events are hook locations/ledges. For more information about them and how to add them please take a look at the wiki events and listeners category.

Please note all explanations in this post should include:
  • At least 1 use-case
  • Preferably an extension/MOD that exists that might make use of it (optional)
  • What it could be used for
  • Why should it have those parameters and that location
How to request a template event:
Create a ticket with the title [Template] Identifier

Then it should include the following information:

Code: Select all

Identifier:
Prosilver Location (if applicable):
Subsilver Location (if applicable):
Explanation:
The identifier should be formatted as prosilver location file followed by a descriptor. For e.g.
overall_footer_copyright
If it is only in subsilver then the subsilver location should be used (as hooks don't have to be in both styles).

How to request an acp template event:
Create a ticket with the title [ACP Template] Identifier

Then it should include the following information:

Code: Select all

Identifier:
Location:
Explanation:
How to request a core event:
Create a ticket with the title [PHP] Identifier

Then it should include the following information:

Code: Select all

Identifer:
Location:
Parameters:
Explanation:
The identifier should be formatted as a general descriptor (preferably the function if its in one; possibly followed by a descriptor if there are more than one event in the function). All core events are prefixed by core. For e.g.
core.viewtopic_postrow for postrow in viewtopic.php

Review Process:
After being posted it will be reviewed to check it would work ok and then someone will either implement it for you or you can submit a patch for it.

The patch will then be reviewed by someone who cannot be the original suggester or implementer. It will then be merged by a developer.

Adding events:
You can add the events yourself (via submitting a PR) or by creating a ticket and then someone might come along and do it for you.
Once a PR is submitted it will be reviewed and merged by the development team / events reviewers
You may use this forum to discuss anything related to 3.1.x extensions and to voice your opinions on what we, the phpBB Extensions Team need to provide you in order to:
  1. Help you convert your 3.0.x MODs to Extensions
  2. Understand how events work
  3. Documentation needed
  4. Tools that will help you in the long run
Thank you all for your hard work and contributions throughout the years to the phpBB MOD community.

Re: General forum information/Events requests

Posted: Fri Nov 08, 2013 12:31 am
by Galandas
A guide or guide video on how to install an extension would help a lot other nationality languages.

Re: General forum information/Events requests

Posted: Fri Nov 08, 2013 1:26 pm
by tbackoff
Extensions are basically "drop in, install, and go". The entire extension gets placed in \ext\{vendor}\{extension}\, where {vendor} is the extension author(s) and {extension} is the name of the extension.
DavidIQ wrote:3.1 introduces extensions and with that the end to code modifications
I've said this once, but I'll say it again: I believe code modifications will never go away until phpBB allows extensions to remove\alter existing code. Events that allow you to add are a great step, and I applaud the effort, but how does phpBB plan to handle extensions that need the following comparable functionality that MODs currently offer?
OPEN: somefile.php

FIND AND DELETE:

Code: Select all

code here
or
OPEN: somefile.php

FIND:

Code: Select all

code here
REPLACE WITH:

Code: Select all

modified code here

Re: General forum information/Events requests

Posted: Fri Nov 08, 2013 1:50 pm
by imkingdavid
if() statements, for the most part. If you have code that absolutely needs to be ignored when a certain extension is running, request that an event be placed above that code, and an if() statement to wrap it. Then, you can set the boolean variable controlling the if() logic to a false value, and run your own code.

Maybe not the most elegant, but that's the best I can come up with at the moment.

Re: General forum information/Events requests

Posted: Fri Nov 08, 2013 10:27 pm
by Danielx64
imkingdavid wrote:if() statements, for the most part. If you have code that absolutely needs to be ignored when a certain extension is running, request that an event be placed above that code, and an if() statement to wrap it. Then, you can set the boolean variable controlling the if() logic to a false value, and run your own code.

Maybe not the most elegant, but that's the best I can come up with at the moment.
What about something like the need for

Code: Select all

if (!function_exists('make_clickable'))
{

//Code here

}

The phpbb bridge that I'm working on will require some of those.

Re: General forum information/Events requests

Posted: Sat Nov 09, 2013 2:07 am
by VSE
imkingdavid wrote:if() statements, for the most part. If you have code that absolutely needs to be ignored when a certain extension is running, request that an event be placed above that code, and an if() statement to wrap it. Then, you can set the boolean variable controlling the if() logic to a false value, and run your own code.

Maybe not the most elegant, but that's the best I can come up with at the moment.
To elaborate on this, for template files, I see something like this working.

Let's say the template core file has this, which we want to replace with new code:

Code: Select all

<div>Hello World</div>
1. Request new template events be made, one above and one below, so we get this:

Code: Select all

<!-- EVENT my_example_before -->

<div>Hello World</div>

<!-- EVENT my_example_after -->
2. your my_example_before.html you would do something like:

Code: Select all

<!-- IF S_MY_EXAMPLE_ENABLED -->
    <div>Goodbye cruel world!</div>
<!-- ELSE -->
3. your my_example_after.html you would have this:

Code: Select all

<!-- ENDIF -->
This way, if your extension is active/enabled, it will use your template code, otherwise, it will use the core code.

The overall result effectively looks like this:

Code: Select all

<!-- IF S_MY_EXAMPLE_ENABLED -->
    <div>Goodbye cruel world!</div>
<!-- ELSE -->

<div>Hello World</div>

<!-- ENDIF -->
The only negative is a potential for problems with other Extensions inserting code at these same locations.

Re: General forum information/Events requests

Posted: Sat Nov 09, 2013 3:41 am
by RMcGirr83
What if an Extension improves a certain feature of phpBB, eg the "previous" and "next" in subsilver2 which is not contingent on anything but just simply "displays" whether there is a previous or next topic does not come into play?

Granted this could be handled with jQuery call to either hide or display based on ajax return.

Re: General forum information/Events requests

Posted: Sat Nov 09, 2013 3:45 am
by imkingdavid
VSE wrote:
imkingdavid wrote:if() statements, for the most part. If you have code that absolutely needs to be ignored when a certain extension is running, request that an event be placed above that code, and an if() statement to wrap it. Then, you can set the boolean variable controlling the if() logic to a false value, and run your own code.

Maybe not the most elegant, but that's the best I can come up with at the moment.
To elaborate on this, for template files, I see something like this working.

Let's say the template core file has this, which we want to replace with new code:

Code: Select all

<div>Hello World</div>
1. Request new template events be made, one above and one below, so we get this:

Code: Select all

<!-- EVENT my_example_before -->

<div>Hello World</div>

<!-- EVENT my_example_after -->
2. your my_example_before.html you would do something like:

Code: Select all

<!-- IF S_MY_EXAMPLE_ENABLED -->
    <div>Goodbye cruel world!</div>
<!-- ELSE -->
3. your my_example_after.html you would have this:

Code: Select all

<!-- ENDIF -->
This way, if your extension is active/enabled, it will use your template code, otherwise, it will use the core code.

The overall result effectively looks like this:

Code: Select all

<!-- IF S_MY_EXAMPLE_ENABLED -->
    <div>Goodbye cruel world!</div>
<!-- ELSE -->

<div>Hello World</div>

<!-- ENDIF -->
The only negative is a potential for problems with other Extensions inserting code at these same locations.
That should work for template events. (turns out that doesn't work for template events) For PHP events, the scope changes so the if() statement has to be added in the core directly and then you have to use a boolean value in your event to turn it off and on.

For instance:

Code: Select all

$override = false;
$vars = array('override');
extract($phpbb_dispatcher->trigger_event('core.foo_override', compact($vars)));
if ($override === false) {
    // Original phpBB core code goes here.
}
Now, your event listener method 'my_foo_override()' (below) listens for the 'core.foo_override' event and does this:

Code: Select all

function my_foo_override($event)
{
    $event['override'] = true;
    // Now here I put the code I want to have run instead of the code I am overriding
}
Obviously, in a real scenario, any variables that are available outside of the event scope and are used by the original block would need to be provided to the event, but this is just a theoretical example.

Re: General forum information/Events requests

Posted: Sat Nov 09, 2013 4:26 am
by VSE
I actually just tried my Template events technique. It does NOT work. Apparently TWIG does not like it when template events end with unclosed if/then conditionals.

Code: Select all

<!-- IF S_MY_EXAMPLE_ENABLED -->
    <div>Goodbye cruel world!</div>
<!-- ELSE -->

Results in:

PHP Fatal error:  Uncaught exception 'Twig_Error_Syntax' with message 'Unexpected end of template in "@foobar/event/my_example_before.html"
So, I can't find any way to "replace" core template code now :(

Re: General forum information/Events requests

Posted: Sat Nov 09, 2013 10:43 am
by Danielx64
VSE wrote:I actually just tried my Template events technique. It does NOT work. Apparently TWIG does not like it when template events end with unclosed if/then conditionals.

Code: Select all

<!-- IF S_MY_EXAMPLE_ENABLED -->
    <div>Goodbye cruel world!</div>
<!-- ELSE -->

Results in:

PHP Fatal error:  Uncaught exception 'Twig_Error_Syntax' with message 'Unexpected end of template in "@foobar/event/my_example_before.html"
So, I can't find any way to "replace" core template code now :(
That suck, now I got issues as well as I was going to do the same for a bridge extension.

Re: General forum information/Events requests

Posted: Sat Nov 09, 2013 8:31 pm
by EXreaction
Each template is rendered individually, so that would not work.

One thing you could try is using the BLOCK element (from Twig).

Core:
<!-- BLOCK test -->
foo
<!-- END BLOCK -->

<!-- EVENT test_event -->

Extension:
<!-- BLOCK test -->
bar
<!-- END BLOCK -->

I'm not sure if this is possible to edit through an event or can only be done through template inheritance.

Re: General forum information/Events requests

Posted: Sun Nov 10, 2013 11:05 pm
by VSE
EXreaction wrote:Each template is rendered individually, so that would not work.

One thing you could try is using the BLOCK element (from Twig).

Core:
<!-- BLOCK test -->
foo
<!-- END BLOCK -->

<!-- EVENT test_event -->

Extension:
<!-- BLOCK test -->
bar
<!-- END BLOCK -->

I'm not sure if this is possible to edit through an event or can only be done through template inheritance.
That doesn't work yet... There is no <!-- END BLOCK --> conversion to {% end block %} in the lexer, so it fails for now. But also, it relies on blocks existing in the core (which don't) in addition to template events.

Re: General forum information/Events requests

Posted: Thu Mar 27, 2014 12:29 pm
by PayBas
What happens exactly when multiple extensions call on the same template event?

ext/me/my_mod/styles/all/template/event/overall_footer_after.html
ext/him/his_mod/styles/all/template/event/overall_footer_after.html
ext/her/her_mod/styles/all/template/event/overall_footer_after.html

Re: General forum information/Events requests

Posted: Thu Mar 27, 2014 5:57 pm
by VSE
They all append their template code to it. It is currently done in the order extensions are loaded, which I believe is by vendor name / extension name

There is a ticket set up with plans to come up with some sort of loading strategy that an Admin can define, in case they have extensions causing conflicts with each other and may want to re-arrange the loading order to prevent the issues.

Re: General forum information/Events requests

Posted: Tue May 13, 2014 5:27 pm
by Neuropass
Is this going anywhere? Any progress on the matter?