Using OpenGrok groupings

------------------------

This is a howto to introduce new feature in OpenGrok which allows

you to group projects into groups by using regexps and display them on the

index page.

Compatibility

-------------

If no configuration about groups is provided then groups are not used. Instead there is a

list of repositories on the main page and list of repositories and projects in the select box.

Simple configuration

--------------------

Suppose we have couple of projects:

ctags-5.6

ctags-5.6-stable

ctags-5.7

ctags-5.8

apache-ant-1.9

opengrok-master

opengrok-0.12-stable

The new feature allows us to create a structure like this (example):

ctags

| -- ctags 5.6

| | -- ctags-5.6

| | -- ctags-5.6-stable

| -- ctags 5.7

| | -- ctags-5.7

| -- ctags 5.8

| | -- ctags-5.8

apache

| -- apache-ant-1.9

opengrok

| -- opengrok-master

| -- opengrok-0.12-stable

and display that structure on the main page below the search form.

Configuration for this structure could look like this:

<?xml version="1.0" encoding="UTF-8"?>

<java version="1.8.0_65" class="java.beans.XMLDecoder">

<object class="org.opensolaris.opengrok.configuration.Configuration" id="Configuration0">

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags</string>

</void>

<void property="pattern">

<string></string>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags 5.6</string>

</void>

<void property="pattern">

<string>ctags 5.6.*</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags 5.7</string>

</void>

<void property="pattern">

<string>ctags 5.7</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags 5.8</string>

</void>

<void property="pattern">

<string>ctags 5.8</string>

</void>

</object>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>apache</string>

</void>

<void property="pattern">

<string>apache-.*</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>opengrok</string>

</void>

<void property="pattern">

<string>opengrok.*</string>

</void>

</object>

</void>

</object>

</java>

Configuration is provided in the read only configuration (-R parameter for the opengrok.jar or

READ_XML_CONFIGURATION variable in the OpenGrok script). This configuration is merged with the

instance configuration in /var/opengrok/etc/configuration.xml (default) so the groups are available

for the webapp.

NOTE:

There is no other way to persistently provide the group configuration than using

READ_XML_CONFIGURATION variable for each run of the indexer. If you run the indexer

without the read only configuration, your groups will vanish from the configuration.xml.

Display

-------

Groups, projects and repositories should be displayed in alphabetical order.

Listing

-------

Groups are displayed in accordion on the main page, accordion can be expanded to see all subgroups and repositories

in that group. It is neccessary to mention that in the accordion there are only repositories, i. e. projects with

repository information.

If no group matches the project the special section 'Other' is maintained with all such projects and repositories.

Select Box

----------

Using <optgroup> in select box displays all groups with their projects and repositories in the select box.

Special section 'Other' is also included for non-matched projects. Double click on the project leads to its xref

as usual (not working in IE) and double click in group name selects all projects in that group.

Method summary

--------------

Configuration.addGroup(Group group)

This method adds a group to the set of groups in the configuration. If the group name is not

unique accross the set, it throws an IOException and does not add that group.

Group.addGroup(Group group)

This method adds a group to the other group as its subgroup. It correctly sets the parent group

so that the whole structure can be traversed.

Property summary

----------------

String Group::name - displayed group name

String Group::pattern - regexp which is tested for each project

empty pattern implies that no project matches this group thus

it can be used as a superior group without repeating the projects

from subgroups

Other sample configuration

--------------------------

It is possible to include the same project in multiple groups. We could create also a structure like this:

ctags

| -- ctags 5.6

| | -- ctags-5.6

| | -- ctags-5.6-stable

| -- ctags 5.7

| | -- ctags-5.7

| -- ctags 5.8

| | -- ctags-5.8

apache

| -- apache-ant-1.9

opengrok

| -- opengrok-master

| -- opengrok-0.12-stable

java

| -- apache-ant-1.9

| -- opengrok-master

| -- opengrok-0.12-stable

C language

| -- ctags-5.6

| -- ctags-5.6-stable

| -- ctags-5.7

| -- ctags-5.8

with configuration like this:

<?xml version="1.0" encoding="UTF-8"?>

<java version="1.8.0_65" class="java.beans.XMLDecoder">

<object class="org.opensolaris.opengrok.configuration.Configuration" id="Configuration0">

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags</string>

</void>

<void property="pattern">

<string></string>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags 5.6</string>

</void>

<void property="pattern">

<string>ctags 5.6.*</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags 5.7</string>

</void>

<void property="pattern">

<string>ctags 5.7</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>ctags 5.8</string>

</void>

<void property="pattern">

<string>ctags 5.8</string>

</void>

</object>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>apache</string>

</void>

<void property="pattern">

<string>apache-.*</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>opengrok</string>

</void>

<void property="pattern">

<string>opengrok.*</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>java</string>

</void>

<void property="pattern">

<string>opengrok.*|apache-.*</string>

</void>

</object>

</void>

<void method="addGroup">

<object class="org.opensolaris.opengrok.configuration.Group">

<void property="name">

<string>C language</string>

</void>

<void property="pattern">

<string>ctags.*</string>

</void>

</object>

</void>

</object>

</java>