Skip to content

Commit 5cb1b41

Browse files
golschgolsch
committed
Improve README.md
1 parent e8256a8 commit 5cb1b41

File tree

1 file changed

+92
-30
lines changed

1 file changed

+92
-30
lines changed

‎README.md‎

Lines changed: 92 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,109 @@
11
# mir-navigation-plugin
22

3-
Includes an extended navigation for newspapers and series. It based on a widen solr handling for
4-
parent documents (root field).
3+
This MIR plugin provides navigation functionality for newspapers and series.
54

6-
The plugin provides the extended solr handling for series (solr-navigation.xsl). In frontend
7-
context there is a series layout with a panel that shows the navigation.
5+
It provides a panel for the frontend that displays the series navigation, including banner and search.
6+
The navigation is based on a derivate that contains a `navigation.xml` file, where the navigation structure and banner
7+
can be configured.
88

9-
## Installation instructions for mir lts 2023.06 (As mir-enduser)
9+
It leverages enhanced Solr handling for parent documents (root field) and includes extended Solr processing for series.
1010

11-
1. Download the project from this repository and place it on your computer
11+
> ⚠️ Note: The plugin will overwrite `response-mir.xsl`; any custom frontend changes may be lost.
1212
13-
2. Unzip the downloaded file to create a development project folder location
13+
---
1414

15-
3. Customize general mycore.properties(http://www.mycore.de/documentation/getting_started/mcr_properties.html) for this plugin (/mir-navigation-plugin/src/main/resources/config/mir-navigation-plugin/mycore.properties)
15+
## Features
1616

17-
4. Create jar file with maven => mvn clean && mvn install
17+
The plugin offers the following features:
1818

19-
5. Copy the created jar file from target (/mir-navigation-plugin/target) to mycore home lib
19+
- Frontend Navigation Panel: Displays a series of pages or objects with banner and search.
20+
- Banner Support: Root item can include a banner image.
21+
- Flexible Navigation: Defined via navigation.xml with relative/absolute links and multilingual labels.
22+
- Enhanced Solr Handling: Supports parent documents (root field) and requires schema extensions.
23+
- Optional RSS Feed: RSS link can be displayed or disabled.
2024

21-
(Windows Systems C:\Users\User\AppData\Local\MyCoRe\mirapplication\lib) <br />
22-
(Linux Systems /home/user/.mycore/mirapplication/lib)
25+
---
2326

24-
6. The navigation plugin uses a widen solr handling for parent documents. For this purpose, the plugin brings its own schema extensions. It is necessary to reload the solr schema (for further information have a look on solr mycore documentation http://www.mycore.de/documentation/search/using_solr.html).
25-
In case of a standard solr core installation (the main core is named „main“) open the mir web cli:
27+
## Requirements
2628

27-
- run command „reload solr configuration main in core main“
28-
* This command synchronizes the solr main core with the solr schema from this plugin
29-
- Reload the mir core with solr webadmin (Core Admin - reload)
30-
* You can do a quick check in the solr webadmin via mir schema menu item (root field should be there now)
31-
- Reindex solr with the rules from the navigation plugin with command „rebuild solr metadata and content index in core main“
32-
* solr entries should provide the extended handling for parent documents now (root field)
29+
### Navigation category in `derivate_types` classification
3330

34-
## Requirements for mods document metadata
35-
The standard implementation identifies derivates as series-navigation relatable if they have set categid="navigation" in derobject classification:
31+
The plugin is based on a derivate which must be classified via `derivate_types:navigation`.
32+
Therefore, the `derivate_types` classification must include a category `navigation`.
33+
The category can be defined as follows:
3634

37-
<derobject inherited="0" xlink:type="locator" xlink:href="mir_derivate_00000001">
38-
<order>1</order>
39-
<maindoc>index.xml</maindoc>
40-
<classification classid="derivate_types" categid="navigation" />
41-
</derobject>
35+
```xml
36+
<category ID="navigation">
37+
<label xml:lang="de" text="Navigation" />
38+
<label xml:lang="en" text="Navigation" />
39+
</category>
40+
```
4241

42+
---
4343

44-
## Migrate series navigation in mir
45-
For adding the series navigation panel in the right corner you have to adapt the MIR.Layout.End property (add series-banner,series-layout):
44+
## Installation & Configuration
4645

47-
`MIR.Layout.End=mir-edit,series-banner,series-layout,mir-citation,mir-thumbnail,mir-epusta,mir-access-rights,mir-export,mir-admindata,mir-historydata`
46+
### Build and provide plugin
47+
48+
Build the JAR file with `mvn clean install` and copy it to `~/.mycore/(dev-)mir/lib/`.
49+
50+
### Configure `mycore.properties`
51+
52+
To use the plugin, configuration in `~/.mycore/(dev-)mir/mycore.properties` is required.
53+
The RSS feed requires a `mycoreobject-rss` stylesheet, which is not included by default.
54+
For historical reasons, the link to the RSS feed is always displayed, but it can be disabled if needed.
55+
All in all, configure as follows:
56+
57+
```text
58+
# Add 'series-banner' and 'series-layout'.
59+
MIR.Layout.End=mir-edit,series-banner,series-layout,mir-citation,mir-thumbnail,mir-epusta,mir-access-rights,mir-export,mir-admindata,mir-historydata
60+
61+
# Optional: disable RSS feed.
62+
MIR.Metadata.Navigation.SeriesPanel.RSS.Enabled=false
63+
```
64+
65+
### Reload and rebuild Solr
66+
67+
The plugin leverages enhanced Solr handling for parent documents.
68+
For this purpose, the plugin brings its own schema extensions.
69+
It is necessary to reload the Solr schema (for further information have a look on Solr
70+
[documentation](https://www.mycore.de/documentation/search/search_solr_use/)).
71+
In the case of a standard Solr core installation (where the main core is named `main`), run the following CLI commands:
72+
73+
```text
74+
# Synchronize the solr main core with the solr schema from this plugin.
75+
reload solr configuration main in core main
76+
# Reindex solr with the rules.
77+
rebuild solr metadata and content index in core main
78+
```
79+
80+
As a result, Solr entries will now support the extended handling for parent documents (root field).
81+
82+
---
83+
84+
## Usage
85+
86+
A panel on an object page, including a banner, navigation, and search, can be integrated via a `navigation.xml` file
87+
contained in a derivative whose _derivate type_ is set to _navigation_.
88+
The following format is expected for the `navigation.xml` file:
89+
90+
```xml
91+
<item banner="path/to/banner.png">
92+
<item ref="path/to/page1.xml">
93+
<label xml:lang="de">German label for page 1</label>
94+
<label xml:lang="en">English label for page 1</label>
95+
</item>
96+
<item ref="path/to/page2.xml">
97+
<label xml:lang="de">German label for page 2</label>
98+
<label xml:lang="en">English label for page 2</label>
99+
</item>
100+
</item>
101+
```
102+
103+
A root item is expected first. The optional `banner` attribute can be used to specify a link to an image that will be
104+
displayed above the navigation.
105+
106+
Within the root item, the actual navigation points can be defined. The `ref` attribute specifies the target of a navigation point and can contain either a relative or an absolute link.
107+
Additionally, labels can be defined for the relevant languages.
108+
109+
> 💡 Tip: Using the [mir-alias-plugin](https://github.com/MyCoRe-Org/mir-alias-plugin), you can simplify the links for objects in the navigation.

0 commit comments

Comments
 (0)