General forum information/Events requests

[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:

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.

[Galandas]

A guide or guide video on how to install an extension would help a lot other nationality languages.

[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.

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

[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.

[Danielx64]

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.

[MattF]

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.

[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.

[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.

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.

[MattF]

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

[Danielx64]

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.

[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.

[MattF]

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.

[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

[MattF]

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.

[Neuropass]

Is this going anywhere? Any progress on the matter?