MARC Plugin documentation

The MARC-DB is able to manage any flavor of MARC. To enable this, the base acquisition system is very simple : you choose which field/subfield you want to manage, and an input is generated in the form. this input is free, you can enter whatever you want, without any control. This is a very poor input system, which is well completed by the Plugin system. the Plugin system, which is NOT user-level but developper-level system defines specific methods to apply to field/subfields. This documentation explain how this system works.

For the end-user, the plugin system is very simple to use : in the marc parameters administration, on the subfield screen, you can choose (on the right column), a category of authorised values, a thesaurus category or a Plugin. the plugin is automatically builded from the plugin directory.

When a subfield is “linked” to a plugin, differents things occurs :

• A specific javascript script (included in the plugin) is called on Onfocus and Onblur event : you can check a value, report it on a different field/subfield, calculate something, modify a value… when the user enters or quits the field.
• A … appears on the right of the field. If the user clic on the …, a specific javascript script is called, which usually opens a popup to help entering the value (through a list, a “search mechanism” or whatever you want. When the popup is closed, the plugin reports the result in the “plugged” subfield.

The plugins are stored in the marc_value directory. The name of the file can be anything, but it's better to show which marc flavour it manages and which field/subfield is concerned. For example : unimarc_field_225a.pl or unimarc_field_700_701_702.pl. the plugins are used in 2 scripts :

• acqui.simple/addbiblio and acqui.simple/additem, which uses the plugin to find what to do in the javascript part of the plugin
• /plugin_launcher.pl which is used in the server side part of the plugin.

A plugin is a perl script containing 2 differents subs. 1st of them is called when building the add biblio screen. The second is called when the user clicks on …

This is the javascript part of the plugin. What is hard to understand in this script is that it's called on SERVER, and generates javascript code that will be executed on CLIENT. The easiest solution to understand them is to look at the unimarc samples.

The plugin_javascript sub has the following input parameters : my ($dbh,$record,$tagslib,$field_number,$tabloop) = @_; $dbh = db handler $record = the initial record, in MARC::Record format $tagslib = A hash containing the marc structure. the hash has the following structure :

• $tagslib→{$tag}→{lib} ⇒ the tag lib
• $tagslib→{$tag}→{$subfield}→{lib} ⇒ the lib of the subfield
• $tagslib→{$tag}→{$subfield}→{tab} ⇒ the tab number (from -1 to 10). Not useful in plugin
• $tagslib→{$tag}→{$subfield}→{mandatory} ⇒ 1 if yes, 0 if no
• $tagslib→{$tag}→{$subfield}→{repeatable} ⇒ 1 if yes, 0 if no
• $tagslib→{$tag}→{$subfield}→{authorised_value} ⇒ not useful in plugin
• $tagslib→{$tag}→{$subfield}→{thesaurus_category} ⇒ not useful in plugin
• $tagslib→{$tag}→{$subfield}→{value_builder} ⇒ not useful in plugin

$field_number : the number of the field in the html form. the variable (on the client side can be accessed through defaultvalue=document.forms[0].field_value[$field_number].value

$tabloop : the effective tab where the subfield is called from.

Note that those input parameters are always provided, but may be unused by some (or most) plugins. But if oone of them is needed, you've got it without changing plugin api.

The plugin_javascript returns 2 parameters :

• The “function_name”.

The function name is used when building the html, to “reach” the OnClic, OnFocus and OnBlur events and the corresponding function in the plugin. the best solution is to use a random name generated like this : my $function_name= “plugin_name”.(int(rand(100000))+1);

• The javascript.

It's a $ variable that contains the javascript code to include in the html. This variable must containt at least 3 subs : function Focus$function_name(subfield_managed) { function Blur$function_name(subfield_managed) { function Clic$function_name(i) { Each function is called on the corresponding event.

The subfield managed will contain document.forms[0].field_value[xx]. So subfield_managed.value will contain the value of the “caller” subfield.

This sub is usually called when the user clics on …, through the plugin_launcher.pl script. Note that you may want NOT to use the plugin_launcher. In this case, you can modify the clic$function_name in the pugin_javascript sub.

The cgi handle

Does not need to return any parameters, but html instead. Note that the popup should usually modify the value managed in the caller html page. Something like : function report() {

opener.document.f.field_value[xx].value= document.popup.pop_variable.value;
self.close();
return false;

} which is called on the OnSubmit event of the plugin popup form.

And now, the best solution should be to go to the unimarc plugins and modify them. They are documented.

• unimarc_field_210c : auto-finds and editor with the isbn
• unimarc_field_700_701_702 : searches an author and split name, surname, birthdate and title (Holy, King) in the good inputs.