-
Notifications
You must be signed in to change notification settings - Fork 36
devguide htmlhead
Often plugins need to inject custom styling and behavior into a page. This is often done through stylesheets and javascript respectively. One way to accomplish this is through the use of "transformer callbacks" which allow developers to modify the source of a template prior to it being parsed and/or rendered. This process however is cumbersome because it requires the developer to know Perl and have advanced knowledge of how callbacks work in Melody -- not to mention know a little something about regular expressions and other string manipulation techniques.
So when all you need to do is insert a stylesheet or script block, here is a much easier way, and a way that requires no programming knowledge whatsoever. Just edit your plugin's config.yaml file and insert one or more of the following examples, tweaked of course to your needs:
The following:
html_head:
scripts:
- content: >
$(document).ready( function() { alert('foo'); } );
Would result in this HTML being inserted into the <head>:
<script type="text/javascript">
$(document).ready( function() { alert('foo'); } );
</script>
You can also just link to a javascript file. The following:
html_head:
scripts:
- src: 'js/jquery.foo.js'
Would result in:
<script type="text/javascript" src="path/to/js/jquery.foo.js"></script>
html_head:
stylesheets:
- href: 'css/foo.css'
- href: 'css/dashboard-foo.css'
Sometimes you want to embed a generic link relation. A link relation or <link> element consists of three properties:
- rel
- href
- type
Each of these properties can be set with corresponding properties in the registery, like so:
html_head:
links:
- rel: 'bookmark'
href: 'http://somewhe.re/'
type: 'text/html'
- rel: 'me'
href: 'foo.html'
type: 'text/html'
Programmatic Conditions
The following example shows to link to a stylesheet, but only if the current screen is the dashboard.
html_head:
stylesheets:
- href: 'css/foo.css'
condition: >
sub { my $app = shift; return ($app->isa('MT::App') &&
$app->mode() eq 'dashboard'); }
The condition block must be a subroutine, which takes as input the current instance of the Melody application. The subroutine must return true or false. If it returns false, the associated link/stylesheet/script will not be embedded.
Embedding Links only for specific screens
The following example shows how to link to a stylesheet, but only from the Dashboard screen, the view Activity Log screen and the Manage Entries screen:
html_head:
stylesheets:
- href: 'css/foo.css'
modes: 'dashboard,view_log,list_entries'
You can target one or more screens in the app using each screens respective mode, corresponding to the value of the __mode query string parameter.
Scripts, stylesheets and other links are inserted in the same order they appear in your config.yaml.
If at any time you reference an absolute URL in an href or src attribute, then Melody will embed the URL as-is without any modification.
Every other URL is determined to be a relative URL, and is relative to the registering plugin's static web path. Melody will automatically convert your relative URL into an absolute URL. For example, let's say I have packaged the following files with my plugin:
plugins/MyPlugin/config.yaml
plugins/MyPlugin/static/js/foo.js
plugins/MyPlugin/static/css/foo.css
I want to add a link to a javascript file hosted on a remote service, in addition to my foo.js and foo.css file to every page of the Melody application. My config.yaml would then look like this:
id: MyPlugin
name: "My Test Plugin"
html_head:
stylesheets:
- href: 'css/foo.css'
scripts:
- src: 'http://someservice.com/js/insert_something_cool.js'
- src: 'js/foo.js'
This would result in Melody generating and embedding the following HTML into the <head> portion of every page of Melody:
<link rel="stylesheet" type="text/css" href="/cgi-bin/melody/mt-static/support/plugins/myplugin/css/foo.css" />
<script type="text/javascript" src="http://someservice.com/js/insert_something_cool.js"></script>
<script type="text/javascript" src="/cgi-bin/melody/mt-static/support/plugins/myplugin/js/foo.js"></script>
[[http://openmelody.org/assets_c/2009/06/melody-logo-mark-on-white-thumb-150x150-7.jpg|float|align=left]]
Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.
- Author: Byrne Reese