Difference between revisions of "MultiLang Fields Bazaar Package"

From EPrints Documentation
Jump to: navigation, search
(Introducing ml_title field in EPrints)
 
(29 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:EPrints 3 Plugins]]
 
[[Category:EPrints 3 Plugins]]
  
The MultiLang plugins introduces multiple language support in EPrints fields. The specific plugin replaces '''title''' and '''abstract''' fields with their multilanguage version ('''ml_title''' and '''ml_abstract''' respectively), but this wiki-page will explain how one can achieve this functionality in other EPrints fields as well.
+
The MultiLang plugins introduces multiple language support in EPrints fields. The specific plugin replaces the '''title''' and '''abstract''' fields' types with their multilingual versions that calculate their values based on two newly added multilingual fields ('''ml_title''' and '''ml_abstract''' respectively). The wiki-page that explains how one can replace basic EPrints fields with multilang-fields -which basically explains how this plugin was created- is [[Adding multilang fields]].  
  
 
== Installation Prerequisites ==
 
== Installation Prerequisites ==
None
+
None.
  
 
== Installation ==
 
== Installation ==
  
Install through the EPrints Bazaar
+
Install through the EPrints Bazaar.
 +
 
 +
== Warning for already populated repositories ==
 +
Once this plugin is installed, '''existing titles and abstracts''' will not be copied into their multilingual counterparts and '''access to them via the API will be lost'''! The users of this plugin are requested to use EPrints API to copy the values from the old fields to the new ones. A script that copies the '''title''' value of each eprint to '''ml_title''' field's '''en''' and '''el''' languages can be found here:[https://github.com/mamalos/eprints/blob/master/help_scripts/set_ml_title.pl]. Please, use this script at your own risk and don't forget to change its content to reflect the languages of your repository. The same script can be used for copying the '''abstract''' field's values to '''ml_abstract''' '''en''' and '''el''' by replacing title with abstract in this script.
  
 
== How to use the plugin ==
 
== How to use the plugin ==
Once the plugin has been installed, the user needs to edit the workflow to contain the multilingual fields' versions instead of the default ones. This procedure is explained in [[MultiLang Fields Bazaar Package::Edit workflow]] section.
+
Once the plugin has been installed, the user needs to edit the workflow to contain the multilingual fields' versions instead of the default ones. This procedure is explained in the next section.
  
== How the plugin works ==
+
== Editing the workflow ==
In order to introduce a new field in EPrints (such as the '''ml_title''' field), a few things need to take place:
+
In order for the plugin to be usable, the default field versions need to be commented out and the new multilingual ones need to be added. So, '''~eprints/archives/reponame/cfg/workflows/eprint/default.xml''' has to be edited as follows:
  
* The field's name and functionality needs to be introduced to the EPrints system via a configuration file located in '''~eprints/archives/<reponame>/cfg/cfg.d/'''.
+
<source lang="html4strict">
* EPrints' database needs to be updated to include the new field. This is achieved when user eprints executes (from his home directory):
+
<!--   
<pre>
+
    <component><field ref="title" required="yes" input_lookup_url="{$config{rel_cgipath}}/users/lookup/title_duplicates" input_lookup_params="id={eprintid}&amp;dataset=eprint&amp;field=title" /></component>
$ ./bin/epadmin update reponame
+
    <component><field ref="abstract"/></component>
</pre>
+
-->
* The appropriate phrases need to be added for each field and for each supported language.
 
* The workflow needs to be edited in order to contain the new fields - and not include the original ones.
 
* The repository needs to be reloaded, by running:
 
<pre>
 
$ ./bin/epadmin reload reponame
 
</pre>
 
within eprints' home directory.
 
  
The following sections explain each step in detail, where we are using '''ml_title''' as our example field. The code snippets are just for demonstration purposes (and proof of concept). If you want to see the final, working implementation, you should look at the source code of the plugin.
+
    <component><field ref="ml_title" required="yes" input_lookup_url="{$config{rel_cgipath}}/users/lookup/ml_title_duplicates" input_lookup_params="id={eprintid}&amp;dataset=eprint&amp;field=ml_title"/></component>
 +
    <component><field ref="ml_abstract"/></component>
 +
</source>
  
== Introducing ml_title field in EPrints ==
+
As can be seen, the default lookup script is replaced by the plugin's lookup script ('''ml_title_duplicates''') which supports the new '''ml_'''fields. Once the workflow has changed, the repository needs to be reloaded for the changes to take effect:
We create the file: '''~eprints/archives/<reponame>/cfg/cfg.d/zz_multilang_field.pl''' with the following content:
 
  
<source lang='perl'>
+
<source lang="bash">
#define local fields
+
./epadmin reload reponame
my $local_fields = [
+
</source>
{
 
    name => 'ml_title',
 
    type => 'multilang',
 
    multiple => 1,
 
    fields => [ { sub_name => "text", type => "longtext", input_rows => 3, make_single_value_orderkey => 'EPrints::Extras::english_title_orderkey' } ],
 
    input_add_boxes => 1,
 
},
 
  
{
+
== Editing the phrase files ==
    name => 'title',
+
The plugin updates the EPrints system by providing an English and a Greek phrase file for the new fields it creates. The new fields are named '''ml_title''' and '''ml_abstract'''. So, if this plugin is used for repositories in other languages than these, the site administrator needs to provide the appropriate phrase files for their languages manually. What they can do is copy the phrases from the English language phrase file located in '''~eprints/archives/<reponame>/cfg/lang/en/phrases/local.xml''' and copy them to a new file located in '''~eprints/archives/<reponame>/cfg/lang/<your_lang>/phrases/'''. The file-name should have an '''xml''' extension (like '''local.xml''' in our example).
    type => 'virtualwithvalue',
 
    virtual => 1,
 
  
    get_value => sub
+
The phrases that need to be added are the following (excerpt from the Greek phrases file):
    {
+
<source lang="html4strict">
        my ($eprint) = @_;
+
<!-- multilang title related phrases -->
        if ($eprint->is_set('ml_title'))
+
    <epp:phrase id="eprint_fieldname_ml_title">Τίτλος</epp:phrase>
        {
+
    <epp:phrase id="eprint_fieldname_ml_title_text">Κείμενο</epp:phrase>
            my $lang = $eprint->repository->get_langid;
+
    <epp:phrase id="eprint_fieldname_ml_title_help">Το help τεξτ</epp:phrase>
            my $lang_set = 0;
+
    <epp:phrase id="eprint_fieldname_ml_title_lang">Γλώσσα</epp:phrase>
            my $vals = $eprint->get_value('ml_title');
+
    <epp:phrase id="eprint_fieldhelp_ml_title">Ο τίτλος του τεκμηρίου. Ο τίτλος δεν πρέπει να τελειώνει με τελεία, αλλά μπορεί να τελειώνει με ερωτηματικό. Δεν υπάρχει τρόπος να γράψετε με πλάγια γράμματα, παρακαλώ χρησιμοποιήστε απλό κείμενο. Εάν έχετε έναν υπότιτλο, θα πρέπει να προηγείται η άνω και κάτω τελεία του υπότιτλου [:]. Χρησιμοποιήστε κεφαλαία γράμματα μόνο στην πρώτη λέξη και στα κύρια ονόματα.
            my $title = '';
+
        <br/>Παράδειγμα: <span class="ep_form_example">Μια σύντομη ιστορία</span>
            if (!$lang)
+
        <br/>Παράδειγμα: <span class="ep_form_example">Καβάφης: η βιογραφία</span>
            {
+
        <br/>Παράδειγμα: <span class="ep_form_example">Μαθηματικά για μηχανικούς και επιστήμονες. 5η έκδοση</span>
                $lang_set = 1;
+
        <br/>Παράδειγμα: <span class="ep_form_example">Οικοσυστήματα του πλανήτη. Τόμ. 26. Εκβολές του πλανήτη.</span>
            }
+
    </epp:phrase>
            else
 
            {
 
                # set the default lang's text as title
 
                foreach my $v1 (@{$vals})
 
                {
 
                    if ($v1->{lang} eq $lang)
 
                    {
 
                        $title = $v1->{text};
 
                    }
 
                }
 
            }
 
            # if the language is not set or I can't find an abstract in the
 
            # user's language, get the first object's text as abstract
 
            if ($lang_set or $title eq '')
 
            {
 
                $title = $vals->[0]->{text};
 
            }
 
            return $title;
 
  
        }
+
<!-- multilang abstract related phrases -->
        return undef;
 
    },
 
  
     set_value => sub
+
     <epp:phrase id="eprint_fieldname_ml_abstract">Περίληψη</epp:phrase>
     {
+
     <epp:phrase id="eprint_fieldname_ml_abstract_text">Κείμενο</epp:phrase>
        my ($eprint, $value) = @_;
+
    <epp:phrase id="eprint_fieldname_ml_abstract_help">Το help τεξτ</epp:phrase>
        my $lang = 'en';
+
    <epp:phrase id="eprint_fieldname_ml_abstract_lang">Γλώσσα</epp:phrase>
        #only use this on imports, NOT if the value is already set
+
     <epp:phrase id="eprint_fieldhelp_ml_abstract">Μία περίληψη των περιεχομένων. Εάν το τεκμήριο διαθέτει περίληψη, αυτή πρέπει να τοποθετηθεί εδώ. Υποστηρίζεται μόνον απλό κείμενο.</epp:phrase>
        if ($eprint->is_set('ml_title'))
 
        {
 
            return;
 
        }
 
        if ($value)
 
        {
 
            $eprint->set_value('ml_title', [{lang=>$lang, text=>$value}]);
 
        }
 
     }
 
},
 
];
 
  
#create lookup hash of local field names
 
my $local_fieldnames = {};
 
  
foreach my $f (@{$local_fields})
+
</source>
{
 
    $local_fieldnames->{$f->{name}} = 1;
 
}
 
  
#merge in existing field configurations
+
== Regenerating static files and abstracts ==
foreach my $f (@{$c->{fields}->{eprint}})
+
If our repository already contained records, we need to recreate static content such as static pages and abstracts. Hence, as eprints user we should run:
{
+
<source lang="bash">
    if (!$local_fieldnames->{$f->{name}})
+
$ ./bin/generate_abstracts reponame
    {
+
$ ./bin/generate_static reponame
    push @{$local_fields}, $f;
+
</source>
    }
+
within eprints user's home directory.
}
 
  
#overwrite original array of configured fields
 
$c->{fields}->{eprint} = $local_fields;
 
</source>
 
  
Where we can see that our new '''ml_title''' field is of type '''virtualwithvalue''' (which we'll explain later in this section) and implements two functions: '''get_value''' and '''set_value'''. Both these functions are used by EPrints API and their existence, as well as their return values, are critical for EPrints to work properly, and do exactly what their names suggest. In the end of our example code one can see how a custom field can be added in the list of EPrints fields.
+
== How the plugin works ==
 +
Basically, what the plugin does is that it replaces EPrints default '''title''' and '''abstract''' field types with a type that supports storing and retrieving information on multilingual fields. The procedure that we followed in order to achieve this functionality was the following:
 +
 
 +
* We introduced a new field's type, '''virtualwithvalue''', that would allow our fields to override EPrints fields' default behaviour.
 +
* We added multilingual versions of the fields that are replaced (namely '''ml_title''' and '''ml_abstract''') to store multilingual content.
 +
* We introduced our new fields' names, types and functionality to EPrints via a configuration file located in '''~eprints/archives/<reponame>/cfg/cfg.d/'''
 +
* We added the appropriate phrases in each language's phrase file.
 +
* We added a custom lookup cgi script that uses the new '''ml_title''' field for the autocompletion feature.
 +
* We changed EPrints basic and advanced search scripts to search our new multilingual fields instead of the original ones.
  
== Editing the workflow ==
+
A screenshot showing how the two fields look when inserting a new document follows:
blahblah
+
[[File:ruomo_multilang.jpg]]

Latest revision as of 10:28, 7 July 2016


The MultiLang plugins introduces multiple language support in EPrints fields. The specific plugin replaces the title and abstract fields' types with their multilingual versions that calculate their values based on two newly added multilingual fields (ml_title and ml_abstract respectively). The wiki-page that explains how one can replace basic EPrints fields with multilang-fields -which basically explains how this plugin was created- is Adding multilang fields.

Installation Prerequisites

None.

Installation

Install through the EPrints Bazaar.

Warning for already populated repositories

Once this plugin is installed, existing titles and abstracts will not be copied into their multilingual counterparts and access to them via the API will be lost! The users of this plugin are requested to use EPrints API to copy the values from the old fields to the new ones. A script that copies the title value of each eprint to ml_title field's en and el languages can be found here:[1]. Please, use this script at your own risk and don't forget to change its content to reflect the languages of your repository. The same script can be used for copying the abstract field's values to ml_abstract en and el by replacing title with abstract in this script.

How to use the plugin

Once the plugin has been installed, the user needs to edit the workflow to contain the multilingual fields' versions instead of the default ones. This procedure is explained in the next section.

Editing the workflow

In order for the plugin to be usable, the default field versions need to be commented out and the new multilingual ones need to be added. So, ~eprints/archives/reponame/cfg/workflows/eprint/default.xml has to be edited as follows:

<!--    
    <component><field ref="title" required="yes" input_lookup_url="{$config{rel_cgipath}}/users/lookup/title_duplicates" input_lookup_params="id={eprintid}&amp;dataset=eprint&amp;field=title" /></component>
    <component><field ref="abstract"/></component>
-->

    <component><field ref="ml_title" required="yes" input_lookup_url="{$config{rel_cgipath}}/users/lookup/ml_title_duplicates" input_lookup_params="id={eprintid}&amp;dataset=eprint&amp;field=ml_title"/></component>
    <component><field ref="ml_abstract"/></component>

As can be seen, the default lookup script is replaced by the plugin's lookup script (ml_title_duplicates) which supports the new ml_fields. Once the workflow has changed, the repository needs to be reloaded for the changes to take effect:

./epadmin reload reponame

Editing the phrase files

The plugin updates the EPrints system by providing an English and a Greek phrase file for the new fields it creates. The new fields are named ml_title and ml_abstract. So, if this plugin is used for repositories in other languages than these, the site administrator needs to provide the appropriate phrase files for their languages manually. What they can do is copy the phrases from the English language phrase file located in ~eprints/archives/<reponame>/cfg/lang/en/phrases/local.xml and copy them to a new file located in ~eprints/archives/<reponame>/cfg/lang/<your_lang>/phrases/. The file-name should have an xml extension (like local.xml in our example).

The phrases that need to be added are the following (excerpt from the Greek phrases file):

<!-- multilang title related phrases -->
    <epp:phrase id="eprint_fieldname_ml_title">Τίτλος</epp:phrase>
    <epp:phrase id="eprint_fieldname_ml_title_text">Κείμενο</epp:phrase>
    <epp:phrase id="eprint_fieldname_ml_title_help">Το help τεξτ</epp:phrase>
    <epp:phrase id="eprint_fieldname_ml_title_lang">Γλώσσα</epp:phrase>
    <epp:phrase id="eprint_fieldhelp_ml_title">Ο τίτλος του τεκμηρίου. Ο τίτλος δεν πρέπει να τελειώνει με τελεία, αλλά μπορεί να τελειώνει με ερωτηματικό. Δεν υπάρχει τρόπος να γράψετε με πλάγια γράμματα, παρακαλώ χρησιμοποιήστε απλό κείμενο. Εάν έχετε έναν υπότιτλο, θα πρέπει να προηγείται η άνω και κάτω τελεία του υπότιτλου [:]. Χρησιμοποιήστε κεφαλαία γράμματα μόνο στην πρώτη λέξη και στα κύρια ονόματα.
        <br/>Παράδειγμα: <span class="ep_form_example">Μια σύντομη ιστορία</span>
        <br/>Παράδειγμα: <span class="ep_form_example">Καβάφης: η βιογραφία</span>
        <br/>Παράδειγμα: <span class="ep_form_example">Μαθηματικά για μηχανικούς και επιστήμονες. 5η έκδοση</span>
        <br/>Παράδειγμα: <span class="ep_form_example">Οικοσυστήματα του πλανήτη. Τόμ. 26. Εκβολές του πλανήτη.</span>
    </epp:phrase>

<!-- multilang abstract related phrases -->

    <epp:phrase id="eprint_fieldname_ml_abstract">Περίληψη</epp:phrase>
    <epp:phrase id="eprint_fieldname_ml_abstract_text">Κείμενο</epp:phrase>
    <epp:phrase id="eprint_fieldname_ml_abstract_help">Το help τεξτ</epp:phrase>
    <epp:phrase id="eprint_fieldname_ml_abstract_lang">Γλώσσα</epp:phrase>
    <epp:phrase id="eprint_fieldhelp_ml_abstract">Μία περίληψη των περιεχομένων. Εάν το τεκμήριο διαθέτει περίληψη, αυτή πρέπει να τοποθετηθεί εδώ. Υποστηρίζεται μόνον απλό κείμενο.</epp:phrase>

Regenerating static files and abstracts

If our repository already contained records, we need to recreate static content such as static pages and abstracts. Hence, as eprints user we should run:

$ ./bin/generate_abstracts reponame
$ ./bin/generate_static reponame

within eprints user's home directory.


How the plugin works

Basically, what the plugin does is that it replaces EPrints default title and abstract field types with a type that supports storing and retrieving information on multilingual fields. The procedure that we followed in order to achieve this functionality was the following:

  • We introduced a new field's type, virtualwithvalue, that would allow our fields to override EPrints fields' default behaviour.
  • We added multilingual versions of the fields that are replaced (namely ml_title and ml_abstract) to store multilingual content.
  • We introduced our new fields' names, types and functionality to EPrints via a configuration file located in ~eprints/archives/<reponame>/cfg/cfg.d/
  • We added the appropriate phrases in each language's phrase file.
  • We added a custom lookup cgi script that uses the new ml_title field for the autocompletion feature.
  • We changed EPrints basic and advanced search scripts to search our new multilingual fields instead of the original ones.

A screenshot showing how the two fields look when inserting a new document follows: Ruomo multilang.jpg