Editing Adding multilang fields (section)

== Introducing ml_title field in EPrints and replacing title field's type==
To inform EPrints about our new field (that will be of type '''virtualwithvalue'''), we should create a configuration file, eg: '''~eprints/archives/<reponame>/cfg/cfg.d/zz_multilang_field.pl''' with content like the following:

<source lang='perl'>
#define local fields
my $local_fields = [
{
    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,
},

{
    name => 'title',
    type => 'virtualwithvalue',
    virtual => 1,

    get_value => sub
    {
        my ($eprint) = @_;
        if ($eprint->is_set('ml_title'))
        {
            my $lang = $eprint->repository->get_langid;
            my $lang_set = 0;
            my $vals = $eprint->get_value('ml_title');
            my $title = '';
            if (!$lang)
            {
                $lang_set = 1;
            }
            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;

        }
        return undef; # This is important. Using just a 'return;' or no return statement may break your repository e.g. when an EPrint revision file tried to be created.
    },

    set_value => sub
    {
        my ($eprint, $value) = @_;
        my $lang = 'en';
        #only use this on imports, NOT if the value is already set
        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})
{
    $local_fieldnames->{$f->{name}} = 1;
}

#merge in existing field configurations
foreach my $f (@{$c->{fields}->{eprint}})
{
    if (!$local_fieldnames->{$f->{name}})
    {
     push @{$local_fields}, $f;
    }
}

#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 '''multilang''' and the '''title''' field's type has become '''virtualwithvalue'''. Moreover, the '''title''' field now implements the two aforementioned functions: '''get_value''' and '''set_value'''. Both these functions -whose names imply their functionality- are used by EPrints API, and their existence, as well as their return values, are critical for EPrints to work properly. The last statements of our example code show how a custom field can be added in the list of EPrints fields.

What has happened in effect is that the '''title''' field has become a calculated field that gets or sets its value via its corresponding '''multilang''' field ('''ml_title'''). So, each new record now has a '''multilang''' field which it can access via the interface provided by the calculated field of type '''virtualwithvalue''', which is no other than EPrints' basic '''title''' field.

The reason we didn't set the '''title''' field to be of type '''multilang''' in the first place is that many EPrints builtin functions expect only a single value from the '''title''' (and '''abstract''') field, and '''multilang''' fields don't support such functionality. Hence, doing so would cause EPrints to throw errors. By using and extending calculated fields (like '''MetaFields'''), we can calculate and produce always a single output for our '''title''' field (using the data stored in '''ml_title''' field) via its '''get_value''' function; its '''set_value''' function is used for populating our '''ml_title''' field's values. Our sample code prints output based on the user's language settings, but the programmer can do whatever they wish when overriding these functions, as long as their code return values that comply with EPrints' API.