Our plugin lets us create a list of fancy words now, so what are some of the things we can do with it? Sometimes we may want to craft our code to define specific actions, but possibly we want to take advantage of existing code from the world of developers (i.e. we are lazy, someone else already did what we need)

In this post we will create an api route to deliver a static asset for our plugin to add a jQuery plugin that we can utilise with our list of fancy words.

In particular we are adding marks.js

Static plugin route

Koha’s REST API is built using Mojolicious and Swagger/OpenAPI - for plugins we can take advantage of the existing structure, and we simply need to add a json file describing the new route we wish to add

{
"/jquery-mark/jquery.mark.es6.min.js": {
  "get": {
    "x-mojo-to": "Static#get",
    "tags": [
      "pluginStatic"
    ],
    "responses": {
      "200": {
        "description": "File found",
        "schema": {
          "type": "file"
        }
      },
      "400": {
        "description": "Bad request",
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "description": "An explanation for the error",
              "type": "string"
            }
          }
        }
      },
      "404": {
        "description": "File not found",
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "description": "An explanation for the error",
              "type": "string"
            }
          }
        }
      },
      "500": {
        "description": "Internal server error",
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "description": "An explanation for the error",
              "type": "string"
            }
          }
        }
      }
    }
  }
}
}

For the static route we simply add the path to the file, and describe the basic HTML responses.

Controller code

We need to make sure our plugin expects and loads the static route, and define our api namespace so that swagger can build the documentation correctly.

use JSON;
.
.
.
sub static_routes {
    my ( $self, $args ) = @_;

    my $spec_str = $self->mbf_read('staticapi.json');
    my $spec     = decode_json($spec_str);

    return $spec;
}

sub api_namespace {
    my ($self) = @_;

    return 'fancyplugin';
}

With those changes, and the adding of the mark.js file to our plugin we can serve that file to koha.

Taking advantage of another plugin method, opac_js, we can utilise the new js file.

sub opac_js {
    my ( $self ) = @_;

    my $fancy_words = Koha::FancyWords->search();
    my @fancy_array;
    while (my $fancy_word = $fancy_words->next){
        push @fancy_array, '"'.$fancy_word->fancy_word.'"';
    }
    my $fancy_js_array = '[' . join(",",@fancy_array) . ']';
    return q{
      <script src="/api/v1/contrib/fancyplugin/static/jquery-mark/jquery.mark.es6.min.js"></script>
      <script>
          var fancy_words = $fancy_js_array;
          var context = document.querySelector("div.searchresults");
          var instance = new Mark(context);
          instance.mark(fancy_words);
      </script>

    };
}

Now if you search on the OPAC, any words that you have defined as ‘fancy’ in the plugin will be highlighted in search results. You could use this to highlight local authors, special item types, or whatever you wished.

You could expand this to add css files, serve pdfs, or add other plugins/resources to your plugins. The static route ensures that your resources are bundled with the plugin and easy to utilise.

Historic note

Note: Addendum from the editor, Martin

You may find some plugins out there that implement this using a now defunct method. When the plugin system was first crafted the recommendation was to simply package your static assets with the plugin and reference them from the template using:

src="[% PLUGIN_PATH %]/assets/file.png"

Whilst this was a nice simple way of bundling and references such files it required end users to reconfigure their apache server to proxy requests to the right place by adding something like the following to their virtual host file:

   Alias /plugin/ "/var/lib/koha/kohadev/plugins/"
   <Directory /var/lib/koha/kohadev/plugins/>
         Options Indexes FollowSymLinks
         AllowOverride None
         Require all granted
         Options +ExecCGI
         AddHandler cgi-script .pl
    </Directory>

Whilst this option is still supported, it is no longer recommended as it requires additional actions on the end user to enable your plugin and the user may inadvertantly introduce security issues by doing so (for example, the above snippet will allow nefarious entities to browse the plugin path data).

I hope you’ve enjoyed following along so far!