Configuring the Web Application

Layout of a PhiloLogic Web Application Instance

Each loaded database contains its own copy of the web application and data. Here is what the database directory looks like after a load:


database/
├── app/                    # Vue.js client application
│   ├── src/
│   │   └── assets/styles/
│   │       └── theme.module.scss
│   ├── dist/               # Built frontend (generated by npm run build)
│   ├── appConfig.json
│   ├── package.json
│   └── vite.config.js
├── data/
│   ├── db.locals.py        # Database-level settings
│   ├── web_config.cfg      # Web application configuration
│   ├── load_config.py      # Load-time configuration (read-only after load)
│   ├── frequencies/        # Word frequency data
│   ├── words.lmdb          # Word index (LMDB)
│   ├── toms.db             # Metadata (SQLite)
│   ├── TEXT/               # Source XML files
│   └── hitlists/           # Cached query results
├── custom_functions/       # User-defined Python functions
└── favicon.ico

There are three main sections:

  • The app/ directory contains the Vue.js web client. The src/ subdirectory has the source code, and dist/ contains the built production files served to browsers.
  • The data/ directory contains all indexes, LMDB databases, SQLite tables, and configuration files needed for search and retrieval.
  • The custom_functions/ directory allows you to override or extend the default server-side behavior with custom Python functions.

Modifying the behavior of the Web Application

To change the behavior of the Web Application, you should edit the web_config.cfg file contained in the data/ directory. Refer to the documentation contained in the file for editing options. Note that PhiloLogic uses the Python syntax in the config file.

Access control

There are two components in the built-in access control:

  • IP range check
  • user login

In order for access control to be turned on, you first need to set the access_control variable in web_config.cfg to True.

Once access control has been turned on, PhiloLogic will check the access_file variable which defines a file contained in the /data directory which will contain the domain names allowed as well as the IPs addresses to be blocked. If no such file is provided, access will be automatically granted.

Changing the Web Application theme

Changing the Web Application theme requires editing the theme.module.scss file which can be found in the database directory under app/src/assets/styles/.

The theme.module.scss file is a Sass stylesheet which uses global variables to define the main colors used in the web app. The key variables are:

$header-color: rgb(95, 2, 2);          // Navigation bar background
$button-color: rgb(173, 66, 66);       // Primary buttons, form elements
$button-color-active: rgba(160, 55, 55, 0.9);  // Active/hover state
$link-color: rgb(156, 60, 60);         // Hyperlinks and text accents
$passage-color: rgb(155, 65, 55);      // Search result highlights
$card-header-color: rgb(173, 66, 66);  // Card and table headers

Once you’ve edited the theme file, rebuild the web application by running the following command from the app/ directory:

npm run build

Configuring the aggregation report

The aggregation report (much like faceted browsing) sums up results from concordances by metadata fields. What it can also do is break-up results from any metadata field into smaller groups of results. For instance, you can get results grouped by author, and for each author, you can break up results by title, all within the same results page.

To configure the aggregation report, you need to modify the aggregation_report variable. This variable is a list where you define what groupings are possible. Below is an annotated example of such groupings:

Here’s a example of a database comprised of novels (with groupings done at the doc level):

aggregation_config = [
    {
        "field": "author",  # what metadata fieds is used for grouping results
        "object_level": "doc", # object level of the metadata field used for grouping
        "field_citation": [citations["author"]], # citation object used for citing this field
        "break_up_field": "title", # define by what metadata field the results can be further broken into
        "break_up_field_citation": [ # define the citation for the break-up field
            citations["title"],
            citations["pub_place"],
            citations["publisher"],
            citations["collection"],
            citations["year"],
        ],
    },
    {
        "field": "title",
        "object_level": "doc",
        "field_citation": [
            citations["title"],
            citations["pub_place"],
            citations["publisher"],
            citations["collection"],
            citations["year"],
        ],
        "break_up_field": None, # set to None if no break-up field (in this case titles are typically unique so doesn't make sense)
        "break_up_field_citation": None, # leave to None for citation as well.
    },
]

Here’s an example of a database containing articles (with groupings done rather at the div1 level):

aggregation_config = [
    {
        "field": "author",
        "object_level": "div1",
        "break_up_field": "head", # IMPORTANT NOTE: the break-up field MUST be of the same object level as the main metadata field used for grouping
        "field_citation": [citations["author"]],
        "break_up_field_citation": [
            citations["div1_head"],
            citations["class"],
        ],
    },
    {
        "field": "head",
        "object_level": "div1",
        "field_citation": [
            citations["div1_head"],
            citations["class"],
        ],
        "break_up_field": None,
        "break_up_field_citation": None,
    },
    {
        "field": "class",
        "object_level": "div1",
        "field_citation": [
            citations["class"],
        ],
        "break_up_field": "head",
        "break_up_field_citation": [citations["div1_head"], citations["author"]],
    },
]