Insert code pre and post entry data in backend preview?

Discussion corner for Developers of Serendipity.
Post Reply
Brendon K
Regular
Posts: 44
Joined: Thu Feb 23, 2006 10:35 pm
Location: Saratoga Springs, NY, USA
Contact:

Insert code pre and post entry data in backend preview?

Post by Brendon K »

I'm looking to update my dp.SyntaxHighlighter plugin and I'm trying to determine how I can add JavaScript to the header and footer of the frame so that users using the plugin will see what their output would look like on the live portion of the site after publishing it.

I see there's backend_preview, but from what I've seen in the forum, this won't do what I'm looking for? Is there an actual API hook for this? I would suspect there'd be a backend_header, backend_footer, backend_preview_header, and backend_preview_footer hook if there's a frontend version of the two. :(

Also, while I'm asking for pointers, does anyone know how the cachable_events works? I don't really understand its usage (other than the fact that it caches things).

Thanks in advance.

Oh... Garvin, if you read this, is there a SPARTACUS SUBMISSION process? I've read that you follow certain syntax guidelines and have tried to follow them -- are there any other requirements (other than the developers deciding whether a plugin is worthy)?
They say, "Practice makes perfect," yet they also say, "Nobody's perfect." I don't get it.
mgroeninger
Regular
Posts: 546
Joined: Mon Dec 20, 2004 11:57 pm
Contact:

Post by mgroeninger »

I think the list of hooks at http://www.s9y.org/116.html is still in pretty good shape. I haven't played with most of those hooks, so I can't help you much on which ones you need, but entries_header, entries_footer, frontend_header, and frontend_footer might help you out.


As for "cachable_events", my understanding of that is too limited to comment on it. Garvin, it might be worth explaining the entryproperties caching system a little better. (I've generally just handled caching on my own with the Pear Cache_Lite library core includes. I think I have been correct in this, since most of my plugins work in sidebars or full pages. I haven't felt the need to mess with entries all that much... *grin* )
garvinhicking
Core Developer
Posts: 30022
Joined: Tue Sep 16, 2003 9:45 pm
Location: Cologne, Germany
Contact:

Re: Insert code pre and post entry data in backend preview?

Post by garvinhicking »

Hi!

I suppose you are speaking of the constructed iframe preview window?

To save performance (and because it had not been requested yet) on that iframe there are no hooks like 'backend_header' and 'frontend_header', sorry. Sadly we can't easily add that, because what hooks are executed there are subject to the 'preview_iframe.tpl' template file. We could add a hook into that file for the default template, but users without the updated template file won'T get that hook executed.

So, the ideal thing would be to issue the javascript inside the 'backend_preview' hook, and add the <script>...</script> stuff at that point. All browsers support inline javascript quite well, so even though it'S dirty, it should work without a problem?
Also, while I'm asking for pointers, does anyone know how the cachable_events works? I don't really understand its usage (other than the fact that it caches things).
Well, those are rather complicated. But let me try to describe it. :)

I'll use the serendipity_event_nl2br plugin as an example for this, because it's the easiest markup plugin available.

First of all, cachable events tell the plugin API that when a special eventData variable is passed to an event ($eventDat['is_cached']), the event will not be passed on to the plugin's hook_event() method. This saves performance, and makes the plugin indicate that because it has set its caching data, it does not need to be executed again.

Cachable events currently only make sense for plugins that deal with an entry body or extended entry. In all other cases, it's quite useless.

The entryproperties plugin is the core plugin that handles the caching for all markup plugins that support cachable events. That means, the entryproperties plugin holds the core logic that will run an entry through a "filter" pipe, gathers the output and stores the output as a unified cache (inside the serendipity_entryproperties table). When an entry is fetched and a unified cache is found in the table, the entryproperties plugin sets this $eventDAta['is_cached'] variable.

Thanks to that variable, all plugins that have declared the 'frontend_display' hook (which is the hook responsible for markup transformations) will be skipped. They don't need to be called, because the entry body does not differ and the cached result is always up to date (it will be rebuild when an entry is edited).

There are two kinds of plugins that apply markups: One sort of plugins need to apply them all the time and their output MUST NOT be stored in the cache. Those plugins are called 'scrambling' plugins. They need to set a property bag attribute 'scrambles_true_content'. The trackexits-Plugin for example does that, and using that bag attribute it will not apply its markup to the caching output to preserve an untainted cache. Those plugins will also apply their true markup functions to the 'frontend_display_cache' hook (see how the trackexits plugin actually re-routes the 'frontend_display' hook call to the 'frontend_display_cache' in case the plugin API passes entry-data to it where the 'no_scramble' attribute is not present).

The core trouble with scrambling markup plugins is that they interfer with the "true" content of an entry. Like the 'trackexits' plugin will unrecoverably replace a <a href="http://blablabla"> link with a <a href="http://exit.php?" one. If there were any other plugins after this markup plugin in queue, they would not get the true URL of the entry! Like the lightbox plugin, which needs to have the true URLs to make its magic work, they would not be able to execute properly with a scrambled entry. This is why a scrambling markup plugin has to go through so much pain to make sure that the serendipity API only will scramble the plugin at the specific event where the plugin is allowed to be executed ('frontend_display_cache') and where previous filtering results have already executed all other plugins properly.

The other sort of plugins is the one you'll probably want to use - "write once, read many". Those do not use

Now for the inner workings of that:

When an entry is saved, the hook 'backend_save' (or backend_publish, depending on the draft state) is executed. The entryproperties plugin hooks into that event, passes the entry data to the 'frontend_display_cache' hook which all SCRAMBLING markup plugins that support caching need to implement. The result of the filter run (containing the markup-transformations of a 'frontend_display' run earlier in the serendipity_updertEntry() flow) will be stored in the cache.

Now let's look at an example non-scrambling markup plugin that hooks into the caching system, the nl2br plugin.

As mentioned, it needs to declare the 'cachable_events', currently only really supporting 'frontend_display'. When that hook is executed on saving, it will apply the required transformations. In case of an entryproperties caching run, the transformations are also executed in this hook. And the API takes care that the hook is not executed, if the entryproperties plugin has set the 'is_cached' attributes. A lot of explanation for this simple logic, right?

All a plugin author has to do for a markup plugin is to make his logic be emitted in 'frontend_display' and declare that as a cachabable event. It only gets ugly if a plugin has to be invented that uses scrambling methods, where I suggest to adapt the workflow of the 'trackexits' event plugin.

To make a real long story short: Actually, since your plugin does not apply any markup (it only uses javascript, right?) you won't really be using any of this caching stuff, because your results can't be cached on server side. :-)
Oh... Garvin, if you read this, is there a SPARTACUS SUBMISSION process? I've read that you follow certain syntax guidelines and have tried to follow them -- are there any other requirements (other than the developers deciding whether a plugin is worthy)?
The only submission guidelines are proper indenting (4 Spaces instead of tabs) and that the code doesn't have any obvious XSS, SQL injection and arbitrary file inclusion problems. Since you only use client scripting, those risks are basically nonexistant. I could add your plugin to Spartacus anytime you like, but I suppose you'll try to get the admin preview fixed :)

Best regards,
Garvin
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
Brendon K
Regular
Posts: 44
Joined: Thu Feb 23, 2006 10:35 pm
Location: Saratoga Springs, NY, USA
Contact:

Post by Brendon K »

Absolutely wonderful! THANK YOU! I've skimmed through this and it appears that you were able to give me enough information to get a good grasp of the "How"'s and "Why"'s. I'll probably take the weekend to work through it (read, understand, and implement), but this is invaluable. If only the plugin hook page came with as much detail. ;)
They say, "Practice makes perfect," yet they also say, "Nobody's perfect." I don't get it.
Timbalu
Regular
Posts: 4598
Joined: Sun May 02, 2004 3:04 pm

Re: Insert code pre and post entry data in backend preview?

Post by Timbalu »

@Garvin

I just capture this thread, since my request is been mentioned.
I need a "backend_footer" hook! :) Starting with 1.7.4, please.
I think its time for it, since we have frontend_header & frontend_footer, but only the backend_header in the backyard.

Placing JS files down to the bottom page comes more and more important and this new hook would also help to prevent some plugins to create inline js doublettes.
Regards,
Ian

Serendipity Styx Edition and additional_plugins @ https://ophian.github.io/ @ https://github.com/ophian
onli
Regular
Posts: 2825
Joined: Tue Sep 09, 2008 10:04 pm
Contact:

Re: Insert code pre and post entry data in backend preview?

Post by onli »

Why not use the new js hook?
Timbalu
Regular
Posts: 4598
Joined: Sun May 02, 2004 3:04 pm

Re: Insert code pre and post entry data in backend preview?

Post by Timbalu »

...Where, what, .?. :?:
Regards,
Ian

Serendipity Styx Edition and additional_plugins @ https://ophian.github.io/ @ https://github.com/ophian
onli
Regular
Posts: 2825
Joined: Tue Sep 09, 2008 10:04 pm
Contact:

Re: Insert code pre and post entry data in backend preview?

Post by onli »

2.0 stuff.

Instead of fiddling with single files and position on the page, plugins should use the new hook 'js' to emit their javascript code. I think that is better than adding additional events just to position javascript-inserts where wanted.
Timbalu
Regular
Posts: 4598
Joined: Sun May 02, 2004 3:04 pm

Re: Insert code pre and post entry data in backend preview?

Post by Timbalu »

Ah! That might well be for some others...

I definitely need a "backend_footer" hook! And I do not want to wait for a far 2.0 version to use it.
This is something good to have in general, IMO, even if the 2.0 will provide something else in future, which is not the same.

So my request remains still valid. ::G.A.R.V.I.N.!:: :wink:
Regards,
Ian

Serendipity Styx Edition and additional_plugins @ https://ophian.github.io/ @ https://github.com/ophian
garvinhicking
Core Developer
Posts: 30022
Joined: Tue Sep 16, 2003 9:45 pm
Location: Cologne, Germany
Contact:

Re: Insert code pre and post entry data in backend preview?

Post by garvinhicking »

Hi!

I have no problem with a new hook for the 1.7.x line. However, this alone would IMO not rectif releasing 1.7.x - so it could very well be that we might never release 1.7.4... ;)
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
Timbalu
Regular
Posts: 4598
Joined: Sun May 02, 2004 3:04 pm

Re: Insert code pre and post entry data in backend preview?

Post by Timbalu »

Oh yeah, please drop that into both branches for me! :)

No, that would not trigger a new release, but I am pretty sure, we will need to release a 1.7.4 sometime later on. :wink:
Regards,
Ian

Serendipity Styx Edition and additional_plugins @ https://ophian.github.io/ @ https://github.com/ophian
garvinhicking
Core Developer
Posts: 30022
Joined: Tue Sep 16, 2003 9:45 pm
Location: Cologne, Germany
Contact:

Re: Insert code pre and post entry data in backend preview?

Post by garvinhicking »

Done!
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
Timbalu
Regular
Posts: 4598
Joined: Sun May 02, 2004 3:04 pm

Re: Insert code pre and post entry data in backend preview?

Post by Timbalu »

:D Thanks!

I am still waiting for the new smarty bugfix release, which has some real interesting fixes!
Regards,
Ian

Serendipity Styx Edition and additional_plugins @ https://ophian.github.io/ @ https://github.com/ophian
Post Reply