/ BlackLab Frontend /

Appearance

Search.xml ​

Location
/etc/projectConfigs/
└─
corpus-1/
   ├─
search.xml
   ├─
help.inc
   ├─
about.inc
   ├─
article.xsl
   ├─
meta.xsl
   ├─
static/
   |  ├─
locales/
   |  |  ├─
en-us.json
   |  |  └─
...
   |  └─
...
   ├─
corpus-2/
   ├─
corpus-3/
   ├─
...
   ├─
default/
   |  ├─
search.xml
   |  └─
...
   └─
...
<--- The location set in the corporaInterfaceDataDir setting
<--- Exact name/ID of the corpus as in BlackLab
 
 
 
 
 
 
<--- Language files for the interface, specific to this corpus
 
 
<--- Anything else you want to make available client-side
 
 
 
<--- Fallbacks / Defaults go here
 
 
 

Search.xml allows you to configure various aspects of the BlackLab Frontend interface, such as navbar links, custom CSS/JS, and pagination settings for documents. It's always required if you want to apply any customization for your corpus after initial creation. BlackLab lets you configure some aspect of your corpus, but you can only do this while creating the corpus.

TIP

Set cache=false in the main blacklab-frontend.properties configuration file, so you don't need to restart the server every time you update the search.xml file.

Capabilities ​

Check the sidebar for the full list of options available in search.xml. The example file below also contains some comments to help you understand what each option does.

Some variables are available in the search.xml file. These variables are replaced with their actual values. The following variables are available:

  • ${request:contextPath}
    E.g. /blacklab-frontend
    The "home" link for the BlackLab Frontend.
    This does not end with a slash.
  • ${request:corpusId} E.g. my_corpus.
    The ID of the corpus.
    This is not the display name, but the internal ID of the corpus. Useful to refer to the static files, or create urls, etc.
  • ${request:corpusPath}
    E.g. /blacklab-frontend/${corpus_id}/
    The "home link" for the corpus.
    This is just a concatenation of the contextPath and the corpusId.
    This does not end with a slash.

Example file ​

Full search.xml file and defaults
xml
<?xml version="1.0" encoding="utf-8" ?>
<SearchInterface>
    <InterfaceProperties>
        <!--
        Limited variable interpolation is supported.
        ${request:contextPath}  - the application root path on the client, usually /blacklab-frontend . Is equal to the cfUrlExternal setting. Does not contain a trailing slash.
        ${request:corpusPath}   - the corpus root path on the client, usually /blacklab-frontend/${corpus-id}, equal to ${request:contextPath} if not viewing a corpus. Does not contain a trailing slash.
        ${request:corpusId}     - the corpus id (including username portion for user corpora), so 'lassy' or 'username:corpus-name', empty if not viewing a corpus.
        Paths do not contain a trailing slash
        -->

        <!--
        Custom files can be made available by placing them in a ./static directory within the corpus data directory
        (the exact location of that directory is configured in the .properties file for AutoSearch.)

        These files can then be accessed through the url ${request:corpusPath}/static/**

        So when you create a static/img/ directory containing logo.png for the 'zeebrieven' corpus,
        the url here would be '${request:contextPath}/zeebrieven/static/img/logo.png', or '${request:corpusPath}/static/img/logo.png'
        and the directory structure would be ${interfaceDataDir}/zeebrieven/static/img/logo.png

        Tip: use relative urls to reference resources from inside other resources (such from within custom css or js) (e.g. '../img/**' for images in a css file)
        -->

        <!-- When a DisplayName has been set, it will be shown in stead of the raw corpus name.
        If omitted, we will fall back to the displayName configured in BlackLab-Server,
        if that is not configured either, the internal corpus name is shown. -->
        <!--<DisplayName>BlackLab AutoSearch Corpus Search</DisplayName>-->


        <!-- Should be a directory; see webapp/img/ for a full listing of files -->
        <FaviconDir>${request:contextPath}/img</FaviconDir>

        <!-- 
            You can include custom js and css (usually from your corpus interface directory under /${contextPath}/corpusname/static/**), but external sites are supported.
            Attributes on the <CustomJs> (such as 'type="module"') tag are copied to the <script> tag on the page.
            The 'page' attribute is special, it's not copied, but controls lets you only run the script on the specified page (options: search, article, about, help, error, config, corpora, remote-index).
            Simply remove the 'page' attribute to include the script on every page.
        -->
        <!-- 
            <CustomJs page="search" type="module">${request:corpusPath}/static/some.other.js</CustomJs>
            <CustomCss page="article">${request:corpusPath}/static/your.css</CustomCss> 
        -->

        <!--
            You can define which properties/annotations to show as columns in the results table.
            By default (up to) the first 3 properties are shown, but 'lemma' and 'pos' have precedence and are always shown if they exist in the corpus.
        -->
        <!-- <PropColumns>lemma,pos,tense, person,number</PropColumns> -->

        
        <NavLinks>
            <Link value="http://www.ivdnt.org/" newWindow="true">INT</Link>
            <Link value="http://www.clarin.eu/" newWindow="true">CLARIN</Link>
            <Link value="https://www.clariah.nl/" newWindow="true">CLARIAH</Link>
            <Link value="${request:corpusPath}/help">Help</Link>
            <Link value="${request:corpusPath}/about">About</Link>
        </NavLinks>

        <!-- #region docspagination -->
        <Article>
            <!--
            Set to true to enable pagination when viewing documents.
            This setting is not enabled by default, as it may result in issues displaying the document's content,
            because xsl files will not run on the complete document any longer, thus xpaths may fail unexpectedly.
            -->
            <Pagination>false</Pagination>
            <!-- When pagination is enabled, this controls the length of a page. -->
            <PageSize>1000</PageSize>
        </Article>
        <!-- #endregion docspagination -->

        <!-- see https://github.com/moritzsternemann/vue-plausible -->
        <!-- 
        <Plausible>
            <domain>The domain registered with plausible</domain>
            <apiHost>The instance of plausible to use (for when self-hosting), normally https://plausible.io</apiHost>
        </Plausible> 
        -->

    </InterfaceProperties>
    <XsltParameters>
    <!--
        The following values are provided automatically:
        
        Typically /blacklab-frontend/ or similar. Takes the value of cfUrlExternal from the .properties file.
        Will not contain a trailing slash.
        <XsltParameter name="contextPath" value="${request:contextPath}"/>
        The corpus path, usually /blacklab-frontend/${corpus-id}, equal to ${request:contextPath} if not viewing a corpus.
        Will not contain a trailing slash.
        <XsltParameter name="corpusPath" value="${request:corpusPath}"/>
        The corpus ID (including username portion for user corpora), so 'lassy' or 'username:corpus-name', empty if not viewing a corpus.
        <XsltParameter name="corpusId" value="${request:corpusId}"/>
     -->
    </XsltParameters>
</SearchInterface>

A simple example ​

For example, to include a custom JavaScript file on the search page, you can add add the following search.xml:

xml
<?xml version="1.0" encoding="utf-8" ?>
<SearchInterface>
    <InterfaceProperties>
        <CustomJs page="search">${request:corpusPath}/static/js/custom.search.js</CustomJs> 
    </InterfaceProperties>
</SearchInterface>

Apache license 2.0

Copyright © 2010-present Dutch Language Institute