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