S.J. Huskey's Blog

Git for Digital Humanities

2025-07-30T00:00:00Z

Version control is not only for keeping track of research data and files; it is also a potential safeguard against loss of information and a vital component in making research reproducible and, if done well, understandable.

Here are some tips I have developed for myself over the years:

Every DH research project should employ the distributed version control system Git for code and, in a separate repository, data.
- Concerns about the size of the dataset and its content (e.g., whether it contains protected, private, sensitive, or proprietary information) must dictate how the dataset is tracked.
- Use Git LFS for tracking large files (audio, video, large datasets, etc.).
A .gitignore file should be used judiciously to prevent sensitive, protected, or proprietary knowledge from being tracked by Git and pushed to remote repositories. A useful collection of ready-made .gitignore files can be found at https://github.com/github/gitignore.
Exercise great caution when tracking private or sensitive information with Git. If protected data is included in even one commit, it will be discoverable if the repository is publicly shared—even if the file is removed from later commits. Never fear, though. You can use git-filter-repo to, well, filter that mistake out of all commits and tags in your repo. You can also do this, but it's riskier.
Every Git repository should have a README.md file that provides basic information about the project.
Every Git repository should have a license clearly indicating whether the content can be shared, reused, repurposed, etc. The site https://choosealicense.com/ is a good resource for determining which license is appropriate.
Code repositories should include files (e.g., requirements.txt, environment.yml) that enable other researchers to use the same software versions that were used in the original project.
Commit messages should be thought of as a research journal, containing consistent and clear language. The Conventional Commits standard is worth following.e Not to toot my own horn, but I wrote an article on this subject. Don't follow this example: https://xkcd.com/1296/ 😉.
Milestones in the project should have annotated tags that follow an obvious system (e.g., Semantic Versioning), and those tags should be pushed to the remote repository.
Major milestones should be made citable with a service such as Zenodo.
Each project should have a remote repository on a platform such as GitHub, GitLab, or ideally an institutional repository.
Remote repositories should be set to private if they contain any information that should not be publicly available.

Photo by Gabriel Heinzer on Unsplash

Wrestling with Solr on Docker

2024-07-31T00:00:00Z

Every time I install and configure Apache Solr for a Drupal site, I find myself bogged down in a variety of issues, so I thought it would be helpful (if only to me) to record what I gleaned from the latest instance.

My History with Solr

My first experience with Solr was on the original Digital Latin Library Catalog site, which was on Drupal 7. I preparation for working with it, I read the extensive documentation. With all its talk of zookeepers, my confusion and trepidation grew quickly. Then I realized that Drupal's Search API Solr module took care of most, but certainly not all, of the difficulties. I still had to install and configure Solr, but I eventually managed to get it up and running. I wish that I had documented all the steps back then, but I was so relieved to have made progress that I moved on to something else.

My second experience with Solr was when I enhanced the search features on the website of the Society for Classical Studies. Since I am not the system administrator for the SCS, we paid the hosting company (the heroic and wonderful folks at EsoSoft) to spin up a Solr server. They opted to install Solr as a Docker container, so I had the opportunity to learn about managing Solr via docker commands. I wish that I had documented that experience, too, but I was eager to move on after I had a working setup.

When I started using the super-awesome DDEV for local development, I had to work with Solr again as a Docker container. In this instance, I did take the time to document the process.

Now that I have finished migrating the content of the DLL's Catalog site from Drupal 7 to Drupal 10 and rebuilding its theme, I need to move the site to my production server, and that involves upgrading Solr. Having learned my lesson from previous experiences, I'm going to document the process here.

Upgrading or Reinstalling Solr?

Since the server is currently configured for a Drupal 7 site, Solr wasn't the only item in need of an upgrade. I had to upgrade PHP, MariaDB, and Java, among other things. Fortunately, the dnf package manager made quick work of that.

I tried simply upgrading Solr, but I ran into a mess of conflicts and permissions issues, so I decided to uninstall it, remove it, and start with a clean slate. I had a decision to make: run Solr as an application on the server or as a Docker container? The latter has a lot to recommend it, particularly when it comes to maintenance and upkeep, so I decided to install it that way.

Solr in Docker

Apache's documentation on Solr in Docker is pretty good, as is the documentation for the Search API Solr module. But there are definitely gaps here and there, and I spent more hours than I care to admit trying to figure out how to fill them. It was a "non-trivial" number of hours. That's all I will say.

Installing Docker and Solr

To run Solr in Docker, you obviously need to have Docker on your server. That's easy. I'm using a Red Hat Linux server, so the dnf package manager can take care of it:

Make sure that dnf can find the Docker repository: sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
Install Docker, et al.: sudo dnf install -y docker-ce docker-ce-cli containerd.io
Start Docker: sudo systemctl start docker
Enable Docker (i.e., make sure that it will start automatically after rebooting): sudo systemctl enable docker

Grabbing the official Docker Solr image is not difficult, either: sudo docker pull solr:9.6.1.

Okay, I have all the components. Now what?

This is where the documentation becomes opaque, at least for me. It's clear enough if you just need to start a Solr server and get to work. If you need Drupal to connect to your Solr server, you have to hold your mouth just right. At least it seems that way.

The Search API Solr module makes you put the cart before the horse, as it were. That is, you have to create a server first, then connect Drupal to it. Only then can you download a configuration set and create the Solr core that you need to start indexing content.

So, the first step is to create a Solr server.

Creating a Solr Server

In the following steps, the Solr server I'm creating is dllsolr, and the core is dllcatsolr. You should be able to substitute your own values for those.

Since I'm going to run Solr in a Docker container, I need to use a docker command to create it: docker run -d -p 8983:8983 --name dllsolr solr

I'll break that down:

docker run is the command to create and run a container
-d causes the container to run in the background
p 8983:8983 maps the container to port 8983, which is the port often used for Solr
--name dllsolr gives the container the name dllsolr.
solr tells Docker to use the Solr image that I downloaded earlier

After running that command, Solr was running as a Docker container. Great! But Drupal wasn't able to connect to it because the Search API Solr module expects to use a username and password. To satisfy that requirement, I need to secure Solr with a security.json file.

Securing Solr

Fortunately, the DLL Catalog doesn't need most of the robust security measures available. I just need to add a security.json file to set up Basic Authentication. But even that's not a trivial affair.

At a minimum, a security.json file should look like this:

{
   "authentication":{
      "class":"solr.BasicAuthPlugin",
      "credentials":{"solr":"IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="}
   },
   "authorization":{
      "class":"solr.RuleBasedAuthorizationPlugin",
      "permissions":[{"name":"security-edit",
         "role":"admin"}],
      "user-role":{"solr":"admin"}
   }
}

That's directly from the Apache Solr documentation.

The really important part is this:

{
   "credentials":{"solr":"IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="}   
}

This is the line that establishes the credentials (obviously) needed to log on to the Solr server and perform operations. It's pretty clear that solr is meant to be the username, but the password needs some explaining. In this example, the password is actually "SolrRocks". But it wouldn't be safe to put that in plain text, so it must be "hashed" first. And you can't use just any tool to hash the password. I tried using a Python script with the bcrypt library to hash a password, but that didn't work. Well, it produced a hashed password, but it didn't work with Solr. I couldn't find any guidance in the Solr documentation about how to create the hash, so I did a search of the internet and found this wonderful tool: https://clemente-biondo.github.io. (Bless you, Clemente Biondo, whoever you are!) This client-side tool allows you to enter a password of your choice into a form and get a hashed password and a template for using it in a security.json file.

Okay, now that I had a hashed password in a security.json file, I had to get it into the Docker container. Here, again, you need to know a secret.

It's easy to copy files to and from a Docker container. As long as you know the ID of the container, you just use docker cp, as in docker cp myfile.txt DOCKERID:/path/to/directory. But if you just do that, the file you copy won't have the correct permissions, and there will be no way to change them or to remove the file after it is in the container. The answer is to use the -a switch on docker cp. That switch preserves (the "a" is for "archive") everything about the file's permissions and ownership and prevents it from being changed by Docker.

So, after hashing the password and adding it to security.json, copy it into the Solr Docker container like this: docker cp -a security.json 82fd162cad53:/var/solr/data.

I'll break that down:

docker cp tells Docker to copy something into or out of a container
-a: archive mode, to preserve the file's permissions from being modified by Docker
security.json is the name of the file to be copied from the server to the Docker container
82fd162cad53: is the ID of the Docker container. The ID can be discovered by doing docker ps.
/var/solr/data is the destination for the file in the Docker container.

Now, do docker restart dllsolr to put the security measure into effect.

Great! I have a Solr server running in a Docker container, and it is secured with basic authentication. Now I need to tell Drupal how to reach it.

Configure Search API Solr in Drupal

Important, time-saving advice: Before doing anything else, determine the IP address of the Docker container. This is a crucial piece of information for configuring Drupal to connect to the Solr server:

docker inspect -f "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}" dllsolr

Copy the IP address into a text file and keep it on hand.

Now, to start the process of creating a Solr "server" in Drupal, go to /admin/config/search/search-api in the Drupal site. I put "server" in quotation marks because we've already created the server. That's what everything above was about. It's more accurate to say that we're creating a connection to the Solr server.

Click "+Add server"
Enter a name for the server
Check the "Enabled" box (if it isn't already checked)
Enter a description
Select "Solr" as the Backend
In "Configure Solr backend", select "Basic Auth"

Now, in the "Configure Basic Auth Solr connector" submenu, do the following:

HTTP protocol: http
Solr host: Enter the IP address of the Docker container that you obtained earlier. You'll see some instructions that say you should enter localhost here. That's true if you're running Solr as an application (i.e., not in a Docker container). But if you're running Solr in a Docker container, you need the IP address.
Solr port: enter "8983"
Solr path: enter "/"
Solr core: enter the name of the core that you will create later. I'm using "dllcatsolr".

Leave everything else as it is, except for the HTTP basic authentication fields. Here you should enter the username from your security.json file (e.g., "solr") and the actual password (i.e., NOT THE HASH in the security.json file). If you entered "MYPASSWORD" in the hashing tool https://clemente-biondo.github.io/, enter "MYPASSWORD" in the password field here.

Click "Save". If all goes well, you should see a message that the Solr server could be reached. The Core Connection field, however, should say "The Solr core could not be accessed" (or something like that). That's because we still need to create a core on the Solr server.

Create a Solr Core

This is the most involved part of this whole process. The first step is to download a configuration set ("configset"):

Go to /admin/config/search/search-api in the Drupal UI
Click the name of your server
On the "View" page that should come up, click the button "+ Get config.zip" to download the configset (probably named something like solr_9.x_config.zip)

Now you need to upload the configset to your the server that hosts your site and your Solr Docker container. I use scp ("secure copy") to do that: scp solr_9.x_config.zip myuser@myserver:~/.

After logging on to your server:

Make a new director called "conf": mkdir conf.
Unzip the configset to the "conf" directory: unzip solr_9.x_config.zip -d conf
Copy the "conf" directory to Solr's home directory (/var/solr/data) in the Docker container: docker cp -a conf 82fd162cad53:/var/solr/data
Restart the Docker container: sudo systemctl restart dllsolr (replace dllsolr with the name of your Solr Docker container)

Now it's time to log on to the Solr Docker container and create the core:

Log on to the Docker container: docker exec -it dllsolr /bin/bash (replace dllsolr with the name of your Solr Docker container)
Create the core: /opt/solr/bin/solr create_core -c dllcatsolr -d conf

I'll break that last line down:

/opt/solr/bin/solr: This is the directory where Solr's commands are stored
create_core: This is one of the commands stored in /opt/solr/bin/solr
-c dllcatsolr: This tells Solr to name the core "dllcatsolr"
d conf: This tells Solr to use the configset that you downloaded from your Drupal site and copied to the Solr Docker container

If all goes well, you should now have a Solr core.

Make Sure Docker and Solr Restart Automatically

In the section on installing Docker above, I recommended doing sudo systemctl enable docker to make sure that Docker restarts automatically whenever the server is rebooted. We need to update the Solr Docker container to tell it to restart automatically, too. That can be done with docker update --restart always dllsolr (or whatever your Solr server is called). Now, both Docker and the Solr server should start up automatically whenever the system is rebooted.

Useful Commands

Some useful commands to know for managing Solr as a Docker container:

docker ps: Shows the ID of any running containers and their status, among other things
docker exec -it dllsolr /bin/bash: Get access to the container's shell
docker logs dllsolr: Outputs all the log entries for your Solr server. The output can be reduced to the most recent entries by piping it to tail: docker logs dllsolr | tail
curl http://localhost:8983/solr/admin/info/system: Check the status of the Solr server
curl http://localhost:8983/solr/admin/cores\?action\=STATUS\&core\=\dllcatsolr: Check the status of a core (the last value in the URL string)

Also, to find the IP address of the Docker container:

docker inspect -f "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' dllsolr

Image credit: The Blue Whale of Catoosa. Photo by Carol M. Highsmith - https://www.loc.gov/pictures/collection/highsm/item/2010630004/, Public Domain, https://commons.wikimedia.org/w/index.php?curid=20572688

Rebuilding A Theme, Part XII: Styling the Search Page

2024-07-24T00:00:00Z

Now that I have a search view and a template for displaying it (see part 11 of this series), I can begin styling it.

Here is what that looks like without any styling:

My goals are:

To display the search form prominently in the center of the page
To give the facets a background color and to remove the redundant bullets from the checkboxes
To make the display of results tidier and easier to read

I'll be working mostly in the style.scss file to accomplish those goals.

Search Form

First I'll center the search form's heading. Using my browser's web developer tools, I see that it has the following classes: views-exposed-form contextual-region block block-views block-views-exposed-filter-blockmain-solr-search-search. The last one is the most specific, so I'll use that:

.block-views-exposed-filter-blockmain-solr-search-search h2 {
  text-align: center;
  margin-bottom: 2rem;
}

Now I want to center the form. Using the web developer tools, I'll highlight the form and inspect its HTML and CSS. I see that the div enclosing it is currently subject to this:

.form--inline .form-item {
  float: left;
  margin-right: 0.5em;
}

Both the float and margin-right properties will interfere with any effort to center the form, so I'll need to override them. But I don't want to override them globally; I just want to override them in this one place. I'll do that by adding another one of the classes that I see on the div: form-type-search-api-autocomplete. Here's the CSS:

/* Centering the search box.*/
.form--inline .form-item.form-type-search-api-autocomplete {
  float: none;
  width: 75%;
  text-align: center;
  margin-left: auto;
  margin-right: auto;
}

That takes care of the float, and it uses the value of auto on margin-left and margin-right to center the div.

The helper text inside the input area is aligned to the left. It would look better aligned to the center. Since I don't want to style all input tags, I'll specify the input tag inside of the form with id="views-exposed-form-main-solr-search-search":

/* Centering the search terms */
#views-exposed-form-main-solr-search-search input {
  text-align: center;
}

Now I'll deal with the "Go" button. After some experimentation, I found that I could control the placement of the button by setting text-align on form with id="views-exposed-form-main-solr-search-search" to center. Since that is the same style for the search terms above, I can just add that selector to the existing style:

/* Centering the search terms and the "Go" button */
#views-exposed-form-main-solr-search-search,
#views-exposed-form-main-solr-search-search input {
  text-align: center;
}

Cool! Now I can move on to styling the facets and the search results.

Facets

The first thing I want to do is set a background color for the facets. I like the light blue color that I used for the sidebar in the templates for my content types, so I'll use that. When I created the page--search.html.twig template, I added the class search-sidebar to the div where the facets are placed. That means that I can set background-color on that div. I'll also give it some padding, so that the content isn't smooshed on all sides.

/* Search Sidebar (facets) */
.search-sidebar {
  background: #ade0f2;
  padding: 2rem 0.5rem 1.5rem 1rem;
}

The way I've handled padding is shorthand, by the way, for setting padding-top, padding-right, padding-bottom, and padding-left, in that order (i.e., clockwise).

I want the heading for the sidebar to be set off from the content, so I'll add a bottom border and some spacing:

/* Search sidebar h3 style */
.search-sidebar h3 {
  border-bottom: solid thin grey;
  padding-bottom: 0.5rem;
  margin-right: 2rem;
  margin-bottom: 1.25rem;
}

Now I need to remove the redundant bullets from the checkboxes and adjust for their removal. I can do that by specifying that li (list item) tags in the div with class search-sidebar should have their display property set to block.

/* Remove bullets from facet checkboxes */
.search-sidebar li {
  padding: 0;
  display: block;
  margin-left: 0;
}

While I'm at it, I'll add some spacing to the label, too:

/* Add some space between facet checkboxes and labels */
.search-sidebar label {
  margin-left: 0.5rem;
}

Now my facets sidebar is looking better!

On to the search results!

Search Results

I don't think the results require a lot of styling. To my admittedly untrained eye, the items in the list could benefit from a border to make them more distinct. I'll try adding a box shadow around them, too.

/* Search results */
#views-bootstrap-main-solr-search-search--2 article {
  border: thin solid grey;
  padding: 1rem;
  box-shadow: 0 0 5px rgba(0, 0, 0, 0.5);
}

The box-shadow might be over the top. I added it just as an example of what can be done with CSS. Here's a screenshot:

No, I don't like the box-shadow. Let's try giving a different background color to the odd items in the list. For this, I can use the nth-of-type(odd) pseudo-class. Since every result is a list item (li) in an unordered list (ul), and since each list item has the class list-group-item, I can apply a background color to the odd or even list items. For the record, I could also use a number (n) to specify every nth item. Here's what I ended up doing to give each odd item a grey background:

// Grey background for odd items in the search results
#views-bootstrap-main-solr-search-search--2 li.list-group-item:nth-of-type(odd) {
  background-color: #f6f7f8;
}

I also added another facet and selected a lighter shade of blue for the sidebar. Here's a screenshot:

Takeaways

I'm by no means a CSS guru, but I hope that I've demonstrated how powerful it is. With just a few properties and units in your toolbox, you can do quite a lot to change the look of your site.

Rebuilding A Theme, Part XI: Template for the Search Page

2024-07-22T00:00:00Z

After installing and configuring Solr and creating a search view and facets (see part 10 of this series), I can begin building the search page and the view of results.

To do that, I need to do create a page--search.html.twig template, use Twig Tweak to place the relevant blocks in the template, and style the components with CSS.

Extending the Existing Page Template

When I created the search view, I specified the path as /search. When I navigate to that page in my browser and inspect it with the web developer tools, I can see that Twig's file name suggestions list two options for the layout: page--search.html.twig and page.html.twig. The latter is currently active, so I'm going to make a new template with the name of the former in my subtheme's templates/layouts directory.

Since the search page will look different from other pages on the site, this is not just a matter of copying the content of page.html.twig and making some minor adjustments. Remember that page.html.twig covers practically everything you see on a given page: the header, the navbar, the content, and the footer. I don't want to repeat all that in my page--search.html.twig template, since that would mean that if I make any changes to the navbar, for example, I'd have to be sure that I made the changes in both page.html.twig and page--search.html.twig—and that's just wasting time! Fortunately, I can just make a couple of minor adjustments to my page.html.twig template to turn it into something I can extend with other templates.

Specifically, I'll enclose the <main> section with {% block main %} … {% endblock %}, and I'll enclose {{ page.content }} with {% block content %} … {% endblock %}. This is a nice feature of Twig that gives me the option to override a portion of a template. In other words, it is effectively a condition: "If another template extends this one, and if it has content, insert the content here; otherwise, just render the content of the current page."

Here's the new code for the relevant area of page.html.twig:

{% block main %}
 <main role="main">
  <a id="main-content" tabindex="-1"></a>
  {# link is in html.html.twig #}

  {%
  set sidebar_first_classes = (page.sidebar_first and page.sidebar_second) ? 'col-12 col-sm-6 col-lg-3' : 'col-12 col-lg-3'
  %}

  {%
  set sidebar_second_classes = (page.sidebar_first and page.sidebar_second) ? 'col-12 col-sm-6 col-lg-3' : 'col-12 col-lg-3'
  %}

  {%
  set content_classes = (page.sidebar_first and page.sidebar_second) ? 'col-12 col-lg-6' : ((page.sidebar_first or page.sidebar_second) ? 'col-12 col-lg-9' : 'col-12' )
   %}


  <div class="{{ b5_top_container }}">
   {% if page.breadcrumb %}
    {{ page.breadcrumb }}
   {% endif %}
   <div class="row g-0">
    {% if page.sidebar_first %}
     <div class="order-2 order-lg-1 {{ sidebar_first_classes }}">
      {{ page.sidebar_first }}
     </div>
    {% endif %}
    <div class="order-1 order-lg-2 {{ content_classes }}">
          {% block content %}
            {{ page.content }}
          {% endblock %}
    </div>
    {% if page.sidebar_second %}
     <div class="order-3 {{ sidebar_second_classes }}">
      {{ page.sidebar_second }}
     </div>
    {% endif %}
   </div>
  </div>
 </main>
{% endblock %}

Now I can focus on the content part in the page--search.html.twig template. If I make any adjustments to other parts of the page.html.twig template (e.g., the navbar), those will affect page--search.html.twig, too.

At the top of my page--search.html.twig template, I'll insert the following code:

{% extends 'page.html.twig' %}
    {% block content %}

    {% endblock %}

The first line shows that this template extends the default page template. The next lines signal that everything between after block content and endblock should be inserted into the corresponding content block in page.html.twig.

Now I can work on setting up my search page without worrying about inserting code for the navbar or any other part of the regular page structure.

Placing the Search Form

In the previous post, I described the process of creating a block for the exposed search form that is part of the search view. That is what I see when I look at my unstyled search page:

It's doing the job, but I don't like the fact that it's displaying the "No results" text ("Your search returned no results") when I haven't even searched for anything. Also, if I search for something, I want the form to remain at the top of the list of results so that I can do a new search.

The Twig Tweak module has a handy drupal_block() function that I can use to place the search block that I created earlier. First, though, I need to know the machine name for that block. The Twig Tweak Cheat Sheet tells me how to do that using drush: drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));". That gives me a list of all the blocks with their ID numbers. The one I'm looking for is views_exposed_filter_block:main_solr_search-search'.

With that information, I'll add this to my page--search.html.twig template:

{% if page.content %}
    <div class="page__content">
        {# Place the search form block #}
        {{ drupal_block('views_exposed_filter_block:main_solr_search-search') }}
    </div>
{% endif %}

After clearing the caches (drush cr) and reloading the page in my browser, I now see this:

But if I search for something, no results will be displayed, because the template doesn't yet have a place for results.

Search Results

I don't want my "No results" text to be displayed when I haven't searched for anything, so I need a way to control the initial view of the search page. I have a trick for that:

{# Don't display search results if there aren't any #}
    {% if drupal_view_result('main_solr_search', 'search') is empty %}
     <div></div>
    {% else %}…{% endif %}{}

The if statement makes use of Twig Tweak's drupal_view_result() function and displays an empty div if there aren't any results—and there won't be on the initial view of the search page!

When there are results, I want to display them, obviously, so here's what happens after the else statement:

<div class="container search-container">
    {# Render the search results #}
    <h3>Search Results</h3>
        {{ drupal_view('main_solr_search', 'search') }}
    </div>
{% endif %}

I use the Twig Tweak function drupal_view() function to display the results.

Facets

Solr is all about facets, but I haven't done anything about them yet. Fortunately, they're just Drupal blocks, so I can use the drupal_block() function again. First, I have to identify the facets I want to use, so I'll execute the drush command that I used earlier: ``drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));". The resulting list tells me that I wantfacet_block:content_typeandfacet_block:time_period` (at least for now).

I'd like to use a columnar layout for the search page, so that the facets are in a thin column on the left side of the screen, and the results are in a wider column to the right of that. Here's the code to accomplish that:

{% extends 'page.html.twig' %}
    {% block content %}
  {% if page.content %}
   <div class="page__content">
    {# Place the search form block #}
    {{ drupal_block('views_exposed_filter_block:main_solr_search-search') }}

    {# Don't display search results if there aren't any #}
    {% if drupal_view_result('main_solr_search', 'search') is empty %}
        <div></div>
    
    {% else %}
     <div class="container search-container">
      <div class="row">
       <div class="col-sm-3">
       {# Render the facets #}
        <div class="search-sidebar">
            <h3>Filter(s)</h3>
            <h4>Content type</h4>
            {{ drupal_block('facet_block:content_type') }}
            <h4>Time period</h4>
            {{ drupal_block('facet_block:time_period') }}
        </div>
       </div>
       
       {# Render the search results #}
       <div class="col-sm-9">
       <h3>Search Results</h3>
            {{ drupal_view('main_solr_search', 'search') }}
       </div>
      </div>
     {% endif %}
    </div>
   </div>
  {% endif %}
{% endblock %}

Here is what that looks like when I search for "Vergil":

It doesn't look great because I haven't done anything about styling it. That's in the next post.

Takeaways

The ability to extend a template is a great way to keep your theme's code easy to manage.
Twig Tweak functions make it really easy to place blocks, views, and other elements.
Using if statements can give you a lot of control over what is displayed on the screen.

Rebuilding A Theme, Part X: Solr

2024-07-19T00:00:00Z

The old Drupal 7 version of the DLL Catalog uses Apache Solr to provide faceted search. Since the search page and its results are important features on the DLL Catalog site, I need to install and configure Solr before I can continue rebuilding my theme.

Fortunately, that's relatively easy to do in DDEV, which I'm using to develop my theme locally. The ddev-solr repo has instructions for installation and configuration, but I'm going to document what I did, since I ran into some obstacles along the way.

Install DDEV Solr

Installation of ddev-solr boils down to these steps:

ddev get ddev/ddev-solr
ddev restart

Install Drupal Modules

Again, fortunately, the ddev-solr repo also has instructions for preparing a Drupal site for using Solr:

Install the Search API Solr module: composer require 'drupal/search_api_solr:^4.3'. That will cause a bunch of other things to be installed.
Enable the Search API Solr module: drush en -y search_api_solr. Again, this will cause some other modules to be installed, too. Be sure to enable the search_api_solr_admin module, too. It comes with the Search API Solr module, but it isn't installed automatically: drush en -y search_api_solr_admin. If you want autocomplete functionality, enable the Search API Solr Autocomplete module: drush en -y search_api_solr_autocomplete.
Install the Search API Autocomplete module, if you want search forms to have autocomplete functionality: composer require drupal/search_api_autocomplete, then drush en -y search_api_autocomplete.
Install the Facets module: composer require 'drupal/facets:^2.0', then drush en -y facets.

Since my theme is a subtheme of the Bootstrap5 theme, I'm also going to install the Views Bootstrap module. It will give me some nice options for rendering the search results.

Configure Solr

The documentation is a little hazy here, at least for me. The documentation for Solr uses the terms "core" and "collection," but the Search API Solr interface at /admin/config/search/search-api only gives you the option to add a new "server" or "index". I finally realized that a "server" in Search API Solr is really a "core" or a "collection", depending on which mode your installation of Solr is using (traditional = core; cloud = collection).

In any case, the first step is to create a server in Drupal's UI.

Create a server

Go to admin/config/search/search-api
Click "+Add Server". This will open a new page.
Enter a name into the "Server name" field and note the corresponding machine name to the right of the field. In my case, I named the server "DLL Catalog"; the machine name is dll_catalog.
Leave the "Enabled" box checked
Enter a description in the "Description" field
Under "Backend", choose "Solr"
In "Configure Solr backend", select "Solr Cloud with Basic Auth"
In "Solr node", insert "solr". Don't miss this step! If you leave it at "localhost", you'll run into a lot of trouble. I speak from experience!
In "Solr port", insert "8983"
"Solr path" should be just "/"
"Default Solr collection": Insert the name you want to use for your collection.
Leave everything else alone, but scroll down and enter "solr" in the "Username" field and "SolrRocks" in the "Password" field.
Click "Save".

You'll probably see some warning messages at this point. That's okay. They'll be handled by the next step. Also, the "Server Connection" field should say "The Solr server could be reached." The "Collection Connection" should say that the collection could not be accessed. That's because you haven't uploaded a configset yet. That's the next step.

Upload a configset

There are two ways to do this.

The easiest way is in the UI. If you enabled the search_api_solr_admin module, you should see a button "+Upload Configset". Click that. After a bit, you should see status messages that say "Successfully uploaded configset" and "Successfully created collection", with the name of your collection. Additionally, the "Collection Connection" should now say that the collection could be accessed.

You can also use drush on the command line. Navigate to your site's root directory (i.e., where your site is saved on your computer. Mine is in~/Sites/d10dllcat) and execute this command:ddev drush --numShards=1 search-api-solr:upload-configset SEARCH_API_SERVER_ID, replacingSEARCH_API_SERVER_ID with the machine name of your server (see above). In my case, the command looks like this:

ddev drush --numShards=1 search-api-solr:upload-configset dllcatalog

Create the Index

Solr needs something to search. That's the role of an index. I'm going to create an index for site-wide searching of my four main content types here.

Go to /admin/config/search/search-api in the UI.
Click "+Add index"
On the page that comes up, give the index a name in the "Index name" field. I'm using "DLL Catalog Search".
In the "Datasources" area, select "Content" to search the content of the site. There are several other options that you might wish to explore.
A warning message appeared at this point: "Configure the used datasources". In my case, a "Bundles" area appeared. I'm going to answer the question "Which bundles should be indexed?" with "Only those selected", since I don't want to include blog posts and basic pages.
In the "Bundles" checklist, I'm going to select "Author Authority", "DLL Work", "Item Record", and "Web Page".
I'll leave the "Languages" section alone, since I don't have multilingual content.
Under "Server", I'll select the server I created above: DLLCatalog.
I'll check "Enabled"
I'll enter a description in the "Description" box.
I don't need to do anything in "Index options" or "Solr specific index options".
Click "Save and add fields"

Selecting fields takes time and care. You have to make a lot of decisions about what is important to include in the search and how it should be indexed. Since my experience tells me that each site has different needs, I can't offer any general wisdom other than this: consider including the "Rendered HTML output" (rendered_item) along with other specific fields that you want to use as facets. "Content type" is another good one. If you want to use text fields as facets, make sure the "Type" is set to "String", since "Fulltext" will not work for facets. Unless you're a super genius, you'll probably have to tinker with this and revise the selection as you test the search functionality.

When you're finished with selecting fields, click "Save changes", then move on to the "Processors" tab. Again, the processors selected here will vary for each site.

You won't be able to do anything with the "Autocomplete" tab until you have set up a search view (see below).

Go back to the "View" tab and select "Queue all items for reindexing", then click "Index now" in the "Start indexing now" area.

Create a Display Mode for the Content

The search view that I'll create below will display either "Rendered Entity" or "Fields." I'd like to use "Rendered Entity" because I don't want to configure a bunch of individual fields. But I also don't want the view to display the full node for each result. The solution is to create a display mode.

Go to /admin/structure/display-modes in the UI
Click "View modes"
Click "+Add view mode"
Choose view mode entity type "Content"
Give the view mode a descriptive name (e.g., "Solr Search") and a description
Check the content types that the view mode should apply to
Click "Save"

Now it's time to indicate what will be displayed when different content types are rendered in the new view mode.

First, go to /admin/structure/types.

Now, for each content type that was specified when the view mode was created:

Click the arrow in the "Operations" column
Select "Manage display"
When the display window appears, select the new view mode's name
Drag and drop the field names into or out of the "Disabled" area according to your needs. Whatever is not in the "Disabled" area will appear on the screen when the content is rendered in the view mode, in the order in which it is listed in "Field".

Create a Search View

Go to /admin/structure/views in the UI and click "+Add view"

Add View

Give the view a name (e.g., "Main Solr Search") and a description
In "View Settings", in the "Show" dropdown menu, select the name of the index you created above (e.g., "Index DLL Catalog Search")
In "Page Settings", check "Create a page" and give the page a title and a path. I'm setting my title to "Search" and the path to search.
I'm going to select "Bootstrap List Group" of "Rendered entity" in the "Page display settings" area. I can change it later, if needed.
Click "Save and edit"

Views Interface

You'll need to do a lot of work here, so save early and save often. I'm going to break it down according to the columns of the Views interface.

First column

Title: You can change the title if you want. It isn't necessary unless you're going to have multiple displays in your view.

Format: I like to use the Bootstrap List Group here because it fits well with my overall use of the Bootstrap framework.

Show: I have used "Rendered Entity" or "Fields" here for different projects. In this one, I'm using "Rendered Entity" because I don't want to configure a bunch of individual fields. Instead, I'm going to use the view mode I created above. I'll click "Settings" and select the name of my new view mode for each of the content types listed.

Filter criteria: This is where you create the search box. This one requires a lot of configuration. To get started, click "Add" and select "Fulltext search". In the window that appears when you click "Apply and configure filter criteria" do the following:

Check "Expose this filter to visitors, to allow them to change it"
Check "Required"
Choose "Single filter" in "Filter type to expose"
Make a label and a description, if you wish
In "Operator", choose "Contains any of theses words" to ensure a greedy search
"Parse mode" should be set to "Multiple words"
If you want to give your users a hint, insert some text in "Placeholder" (e.g., "Enter your search term(s) …")
Set the "Minimum keyword length" to "1" to ensure that something has to be in the field to search

Second column

Page settings: Enter the path that you want for your search page. I chose search. Leave Menu and Administration theme alone.

Access: The default "Unrestricted" is fine, unless you want to restrict your search to certain users or roles.

Header: Click "Add" and select "Result summary". In the configuration window, enter "Displaying @start - @end of @total results. Use the filters to limit the results." Those placeholders will change as needed.

Footer: I leave this blank.

No results behavior: Click "Add" and select "Text area". In the configuration window, enter "Your search returned no results." You'll need to do some work with a Twig template later to keep that from showing up even before a user has performed a search.

Pager: Select "Full" and "Paged, 10 items".

Third column (Advanced)

Expland the column by clicking on the arrow next to "Advanced". There's no need to do anything in either the "Relationships" or the "Contextual filters" area.

Exposed form: Change "No" to "Yes" in "Exposed form in block". In "Exposed form style", select "Basic". In "Settings", I like to use "Go" as my "Submit button text". I don't check either of the boxes in this window, and I leave "Exposed sorts label" as it is.

Other:

Machine Name: "search"
Administrative comment: "None"
Use Ajax: "No"
Hide attachments in summary: "No"
Contextual links: "Shown"
Query settings: Check "Skip item access checks" and "Bypass access checks"
Caching: "Search API (none)"
CSS class: "search-index". I add this class so that I can do some styling later on.

Click "Save"

Create Facets

Now that you have a search view, you can go to /admin/config/search/facets in the UI and add some facets.

Click "+Add facet"
Select your search view's name in "Facet source"
Select a field that you want to use as a facet
Enter a name for the facet
Click "Save"

Now you need to configure the facet.

In the "Widget" area, I like to use "List of checkboxes" for most things, but the others can be good options depending on the use case.
In "List of links settings", I select all the boxes.
"Facet settings" includes a lot of options that will depend on the site's needs. The names make their functions more or less obvious.
Facet sorting: I tend to leave the default values, unless there's a special circumstance.
Click "Save"

Set Autocomplete

Go back to /admin/config/search/search-api and click on your index
Click the "Autocomplete" tab
Your search view's name should appear in a list. Check it.
Click "Save"

You should see a notice telling you to set the permissions for the search. Click on its link or go to /admin/people/permissions and filter on "search". Under "Search API Autocomplete", check "anonymous user" and "authenticated user" for the permission "Use autocomplete for the YOUR_SEARCH_NAME search." Click "Save permissions".

Enable and Place the Search Block

If you go to your-url.com/search now, you will probably see a mostly blank page. That is because the search block that you created when you made the search view has not been enabled and placed in a page.

Go to /admin/structure/block in the UI
Scroll down to "Main content" and click "Place block"
Filter by your search view's name. Mine was "Exposed form: main_solr_search-search"
Click "Place block"
I generally uncheck "Display title" and choose "Override title" so that I can specify the text I want to appear on the search page. I've settled on "Search".
In the "Visibility" area, click the "Pages" tab, enter "/" and the path of your search view on one line, then "/" and the path of your search view plus "/*" on a second line:

Click "Save block".

Summary

After all that, you should have a functioning search page, but you're not going to like how it looks. Here's mine:

That's because it hasn't been styled! In the next post(s)—it will probably take more than one—I'll write about making a display mode for search results, overriding the template for the search page, placing the facets, and styling the various elements.

Rebuilding A Theme, Part IX: Content Types, Continued

2024-07-18T00:00:00Z

As I mentioned in the last post, The DLL Catalog site has four main content types:

Author Authority: Nodes in this content type contain information about an author's authorized name, variations on the name, dates, and various identifiers.
DLL Work: This content type contains the title(s) of works.
Item Record: These nodes contain metadata for published editions of works.
Web Page: This content type is for internet pages that present the texts of works.

The site also makes use of the default Drupal content types Article (for blog posts and updates) and Basic Page (for static content).

The work I did on the Author Authority content type will be the starting place for working on the other content types. I'll start with DLL Work.

DLL Work

Nodes of the DLL Work content type on the old version of the site look like this:

Like the old Author Authority page, the old DLL Work page is based on Panels, but I don't want to use that module anymore. Fortunately, the layout of the two pages is very similar: two-columns of different widths and colors. My first step, then, is to make a copy of the node--author-authorities.html.twig template and name it node--dll-work.html.twig, according to the file name suggestions provided by Twig. Mutatis mutandis, here is the content of the new template:

{%
  set classes = [
    'node',
    'node--type-' ~ node.bundle|clean_class,
    node.isPromoted() ? 'node--promoted',
    node.isSticky() ? 'node--sticky',
    not node.isPublished() ? 'node--unpublished',
    view_mode ? 'node--view-mode-' ~ view_mode|clean_class,
  ]
%}
{{ attach_library('bootstrap5/node') }}
<article{{attributes.addClass(classes)}}>

 {{ title_prefix }}
 {% if label and not page %}
  <h2{{title_attributes}}>
   <a href="{{ url }}" rel="bookmark">{{ label }}</a>
  </h2>
 {% endif %}
 {{ title_suffix }}

 <div{{content_attributes.addClass('node__content')}}>
        <div class="container">
            <div class="row">
                {# Render the content of the DLL Work node in a thin column #}
                <div id="work-data" class="col-md-4 col-md-4 order-lg-2 order-md-2">
                    <h3>DLL Work Data</h3>
                    {{ content }}
                </div>
                {# Render the contextual views in a wider column #}
                <div id="work-contextual-views" class="col-md-8 order-lg-1 order-md-1">
                    {# Set the variable for the contextual filter #}
                    {% set arg_1 = node.field_dll_identifier.value %}
                    <div id="work-item-records">
                        <h3>Item Records</h3>
                        {{ drupal_view('contextual_view_for_dll_work', 'page_1', arg_1) }}
                    </div>
                    <div id="work-web-pages">
                        <h3>Texts on the Internet</h3>
                        {{ drupal_view('contextual_view_for_dll_work', 'page_2', arg_1) }}
                    </div>
                </div>
            </div>
        </div>
 </div>

</article>

The only things I changed are the values of the ID attributes on the div elements (e.g., from author-data to work-data) and the information for the contextual views. Everything else is the same.

Now I need to update my style.scss file. Since I'm going for the same basic look, I can piggy-back onto the styles I wrote for the Author Authority page. For example, to match the blue background and other formatting of the author-data column, I can just add #work-data to those blocks in style.css:

#author-data,
#work-data {
  background-color: #eaf7fb;
  padding-top: 1rem;
  margin-bottom: 1rem;
}

#author-data .field,
#work-data .field {
  margin-bottom: 1rem;
}

#author-data .field__label,
#work-data .field__label {
  text-transform: uppercase;
}

Note that I inserted a comma after the existing style, then added #word-data. I'll do the same thing to the other styles:

#author-contextual-views > div,
#work-contextual-views > div {
  margin-bottom: 3.5rem;
}

#author-data h3,
#author-contextual-views h3,
#work-data h3,
#work-contextual-views h3 {
  border-bottom: thin solid gray;
  background-repeat: no-repeat;
  background-position: left top;
  padding: 0 0 0.75rem 3rem;
}

#author-data h3 {
  background-image: url(/themes/custom/dll_catalog/images/authority-record-on-blue.svg);
}

#work-data h3 {
  background-image: url(/themes/custom/dll_catalog/images/dll-work-on-blue.svg);
}

#author-works .views-field-title {
  margin-bottom: 1rem;
}

#author-works h3 {
  background-image: url(/themes/custom/dll_catalog/images/dll-work-on-blue.svg);
}

#author-item-records h3,
#work-item-records h3 {
  background-image: url(/themes/custom/dll_catalog/images/item-record-on-blue.svg);
}

#author-web-pages h3,
#work-web-pages h3 {
  background-image: url(/themes/custom/dll_catalog/images/webpage-on-blue.svg);
}

After compiling the SCSS (sass scss/style.scss css/style.css && sass scss/ck5style.scss css/ck5style.css) and clear the caches (drush cr), this is what I see on my screen:

That was pretty easy!

Item Record

Comparatively speaking, the Item Record content type has a pretty straightforward display. Here's a screenshot of the old version:

Here's the same record on the new site, without any extra styling:

![New Item Record](/assets/images/front-end/content-item-record-new.png "New Item Record page).

I don't need to do much to it! Hooray!

I'll just transform the field labels to uppercase, adjust the spacing, and add the icon to the heading. The first two items are easy: I'll just add the id for the content type to the relevant styles in style.scss

#author-data .field,
#work-data .field,
#item-record .field {
  margin-bottom: 1rem;
}

#author-data .field__label,
#work-data .field__label,
#item-record .field__label {
  text-transform: uppercase;
}

Now I'll add the icon to the heading. When I started to work on this, I noticed an opportunity to make my CSS less redundant. Here's the CSS for the headings of Author Authority and DLL Work nodes:

#author-authority-title {
  background-image: url(/themes/custom/dll_catalog/images/authority-record-on-orange.svg);
  margin-bottom: 2rem;
  background-size: 2.75rem 2.75rem;
  background-repeat: no-repeat;
  background-position: left 8px;
  padding: 0.25rem 0 1rem 3.75rem;
}

#dll-work-title {
  background-image: url(/themes/custom/dll_catalog/images/dll-work-on-orange.svg);
  margin-bottom: 2rem;
  background-size: 2.75rem 2.75rem;
  background-repeat: no-repeat;
  background-position: left 8px;
  padding: 0.25rem 0 1rem 3.75rem;
}

The only difference between them is the value of background-image. Instead of making a third block for item-record-title, I'll make one block for the positioning of all three, then separate blocks for the background images:

#author-authority-title,
#dll-work-title,
#item-record-title {
  margin-bottom: 2rem;
  background-size: 2.75rem 2.75rem;
  background-repeat: no-repeat;
  background-position: left 8px;
  padding: 0.25rem 0 1rem 3.75rem;
}

#author-authority-title {
  background-image: url(/themes/custom/dll_catalog/images/authority-record-on-orange.svg);
}

#dll-work-title {
  background-image: url(/themes/custom/dll_catalog/images/dll-work-on-orange.svg);
}

#item-record-title {
  background-image: url(/themes/custom/dll_catalog/images/item-record-on-orange.svg);
}

Now, if I need to adjust the positioning of all three title areas, I can do it in one place.

After compiling the SCSS (sass scss/style.scss css/style.css && sass scss/ck5style.scss css/ck5style.css) and clear the caches (drush cr), this is what I see on my screen:

Web Page

I can repeat the process for the Web Page content type. Here's how a Web Page node appears on the old site:

And here is the same content on the new page, after I add the relevant ID values to the existing styles:

Takeaway

Repurposing existing templates and styles is a great way to save time and make your code more efficient! After investing time in styling the Author Authority content type, I was able to do the other three main content types in one morning!

Rebuilding A Theme, Part VIII: Content Types

2024-07-17T00:00:00Z

The DLL Catalog site has four main content types:

Author Authority: Nodes in this content type contain information about an author's authorized name, variations on the name, dates, and various identifiers.
DLL Work: This content type contains the title(s) of works.
Item Record: These nodes contain metadata for published editions of works.
Web Page: This content type is for internet pages that present the texts of works.

The site also makes use of the default Drupal content types Article (for blog posts and updates) and Basic Page (for static content).

The old site made heavy use of Panels, a module that took a point and click approach to content layout. It was useful at the time, but it was complicated and difficult to learn. It has been ported over to Drupal 10, but it now has serious competition from Gutenberg.

Rather than attempt to migrate the panel pages, I'm going to recreate the functionality with a combination of Drupal blocks and Twig. The advantage to this approach is that if there's another big migration in the future, my layouts won't be tied to a specific module that might or might not be ported over to the new version.

Author Authority

Here's a screenshot of an Author Authority page on the old site:

And here's a screenshot of the same Author Authority as migrated into Drupal 10:

Most of the Author Authority content on the old site is in a sidebar, while contextual views are pulling related DLL Work, Item Record, and Web Page content into Panels. Since I already recreated those contextual views in my new site (see Rebuilding A Theme, Part VII: Contextual Views), I'm ready to insert them into the templates for the Author Authority content type.

But first I need to deal with rendering the fields already in the Author Authority content type.

Node Fields

If I navigate to an Author Authority node and inspect it with my Developer Tools, I'll see that the current Twig template in use is node.html.twig.

<!-- FILE NAME SUGGESTIONS:
   ▪️ node--29982--full.html.twig
   ▪️ node--29982.html.twig
   ▪️ node--author-authorities--full.html.twig
   ▪️ node--author-authorities.html.twig
   ▪️ node--full.html.twig
   ✅ node.html.twig
-->

I also see that node--author-authorities--full.html.twig is one of the file name suggestions, so I'll go to the Bootstrap5 parent theme's templates/content directory, copy the content of node.html.twig, and create a new node--author-authorities--full.html.twig file in my subtheme's templates/content directory, which I have created beforehand. I've selected node-author-authories--full.html.twig instead of just node--author-authorities.html.twig because it is more specific. If I need to create other display modes for this content type, I'll need to make sure that the template I'm making now won't override them. It's always best to be as specific as you can be with your Twig template names—but not so specific that the template applies to only one specific node, like node--29982.html.twig would.

The node.html.twig template renders the content all at once with {{ content }}:

<div{{content_attributes.addClass('node__content')}}>
  {{ content }}
 </div>

In the old version of the site, I used a feature of the Panel layout to display select fields from the content. I can do that directly in Twig by building onto the {{ content }} variable. For example, if I want to display the "Authorized Name" field, I can do this: {{ content.field_authorized_name }}. That will display the field and its markup. If I just want the value of the field, I can do this: {{ node.field_authorized_name.value }}. Here's what happens if I replace {{ content }} with {{ content.field_authorized_name }} in my template:

But we put a lot of work into those metadata records, so I'm going to reverse course and display all the data points available. I think I'll render them in a column on the left side of the page, with the rest of the page reserved for the contextual views that show other records associated with the author.

To do that, I'll do something like what I did when I made three columns for the site's footer. There, I made three columns of equal width. Here, I'm going to make two columns of different widths.

Columns

Bootstrap's grid system is based on twelve columns. When I used three columns in the footer, I didn't specify their width, so they defaulted to four units: 4 + 4 + 4 = 12. But now I want a thin column for the metadata fields and a wider one for the contextual views. I can do that by adding a number value to the col class on div:

<div class="container">
  <div class="row">
    <div class="col-4">Thin column</div>
    <div class="col-8">Wide column</div>
  </div>
</div>

To give you an idea of what that looks like, here's a mock-up:

I'll insert the content into the first column and give it an id to make it easy to style.

<div class="container">
  <div class="row">
    <div id="author-data" class="col-4">{{ content }}</div>
    <div class="col-8">Wide column</div>
  </div>
</div>

And I'll use the {{ drupal_view() }} function from the Twig Tweak module to render my contextual views. Since the contextual views need context (obviously!), I'll need to supply the information they need. In this case, it's the value of the author's DLL Identifier. The Twig Tweak Cheat Sheet shows me almost all the details for doing that.

The example given looks like this: {{ drupal_view('who_s_new', 'block_1', arg_1, arg_2, arg_3) }}. It doesn't tell me that I have to set the values for the arguments. See below for the way to do that:

<div class="container">
  <div class="row">
    <div id="author-data" class="col-4">
      {{ content }}
    </div>
    <div id="author-contextual-views" class="col-8">
        
        
        <div id="author-works">
            <h3>Works</h3>
            {{ drupal_view('contextual_view_for_author_authority', 'page_1', arg_1) }}
        </div>
        <div id="author-item-records">
        <h3>Item Records</h3>
            {{ drupal_view('contextual_view_for_author_authority', 'page_2', arg_1) }}
        </div>
        <div id="author-web-pages">
            <h3>Texts on the Internet</h3>
            {{ drupal_view('contextual_view_for_author_authority', 'page_3', arg_1) }}
        </div>
    </div>
  </div>
</div>

With those functions in place, my Author Authority node now looks like this:

The content is being displayed, but it doesn't look very good because I haven't styled it.

Styling

I gave each of the different div elements an ID because that makes them easier to style on an individual basis, if I need to.

I'm going to give the author-data a background color of the light blue that is in the DLL's logo, and I'll insert a bit of padding at the top so that the content has some room to breathe:

#author-data {
  background-color: #eaf7fb;
  padding-top: 1rem;
}

I also want to insert some space between the fields for the sake of readability:

#author-data .field {
  margin-bottom: 1rem;
}

I like the way the field labels on the old site were in all capitals, so I'll do that:

#author-data .field__label {
  text-transform: uppercase;
}

Finally, I'd like to give the author-data section a header and use the icon for author authorities that the old theme included. To do that, I'll need to edit the node--author-authorities--full.html.twig template by inserting <h3>Author Data</h3> inside of <div id="author-data">. I will also need to make an image directory in my subtheme and add the image I need. After that, I can use CSS to add the image to the header:

#author-data h3 {
  background-image: url(/themes/custom/dll_catalog/images/authority-record-on-blue.svg);
  border-bottom: thin solid gray;
  background-repeat: no-repeat;
  background-position: left top;
  padding: 0 0 0.75rem 3rem;
}

Actually, since I want those last four properties to apply to h3 in the contextual-views column, too, I'll do this:

#author-data h3,
#author-contextual-views h3 {
  border-bottom: thin solid gray;
  background-repeat: no-repeat;
  background-position: left top;
  padding: 0 0 0.75rem 3rem;
}

And now my author-data heading can be styled like this:

#author-data h3 {
  background-image: url(/themes/custom/dll_catalog/images/authority-record-on-blue.svg);
}

I'll do something similar for the contextual views. First of all, I want to increase the space between the sections, so I'll use the margin-bottom property:

#author-contextual-views > div {
  margin-bottom: 3.5rem;
}

I already added #author-contextual-views h3 to the block for author-data h3 to make sure that the headings in this section have the same border. Now I will add the background images to the h3 tags for each contextual view:

#author-works h3 {
  background-image: url(/themes/custom/dll_catalog/images/dll-work-on-blue.svg);
}

#author-item-records h3 {
  background-image: url(/themes/custom/dll_catalog/images/item-record-on-blue.svg);
}

#author-web-pages h3 {
  background-image: url(/themes/custom/dll_catalog/images/webpage-on-blue.svg);
}

If I compile my SCSS (sass scss/style.scss css/style.css && sass scss/ck5style.scss css/ck5style.css) and refresh the caches (drush cr), I can see the outcome of this work:

The images are in place and the headings look okay, but I'm not wild about the look. On the old site, the blue side bar was on the right side of the page. I could just switch the order of the div elements and put the one with id="author-contextual-views" first, but that would cause trouble on smaller screen sizes, since the author data would be pushed to the very bottom of the screen, requiring the user to scroll and scroll to see it.

What's the solution? This might be a good place for Bootstrap's order class, which allows you to control the order in which elements are displayed on different screen sizes.

If I add order-lg-2 order-md-2 to the div with id="author-data" and order-lg-1 order-md-1 to the div with id="author-contextual-views, I can reverse the order in which the div elements will be displayed: order-lg-2 order-md-2 cause theauthor-data div to be displayed second (i.e., on the right side of the page) on large (lg) and medium (md) screens, but it will be displayed in its natural order on small and extra-small screens. Here's the new code:

<div class="container">
  <div class="row">
    <div id="author-data" class="col-4">
      {{ content }}
    </div>
    <div id="author-contextual-views" class="col-8">
        
        
        <div id="author-works">
            <h3>Works</h3>
            {{ drupal_view('contextual_view_for_author_authority', 'page_1', arg_1) }}
        </div>
        <div id="author-item-records">
        <h3>Item Records</h3>
            {{ drupal_view('contextual_view_for_author_authority', 'page_2', arg_1) }}
        </div>
        <div id="author-web-pages">
            <h3>Texts on the Internet</h3>
            {{ drupal_view('contextual_view_for_author_authority', 'page_3', arg_1) }}
        </div>
    </div>
  </div>
</div>

Here's a screenshot of the page viewed on a desktop screen:

Here it is on a tablet:

And here it is, with the columns in their natural order, on a phone:

Takeaways

It should be pretty clear that Bootstrap, Twig, and CSS are a powerful combination.

Bootstrap's grid system makes responsive content layout a breeze, as long as you remember that it's based on the number "12"
Twig gives you almost total control over where (and whether!) your content is placed on the screen. The Twig Tweak module adds a lot of extra functionality to Twig's already full feature set.
CSS gives you a log of control over the appearance of the content. With just a little knowledge of CSS, you can do quite a lot!

In the next post, I'll use my node--author-authorities--full.html.twig file and the CSS work that I did to theme the other content types.

Rebuilding A Theme, Part VII: Contextual Views

2024-07-16T00:00:00Z

When users come to an author's page on the DLL Catalog site, they should see all of the information about that author, plus links to related content such as works by that author, individual editions of those works, and web pages that contain the author's works.

Here's what that looks like on the old site:

I accomplished the lists of related content with contextual views. A contextual view is a feature of the powerful Views module, an interface for generating, obviously, views of content. The "contextual" part refers to the display of content depending on a specific context, like when a particular value (e.g., a node's ID) is in the page's URL.

Since there isn't a migration path for views, I must rebuild all of the site's views from scratch. Fortunately, it's a pretty easy job. I'll just go through the steps for showing works related to an author, since the others pretty much work the same way on my site.

Adding a View

I'll head over to the Views interface at admin/structure/views. From there I'll click "+Add view", which will take me to a form for creating my view:

View name: I like to be as systematic and descriptive as possible with view names, so I'm going to name this view "Contextual view for Author Authority: DLL Work". I'll also check the "Description" box and enter "A contextual view that displays DLL Work nodes related to a specific Author Authority".
View settings: I want to show "Content" of type "DLL Work". I don't really care how the content is sorted.
Page settings: I want to create a page, so I'll check this box. I can leave the default values in the other fields, but I want to select "HTML List" of "Titles (linked)" in the pulldown menus.
Block settings: I don't need to create a block, so I'll leave this unchecked.
Click "Save and edit"

Now I'll see the View interface:

Building a Relationship

Since establishing a relationship between DLL Work nodes and their corresponding Author Authority node is essential for this view (i.e., it's the contextual part), I'll go over to the "Advanced" part of the View interface first and click "Add" next to "Relationships". I want to select "Content referenced from field_author" so that I can have access to all of the fields of the Author Authority node associated with DLL Work through the "Author" field (field_author). Basically, this opens a window onto the associated Author Authority record, and I'll be able to grab practially any data from it. I'll click "Add and configure relationships". Now I'll check "Require this relationship" so that I won't get any unrelated content, then I'll click "Apply".

Providing Context

Now I can create the contextual part of the view. In the "Advanced" part of the View interface, I'll click "Add" next to "Contextual filters". In the window that opens, I'll select "DLL Identifier (field_dll_identifier)", since I want to view DLL Work nodes in the context of their author, each of which has a unique identifier. Now I'll click "Add and configure contextual filters". In the new window, I'll select "field_author: Content" from the Relationship dropdown, to make sure that the context is dependent upon that relationship. Now, sometimes there aren't any works to display, so I need a way to handle that. That's where the "When the filter value is NOT available" part comes in handy. I'll select "Display contents of 'No results found'". Later, I'll go to the "No results behavior" area of the Views interface and add a text field with the content <p><em>No records have been entered for this author at this time.</em></p>. That way, the user will see something if there aren't any records to display. Now I'll click "Apply" to, well, apply those settings.

Testing

Now I can test the contextual view. The Views interface has a handy "Preview" feature. I'll scroll down to that part and enter the DLL Identifier for Virgil (A4830) in the "Preview with contextual filters" field. This is what I see after clicking "Update preview":

It works! The DLL Works related to Virgil—and only those DLL Works—are listed.

Fine-tuning

For a contextual view to work, it needs a placeholder (e.g., %) in its URL. I'll go to the "Page Settings" part of the Views interface and click on "Path:". Now I'll insert /% at the end of the URL (e.g., contextual-view-for-author-authority-dll-work/%). Now I'll be able to use the DLL identifier in the Twig template for the Author Authority content type to filter this view.

I also want to be sure to list all of the works without relying on a pager. I'll go down to the "Pager" section and click on "Mini", the default value for "Use pager:". Now I'll select "Display all items" and click on "Apply". I'll click "Apply" again in response to the next window about offset values. The "Use pager:" field should now have the values "Display all items | All items".

I'll click "Save" now and move on to creating my other contextual displays. I can easily do that from the same Views interface I've been working on in this post. I just click "+Add" in the Views interface and select "Page" to create a copy of the display that I have just made. I'll change "Content: Content type (= DLL Work)" in the "Filter Criteria" section to "Content: Content type (= Item Record)". Now the relationship and contextual filter I created previously will apply to this display, too, only this time it will display "Item Record" content. I need to change the URL, too.

Note: When changing the filter criteria, select "This page (override)" in the "For" dropdown at the top of the window. Otherwise, whatever you do will apply to EVERY display in the View.

Another note: Give your pages distinctive names by clicking the "Display name" link and entering something descriptive. That makes managing the site much easier.

I might have to come back to this view when I start to work on theming the content type that will use it, but at least it does what I need it to do for now.

Takeaway

Views is a powerful, extremely useful feature of Drupal. It's no wonder that it became a part of Drupal's core starting with version 8. Relationships and contexts make Views even more versatile, since they make it easy to connect content on a Drupal site in a dynamic way.

Rebuilding A Theme, Part VI: Customizing the Footer

2024-07-15T00:00:00Z

The footer on the old Drupal 7 version of the DLL Catalog site looks like this:

After migration to Drupal 10, this is what the footer looks like without any extra theming:

I kind of like the darker gray, so I'll keep it. But I need to restore the footer menu, the contact information, and the social media icons and links.

Inspecting the Structure of the Footer

Using the Developer Tools, I see that the footer is handled by a number of different templates, but region.html.twig is the one responsible for the overall structure. Since I want to have three columns in my footer (one each for navigation, social media, and contact information), I'm going to use Twig's file name suggestion and create a new template in my subtheme's templates/layouts directory called region--footer.html.twig. I'll copy the contents of Bootstrap5 parent theme's region.html.twig file as a starting place and customize it for my purposes.

Creating a Three-column Layout

My new region--footer.html.twig template looks like this:

{%
  set classes = [
    'region',
    'region-' ~ region|clean_class,
  ]
%}
{% if content %}
  <div{{ attributes.addClass(classes) }}>
    {{ content }}
  </div>
{% endif %}

To create the three-column layout, I'll focus on the part between the if content and endif tags.

In Bootstrap, columns are easy to make: we need a div with class container, another div inside that with class row, and then divs with class col inside of that. So, here's my customized template, with some placeholder text:

{%
  set classes = [
    'region',
    'region-' ~ region|clean_class,
  ]
%}

  <div{{ attributes.addClass(classes) }}>
    <div class="container">
      <div class="row align-items-start">
        <div class="col">
          <p>First column</p>
        </div>
        <div class="col">
          <p>Second column</p>
        </div>
        <div class="col">
          <p>Third column</p>
        </div>
      </div>
    </div>
  </div>

After clearing the caches, this is what it looks like:

That's a start. I want the first column to have a footer navigation menu, and I'd like to use that to point users to other parts of the DLL's corner of the internet. In my case, the footer menu from the old site came over in the migration, so I can simply place the menu into the first column with some help from the Twig Tweak module.

Place an Existing Menu

The first step in placing a menu into a template is finding the machine name for the block. The simplest way to do this is in the UI:

Go to admin/structure/menu in your site
Look for the menu you want and click "Edit menu"
Copy whatever is in the "Machine name" field. In my case, it was menu-footer-menu.

When you have the machine name of your block, add it to the Twig template like this:

{{ drupal_menu('menu-footer-menu') }}

In my case, I did this:

{%
  set classes = [
    'region',
    'region-' ~ region|clean_class,
  ]
%}

  <div{{ attributes.addClass(classes) }}>
    <div class="container">
      <div class="row align-items-start">
        <div class="col">
          {{ drupal_menu('menu-footer-menu') }}
        </div>
        <div class="col">
          <p>Second column</p>
        </div>
        <div class="col">
          <p>Third column</p>
        </div>
      </div>
    </div>
  </div>

That does the trick for my footer navigation menu:

Social Icons

I like to use Nifty Buttons for social media icons. It makes the job easy and quick with a very simple workflow. I need icons for Facebook, Twitter (a.k.a. "X"), and YouTube, so I'll go to Nifty Buttons and select my icons, choose the background shape, customize the colors, and add the links to the social media feeds. I choose to donate to the developer, so after I take care of that, I get my code:

<!-- Social Media Icons by NiftyButtons https://niftybuttons.com -->
<div style="display: grid">
  <a
    href="https://www.facebook.com/digitallatin"
    target="_blank"
    rel="noopener noreferrer"
    style="text-decoration:none;border:0;width:36px;height:36px;padding:0;margin:3px;color:#fff;"
  >
    <svg
      class="niftybutton-facebook"
      style="display:block;fill:currentColor"
      data-donate="true"
      data-tag="fac"
      data-name="Facebook"
      viewbox="0 0 512 512"
      preserveaspectratio="xMidYMid meet"
    >
      <title>Facebook social icon</title>
      <path
        d="M211.9 197.4h-36.7v59.9h36.7V433.1h70.5V256.5h49.2l5.2-59.1h-54.4c0 0 0-22.1 0-33.7 0-13.9 2.8-19.5 16.3-19.5 10.9 0 38.2 0 38.2 0V82.9c0 0-40.2 0-48.8 0 -52.5 0-76.1 23.1-76.1 67.3C211.9 188.8 211.9 197.4 211.9 197.4z"
      ></path>
    </svg>
  </a>
  <a
    href="https://x.com/digitallatin"
    target="_blank"
    rel="noopener noreferrer"
    style="text-decoration:none;border:0;width:36px;height:36px;padding:0;margin:3px;color:#fff;"
  >
    <svg
      class="niftybutton-twitter"
      style="display:block;fill:currentColor"
      data-donate="true"
      data-tag="twi"
      data-name="Twitter"
      viewbox="0 0 512 512"
      preserveaspectratio="xMidYMid meet"
    >
      <title>Twitter social icon</title>
      <path
        d="M419.6 168.6c-11.7 5.2-24.2 8.7-37.4 10.2 13.4-8.1 23.8-20.8 28.6-36 -12.6 7.5-26.5 12.9-41.3 15.8 -11.9-12.6-28.8-20.6-47.5-20.6 -42 0-72.9 39.2-63.4 79.9 -54.1-2.7-102.1-28.6-134.2-68 -17 29.2-8.8 67.5 20.1 86.9 -10.7-0.3-20.7-3.3-29.5-8.1 -0.7 30.2 20.9 58.4 52.2 64.6 -9.2 2.5-19.2 3.1-29.4 1.1 8.3 25.9 32.3 44.7 60.8 45.2 -27.4 21.4-61.8 31-96.4 27 28.8 18.5 63 29.2 99.8 29.2 120.8 0 189.1-102.1 185-193.6C399.9 193.1 410.9 181.7 419.6 168.6z"
      ></path>
    </svg>
  </a>
  <a
    href="https://www.youtube.com/@DigitalLatinLibrary"
    target="_blank"
    rel="noopener noreferrer"
    style="text-decoration:none;border:0;width:36px;height:36px;padding:0;margin:3px;color:#fff;"
  >
    <svg
      class="niftybutton-youtube"
      style="display:block;fill:currentColor"
      data-donate="true"
      data-tag="you"
      data-name="YouTube"
      viewbox="0 0 512 512"
      preserveaspectratio="xMidYMid meet"
    >
      <title>YouTube social icon</title>
      <path
        d="M422.6 193.6c-5.3-45.3-23.3-51.6-59-54 -50.8-3.5-164.3-3.5-215.1 0 -35.7 2.4-53.7 8.7-59 54 -4 33.6-4 91.1 0 124.8 5.3 45.3 23.3 51.6 59 54 50.9 3.5 164.3 3.5 215.1 0 35.7-2.4 53.7-8.7 59-54C426.6 284.8 426.6 227.3 422.6 193.6zM222.2 303.4v-94.6l90.7 47.3L222.2 303.4z"
      ></path>
    </svg>
  </a>
  <a
    href="https://catalog.digitallatin.org/rss"
    target="_blank"
    rel="noopener noreferrer"
    style="text-decoration:none;border:0;width:36px;height:36px;padding:0;margin:3px;color:#fff;"
  >
    <svg
      class="niftybutton-rss"
      style="display:block;fill:currentColor"
      data-donate="true"
      data-tag="rss"
      data-name="RSS"
      viewbox="0 0 512 512"
      preserveaspectratio="xMidYMid meet"
    >
      <title>RSS icon</title>
      <path
        d="M201.8 347.2c0 20.3-16.5 36.8-36.8 36.8 -20.3 0-36.8-16.5-36.8-36.8s16.5-36.8 36.8-36.8C185.3 310.4 201.8 326.8 201.8 347.2zM128.2 204.7v54.5c68.5 0.7 124 56.3 124.7 124.7h54.5C306.7 285.3 226.9 205.4 128.2 204.7zM128.2 166.6c57.9 0.3 112.3 22.9 153.2 63.9 41 41 63.7 95.5 63.9 153.5h54.5c-0.3-149.9-121.7-271.4-271.6-271.9V166.6L128.2 166.6z"
      ></path>
    </svg>
  </a>
</div>

That's cool, but I made some alterations. For one, that's a lot of CSS in the style attribute, and it's repeated four times. I like to keep my code "DRY" ("Don't Repeat Yourself"), as much as possible, so I've copied the content of style on a into a class in my subtheme's style.scss file and replaced the entire style attribute string with class="social-icon". In my style.scss file, I added this:

.social-icon {
  text-decoration: none;
  border: 0;
  width: 36px;
  height: 36px;
  padding: 0;
  margin: 3px;
  color: #fff;
}

I also didn't want my icons to be on one line, but rather stacked vertically. To accomplish that, I replaced the style of the parent div with display: grid. That's all it took! Here's the footer with the social icons:

Contact Information

For the contact information, I'm going to use a Drupal block. I could hard code it into the template, but hard-coding text is to be avoided, if possible, because it makes it difficult for future developers to track down. It's best to leave content in the Content Management System and reserve cosmetics for the theme.

As it happens, my footer contact block was included in the migration, so I don't have to do much. To create a custom block, go to admin/content/block in the UI and select "+Add content block". Add a description of the block in the "Block description" field and then insert the content into the "Body" field and click "Save".

I need to find the ID of my footer contact block. The simplest way to do that is in the UI:

Go to admin/content/block
Click the link for the block that you want
Look at the URL in the browser: the ID is the last part of the address.

My footer contact block has ID "2", so now I can insert the following into my Twig template:

{{ drupal_entity('block_content', 2) }}

Here's the code for the final column of my footer:

<div class="col">
  {{ drupal_entity('block_content', 2) }}
</div>

Here's how it looks:

Almost done!

Copyright

On the old site, the copyright statement was just a simple text string: "© Copyright 2024 Digital Latin Library". That's okay, but it means that I have to be sure to update the year each January 1. Since I often forget to do that, I'm going to automate it with a Twig filter.

Twig has a ton of built-in functionality, including a date filter that, obviously, renders the date based on the information provided by the server. You can learn all about Twig filters at https://twig.symfony.com/doc/3.x/.

In this simple case, I'm going to add this to the div that contains my site's contact information:

<div id="copyright">
  © {{ 'now' | date('Y') }} Digital Latin Library
</div>

That translates to "get the current date and show only the year."

After clearing the cache, this is how my footer looks:

Adding a Hint of Pizzazz

It's nice to show users which links are active, so I'm going to add some CSS to make the links change color when a user hovers the mouse over them:

footer.footer-dark a:hover,
.social-icon a:hover {
  color: #a33701;
}

Now the links turn a reddish-brown color on hover.

Making the Footer More Responsive

The footer looks okay on large and medium devices, but it's going to run into trouble on small screens because the columns are going to be scrunched into each other. I'd prefer them to be stacked on top of each other instead, so I'll edit their class to col-md. The md stands for medium, and it refers to the breakpoint at which stacking will cease to occur. My final code for the footer looks like this:

{%
  set classes = [
    'region',
    'region-' ~ region|clean_class,
  ]
%}

<div{{ attributes.addClass(classes) }}>
  <div class="container">
    <div class="row align-items-start">
      <div id="footer-menu" class="col-md">
      {# Insert the footer menu. #}
        {{ drupal_menu('menu-footer-menu') }}
      </div>
      <div id="social-media-icons" class="col-md">
        <!-- Social Media Icons by NiftyButtons https://niftybuttons.com -->
        <div style="display: grid">
          <a href="https://www.facebook.com/digitallatin" target="_blank" rel="noopener noreferrer" class="social-icon">
            <svg class="niftybutton-facebook" style="display:block;fill:currentColor" data-donate="true" data-tag="fac" data-name="Facebook" viewbox="0 0 512 512" preserveaspectratio="xMidYMid meet">
              <title>Facebook social icon</title>
              <path d="M211.9 197.4h-36.7v59.9h36.7V433.1h70.5V256.5h49.2l5.2-59.1h-54.4c0 0 0-22.1 0-33.7 0-13.9 2.8-19.5 16.3-19.5 10.9 0 38.2 0 38.2 0V82.9c0 0-40.2 0-48.8 0 -52.5 0-76.1 23.1-76.1 67.3C211.9 188.8 211.9 197.4 211.9 197.4z"></path>
            </svg>
          </a>
          <a href="https://x.com/digitallatin" target="_blank" rel="noopener noreferrer" class="social-icon">
            <svg class="niftybutton-twitter" style="display:block;fill:currentColor" data-donate="true" data-tag="twi" data-name="Twitter" viewbox="0 0 512 512" preserveaspectratio="xMidYMid meet">
              <title>Twitter social icon</title>
              <path d="M419.6 168.6c-11.7 5.2-24.2 8.7-37.4 10.2 13.4-8.1 23.8-20.8 28.6-36 -12.6 7.5-26.5 12.9-41.3 15.8 -11.9-12.6-28.8-20.6-47.5-20.6 -42 0-72.9 39.2-63.4 79.9 -54.1-2.7-102.1-28.6-134.2-68 -17 29.2-8.8 67.5 20.1 86.9 -10.7-0.3-20.7-3.3-29.5-8.1 -0.7 30.2 20.9 58.4 52.2 64.6 -9.2 2.5-19.2 3.1-29.4 1.1 8.3 25.9 32.3 44.7 60.8 45.2 -27.4 21.4-61.8 31-96.4 27 28.8 18.5 63 29.2 99.8 29.2 120.8 0 189.1-102.1 185-193.6C399.9 193.1 410.9 181.7 419.6 168.6z"></path>
            </svg>
          </a>
          <a href="https://www.youtube.com/@DigitalLatinLibrary" target="_blank" rel="noopener noreferrer" class="social-icon">
            <svg class="niftybutton-youtube" style="display:block;fill:currentColor" data-donate="true" data-tag="you" data-name="YouTube" viewbox="0 0 512 512" preserveaspectratio="xMidYMid meet">
              <title>YouTube social icon</title>
              <path d="M422.6 193.6c-5.3-45.3-23.3-51.6-59-54 -50.8-3.5-164.3-3.5-215.1 0 -35.7 2.4-53.7 8.7-59 54 -4 33.6-4 91.1 0 124.8 5.3 45.3 23.3 51.6 59 54 50.9 3.5 164.3 3.5 215.1 0 35.7-2.4 53.7-8.7 59-54C426.6 284.8 426.6 227.3 422.6 193.6zM222.2 303.4v-94.6l90.7 47.3L222.2 303.4z"></path>
            </svg>
          </a>
          <a href="https://catalog.digitallatin.org/rss" target="_blank" rel="noopener noreferrer" class="social-icon">
            <svg class="niftybutton-rss" style="display:block;fill:currentColor" data-donate="true" data-tag="rss" data-name="RSS" viewbox="0 0 512 512" preserveaspectratio="xMidYMid meet">
              <title>RSS icon</title>
              <path d="M201.8 347.2c0 20.3-16.5 36.8-36.8 36.8 -20.3 0-36.8-16.5-36.8-36.8s16.5-36.8 36.8-36.8C185.3 310.4 201.8 326.8 201.8 347.2zM128.2 204.7v54.5c68.5 0.7 124 56.3 124.7 124.7h54.5C306.7 285.3 226.9 205.4 128.2 204.7zM128.2 166.6c57.9 0.3 112.3 22.9 153.2 63.9 41 41 63.7 95.5 63.9 153.5h54.5c-0.3-149.9-121.7-271.4-271.6-271.9V166.6L128.2 166.6z"></path>
            </svg>
          </a>
        </div>
      </div>
      <div id="contact" class="col-md">
        {{ drupal_entity('block_content', 2) }}
        <div id="copyright">
          © {{ 'now' | date('Y') }} Digital Latin Library
        </div>
      </div>
    </div>
  </div>
</div>

On small screens, the footer now looks like this:

Takeaways

Making a columnar layout is easy with Bootstrap
The Twig Tweak module makes it easy to place Drupal menus and blocks wherever you need to place them, if you know how to find the information you need
Nifty Buttons is an excellent source for social media icons
Twig functions can interact with the server to get the current date
Bootstrap's col style can be enhanced with breakpoints (e.g., col-md) to tell browsers to display the content differently according to screen size

In the next post, I'll work on the contextual views I'll need before I work on styling the content types.

Rebuilding A Theme, Part V: Customizing the Navbar

2024-07-12T00:00:00Z

Bootstrap's Navbar

I could spend a long time reinventing the wheel or implementing a snazzy navigation bar, but I don't have that kind of time, and I'm not a professional graphic designer. I want something simple that just works. Fortunately, Bootstrap's navbar has me covered. The trade-off is that my site's navbar will look like other sites made with Bootstrap, but that's okay with me. The ease of implementing a responsive navbar more than makes up for it.

Still, there are things I can do to make my site distinctive. That's the subject of this post.

My Navbar Without Styling

As a reminder, after I changed the background color of the navbar in the last post, my site's header looked like this:

Logo

The name of the site and its logo are handled by the "branding block". My subtheme of Bootstrap5 came with a logo.svg (= Scalable Vector Graphic, a particularly good format for images that must be used in different places with different sizes), a favicon.ico file, and a screenshot.png file to display in the "Appearance" menu of Drupal's user interface. My first task is to replace them with the DLL's files.

I happened to have those files from a previous version of the site, so I dropped them into the subtheme's root directory. Since the "Appearance" menu of my site is already set to use the theme's logo and shortcut icon, I just cleared the caches (drush cr), and voilà:

Site Name

As the last screenshot shows, I now have a logo that says "Digital Latin Library" and some text that says "DLL CATALOG" in big, chunky letters. I want the text to match or at least resemble the text on the old site:

I can do this with some CSS code. Using my browser's Developer Tools, I inspect the site's name and find that it has the class "site-title":

<a href="/" title="Home" rel="home" class="site-title">DLL Catalog</a>

The CSS window shows that the following code applies to that class:

font-size: 1.5rem;
font-weight: bold;
letter-spacing: 2px;
text-transform: uppercase;

If I remove the font-weight and text-transform properties, my site's name looks like this:

That's better, but not quite what I want yet. If I bump the font-size up to 2rem and set the font-weight to lighter, it looks good enough for my purposes.

We're almost there, but there's a problem: on smaller screens (e.g., tablets and phones), the 2rem font size will be out of proportion to the logo, which will scale down as the screen size decreases. Instead of specifying separate sizes for tablets and phones, I can use the value larger, which is proportional. I'll also use a media query to make the value change according to screen size:

/* Change the appearance of the site's name */

.navbar-brand .site-title {
  font-size: larger;
  font-weight: lighter;
  letter-spacing: 2px;
  text-transform: none;
}

/* Media query for large screens */
@media (min-width: 992px) {
  .navbar-brand .site-title {
    font-size: 2rem;
  }
}

Now, as we'll see below, the font size of the site's name changes in proportion to the screen size. That's an improvement from the standpoint of accessibility, since the site's name in the old version was part of an image file. Now it is in plain text for anyone to read, however they might read it.

Menus

Just looking at the screenshot above, it's clear that the navigation menu is out of control. The old site had menus with sub menus leading to pages on the other sites in the DLL's domain. There was a point to that: to make sure that users understood where they were in the DLL's corner of the internet. After all, we have the main informational site (https://digitallatin.org/), the online reading interface for Library of Digital Latin Texts (https://ldlt.digitallatin.org/), and the DLL Catalog (https://catalog.digitallatin.org/), so it is important to provide some signposting for users. But the way we were doing it on the old version of the catalog site made the navigation far too busy and cluttered. Besides, it's best to keep a site's main navigation menu simple so that it will be easy to use on mobile, tablet, laptop, and desktop devices. Moreover, dropdown submenus have to be styled, and that is a tedious job.

Fortunately, clearing up the main navigation menu is simple. When I migrated the site to Drupal 10, all the menus were included. That means that I can go into the "Menus" interface (/admin/structure/menu) and turn off or delete any items I don't want to appear in the new version.

For now, I'll disable all the main menu items:

The navbar still has the user menu ("My Account" and "Log Out" for logged-in users) and a search bar. I don't need the user menu, since users don't need accounts to use the site, and I can log in using /user/login whenever I need to. I also plan to make the search bar a much more prominent part of the site, so I can get rid of that, too. In this case, instead of disabling those menu items, I'll edit the Twig template page.html.twig, which has this code near the top:

<button
  class="navbar-toggler collapsed"
  type="button"
  data-bs-toggle="collapse"
  data-bs-target="#navbarSupportedContent"
  aria-controls="navbarSupportedContent"
  aria-expanded="false"
  aria-label="Toggle navigation"
>
  <span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse justify-content-md-end" id="navbarSupportedContent">
   {{ page.nav_main }} {{ page.nav_additional }} 
</div>

The user menu and search bar are included in {{ page.nav_additional }}, so if I remove that line, I'll have this:

Now I can think more clearly about what I want in that space. The old site had a secondary menu with links relevant to the DLL Catalog:

It would make a lot more sense to put that into the main navigation space. So, I'll go into the "Menus" interface (/admin/structure/menu) edit the "Main menu" (/admin/structure/menu/manage/main), et voilà:

What's more, without having to do anything extra (other than the media query I mentioned above), my navbar responds well to different screen sizes. I can do a quick check with my browser's "Developer Tools" if I click on the icon that looks like a phone next to a tablet. That opens up a new menu that lets me emulate the appearance of my site on numerous devices of different shapes and sizes.

Here is my navbar on a tablet:

And here it is on a phone:

In both cases, the menu turns into a "hamburger menu" that will expand when clicked:

I didn't have to write any code to make that happens, since it is baked into Bootstrap's grid system!

Now that I've styled the navbar, I'll work on the footer in the next post.

Rebuilding a Theme, Part IV: Working with Bootstrap

2024-07-11T00:00:00Z

Bootstrap has a lot of default settings, so it's good to familiarize yourself with how the subtheme handles the defaults and, more importantly, how to override them.

The Bootstrap5 theme handles default settings and overrides in an intelligent way. In the subtheme that I made earlier, there's a directory called scss. It contains four files:

_variables_bootstrap.scss
_variables_drupal.scss
ck5style.scss
style.scss

The extension .scss stands for "Sassy Cascading Style Sheets, by the way. I don't know how "sassy" they are, but it's a cool system for dealing with CSS.

_variables_bootstrap.scss

The _variables_bootstrap.scss file is where I'll override any of the Bootstrap settings that I might want to customize. The subtheme already has the following overrides:

// Bootstrap variables (overrides).
$form-text-margin-top: 0;
$legend-font-size: 1rem;
$table-cell-padding-x: 0.75rem;

Obviously, I need to know the names of the variables before I can override them. Fortunately, I can look to the parent theme for that. The file at web/themes/contrib/bootstrap5/dist/bootstrap/5.3.3/scss/_variables.scss lists most of the available variables. If I want to override one across the site, I can copy its name into the _variables_bootstrap.scss file and enter the updated value(s) for it.

Let's say you have a specific shade of blue that is important for your organization's brand. You could use the _variables_bootstrap.scss file to set the variable $blue to your shade of blue. That way, you can just use the word "blue" in your CSS. Bear in mind, however, that you'll affect the other shades of blue that are built into Bootstrap. You could also use these variables to set a specific color for links, font-size, and many, many other aspects of the look of your site.

_variables_drupal.scss

The Bootstrap5 theme also has a bunch of default settings above and beyond what Bootstrap makes available. The _variables_drupal.scss file in the subtheme already has this:

// Theme variables.

$navbar-brand-image-height: 36px !default;
$navbar-brand-image-height-lg: 60px !default;
$navbar-brand-image-width: auto !default;
$navbar-brand-image-margin: 0 1rem 0 0 !default;

$navbar-brand-site-title-text-transform: uppercase !default;
$navbar-brand-site-title-font-size: 1.5rem !default;
$navbar-brand-site-title-font-weight: bold !default;
$navbar-brand-site-title-letter-spacing: 2px !default;
$navbar-brand-site-slogan-font-size: 0.875rem !default;

$region-padding: 0 0.5rem !default;

$footer-padding: 2rem 0 !default;

$nav-tabs-link-active-bg-sm: #dee2e6 !default;

$local-tasks-primary-margin: 1rem 0 !default;
$local-tasks-secondary-margin: 0 0 1rem 0 !default;

$table-striped-bg: #f9f9f9 !default;

The full list of available "theme" variables can be found at web/themes/contrib/bootstrap5/scss/drupal. That directory contains several files with transparent names like _footer.scss and _navbar.scss that make it easy to identify the file that matters to you. Well done, Bootstrap5 developers!

ck5style.scss

Don't touch this file unless you really, really need to style specific things about the WYSIWYG editor CKEditor.

style.scss

This is where I'll do most of my styling work. For example, the navbar in my brand-new subtheme is black. The Digital Latin Library's brand features a specific shade of blue (#005cb9), and I'd like to change the background color of the navbar to that.

I'll follow Carol Kelly's suggestion at https://stackoverflow.com/a/43382283 for accomplishing this objective.

I'll need to override the Twig template for the navbar to change its CSS class, and I'll need to add some CSS code to style.scss to define the new class.

When I use my browser's Developer Tools to inspect the navbar, I find that the Twig debugger tells me that it is handled by the page.html.twig template. When I pull up that file in the Bootstrap5 parent theme's templates/layouts directory, I can see a block that is setting a variable nav_classes. That sets the navbar's classes to specific values for every page. After copying page.html.twig to my subtheme's templates/layouts directory, I'll add navbar-custom to that first line, and then I'll define navbar-custom in style.scss. So, I'll change set nav_classes = 'navbar navbar-expand-lg' ~ to set nav_classes = 'navbar navbar-expand-lg navbar-custom' ~. I also need to change the logic of this line:

(b5_navbar_bg_schema != 'none' ? " bg-#{b5_navbar_bg_schema}" : ' ')

to this:

(b5_navbar_bg_schema != 'dark' and b5_navbar_bg_schema != 'none' ? " bg-#{b5_navbar_bg_schema}" : '')

The original version translates to "If the b5_navbar background scheme is not set to 'none', then set the background to the value of the navbar background schema; otherwise, set it to nothing." The new version translates to "If the background schema is not 'dark' and it isn't set to 'none', then set the background to the background schema; otherwise, set it to nothing." That way, I can remove the bg-dark class that is currently controlling the look of my header.

Now, I need to define the style for navbar-custom. I'll open style.scss and add this below the existing content:

/* ===================================================== 
    Navbar
   ===================================================== */

/* Cribbed from https://stackoverflow.com/a/43382283 */
/* change the background color */
.navbar-custom {
  background-color: #005cb9;
}

/* change the link color */
.navbar-custom .navbar-nav .nav-link {
  color: #fff;
}

/* change the color of active or hovered links */
.navbar-custom .nav-item.active .nav-link,
.navbar-custom .nav-item:focus .nav-link,
.navbar-custom .nav-item:hover .nav-link {
  color: #a33701;
}

Notice that I added a comment with some fancy formatting to make it stand out and to give some structure to my SCSS document. This will make it easier to maintain. I also added a comment to give credit where credit is due.

I've changed the background color of the navbar to the DLL's shade of blue. I also specified that the links in the navbar should be white (#fff), and when they are active they should be a reddish-brown color (#A33701).

Since I made a change to style.scss, I need to recompile the CSS. The theme's README file instructs me to execute the command sass scss/style.scss css/style.css && sass scss/ck5style.scss css/ck5style.css in the root directory of the subtheme. I did that, then I did drush cr to clear the caches. The result is that my navbar's background color is now the right shade of blue!

I'll take care of navbar's content in the next post.

Takeaways

Bootstrap has a lot of pre-defined styles that can be overridden to customize the look of your site
It's important to familiarize yourself with the variables that can be customized or overridden
Theming in Bootstrap typically involves making changes to Twig templates——to add, remove, or change a CSS class or ID—and SCSS files—to define or override CSS classes
Even though it took several lines of code in both Twig and SCSS to change the color of the background for a single region in the site, that change will be applied to the entire site, and I won't have to repeat that code anywhere else

Rebuilding a Theme, Part III: Working with Twig

2024-07-09T00:00:00Z

After creating my subtheme, this is what the front page looked like without any custom styling:

I tend to work from top to bottom when doing front end work, so I'm going to start with the <header>, which contains everything inside the black bar in the image above.

If I open my Web Developer Tools (see part 1), and scroll to the <header> section, this is what I see:

The lines in green text are supplied by the Twig debugger that I turned on earlier (again, see part 1). They tell me which Twig files are responsible for rendering the content. If I'm happy with them, I can leave them as they are. But if I want to change anything, I'll need to override the Twig template.

The <!-- FILE NAME SUGGESTIONS: …> comment tells developers two things: the name of the template currently responsible for rendering something and other potential names that are available, if the template needs to be overridden. The names go from very specific to generic as they go from left to right.

For example, the following is the list of suggestions for the template that renders the entire page:

<!-- FILE NAME SUGGESTIONS: ▪️ page--front.html.twig ▪️ page--node--9938.html.twig 
 ▪️ page--node--%.html.twig ▪️ page--node.html.twig ✅ page.html.twig -->

The check mark in front of page.html.twig tells me that it's the currently active template. As I read back up the list, I find increasingly specific names:

page--node.html.twig: This is the name for a template that would handle all nodes
page--node--%.html.twig: The % is a kind of placeholder for other information, such as what follows in the next point
page--node--9938.html.twig: "9938" is the node ID of the content that is displayed on my front page. I could use this template name to give that node a special layout.
page--front.html.twig: front specifies this template name for any node set as the front page

Example: Overriding the Template for the Front Page

Let's say that I want to create a template just for the front page, so page--front.html.twig. I need to make a new file with that name in my subtheme. For guidance on the location, I'll look at the Twig debug comment right below the file name suggestions:

<!-- 💡 BEGIN CUSTOM TEMPLATE OUTPUT from 'themes/contrib/bootstrap5/templates/layouts/page.html.twig' -->

That tells me that the contributed theme Bootstrap5 supplies the current template for the front page. I can add the templates/layouts directory structure to my subtheme and save the Bootstrap5 theme's page.html.twig there as page--front.html.twig. After clearing the cache drush cr and reloading the front page in my browser, I now see this:

<!--  FILE NAME SUGGESTIONS: ✅ page--front.html.twig ▪️ page--node--9938.html.twig ▪️ page--node--%.html.twig ▪️ page--node.html.twig ▪️ page.html.twig -->
<!-- 💡 BEGIN CUSTOM TEMPLATE OUTPUT from 'themes/custom/dll_catalog/templates/layouts/page--front.html.twig' -->

See? My new page--front.html.twig template is now being used. If I make changes to it, those changes will be reflected on the screen. And if the Bootstrap5 theme is upgraded, I won't lose my work.

Overriding Other Templates

Sometimes, the template that you need to override is not in the parent of your subtheme. In that case, the Twig debug messages will tell you where to look for the theme that is currently being used. A common place to look for templates is in web/core/modules/system/templates, where you'll find all kinds of goodies. You can also look for templates in the theme listed in web/core/themes, but be advised that many of them have content that depends on scripts provided elsewhere in the theme.

Takeaways

In general, the process for overriding a template is the same no matter the source:

Use Twig file name suggestion messages to identify the name of the theme you need to override and a more specific name for it
Use Twig custom template output messages to find the location of the template you need to override
Make a new file in your subtheme
Alter the content of that file to suit your needs

Rebuilding a Theme, Part II: Creating a Subtheme

2024-07-03T00:00:00Z

Install and Enable the Theme

There are several options for developing with Boostrap for Drupal. I have used Radix before, and I liked it, but this time I want to use the Bootstrap5 theme because it isn't so heavily dependent on nodeJS.

So:

Install the Bootstrap5 theme: composer require 'drupal/bootstrap5:^4.0'
Enable the Bootstrap5 theme: drush then bootstrap5

The README file included in the theme also suggests installing the companion module Bootstrap 5 tools, but it doesn't have a stable release, and it hasn't been updated since 2022, so I'm not going to do that.

Create a Subtheme

A subtheme allows developers to customize the theme without having all of their changes obliterated every time the theme is updated. The README provide a drush command: drush --include="web/themes/contrib/bootstrap5/src/Drush" bootstrap5:generate-subtheme MACHINE_NAME --subtheme-name="SUBTHEME_NAME". Obviously, replace MACHINE_NAME with the machine name for the subtheme (I'm using dll_catalog) and SUBTHEME_NAME with a human-readable name (e.g., "DLL Catalog Theme").

If all goes well, there should now be a directory called custom inside of web/themes. There should also be a directory inside of custom with the machine name that was specified in the drush command.

Enable the Subtheme and Set it as the Default

Enable the subtheme: drush then dll_catalog (or whatever the SUBTHEME_NAME is)
Set the subtheme as the default: drush config-set system.theme default dll_catalog

Now, clear the cache (drush cr), go to your browser, and pull up your site. The new subtheme should be in control. Here's a screen shot of mine at this stage:

Already I like this implementation of Bootstrap better than what I've found in Radix. Out of the box, as it were, the Bootstrap5 subtheme takes care of some things that I would have to handle with templates and CSS in Radix. Namely:

The content is centered in the browser window. It's not difficult to do that (see, for example, https://mdbootstrap.com/docs/standard/layout/horizontal-alignment/), but it's nice not to have to cope with it.
The footer is already pushed to the bottom of the browser window. That, too, can be dealt with easily, but I'd rather move on to other things.

As much as I like those things, it's time to customize my subtheme.

Rebuilding a Theme, Part I: Tricks and Tips

2024-07-02T00:00:00Z

Before I start blogging about the specifics of my front-end development project, I thought I should list some things I've picked up over time about theming in Drupal.

Develop with DDEV

I do all my Drupal development work using DDEV to run the site locally. See my post Using ddev for Local Drupal Development for more information on using DDEV. It is so much better than the bad old days of using MAMP or a Virtual Machine!

But since not everyone uses DDEV, I'm going to leave ddev off of several of the commands that I will mention in this series, lest I create confusion.

Use Your Browser's Development Tools

My main web browser is Firefox, which has great Web Developer Tools available in Tools > Browser Tools > Web Developer Tools. These tools are essential for inspecting a page's code to identify what, exactly, needs to be selected for styling. There's also an interface for seeing how your page looks on different devices.

On a Mac, the shortcut for activating the tools in Firefox is ⌘⌥c (command + option + c). I recommend memorizing what the shortcut is in your browser, since you'll need to use it a lot. I'll go so far as to say that you shouldn't even think about front-end development without figuring out how to use your browser's web development tools!

Install a CSS compiler

In my case, the theme I'll be working with uses SASS, which stands for "Syntactically Awesome Style Sheets." According to the website, "Sass is the most mature, stable, and powerful professional grade CSS extension language in the world." Installation instructions are at https://sass-lang.com/install/. In my case, I'll use Homebrew to install it on my Mac: brew install sass/sass/sass.

In some cases, npm takes care of this step.

Set Up Drupal for Theme Development

First of all, install the Twig Tweak module. It adds a bunch of functionality that you'll probably want or need. You should also familiarize yourself with the Twig Tweak Cheat Sheet, which is indispensible.

Twig is the default templating language for Drupal since version 8. In addition to being more user-friendly than the raw PHP of earlier versions of Drupal, Twig has some really helpful hinting and debugging features. To take advantage of these, you need to edit a couple of files in the web/sites/default directory.

Turn on Twig Debugging

Go to web/sites/default
Copy default.services.yml and name the copy services.yml: cp default.services.yml services.yml
Open services.yml
Scroll down to the section twig.config
Change the line debug: false to debug: true
Save and close

Enable Local Settings

The local settings file adds some development tools.

Go to web/sites/default
Copy example.settings.local.php and rename it settings.local.php: cp example.settings.local.php settings.local.php

Now, edit settings.php to tell Drupal to use the settings.local.php file. You might have to change the permissions on settings.php before you edit it. If you do have to change the permissions:

Navigate to web/sites/default
Do chmod ug=rwx settings.php

Now, do the following:

Open settings.php
Scroll down to the bottom of the file
Uncomment the last lines by deleting the # sign at the beginning of each line

The final lines of settings.php should now look like this:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
   include $app_root . '/' . $site_path . '/settings.local.php';
}

Don't forget to reset the permissions on settings.php: chmod ug=r,o= settings.php.

Be sure to clear the caches: drush cr.

Rebuilding a Theme after Upgrading from Drupal 7 to Drupal 10: Introduction

2024-06-23T00:00:00Z

For me, the worst part of upgrading a Drupal site from 7 to the latest version (I've done upgrades to 8, 9, and 10) is rebuilding the theme. Since Drupal 8 introduced an entirely new theming framework, themes for Drupal 7 sites simply will not work on an upgraded site, so the only choices are to rebuild the theme from scratch or build a new one. Either way, if you're not a front-end developer or if you don't have the funds to pay one to do the work for you, this part of an upgrade can seem like an insurmountable obstacle.

I'm here to tell you that it's not. It's doable, if you have at least some familiarity with CSS and HTML, and if you're willing to invest some time into learning Bootstrap and Twig. To be honest, even if you don't know anything about those things, you can make a significant amount of progress with hints from Chat-GPT et al.

I have upgraded two Drupal 7 sites that had custom themes designed by a front-end development company that charged a lot of money (i.e., > $30,000). In both cases, I rebuilt the theme so that it strongly resembles the original D7 custom theme. Since I am by no means a graphic designer, that was the most direct path to getting the sites back online after the upgrade.

I decided to base the new themes on Bootstrap, because it automagically takes care of a lot of the things I don't like to deal with in front-end development. Also, Bootstrap's documentation is crystal clear, tutorials abound online (e.g., https://www.w3schools.com/bootstrap/bootstrap_get_started.asp), and the user community is huge—all factors I strongly consider when making any decisions about technology.

Since I know that other Digital Humanities folks have run up against the problem of doing front-end development with little or no funds, I figured I should write up some notes while I go through this process yet again with the DLL's Catalog site.

I'll add to this list as I finish writing up each step:

Using the OHMS Viewer with DDEV

2024-06-21T00:00:00Z

A colleague asked me to help her get started using the Oral History Metadata Synthesizer's OHMS Viewer. It is meant to integrate with a CMS, but she just needs to see how it works for now. Instead of going through the trouble of setting up access to a remote server, I decided to see if I could get it working with DDEV, a super-easy-to-use application for developing web sites locally (i.e., on a laptop or desktop computer).

Prerequisites

Comfort using a Command Line Interface (e.g., Terminal).
Docker. The instructions for different operating systems are available at https://ddev.readthedocs.io/en/stable/users/install/docker-installation/.
DDEV: Instructions are at https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/.
OHMS Viewer: Download the latest release at https://github.com/uklibraries/ohms-viewer/releases. It is available as a zip or tar.gz archive. I'm working with the tar.gz file.
An account on Aviary.

Set up a PHP environment with DDEV

Make a new directory called "ohms": mkdir ohms. I put mine in ~/Sites.
Change into the new directory and run the following command: ddev config. This will launch a dialog. You can just press the return key for the first two prompts (Project name: and Docroot Location), but be sure to enter php for the third prompt (Project Type).
Execute the command ddev start.

At this point, there should be a bare site that you can visit by opening a web browser and going to http://ohms.ddev.site. You'll probably see the message 403 Forbidden. That's okay.

Copy the OHMS Viewer files into the PHP Environment

Extract the OHMS Viewer archive to your PHP environment: tar -xvf ohms-viewer-3.9.3.tar.gz -C ~/Sites/ohms.
Rename the new directory "ohms-viewer": mv ohms-viewer-3.9.3 ohms-viewer.

Make a cachefiles Directory

Change into ohms-viewer.
Create a new directory called "cachefiles" (mkdir cachefiles).

This is where you'll eventually put your OHMS XML files.

Edit the OHMS Viewer's Config File

Change into the config directory within ohms-viewer: cd ~/Sites/ohms/ohms-viewer/config.
Make a copy of config.template.ini and call it config.ini.
Using a text editor, edit the content of config.ini. Change the first line to read tmpDir = cachefiles. The rest of the file can be left as it is.
Save config.ini.

Test the Viewer

For this step, you'll need an OHMS XML file from an OHMS collection on Aviary. To obtain an XML file, you'll need to create an OHMS record in the OHMS Studio. When the record is complete, you should be able to click on the three vertical dots on the far right of the row and select "Export XML".

Put the XML file into the cachefiles directory created above.

You should now be able to use a web browser to navigate to http://ohms.ddev.site/ohms-viewer/viewer.php?cachefile=YOUR-XML-FILE.xml to see the record in the OHMS Viewer. Be sure to replace YOUR-XML-FILE with the actual name of your file.

Upgrading the DLL Catalog Site to Drupal 10

2024-05-25T00:00:00Z

I finally have some time to devote to upgrading the DLL Catalog from Drupal 7 to Drupal 10! I'm sharing some of the basic stuff here in case DH folks need to upgrade their sites.

I'm going to work on my upgrade project locally (i.e., on my laptop), using the fantastic DDEV Docker-based tool so that I don't have to do it on a remote server or deal with MAMP or something like that. I strongly recommend using DDEV. There's excellent documentation for installing it, so I won't repeat it here.

After installing Docker and DDEV, the next step is to set up DDEV sites for both the existing Drupal 7 (D7) codebase and database and a new Drupal 10 codebase and database. Next, I'll install the migration modules. Finally, I'll run the migrations and troubleshoot.

Setting up the DDEV Sites

DLL Catalog (D7)

On my server, I made a copy of the codebase and database, then I used scp to copy those files to my local machine. I decompressed the codebase (tar -xvf catalog.tar.gz) and changed into the new directory (cd catalog). Then I configured that directory to use DDEV (ddev config) and told DDEV to import the SQL file I downloaded (ddev mysql db < ../catalog.sql). Et voilà: the DLL Catalog site is running locally on my laptop.

Note that there is also a specific DDEV command for importing a database: ddev import-db. Read more at https://ddev.readthedocs.io/en/stable/users/usage/managing-projects/#importing-a-database.

Target Site (D10)

Spinning up a bare D10 site is remarkably easy, thanks to DDEV's CMS quickstart directions for Drupal.

Prepare for Migration

Install Migrate modules on the D10 site

This is easy. First, use Composer to require the migration modules in the D10 site. Note that I'm requiring not only Migrate Upgrade and Migrate Plus, but also Migrate Tools and Migrate File, since experience tells me that I'll avoid errors on import with those installed:

# Require the migrate modules
ddev composer require drupal/migrate_tools drupal/migrate_upgrade drupal/migrate_plus drupal/migrate_file
# Install the migrate modules
ddev drush en -y migrate_tools,migrate_upgrade,migrate_plus,migrate_file

Install Contributed Modules on the D10 site

For this step, the easiest thing to do is to install the Upgrade Status module on the D7 site, enable it, and run its report. That will tell you which contributed modules on the D7 site have versions that are compatible with D10.

Make note of the modules that are not compatible and begin thinking about whether you need to find an alternative. In my case, I wrote some custom modules that I'll need to upgrade, but that's not a crucial detail at this stage.

For the modules that do have compatible versions, ask whether you'll need their functionality on the D10 site. If the answer is yes, then install and enable them.

Define the Migration Source Database

Since I'm migrating content from one Docker container into another, the two need to be able to communicate. Fortunately for all of us, the Drupal community has some good tips about this:

Start up both the source web site (Drupal 7) and target web site (Drupal 10) in separate DDEV instances. Enter the D7 credentials in the Drupal 10 settings.php, using the Docker containers listed during start up, for example ddev-drupal7-db and ddev-drupal7-web, shown during start up.

If you weren't paying that much attention during startup, you can use docker ps to find the container names. Here's the truncated output from when I ran that command:

f5690a2779de ddev-catalog-web
84540cbad1c5 ddev-catalog-db
ac6dc2c61ffa ddev-router
881cf19e2de0 ddev-d10catalog-db
38103ba38a87 ddev-d10catalog-web
70200fafaac5 ddev-ssh-agent

Here's what I entered into my d10catalog site's settings.php, following the Example values for DDEV:

$settings['migrate_source_connection'] = 'migrate';
$settings['migrate_source_version'] = '7';
$settings['migrate_file_public_path'] = 'http://catalog.ddev.site/';
$settings['migrate_file_private_path'] = '';

$databases['migrate']['default'] = [
  'database' => 'db',
  'username' => 'db',
  'password' => 'db',
  'host' => 'ddev-catalog-db',
  'port' => '3306',
  'driver' => 'mysql',
  'prefix' => '',
];

Be sure to clear the cache with ddev drush cr after making this update to settings.php.

Make a Custom Module for the Migration

I have found that it makes sense in the long run to make a custom module for your migration. It's easier than you think.🤠

Set up the Structure for your Module

Switch into web/modules in your D10 site
If you don't already have a custom directory, make one: mkdir custom
Switch into custom and create a new directory for your custom module (e.g., cd custom && mkdir my_migration)
Switch into your custom migration module
Make an info.yml file. Mine is catalog_migrate.info.yml. Change the first part of the file's name to whatever you're calling your module.
Add the following contents to the info.yml file:

type: module
name: Catalog D7 to D10 Migration Module
description: "A module for migrating content from a legacy site to a new one."
package: Custom
core: 10.x
core_version_requirement: ^10
dependencies:
  - drupal:migrate
  - drupal:migrate_drupal
  - drupal:migrate_plus
  - drupal:migrate_tools

Now make the directories for the migration files you'll generate in the next step:

Make a directory called config (mkdir config).
Switch into config and make a new directory called install (mkdir install)

Generate the Migration Files

The drush migrate:upgrade command will generate the files needed for the custom module. Certain things have to be done to make it work on a DDEV site. Specifically, the values in the --legacy-db-url extension have to use the database user, password, Docker name, and database name that I used to make the connection in settings.php. The legacy-root value should be the absolute path to the D7 site; in my case, it's /Users/sjhuskey/Sites/catalog. If you need help finding the absolute path, use cd to navigate to your D7 site's root, then execute pwd (print name of working directory) to get the absolute path.

Taking those items into consideration, this is the command I ran to generate the migration files:

ddev drush migrate:upgrade --legacy-db-url=mysql://db:db@ddev-catalog-db/db --legacy-root=/Users/sjhuskey/Sites/catalog/sites/default/files --configure-only

Export the Migration Files

After running the drush migrate:upgrade command above, I ran the following command to export the files needed for migration to a tmp directoy I created in the root directory of the site:

ddev drush cex --destination=../tmp

../tmp changes from the web directory to the parent or root directory.

If you don't add the --destination flag, the files will end up in your sync file, and when you try to activate your custom module later, you'll get an error.

Copy the Migration Files into your Custom Module

When I did ddev drush cex in the previous step, the configuration files for EVERYTHING were added to the temporary directory. I just need the migration config files, so I changed into the directory at /Users/sjhuskey/Desktop/tmp and executed the following command to copy only the migration config files to my custom module's config/install directory:

cp migrate_plus.migration.* migrate_plus.migration_group.migrate_*.yml ~/Sites/d10catalog/web/modules/custom/catalog_migrate/config/install

Now I have a bunch of files with names like migrate_plus.migration.upgrade_d7_action.yml in my module's config/install directory. Great!

Modify the Names of the Migration Files

First things first: change the name of migrate_plus.migration_group.migrate_drupal_7.yml to migrate_plus.migration_group.my_module.yml.

mv migrate_plus.migration_group.migrate_drupal_7.yml migrate_plus.migration_group.catalog_migrate.yml

This file will define the group for your migration.

I need to replace upgrade_d7 in the file names with the name of my module. Since dozens of files need that change, I wrote a Python script to do it for me:

#!/usr/bin/env python
# coding: utf-8

import os
[os.rename(f, f.replace('upgrade_d7', 'catalog_migrate')) for f in os.listdir('.') if not f.startswith('.')]

As always, if you're following along, replace catalog_migrate with the name of your custom module.

I named the file rename.py and placed it in my custom module's config/install directory. I ran it with python3 rename.py. Shazam! All of my files have been renamed.

Remove Unneeded Files

Remove migrate_plus.migration.catalog_migrate_action.yml and migrate_plus.migration.upgrade_action_settings.yml. From past experience, I know that they cause trouble.

Edit the Migration Config Files

Several find/replace operations are needed across all the migration config files. The command line tool sed is great for this:

for file in *; do
    sed -i '' -e '/^uuid: [0-9a-z\-]*$/d' \
        -e 's/migration_group: migrate_drupal_7/migration_group: catalog_migrate/' \
        -e 's/id: upgrade_d7/id: catalog_migrate/' \
        -e 's/upgrade_d7/catalog_migrate/' "$file"
done

Breaking that down, I'm using a for loop in bash to iterate over the files and perform the following operations:

All of the migration files contain a uuid that must be removed. I'm using the Regular Expression ^uuid: [0-9a-z\-]*$/d to match the pattern and delete the line
Change migration_group: migrate_drupal_7 to the migration_group: catalog_migrate
Change id: upgrade_d7 to id: catalog_migrate
Change remaining instances of upgrade_d7 to catalog_migrate

This can be done in a text editor with "Find and Replace in Files", too. Be sure to change catalog_migrate to the name of your module.

Edit the Migration Group YAML file

Update the content of migrate_plus.migration_group.catalog_migrate.yml. Prior to editing, mine looks like this:

langcode: en
status: true
dependencies: {}
id: migrate_drupal_7
label: "Import from Drupal 7"
description: "Migrations originally generated from drush migrate-upgrade --configure-only"
source_type: "Drupal 7"
module: null
shared_configuration:
  source:
    key: drupal_7
    database:
      driver: mysql
      username: db
      password: db
      host: ddev-catalog-db
      port: ""
      database: db
      prefix: null

I edited it to this (changes commented):

langcode: en
status: true
dependencies: {}
id: catalog_migrate # Change the id to the machine name of the module
label: "Import from Catalog D7 site" # Change the label.
description: "Migrations originally generated from drush migrate-upgrade --configure-only"
source_type: "Drupal 7"
module: null
shared_configuration:
  source:
    key: migrate # Change this to "migrate"
    database:
      driver: mysql
      username: db
      password: db
      host: ddev-catalog-db
      port: ""
      database: db
      prefix: null

Install the Module

Install the module with ddev drush en -y catalog_migrate. If all goes well, the module is enabled and I can move on to the next step.

Check Migration Status

If you run ddev drush migrate:status, you're likely to see a bunch of scary error messages related to Drupal 6 migrations that are included by default. To avoid seeing those, do ddev drush migrate:status --group=catalog_migrate. I did that and found that my migrations were looking good: all were idle, with expected numbers in the Total, Imported, and Unprocessed columns.

Running the Migration

I wish there were a --simulate flag so that I could run a test migration without actually importing a bunch of stuff into my D10 site, but there isn't. So, now's the time to run ddev drush migrate:import --group=catalog_migrate --continue-on-failure. I use the continue-on-failure flag because otherwise the process stops every time there's even a minor issue. There probably will be some issues, but I prefer to find out how extensive the issues are by watching all of the migrations complete their run.

Debugging

I have never seen a migration executed flawlessly on the first run. It's good to know some debugging tips.

Drush does a good job of letting you know when there are problems. For example, my migration produced this message:

[notice] Processed 327 items (315 created, 0 updated, 12 failed, 0 ignored) - done with 'catalog_migrate_field_formatter_settings'
[error]  catalog_migrate_field_formatter_settings Migration - 12 failed.

The migrate:message (mmsg) command, with the name of the troublesome migration, will provide more information: ddev drush mmsg catalog_migrate_field_formatter_settings. Running that told me that most of the issues had to do with field format widgets that were supplied by the Autocomplete Widgets module, which does not have a D10 version.

If there are issues with other migrations, now is the time to use mmsg with those, too. Otherwise, the messages will disappear after you run migrate:rollback (mr) to, well, roll back the migration.

Sometimes, when a migration stops in the middle of the operation, it's necessary to use migrate:reset-status (mrs) to reset a migration.

To resolve the issues, I work in the site's sync directory, which DDEV puts in web/sites/default/files/sync. I edit the files that correspond to the migrations that had problems, then I do ddev drush cim to import the changes, followed by ddev drush cr to clear the caches.

Finally, I run migrate:import (mim) again with the --group and --continue-on-failure flags, watching for the same or new error messages. It might be the case that you will have to live with some of the minor issues that don't affect the content or functionality of your site.

Next Step: Rebuilding the Theme

This is the really unfortunate part of upgrading a Drupal 7 site. Drupal 8 introduced an entirely new theming layer, so I'll need to rebuild the theme in Twig before I can launch the new version. For now, everything will be done locally on my DDEV site. I'll post something about my adventures with rebuilding the theme.

Tales of DH Automation

2023-09-22T00:00:00Z

One of my favorite things is using technology to eliminate or at least reduce the amount of tedious, repetitive, and boring tasks that friends and colleagues encounter in their work, so I'm starting a series on this blog to give others some ideas of what technology can do for them.

My eyes were opened to these possibilities when I read Automate the Boring Stuff with Python by Al Sweigart. It is an excellent book for anyone curious about Python and, more generally, how to get machines to do the mindless tasks that can make life unpleasant. I highly recommend it.

Renaming Files … Lots and Lots of Files

My colleage Bill Endres asked me for help with a task that routinely takes a lot of his time. An expert in multi-spectral imaging, Bill takes dozens and dozens of images in a typical imaging session. The software he uses labels each image with a date-time stamp and the light frequency in use. For example, the file name 20230720_132856_365_nm.tif tells us that the image was taken on July 20, 2023 (20230720) at 1:28:56 p.m., and that the light frequency in use was 365nm.

The thing is that each object (i.e., page of a manuscript in this case) is imaged in sixteen different frequencies, so the result of imaging one page is a list of images like this:

20230815_102820_365_nm.tif
20230815_102826_385_nm.tif
20230815_102832_395_nm.tif
20230815_102838_420_nm.tif
20230815_102844_450_nm.tif
20230815_102851_470_nm.tif
20230815_102857_500_nm.tif
20230815_102903_530_nm.tif
20230815_102909_560_nm.tif
20230815_102915_590_nm.tif
20230815_102922_615_nm.tif
20230815_102928_630_nm.tif
20230815_102934_660_nm.tif
20230815_102941_730_nm.tif
20230815_102947_850_nm.tif
20230815_102953_940_nm.tif

That's one page. The only indicator that the page has changed is the frequency number: when it goes back to 365_nm, you know that Bill has started to take images of a new page.

Bill needed a more descriptive file name. Specifically, he wanted the files to be named using the pattern {Manuscript Name} (e.g., 'HerefordGos'), {Page} (e.g., 1), {Face} ("recto" or "verso"), {Frequency}. He also needed the value of {Page} to increase by one after every cycle of sixteen light frequencies. He has much better things to do with his time than manually renaming hundreds of files, so he wondered about a way to rename the files automatically.

My go-to solution being Python, I started working up a script for him. In days past, I would have spent a fair amount of time trying out various ideas, consulting Stack Overflow, and debugging my script until I got it right. But with the advent of intelligent chatbots, I can cut down significantly on that process. I just need to know how to ask the chatbot the right questions.

(I hear that "Prompt Engineer" is an up-and-coming career. Maybe I should look into that ….)

Here's what I asked:

I need to rename the files in a directory, and I'd like to use Python to do it. Here are the details: my program produces files with names like 20230720_132856_365_nm.tif. The first part of the filename (20230723_132856) is a date-time stamp; the second part (365_nm) is a light frequency. I want to write a function that will accept the arguments directory, msName, page, and face and do the following:

Parse and extract the timestamp from each filename.

Group the files by their timestamp and ensure each group has 16 (or fewer) files.

Sort the groups of files based on the light frequency.

Strip the underscore from the light frequency (i.e., turn 365_nm into 365nm)

Rename the files according to the pattern {msName}_{page}{face}_{frequency}.tif.

I also asked it to make the script callable from the command line and to ignore any files that don't end in .tif. Here's what we ended up with after a couple of iterations:

#!/usr/bin/env python3

import os
import argparse

def rename_files(directory, msName, firstPage, face):
    # Verify that the face value is either 'r' or 'v'
    if face not in ['r', 'v']:
        raise ValueError("The face argument must be either 'r' or 'v'.")
    # Define light frequency order
    light_frequencies = [365, 385, 395, 420, 450, 470,
                         500, 530, 560, 590, 615, 630, 660, 730, 850, 940]

    # Extract files and sort by timestamp
    all_files = os.listdir(directory)
    sorted_files = sorted(all_files, key=lambda f: f.split('_')[
                          1] if '_' in f else f.split(' ')[1])

    # Group files in chunks of 16 based on their timestamp sequence
    chunks = [sorted_files[i:i + 16] for i in range(0, len(sorted_files), 16)]

    # Initialize current page
    current_page = firstPage

    for chunk in chunks:
        # Counter for tracking light frequency index
        freq_index = 0
        # Sort each chunk based on light frequency
        sorted_chunk = sorted(chunk, key=lambda f: int(
            f.split('_')[2] if '_' in f else f.split(' ')[1].split('_')[0]))

        for filename in sorted_chunk:
            # Extract light frequency number
            if '_' in filename:
                light_freq = int(filename.split('_')[2])
            else:
                light_freq = int(filename.split(' ')[1].split('_')[0])

            # Construct the new filename
            new_name = f"{msName}_{str(current_page).zfill(4)}{str(face)}_{light_freq}nm.tif"

            # Full paths to old and new filenames
            old_path = os.path.join(directory, filename)
            new_path = os.path.join(directory, new_name)

            # Rename the file
            os.rename(old_path, new_path)
            print(f"Renamed: {filename} -> {new_name}")

            # Check if we have cycled through all frequencies and need to reset
            # if it's the last frequency in the list
            if light_freq == light_frequencies[-1]:
                current_page += 1
                freq_index = 0
            else:
                # Increment frequency index for the next iteration
                freq_index += 1

# Example usage:
# Let's say your directory is "my_directory" and msName is "HerefordGos" and starting page number is 1
# rename_files("my_directory", "HerefordGos", 1, "r")

if __name__ == "__main__":
    # Initialize the argument parser
    parser = argparse.ArgumentParser(
        description='Rename files based on given rules.')
    parser.add_argument('directory', type=str,
                        help='Path to the directory containing files to be renamed.')
    parser.add_argument('msName', type=str, help='Manuscript name.')
    parser.add_argument('firstPage', type=int, help='Starting page number.')
    parser.add_argument('face', type=str, choices=['r', 'v'], help='r (recto) or v (verso).')

    # Parse the command line arguments
    args = parser.parse_args()

    # Call the function
    rename_files(args.directory, args.msName, args.firstPage, args.face)

That can rename hundreds of files in a couple of seconds. I haven't tried timing it with Python's time functionality, but I imagine you'd have to try running it on tens of thousands of files before you'd notice the amount of time it takes.

Anyway, thanks for reading this first edition of "Tales of DH Automation".

Photo by Joshua Sortino on Unsplash.

Converting a Drupal site to 11ty

2023-06-11T00:00:00Z

The main website for the Digital Latin Library has been running on the Drupal 7 CMS since its launch. As many Digital Humanities scholars know, maintaining the technology stack for an informational site can be an impediment to making real progress on the actual project. As much as I love Drupal, it is definitely more than I need for a few static pages and some blog posts. One must keep up with not only the Drupal codebase, but a MySQL database and the Linux server that it runs on. Moreover, upgrading the site from Drupal 7 to Drupal 10 would simply not be worth the effort. Having performed that task for the Society for Classical Studies' website, I know how to do it, but I'm not interested in going through that again for a small site like https://digitallatin.org/.

Paying for hosting is also an obstacle. For many years, my home institution's Office of the Vice President for Research and Partnerships gave me the use of a virtual machine for the DLL project, provided that I manage the upkeep and maintenance. That is why I now have the skills to administer Linux servers—valuable skills, to be sure, but again, one more thing to keep up with in this world of DIY Digital Humanities. Since the VPRP wanted to get out of the business of hosting virtual machines, I moved everything over to the university's cloud computing resource. That was a good solution, but again, I had to agree to be the system administrator for the server. I don't mind maintaining a Linux server. There's something satisfying about completing those tasks. Still, it does take time away from other aspects of my research and creative activity.

So, I decided to convert the Digital Latin Library site to the static site manager 11ty. First of all, since it's a static site manager, I don't have to maintain a MySQL database. Second, my content isn't stored in pieces in a database. I can just store it in Markdown files. I like writing in Markdown. Indeed, I do almost all of my writing in Markdown these days. Combined with Pandoc, it's remarkably flexible! Third, Git is big part of the workflow for an 11ty site, so count this Git fan in! Finally, I can host my 11ty site on Github for free!

Those are the reasons for converting my site to 11ty. Here are the steps that I took to do it, in case someone else is interested in taking this adventure.

First step: Export Content from Drupal

I used the Views module in Drupal to export all of my nodes to a CSV file. You'll need to have the Views module installed and enabled, along with the Views Data Export module.

My site had a number of different content types, but I was able to use one View for all of them. Your data export view should include at least these fields:

Content: Title (Title)
Content: Body (Body)
Content: Author (Author)
Content: Path (Path)
Content: Post date (Post date)
Content: Category (Category)
Content: Type (Type)

Your content types might have other fields (e.g., images) that you'll want to include.

I set my data export view to download the content as a CSV file so that I could easily work with it in Python in the next step.

Use Python to Convert CSV Data to Markdown Files

To be perfectly honest, I consulted Chat-GPT about how to convert my CSV data to individual Markdown files, so the following script is mostly its work.

The CSV file I downloaded from Drupal was called export_all_content.csv. Where that occurs in the following script, you'll need to change it to your file's name.

The columns in my CSV file were called Title, Body, Author, Path, Post date, Category, and Type. Your titles might be different, depending on how you set up your data export view in Drupal.

I created a new folder on my computer for this project and called it dllnew. Inside that folder, I created two other folders, markdown (for the new markdown files) and data (for the CSV file). The Python script is in the root of dllnew.

import os
import csv
import markdown

# Create the "markdown" directory if it doesn't exist
if not os.path.exists('markdown'):
    os.makedirs('markdown')

''' Default metadata for all pages. Note that I'm using
    'post' as the default for the layout field, since most
    of my pages are blog posts'''

DEFAULT_METADATA = {
    'layout': 'post',
    'title': '',
    'author': '',
    'path': '',
    'date': '',
    'category': ''
}

# Open the CSV file
with open('data/export_all_content.csv', 'r') as csv_file:
    csv_reader = csv.DictReader(csv_file)

    # Loop through each row in the CSV file
    for row in csv_reader:
        # Extract data from the row
        title = row['Title']
        body = row['Body']
        author = row['Author']
        path = row['Path']
        date = row['Post date']
        category = row['Category']
        layout = row['Type']

        # Merge the default metadata with the metadata from the CSV file
        metadata = {**DEFAULT_METADATA, 'title': title, 'author': author, 'path': path, 'date': date, 'category': category, 'layout': layout}

        # Convert the body text to HTML using markdown
        html = markdown.markdown(body)

        # Add the metadata to the beginning of the HTML content
        markdown_text = '---\n' + '\n'.join([f'{k}: {v}' for k, v in metadata.items()]) + '\n---\n\n' + html

        # Replace spaces with hyphens in the filename
        filename = title.replace(' ', '-').lower() + '.md'

        # Write the markdown file
        with open(os.path.join('markdown', filename), 'w') as markdown_file:
            markdown_file.write(markdown_text)

Running this script yields one new Markdown file per row in the CSV file, all saved in the markdown directory.

Cleaning Up the Markdown

I noticed that my new Markdown files weren't completely in the Markdown language. That is, the metadata block looked good, but the HTML code from the original Drupal nodes was still present. For example:

---
layout: base
title: Textual Criticism
author:
permalink: /library-digital-latin-texts/textual-criticism
date: 2015-05-08
category:
---

<p>
  Reading an apparatus criticus is hard enough for a human to do; for a computer, it's impossible—at least if the
  apparatus hasn't been encoded. 
</p>
<p>
  Critical editions in print <em>are</em> heavily encoded, but in a way that only humans with special training and lots
  of experience can decode. Because publishers prefer not to sacrifice much real estate on a page to printing
  information that they think only some readers will use, textual scholars have developed a way of compressing the
  information into the allotted space using abbreviations and symbols. Call it a “print-optimized visualization of
  textual data.”
</p>
<p>
  The image above is an excerpt from the Harvard Servius. Consider all of the types of information that appear in the
  entries on a single page:
</p>
<p>
  <img
    alt=""
    src="https://digitallatin.org/sites/default/files/servius_marked_up.png"
    style="border-style:solid; border-width:1px; height:406px; width:600px"
  />
</p>

So, I consulted Chat-GPT again to find a good way to convert the HTML code into standard Markdown. After a few tries, I ended up with this:

import os
import html2text

def convert_html_in_markdown(markdown_file):
    # Load the Markdown file
    with open(markdown_file, 'r', encoding='utf-8') as file:
        markdown_content = file.read()

    # Split the Markdown content into metadata and body
    metadata, body = markdown_content.split('---', 2)[1:]

    # Convert HTML to Markdown with custom BodyWidth
    converted_body = html2text.html2text(body, bodywidth=0)

    # Combine the metadata and converted body
    md_content = '---\n' + metadata + '\n---\n' + converted_body

    # Generate the output file name
    md_output_file = os.path.splitext(markdown_file)[0] + '_converted.md'

    # Write the converted Markdown content to the output file
    with open(md_output_file, 'w', encoding='utf-8') as file:
        file.write(md_content)

    print(f"Converted HTML in {markdown_file} to Markdown in {md_output_file}")

def batch_convert_html_in_markdown(markdown_folder):
    # Get the list of Markdown files in the folder
    markdown_files = [f for f in os.listdir(markdown_folder) if f.endswith('.md')]

    # Convert HTML in each Markdown file
    for markdown_file in markdown_files:
        markdown_path = os.path.join(markdown_folder, markdown_file)
        convert_html_in_markdown(markdown_path)

# Specify the folder containing the Markdown files
markdown_folder = '../pages'

# Call the batch conversion function
batch_convert_html_in_markdown(markdown_folder)

To use that script on your own files, you'll need to change the value for markdown_folder to the path of your Markdown files.

The script will save a new version of your Markdown files with _converted appended to the file name, so you won't lose your original versions.

Next Steps

My next steps will be:

Download the files directory from my Drupal 7 site
Identify a good place for the image files in my 11ty site
Update the image paths in my new Markdown files
Work on the theme for the site.

That fourth step is going to take the most time. That's always the way for DIY Digital Humanities projects, am I right? I'm not a graphic designer by any stretch of the imagination. Fortunately, there are many good template to use as a starting point. I think I'll use 11ty-plain-bootstrap5, but 11straps also looks like a good option.

Gitignore for Drupal

2023-02-22T00:00:00Z

Here's a .gitignore file that has worked well for my Drupal 8 and 9 sites:

#ignoreSettings
web/sites/default/settings.php
web/sites/default/settings.local.php
web/sites/default/~settings.local.php

# ignore files directories
web/sites/default/files
private
web/sites/default/files
private
files

#ignore ddev
.ddev
web/sites/default/settings.ddev.php

# Packages #
############
*.7z
*.dmg
*.gz
*.bz2
*.iso
*.jar
*.rar
*.tar
*.zip
*.tgz

# Logs and databases #
######################
*.log
*.sql

# OS generated files #
######################
.DS_Store*
ehthumbs.db
Icon

Thumbs.db
._*

# Vim generated files #
######################
*.un~

# SASS #
##########
.sass-cache

Photo by Gabriel Heinzer on Unsplash

Using ddev for Local Drupal Development

2022-10-06T00:00:00Z

Setting up a local development version of a Drupal site has always been a challenge, since you need to have access to a database server and a PHP interpreter, not to mention various other tools (like Drush). After bad experiences with MAMP and Virtual Box, I switched to using a droplet at Digital Ocean for any Drupal development projects. I love Digital Ocean's products and tutorials, but I've been telling myself that I have to become more proficient at using Docker, so I decided to set up a Drupal container on my laptop and test it out.

DDEV + Docker

Although there is an official Docker image for Drupal, it comes with a lot of provisos, and I didn't really want to deal with setting up a separate container for the db, PHP, and a volume for storage. That's why I was happy to find out about ddev, a development framework that does the heavy lifting of setting up Docker containers, etc., for you. It even has configurations for several popular Content Management Systems built in. What's not to love?

Even better, there's a Digital Ocean Tutorial about setting up a Drupal 9 website on your local machine using Docker and ddev!

The Digital Ocean tutorial and others that I found were great for setting up a new site, but I wanted to set up an existing site. That meant that I needed to learn how to tell ddev to use my existing database. I've written this post in case someone else runs into the same issue.

Preparation

Before doing anything else, I had to log on to my Digital Ocean droplet and get the codebase and SQL file for the existing project. I made an SQL file of my database and a tarball of the codebase, and then I downloaded them into the ~/Sites directory on my laptop.

The Digital Ocean tutorial's "Prerequisites" section already tells you everything you need to know about installing Docker Desktop and ddev, so I won't repeat that information here.

Setup

Using the Terminal, I navigated to the directory that was created when I unpacked the tarball that contained my site's files (i.e., cd ~/Sites/dllmain). It's important to run the following commands from the main directory for your site.

After I started Docker Desktop, I did ddev config in my site's main directory. That took me through a dialog that asked me questions about my site:

❯ ddev config
Creating a new ddev project config in the current directory (/Users/sjhuskey/Sites/dllmain)
Once completed, your configuration will be written to /Users/sjhuskey/Sites/dllmain/.ddev/config.yaml

Project name (dllmain):

The docroot is the directory from which your site is served.
This is a relative path from your project root at /Users/sjhuskey/Sites/dllmain
You may leave this value blank if your site files are in the project root
Docroot Location (current directory): web
Warning: the provided docroot at /Users/sjhuskey/Sites/dllmain/web does not currently exist.
Create docroot at /Users/sjhuskey/Sites/dllmain/web? [Y/n] (yes): Y
Created docroot at /Users/sjhuskey/Sites/dllmain/web.
Found a php codebase at /Users/sjhuskey/Sites/dllmain/web.
Project Type [backdrop, drupal10, drupal6, drupal7, drupal8, drupal9, laravel, magento, magento2, php, shopware6, typo3, wordpress] (php): drupal9
Ensuring write permissions for dllmain
No settings.php file exists, creating one
Existing settings.php file includes settings.ddev.php
Configuration complete. You may now run 'ddev start'.

Project name: I gave mine the name "dllmain". The name must conform to standard hostname restrictions, as I learned when I tried to use "digital_latin".
Docroot Location: I indicated web, since that's where all of the docs are for the site.
Project Type: ddev will attempt to identify the type of project it's dealing with and suggest an answer here. It correctly identified the codebase as a drupal9 project, so I used its answer.

Initial Start

Since ddev said that I could run ddev start, I did. That step initializes all of the containers that will be used in the new local environment.

❯ ddev start
Starting dllmain...
Pushed mkcert rootca certs to ddev-global-cache/mkcert
Network ddev-dllmain_default  Created
Container ddev-dllmain-dba  Started
Container ddev-dllmain-db  Started
Container ddev-dllmain-web  Started
Container ddev-router  Started
Ensuring write permissions for dllmain
Existing settings.php file includes settings.ddev.php
Ensuring write permissions for dllmain
Successfully started dllmain
Project can be reached at https://dllmain.ddev.site https://127.0.0.1:56094

That last line says that the project can be reached at https://dllmain.ddev.site, but … my database wasn't available yet, so there would definitely be problems if I did that. Indeed, even if I had been working on a brand new site, I'd still need to run ddev composer create "drupal/recommended-project" to load all of the dependencies. Unfortunately, the tutorials I found online didn't cover how to import a new database.

Importing the Database

When I ran ddev start, ddev started a database server in a container named "ddev-dllmain-db". For a moment, I thought that I would have to log on to that container and interact with MySQL there. I was happy to discover that ddev was several steps ahead of me. All I needed was a simple ddev command.

I moved the SQL file (digital_latin.bak.sql) for my database into the directory for my project, and then I entered this on the command line:

ddev mysql db < digital_latin.bak.sql

That imported the contents of digital_latin.bak.sql into the existing database ("db") that was already set up to be used by the Drupal codebase!

White Screen of Death

I've come to accept as a given that the beginning of any Drupal project will have a bump or two. This case was no different.

I ran ddev launch, which should have opened a browser and displayed my site at https://dllmain.ddev.site. The browser opened, but it displayed the dreaded message "The website encountered an unexpected error. Please try again later."

That's not a very helpful error message, but that's nothing new with Drupal. It's a good thing that Drupal's user community is so helpful! After a quick search of that error message, I learned that I could add this line to the settings.php file to get more information:

$config['system.logging']['error_level'] = 'verbose';

So I did that and discovered that my Radix subtheme was causing problems. After I reset the theme to Bartik (ddev drush config-set system.theme default bartik) and clearned the cache (ddev drush cr), my site was reachable.

Woohoo! Let the development begin!

Photo by Rubaitul Azad on Unsplash

NEH funding histories for AAU Institutions

2022-09-26T00:00:00Z

Introduction

The first pillar in the strategic plan of my home institution, the University of Oklahoma is "Become a Top-Tier Public Research University." Strategy #1 in that pillar is "Meet Association of American Universities-quality benchmarks to position OU among the top public universities in the U.S." OU's Dodge Family College of Arts and Sciences supports this strategy in its (draft) strategic plan: "The DFCAS must build, maintain, and continually advance a culture of excellence to ensure we are at the leading edge of OU’s research ambitions and AAU aspirations."

Accordingly, to do my part to support these efforts, I aim to use my background in the humanities and my data skills (such as they are) to shed some light on research metrics in humanities departments at AAU institutions. What follows is my first effort: analyzing the history of research funding from the National Endowment for the Humanities (NEH) to public AAU institutions.

Sources

I searched the NEH's database, entering the names of AAU institutions into the "Organization Name" field. I downloaded the results in CSV form, then I used the Python Pandas library to analyze the data.

The data and the Jupyter notebook are available on my GitHub page at https://github.com/sjhuskey/aau.

Exploring the Data

After creating a big dataframe out of the 35 CSV files that I downloaded from the NEH's database, I explored the data.

First, I used the info() method to see what was available in the dataframe.

big_frame.info()


    <class 'pandas.core.frame.DataFrame'>
    Int64Index: 9590 entries, 0 to 154
    Data columns (total 45 columns):
     #   Column                         Non-Null Count  Dtype
    ---  ------                         --------------  -----
     0   ApplicationID                  9590 non-null   int64
     1   ApplicationNumber              9590 non-null   object
     2   ApplicantType                  9590 non-null   int64
     3   SuppCount                      9590 non-null   int64
     4   ProductCount                   9590 non-null   int64
     5   CoverageCount                  9590 non-null   int64
     6   PrizeCount                     9590 non-null   int64
     7   ParticipatingInstitutionCount  9590 non-null   int64
     8   WhitePaper                     9590 non-null   int64
     9   WhitePaperPath                 167 non-null    object
     10  PDFirstname                    9590 non-null   object
     11  PDMiddlename                   6406 non-null   object
     12  PDLastname                     9590 non-null   object
     13  PDNameSuffix                   210 non-null    object
     14  CoPDFirstname                  162 non-null    object
     15  CoPDMiddlename                 76 non-null     object
     16  CoPDLastname                   162 non-null    object
     17  CoPDNameSuffix                 3 non-null      object
     18  Participants                   9590 non-null   object
     19  GranteeDisplay                 9590 non-null   object
     20  Institution                    9590 non-null   object
     21  InstCity                       9590 non-null   object
     22  InstState                      9590 non-null   object
     23  InstPostalCode                 9589 non-null   object
     24  InstCountry                    9590 non-null   object
     25  CouncilDate                    9483 non-null   object
     26  YearAwarded                    9590 non-null   int64
     27  ProjectTitle                   9590 non-null   object
     28  PrimaryDiscipline              9569 non-null   object
     29  AllDisciplines                 9144 non-null   object
     30  ProgramID                      9590 non-null   int64
     31  ProgramName                    9590 non-null   object
     32  DivisionID                     9590 non-null   int64
     33  DivisionName                   9590 non-null   object
     34  OfferedOutright                9590 non-null   float64
     35  OfferedMatching                9590 non-null   float64
     36  ApprovedOutright               9590 non-null   float64
     37  ApprovedMatching               9590 non-null   float64
     38  AwardOutright                  9590 non-null   float64
     39  AwardMatching                  9590 non-null   float64
     40  OriginalAmount                 9590 non-null   float64
     41  SupplementAmount               9590 non-null   float64
     42  GrantPeriod                    9590 non-null   object
     43  ProjectDesc                    9590 non-null   object
     44  ToSupport                      0 non-null      float64
    dtypes: float64(9), int64(11), object(25)
    memory usage: 3.4+ MB

I used unique() to zoom in on the 'Institution' column to see what was there:

big_frame['Institution'].unique()

    array(['University of Wisconsin System',
           'University of Wisconsin Extension',
           'University of Wisconsin Colleges',
           'University of Wisconsin Foundation', 'University of Minnesota',
           'University of Minnesota Press',
           'University of Minnesota, University Gallery',
           'University of Maryland, College Park',
           'President and Fellows of Harvard College', 'MLA',
           'Regents of the University of California, Santa Barbara',
           'Regents of the University of California, San Diego',
           …
           'Indiana University of Pennsylvania',
           'Indiana University Southeast', 'Indiana University at South Bend',
           'Indiana University, Kokomo',
           'Indiana University Alumni Association', 'Indiana University East',
           'Indiana University Press', 'University Of Houston',
           'University of Kansas, Lawrence',
           'University of Kansas Center for Research, Inc.',
           'Kansas Humanities Council', 'University of Washington',
           'University of Washington, Bothell',
           'Regents of the University of California, Irvine'], dtype=object)

It's clear that many of the institutions in the data are not AAU institutions, so I took steps to filter the data.

I made a list of just the AAU institutions:

aau_list = ['University of Kansas, Lawrence',
            'Georgia Tech',
            'University of Maryland, College Park',
            'Mizzou',
            'Board of Trustees of the University of Illinois',
            'UCLA; Regents of the University of California, Los Angeles',
            'Penn State',
            'University of Florida',
            'Purdue University',
            'Rutgers, The State University of New Jersey',
            'Michigan State University',
            'University of Wisconsin System',
            'Trustees of Indiana University',
            'Texas A & M University, College Station',
            'Regents of the University of California, Irvine',
            'University of North Carolina at Chapel Hill',
            'University of Virginia',
            'University of Minnesota',
            'University of California, Berkeley',
            'Regents of the University of Colorado, Boulder',
            'University of Texas, Austin',
            'Regents of the University of California, San Diego',
            'University of Washington',
            'Regents of the University of California, Davis',
            'University of Utah',
            'Regents of the University of California, Santa Barbara',
            'SUNY Research Foundation, Stony Brook',
            'Regents of the University of Michigan',
            'Regents of the University of California, Santa Cruz',
            'University of Iowa',
            'SUNY Research Foundation, Buffalo State College',
            'Arizona Board of Regents',
            'Ohio State University',
            'University of Pittsburgh',
            'University of Oregon',
           ]
# How many institutions are in the aau_list? There should be 35.
len(aau_list)
35

Then I used isin() to filter the dataframe to include only the institutions in my list of public AAU institutions.

aau_frame = big_frame[big_frame['Institution'].isin(aau_list)]

I surveyed the columns in the dataframe to see how I might further filter it.

aau_frame.columns

Index(['ApplicationID', 'ApplicationNumber', 'ApplicantType', 'SuppCount',
           'ProductCount', 'CoverageCount', 'PrizeCount',
           'ParticipatingInstitutionCount', 'WhitePaper', 'WhitePaperPath',
           'PDFirstname', 'PDMiddlename', 'PDLastname', 'PDNameSuffix',
           'CoPDFirstname', 'CoPDMiddlename', 'CoPDLastname', 'CoPDNameSuffix',
           'Participants', 'GranteeDisplay', 'Institution', 'InstCity',
           'InstState', 'InstPostalCode', 'InstCountry', 'CouncilDate',
           'YearAwarded', 'ProjectTitle', 'PrimaryDiscipline', 'AllDisciplines',
           'ProgramID', 'ProgramName', 'DivisionID', 'DivisionName',
           'OfferedOutright', 'OfferedMatching', 'ApprovedOutright',
           'ApprovedMatching', 'AwardOutright', 'AwardMatching', 'OriginalAmount',
           'SupplementAmount', 'GrantPeriod', 'ProjectDesc', 'ToSupport'],
          dtype='object')

We'll probably want at least Institution, YearAwarded, ProjectTitle, PrimaryDiscipline, ProgramName, DivisionName, and AwardOutright, so I made a frame with those columns.

data = aau_frame[['Institution','ProjectTitle','PrimaryDiscipline','ProgramName','DivisionName','AwardOutright','YearAwarded']]

	Institution	ProjectTitle	PrimaryDiscipline	ProgramName	DivisionName	AwardOutright	YearAwarded
0	University of Wisconsin System	Accessing the History of Health, Pharmacy, and...	History, General	Humanities Collections and Reference Resources	Preservation and Access	326326.0	2022
1	University of Wisconsin System	"Alternative Modernities" and the Modernizatio...	Theater History and Criticism	Fellowships	Research Programs	60000.0	2020
2	University of Wisconsin System	The Ford Foundation, Social Science, and the P...	Latin American History	Fellowships	Research Programs	60000.0	2020
3	University of Wisconsin System	The History of Cartography Project	Interdisciplinary Studies, General	Humanities Collections and Reference Resources	Preservation and Access	185000.0	2021
4	University of Wisconsin System	Open Access Edition of "Citizen Countess: Sofi...	Russian History	Fellowships Open Book Program	Digital Humanities	5500.0	2020
...	...	...	...	...	...	...	...
150	Mizzou	Utopian Societies Founded in the Soviet Union ...	History, General	Summer Stipends	Research Programs	1500.0	1970
151	Mizzou	The Process of Government During the Presidenc...	History, General	Fellowships for University Teachers	Research Programs	15500.0	1970
152	Mizzou	Dr. Johnson and the New Philosophy	Philosophy, General	Summer Stipends	Research Programs	1500.0	1970
153	Mizzou	Title not available	History, General	Fellowships for Younger Scholars	Fellowships and Seminars	8387.0	1967
154	Mizzou	Title not available	Philosophy, General	Summer Stipends	Research Programs	1500.0	1967

8929 rows × 7 columns

Since the NEH has numerous funding programs, it's important to include only those having to do with research. I took a closer look at the ProgramName column:

data['ProgramName'].unique().tolist()

    ['Humanities Collections and Reference Resources',
     'Fellowships',
     'Fellowships Open Book Program',
     'Summer Stipends',
     'Scholarly Editions and Translations',
     'Preservation Assistance Grants',
     'Humanities Connections',
     'Digital Humanities Advancement Grants',
     'Fellowships for University Teachers',
     'Challenge Grants',
     'Fellowships for Advanced Social Science Research on Japan',
     'Research and Development',
     'Documenting Endangered Languages - Preservation',
     'Reference Materials',
     'Preservation/Access Projects',
     'Humanities Projects in Media',
     'Collaborative Research',
     'Education Development and Demonstration',
     'Institutes for Higher Education Faculty',
     'Regional Center Implementation Grants',
     'Institutes for K-12 Educators',
     'Humanities Projects in Libraries and Archives',
     'Regional Center Planning Grants',
     'Basic Research',
     'Seminars for K-12 Educators',
     'Seminars for Higher Education Faculty',
     'Humanities Projects in Museums and Historical Organizations',
     'Editions',
     'Reference Materials - Tools',
     'Study Grants for College Teachers',
     'Translations',
     'Scholarly Publications',
     'Reference Materials - Guides',
     'Humanities, Science, and Technology',
     'Archaeology Projects',
     'Travel to Collections, 11/85 - 2/95',
     'Preservation and Access Projects Pre-1996',
     'Conferences',
     'Younger Scholars, 2/86 - 2/95',
     'Education Development & Demonstration (OLD)',
     'Travel to Collections, 11/83 - 5/85',
     'Humanities Projects for Youth',
     'Reference Materials - Access',
     'State and Local and  Regional Studies',
     'Fellowships for College Teachers and Independent Scholars',
     'Fellowships and Stipends for Professionals',
     'Residential College Teacher Fellowships, 1976-1981',
     'Younger Scholars, 2/76 - 2/85',
     'Institutional Development',
     'Special Projects',
     'State Humanities Councils General Operating Support Grants',
     'Program Development/Planning Grants',
     'Special Fellowships Programs',
     'Bicentennial Histories',
     'Institutional Planning and Development',
     'Institutes for Advanced Topics in the Digital Humanities',
     'Public Scholars',
     'Sustaining Cultural Heritage Collections',
     'Enduring Questions: Pilot Course Grants',
     'Humanities in the Public Square',
     'Digital Humanities Implementation Grants',
     'Digging into Data',
     'Small Grants to Libraries: King James Bible',
     'Bridging Cultures Forums and Workshops',
     "Interpreting America's Historic Places: Planning Grants",
     'Dynamic Language Infrastructure-Documenting Endangered Languages - Fellowships',
     'Special Opportunity in Foreign Language Education',
     'Dissertation Grants',
     'Humanities Programs for Nontraditional Learners',
     'Pilot Grants - Education',
     'Research Challenge Grants',
     'Education Consultant Grants',
     'Cooperative Agreements and Special Projects (Public Programs)',
     'Common Heritage',
     'Dialogues on the Experience of War',
     'NEH/DFG Bilateral Digital Humanities Program',
     'Digital Humanities Start-Up Grants',
     'National Digital Newspaper Program',
     'Cooperative Agreements and Special Projects (Digital Humanities)',
     'Stabilization Grants',
     'Teaching and Learning Resources and Curriculum Development',
     'Faculty Humanities Workshops',
     'Residential College Teacher Fellowships, 1980',
     'Education Challenge Grants',
     'Fellowships for Younger Scholars',
     'Humanities Initiatives at Colleges and Universities',
     'Next Generation Humanities PhD (Planning)',
     'Digital Projects for the Public: Discovery Grants',
     "Small Grants to Libraries: America's Music",
     'Digital Humanities Fellowships',
     'Challenge Grants for Universities',
     'Humanities Institutes Program',
     'NEH on the Road',
     'International Research',
     'Planning and Assessment Studies',
     'Public Programs Special Projects (GD)',
     'Humanities Connections Planning Grants',
     'ARP-Organizations (Preservation-related)',
     'Exhibitions: Implementation',
     "America's Historical and Cultural Organizations: Planning Grants",
     "Save America's Treasures",
     'Preservation and Access Education and Training',
     'Digital Humanities Workshops',
     'Preservation - Assistance Grants (ER Title Ib)',
     'Consultation Grants (ER Title Ib)',
     'National Heritage Preservation Projects',
     'ARP-Organizations (Research-related)',
     'Small Grants to Libraries: Lincoln, Constitution and Civil War',
     'Grants to Preserve and Create Access to Humanities Collections',
     'Challenge Grants for Museums',
     'NEH/AHRC New Directions for Digital Scholarship in Cultural Institutions',
     'Humanities Open Book Program',
     'Humanities Access Grants',
     "Interpreting America's Historic Places Consultation",
     'Landmarks of American History and Culture',
     'Small Grants to Libraries: Pride and Passion',
     'Special Initiatives',
     'Libraries Implementation',
     'Humanities Connections Implementation Grants',
     'Bridging Cultures at Community Colleges',
     'Iraqi Cultural Heritage Initiative',
     'Small Grants to Libraries: Louisa May Alcott',
     'Media Challenge Grants',
     'Short Documentaries',
     'Awards for Faculty',
     'Small Grants to Libraries: John Adams Unbound',
     'Conferences and Congresses',
     'Archaeological and Ethnographic Field Research',
     'Exhibitions: Planning',
     'Advancing Knowledge: The IMLS/NEH Digital Partnership',
     'Infrastructure and Capacity Building Challenge Grants',
     'Enterprise Awards Pre-2001',
     'ARP-Organizations (Public-related)',
     "America's Historical and Cultural Organizations: Implementation Grants",
     'Bicentennial Projects',
     'Media Projects Production',
     'Digital Projects for the Public: Production Grants',
     "America's Media Makers: Production Grants",
     'NEH/DOE Humanities High Performance Computing Program',
     'Fellowships at Digital Humanities Centers',
     'NEH/DFG Symposia and Workshops Program',
     'Distinguished Teaching Professorships (Challenge)',
     'Museums Implementation',
     'History Project',
     'NEH Teacher-Scholar Program',
     'ARP-Organizations (Digital humanities-related)',
     'Cooperative Agreements and Special Projects (P&A)',
     'Cooperative Agreements and Special Projects (Research)',
     'Humanities Initiatives at Hispanic-Serving Institutions',
     'Cooperative Agreements and Special Projects (Education)',
     'ARP-Organizations (Education-related)',
     'Faculty Research Awards',
     'Fostering Coherence Through Instruction',
     'Picturing America',
     'Special Project Challenge Grants',
     'Improving Introductory Courses',
     'Picturing America School Collaboration Projects',
     'Museums Planning',
     'Public Challenge Grants']

Many of those awards don't look relevant to AAU considerations. It's possible that the DivisionName column will give us a better picture:

data['DivisionName'].unique().tolist()

    ['Preservation and Access',
     'Research Programs',
     'Digital Humanities',
     'Education Programs',
     'Challenge Programs',
     'Public Programs',
     'Agency-wide Projects',
     'Fellowships and Seminars',
     'Federal/State Partnership']

Using `value_counts() will show us how many awards have been given by those divisions.

# Let's get counts of the grants from those programs.
data['DivisionName'].value_counts()


    Research Programs            5287
    Education Programs           1360
    Preservation and Access       852
    Fellowships and Seminars      701
    Public Programs               427
    Digital Humanities            173
    Challenge Programs             84
    Agency-wide Projects           33
    Federal/State Partnership      12
    Name: DivisionName, dtype: int64

Let's see that as a bar graph:

data['DivisionName'].value_counts().plot.barh()

It would be helpful to have a dataframe with grants from Research Programs, Digital Humanities and Fellowship and Seminars.

programs = ['Research Programs', 'Digital Humanities','Fellowships and Seminars']
aau_research = data[data['DivisionName'].isin(programs)]

Let's see how many awards each institution has received over the history of NEH's funding:

# Use value_counts() to get the number of awards per institution.
total_number = aau_research['Institution'].value_counts()
total_number


    Regents of the University of Michigan                         422
    University of California, Berkeley                            413
    Trustees of Indiana University                                361
    University of Virginia                                        336
    UCLA; Regents of the University of California, Los Angeles    315
    University of Texas, Austin                                   279
    Board of Trustees of the University of Illinois               255
    University of Wisconsin System                                252
    University of Maryland, College Park                          230
    University of North Carolina at Chapel Hill                   214
    Rutgers, The State University of New Jersey                   199
    University of Minnesota                                       194
    University of Washington                                      178
    Regents of the University of California, Santa Barbara        176
    University of Iowa                                            163
    Ohio State University                                         146
    University of Kansas, Lawrence                                144
    Penn State                                                    142
    Regents of the University of California, Santa Cruz           135
    Arizona Board of Regents                                      132
    University of Oregon                                          132
    Regents of the University of California, Davis                130
    Regents of the University of Colorado, Boulder                126
    Regents of the University of California, San Diego            119
    University of Florida                                         118
    Mizzou                                                        115
    University of Pittsburgh                                      111
    Michigan State University                                     106
    SUNY Research Foundation, Stony Brook                         102
    Regents of the University of California, Irvine               102
    SUNY Research Foundation, Buffalo State College                82
    Texas A & M University, College Station                        76
    Purdue University                                              72
    University of Utah                                             54
    Georgia Tech                                                   30
    Name: Institution, dtype: int64

Here's the same information as a bar graph.

How about the total amount the institutions have received?

# How about total amount?
total_amount = aau_research.groupby('Institution')['AwardOutright'].sum().sort_values().plot.barh(figsize=(10,10))

I used value_counts() and nlargest() to get the top ten institution by number of grants received.

# Use nlargest() to get the top ten institutions by number of grants received.
top_ten = aau_research['Institution'].value_counts().nlargest(10).to_frame()

I wanted to make sure that the institutions had equivalent funding histories, so I checked on the earliest and most recent dates of awards for each one.

# Make dataframes of the earliest and most recent years per institution.
maximum = aau_research.groupby(['Institution'])['YearAwarded'].max().reset_index()
minimum = aau_research.groupby(['Institution'])['YearAwarded'].min().reset_index()

# Merge the minimum and maximum frames.
merged = pd.merge(minimum,maximum, on='Institution').rename(columns={'YearAwarded_x':'Earliest','YearAwarded_y':'Latest'})
merged

	Institution	Earliest	Latest
0	Arizona Board of Regents	1967	2021
1	Board of Trustees of the University of Illinois	1967	2022
2	Georgia Tech	1970	2017
3	Michigan State University	1967	2021
4	Mizzou	1967	2021
5	Ohio State University	1967	2021
6	Penn State	1967	2021
7	Purdue University	1967	2021
8	Regents of the University of California, Davis	1967	2021
9	Regents of the University of California, Irvine	1967	2021
10	Regents of the University of California, San D...	1967	2020
11	Regents of the University of California, Santa...	1967	2021
12	Regents of the University of California, Santa...	1967	2020
13	Regents of the University of Colorado, Boulder	1967	2022
14	Regents of the University of Michigan	1967	2022
15	Rutgers, The State University of New Jersey	1967	2021
16	SUNY Research Foundation, Buffalo State College	1966	2015
17	SUNY Research Foundation, Stony Brook	1967	2016
18	Texas A & M University, College Station	1971	2021
19	Trustees of Indiana University	1967	2021
20	UCLA; Regents of the University of California,...	1967	2021
21	University of California, Berkeley	1967	2022
22	University of Florida	1967	2021
23	University of Iowa	1967	2022
24	University of Kansas, Lawrence	1967	2022
25	University of Maryland, College Park	1967	2021
26	University of Minnesota	1967	2022
27	University of North Carolina at Chapel Hill	1967	2021
28	University of Oregon	1970	2022
29	University of Pittsburgh	1967	2022
30	University of Texas, Austin	1967	2022
31	University of Utah	1967	2022
32	University of Virginia	1967	2021
33	University of Washington	1967	2022
34	University of Wisconsin System	1967	2021

There's some variation in there, but not much.

Next, I wanted to know more about the disciplines represented in the dataset.

# How many disciplines are represented in this dataset?
aau_research['PrimaryDiscipline'].nunique()
150

# What are the top twenty disciplines in number of grants?
aau_research['PrimaryDiscipline'].value_counts().nlargest(20).to_frame().reset_index()

	index	PrimaryDiscipline
0	U.S. History	481
1	Interdisciplinary Studies, General	370
2	History, General	274
3	British Literature	255
4	European History	235
5	Art History and Criticism	217
6	Music History and Criticism	215
7	American Literature	210
8	Archaeology	210
9	Literature, General	205
10	Anthropology	157
11	Philosophy, General	156
12	Linguistics	138
13	History and Philosophy of Science, Technology,...	114
14	East Asian History	111
15	Latin American History	100
16	Comparative Literature	98
17	Medieval Studies	96
18	British History	87
19	French Literature	83

Here's that information as a pie chart:

Looking at OU

Now that I had some data on the NEH funding history of AAU institutions, it was time to start looking at OU. First, I repeated the steps that I took above: downloading the data, narrowing it down to just OU ('Board of Regents of the University of Oklahoma'), and further narrowing it down to just the NEH awards having to do with research.

Here, I used groupby() and sum() to get a picture of OU's funding history over time:

# Show the history of NEH funding at OU
ou_years = ou_research.groupby('YearAwarded')['AwardOutright'].sum().to_frame()
ou_years

	AwardOutright
YearAwarded
1967	25407.0
1970	9000.0
1972	34750.0
1973	68795.0
1974	4000.0
1975	2000.0
1977	30000.0
1978	101770.0
1979	102065.0
1980	2500.0
1981	4500.0
1983	15900.0
1984	88652.0
1985	58990.0
1986	29750.0
1987	7000.0
1988	10750.0
1989	30500.0
1990	2950.0
1996	30000.0
1997	34000.0
1998	34000.0
1999	34000.0
2000	50000.0
2001	4500.0
2002	85000.0
2003	24000.0
2004	24000.0
2005	40000.0
2008	6000.0
2009	50400.0
2013	50400.0
2014	12000.0
2015	100800.0
2016	6000.0
2017	50400.0
2019	6000.0
2022	6000.0

Here's a dataframe with the most relevant information:

# Here's a dataframe with just the pertinent information about OU.
ou_neh = ou[['Institution','YearAwarded','PDLastname','PDFirstname','ProjectTitle','AwardOutright','PrimaryDiscipline']]
ou_neh

	Institution	YearAwarded	PDLastname	PDFirstname	ProjectTitle	AwardOutright	PrimaryDiscipline
3	Board of Regents of the University of Oklahoma	2021	Marshall	Kimberly	New Stories of the West, for the West	500000.0	U.S. History
7	Board of Regents of the University of Oklahoma	2022	Heaton	Raina	Creating Online Access for the Native American...	345494.0	Linguistic Anthropology
8	Board of Regents of the University of Oklahoma	2022	Mansky	Joseph	Plays, Libels, and the Public Sphere in Shakes...	6000.0	British Literature
15	Board of Regents of the University of Oklahoma	2020	Heaton	Raina	Collaboration and development for digital acce...	49495.0	Native American Studies
27	Board of Regents of the University of Oklahoma	2019	Marshall	Kimberly	Re-Membering the Boise Valley People: Rethinki...	6000.0	Cultural Anthropology
...	...	...	...	...	...	...	...
460	Board of Regents of the University of Oklahoma	1970	Davis	Robert	Title not available	1500.0	English
463	Board of Regents of the University of Oklahoma	1970	Calhoun	Dougald	Correspondence of French Revolutionary Deputie...	7500.0	History, General
468	Board of Regents of the University of Oklahoma	1967	Opler	Morris	Title not available	15520.0	Anthropology
471	Board of Regents of the University of Oklahoma	1967	Davis	Gwenn	Title not available	1500.0	English
472	Board of Regents of the University of Oklahoma	1967	Miller	David	Title not available	8387.0	Hispanic American Studies

114 rows × 7 columns

Which disciplines at OU have been the most successful at getting NEH grants?

ou_neh['PrimaryDiscipline'].value_counts().nlargest(10).plot.pie(label='',figsize=(10,20),fontsize=14)

Comparing OU to AAU institutions

For a very basic overview, I compared OU's NEH funding per year to each AAU institution's NEH funding per year.

'''
Make a frame of OU's NEH funding history to compare to AAU institutions.
'''
OU = ou_neh.groupby('YearAwarded')['AwardOutright'].sum().to_frame()

Getting individual AAU institutions was tricky for me. I'm sure there are much better ways of doing this, but I settled on this method.

First, I made a Python dictionary of AAU institutions, with the AAU name as key and the name as it appears in the NEH data as the value. I used that to make individual dataframes to compare with OU.

aau_dict = {'University of Kansas':'University of Kansas, Lawrence',
            'Georgia Tech':'Georgia Tech',
            'University of Maryland':'University of Maryland, College Park',
            'University of Missouri':'Mizzou',
            'University of Illinois':'Board of Trustees of the University of Illinois',
            'UCLA':'UCLA; Regents of the University of California, Los Angeles',
            'Penn State':'Penn State',
            'University of Florida':'University of Florida',
            'Purdue':'Purdue University',
            'Rutgers':'Rutgers, The State University of New Jersey',
            'Michigan State University':'Michigan State University',
            'University of Wisconsin':'University of Wisconsin System',
            'Indiana University':'Trustees of Indiana University',
            'Texas A & M':'Texas A & M University, College Station',
            'UC Irvine':'Regents of the University of California, Irvine',
            'UNC':'University of North Carolina at Chapel Hill',
            'UVa':'University of Virginia',
            'University of Minnesota':'University of Minnesota',
            'Berkeley':'University of California, Berkeley',
            'University of Colorado':'Regents of the University of Colorado, Boulder',
            'University of Texas':'University of Texas, Austin',
            'UCSD':'Regents of the University of California, San Diego',
            'University of Washington':'University of Washington',
            'UC Davis':'Regents of the University of California, Davis',
            'University of Utah':'University of Utah',
            'UC Santa Barbara':'Regents of the University of California, Santa Barbara',
            'SUNY Stony Brook':'SUNY Research Foundation, Stony Brook',
            'University of Michigan':'Regents of the University of Michigan',
            'UC Santa Cruz':'Regents of the University of California, Santa Cruz',
            'University of Iowa':'University of Iowa',
            'SUNY Buffalo':'SUNY Research Foundation, Buffalo State College',
            'University of Arizona':'Arizona Board of Regents',
            'The Ohio State University':'Ohio State University',
            'University of Pittsburgh':'University of Pittsburgh',
            'University of Oregon':'University of Oregon',}

'''
Loop through the AAU dictionary to get individual histories.
'''
aau_frames = {}
for key,value in aau_dict.items():
    institution = key
    df = aau_research[aau_research['Institution'] == value]
    history = df.groupby('YearAwarded')['AwardOutright'].sum().to_frame()
    aau_frames.update({institution:history})

'''
Loop through the aau_frames and make lines graphs
comparing OU to individual AAU institutions.
'''
for key,value in aau_frames.items():
    merged = pd.merge(OU,value,on='YearAwarded')
    plot = merged.rename(columns={'AwardOutright_x':'OU','AwardOutright_y':key}).plot.line(color={'OU':'#841617',key:'#168483'},figsize=(10,5),title=('OU vs. ' + str(key)),xlabel='Year Awarded',ylabel='Amount ($)')
    fig = plot.get_figure()
    fig.savefig('../plots/OU-' + str(key) + '.png')
    print(plot)

Here are the line graphs showing the NEH funding history of OU as compared to that of each public AAU institution.

More to Come

I have also done some Natural Language Processing work on the ProjectTitle field, just to see if I could identify any trends in projects that receive funding. I plan to write up that work in a future post.

Do you have questions you want to ask of this data? Please feel free to contact me at huskey@ou.edu.

My Journey with Web Technology

2022-04-01T00:00:00Z

I was in graduate school when the internet was first becoming widely used by the general public. Since I am naturally curious about how things work (a trait I inherited from my father, I began teaching myself about HTML and the rudiments of website design in my spare time. Eventually, I developed and published the University of Iowa Department of Classics' first web site (thanks to the Internet Archive's WayBack Machine for preserving those first attempts 😀).

Those first experiences led to my appointment as the Webmaster for the Classical Association of the Middle West and South (2002–2009). Among the other features that I implemented, I added internet commerce capabilities so that they could handle membership dues and conference registrations electronically. After that, I moved on to become the Information Architect for the Society for Classical Studies (2011–present). During these years of working for non-profit professional organizations, the standards and practices for web development underwent major changes. I went from managing a collection of static HTML pages to working with dynamic content management systems like ExpressionEngine and Drupal, along with all of their accompanying technologies (Linux, Apache, MySQL, PHP, JavaScript, CSS, etc.).

Over time, my interests in teaching and scholarship coalesced with my knowledge and use of technology. I was an early adopter of digital tools and methods for enhancing the learning experience in my courses, but my first experience teaching fully online didn't occur until COVID-19 made it necessary. Although I adapted quickly to making short instructional videos and using both synchronous and asynchronous teaching methods, I discovered that I still prefer working with students in person. That doesn't mean that I will revert to teaching entirely in person. Rather, I plan to continue using technology where it is both appropriate and effective.

As for scholarship, I began working at the intersection of traditional philology and the emerging field of digital humanities. In addition to the web technology that I was already comfortable using, I learned about Natural Language Processing, Linked Open Data, text manipulation, and a variety of other ways of working with information. Before I knew it, I was working daily with not only Latin and Greek, but also XML, Python, JavaScript, and other computer languages.

All of that put me in a good position to become the director of the Digital Latin Library, a collaborative effort of the Society for Classical Studies, the Medieval Academy of America, and the Renaissance Society of America. In that capacity, I led a team of colleagues to secure funding (nearly $2 million over five years) from the Mellon Foundation to support the development of a resource for finding and publishing texts in Latin from all eras. During that period of funding, we developed a data model for digital critical editions of Latin texts, experimental applications for visualizing digital critical editions, the framework for a finding aid for existing editions of Latin texts, a platform for publishing peer-reviewed digital editions, an authentication system for those editions, and an interactive reading room.

Photo by Philipp Katzenberger on Unsplash

Installing Drupal

2022-03-10T00:00:00Z

Assumptions

These directions assume that you already have ssh access to a server with a LAMP stack, that you have installed Composer and that you are comfortable working on the command line.

Create a new database and grant user privileges

Do mysql -u USER -p to get to the mysql prompt. Replace USER with your MySQL admin user name.
Create the database: CREATE DATABASE databasename; (replace databasebame with the name of your database).
Create a user for the database: CREATE USER 'databaseuser'@'localhost' IDENTIFIED BY 'password'; (replace databaseuser and password with something)
Grant privileges: GRANT ALL ON database.* TO 'databaseuser'@'localhost';
FLUSH PRIVILEGES;
exit

Set Up the Site's Root Directory

Navigate to the directory that Apache uses for its webroot. On Ubuntu and RHEL that's cd /var/www/html
Make a new directory for your site: sudo mkdir my_site_name_dir
Change the owner of the directory sudo chown YOURUSERNAME:apache my_site_name_dir (note that the Apache user is sometimes www-data)

Use composer to create your drupal project:

composer create-project drupal/recommended-project my_site_name_dir

Enable Version Control

Change into the site's directory: cd my_site_name
Initialize a git repository: git init
Add a .gitignore file (see my post on this subject https://sjhuskey.info/drupal/gitignore-for-drupal/)
Add the current files and commit.

Set up the files directory and give it the correct permissions:

cd my_site_name_dir/web/sites/default
sudo mkdir files
sudo chown YOURUSERNAME:apache files
sudo chmod a+w files

Set up the private files directory:

Navigate to the site's root (e.g., cd my_site_name_dir)
Make the private files directory: sudo mkdir private. Give the directory the correct owner and permissions: sudo chown apache:apache private && sudo chmod a+w private

Create the settings file

Navigate to my_site_name_dir/web/sites/default
Copy the default settings file: cp default.settings.php settings.php
Change the ownership of the settings.php file: sudo chown YOURUSERNAME:apache settings.php
TEMPORARILY change the permissions on the settings.php file: sudo chmod ug=rwx,o=rw settings.php. You'll change the permissions again after the next step.

Run the installer script

Run install by going to the address of the site in a browser. See https://www.drupal.org/docs/user_guide/en/install-run.html for more information.

Choose language: Select your language of preference and click "Save and Continue."
Choose profile: Select the standard profile and click "Save and Continue."
Set up database: Enter the credentials for the database you created earlier. Click "Save and Continue."
Watch the installer run!
Configure site: fill out the form. This creates user number one, which is the admin account for the site.

Move the configuration directory

The installer script created a configuration directory at web/sites/default/files, but you should move it to the root of the installation for security purposes.

cd web/sites/default/files
Make note of the name of the configuration directory and save it because you'll need it a couple more times. The directory name will look something like config_M_Mc2eRHKbh5P0w5JnsFmEhpio44nLb0enNXYIH6v4VtwvzqRnvuXpeyMNr4o2OeEPh07BvYCg
Copy the config directory to the root of the installation: sudo cp -r config_HASH ../../../../config_HASH && sudo chown sjhuskey:sjhuskey ../../../../config_HASH && sudo rm -rf config_HASH (where HASH is the string appended to the config directory's name).

Finish setting up the settings file

Navigate to my_site_name_dir/web/sites/default if you aren't already there.

Edit the settings file

Use your favorite text editor (e.g., nano, vi) to make these changes to settings.php:

Search for 'trusted_host_patterns'. Insert your top-level domain into the trusted_host_patterns variable:

$settings['trusted_host_patterns'] = [
    '^your\.domain\.name\.org$',
];

Search 'file_private_path', then edit:

$settings['file_private_path'] = $app_root . '/../private';

Scroll to the end of the file. You'll see a block that defines your database connection. If you ever change the password for your database user, you'll need to change it here, too.

$databases['migrate']['default'] = [
  'database' => 'YOUR-DATABASE-NAME',
  'username' => 'YOUR-DATABASE-USER-NAME',
  'password' => 'YOUR-DATABASE-USER-NAME-PASSWORD',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

The last line of the settings file should be for the config_sync_directory, but it's no longer accurate after your moved the directory earlier, so edit it like so (replacing HASH with the hash for your config directory):

$settings['config_sync_directory'] = $app_root . '/../config_HASH';

CHANGE THE PERMISSIONS on the settings.php file: sudo chmod ug=r,o=-rwx settings.php (doing ls -la after this should show that the permissions on settings.php are -r--r-----)
CHANGE THE PERMISSIONS on the files directory: sudo chmod a=rwx files

Install drush

composer require drush/drush && composer global require drush/drush && composer global update
So that you can call drush just by typing drush, install "Drush Launcher":
a. Navigate to your user's home directory: cd ~
b. wget -O drush.phar https://github.com/drush-ops/drush-launcher/releases/latest/download/drush.phar
c. chmod +x drush.phar
d. sudo mv drush.phar /usr/local/bin/drush
Navigate back to your site's root (e.g., cd /var/www/html/my_site_name_dir).
Clear your site's cache: drush cr

Secure the Private Files Directory

In the site's UI, navigate to admin/config/media/file-system and click 'Save configuation' to generate the .htaccess file that will protect that directory. Back in the terminal, navigate to the private files directory and do ls -la to verify that the .htaccess file was created.

Install Contributed Modules

To enhance the functionality of the site with contributed modules, you need to know the module's directory name on drupal.org. To find the module's directory name, look at the end of the module's URL. For example, the Views module is at https://www.drupal.org/project/feeds. The directory name is just feeds.

To install a module, use composer: composer require drupal/module_directory_name.

Then enable the module using drush: drush en -y module_directory_name

To uninstall a module:

drush pm-uninstall module_directory_name
composer remove drupal/module_directory_name

Here are the modules that I install on most of my sites:

devel: indispensible for developing themes and modules
feeds: import data from CSV or other formats
google_analytics: the name speaks for itself :-)
honeypot: excellent for keeping the bots away
metatag: facilitates the publication of metadata for your site
pathauto: automatically generates paths for your nodes
redirect: again, speaks for itself
search_api: more robust search than the search that comes with Drupal; also essential if you want to work with a Solr or Elastic Search instance)
token: allows the use of variables in certain situations, making it much easier to apply changes globally, etc.
token_filter: filter your tokens by context
views_bulk_operations: allows you to edite multiple nodes all at once, among other things
views_data_export: export your data in CSV, JSON, and other formats

Photo by Rubaitul Azad on Unsplash

Migrating the Digital Latin Library from Drupal 7 to Drupal 9

2021-10-04T00:00:00Z

Background

I manage several sites that have been running on Drupal 7. For a variety of reasons, I finally decided that it was time to upgrade them to Drupal 9. I wanted to bypass Drupal 8 altogether, since its end-of-life is coming up in November 2021. Previously, the upgrade path required a detour through D8, but now it's possible (theoretically) to go straight to D9, so that's what I planned to do.

My first migration adventure was with https://digitallatin.org/, the main informational site for the Digital Latin Library. I selected that one because it's a pretty simple site: a couple of custom content types and fields, no custom modules, very few users, and hardly any bells or whistles. I figured that migrating a simple site would prepare me for dealing with the more complex https://catalog.digitallatin.org/ later.

I'm going to include some command line stuff here, along with more general observations and notes, in the hope that this information will help someone else.

Just for context, I am working on a droplet at Digital Ocean running CentOS 7. That means it has MariaDB instead of MySQL, but otherwise everything is pretty standard. I am also using Composer (version 2.1.3) for managing the Drupal codebase.

Edit the settings.php file

Make these changes to settings.php.

Navigate to web/sites/default.
Open settings.php using your favorite text editor.
Search for 'trusted_host' and insert the following after the end of the commented section for that setting:

$settings['trusted_host_patterns'] = [
    INSERT_YOUR_HOST_PATTERN_HERE
];

Search 'file_private' and insert the following after the end of the commented section for that setting: $settings['file_private_path'] = $app_root . '/../private';
Search 'config_sync_directory' and insert the following after the end of the commented section for that setting:
$settings['config_sync_directory'] = $app_root . '/../DIRECTORYFROMSTEP8/sync';
At end of file add connection to migration database. NOTE It's important to name the key 'migrate'.

$databases['migrate']['default'] = array (
  'database' => 'DBNAME',
  'username' => 'DBUSER',
  'password' => 'DBPASSWORD',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);

After these steps, navigate in the browser to admin/config/media/file-system and click 'Save configuation' to generate the .htaccess file.

Set up Git

Now is a good time to set up Git so that you can track your work.

Add a .gitignore file to the root directory. Go to https://sjhuskey.info/drupal/gitignore-for-drupal/ for a good one. 🤓
Initiate a git repository: git init
Add files to repository: git add .
Commit: git commit -m "First commit."

Install and Enable Migrate Tools

I have encountered difficulties with installing the essential migration tools, since there are multiple conflicts between the Drupal core version, Drush version, and the various migrate modules. I have found it best to install the the migrate modules with Composer first (i.e., before installing Drush) and enable them with the UI (obviously, since Drush isn't installed yet). Note that --with-all-dependencies will install the right version of Drush, since Drush is a dependency of the migrate modules.

cd to the root site directory.
Install and enable migrate tools: composer require drupal/migrate_tools drupal/migrate_upgrade drupal/migrate_plus drupal/migrate_file --with-all-dependencies.

Evaluate Modules Installed on Original Site

Run the command sudo drush pm-list --type=Module --no-core --status=enabled > ~/SITENAME-modules.txt to save a list of all of the enabled contributed and custom modules to a text file in the user's home directory.
Download that file: scp USERNAME@SERVERNAME:~/SITENAME-modules.txt Directory-of-your-choice
Review the list to see if there are Drupal 9 equivalents.
Install equivalents using Composer.
Enable the modules with Drush.

It's important to do these steps so that the modules are taken into account when you generate the migration files.

Commit everything to the Git repository

At this point, it's a good idea to commit your changes to the Git repository.

git add .
git commit -m "Added modules before starting to build the migration."
git push (if you have a remote repository)

Generate the Migration YAML files

In this step, you'll generate YAML migration files without actually running the migration (that's what --configure-only does).

From the root of the site, run drush migrate-upgrade --configure-only --legacy-db-key=migrate --legacy-root=[INSERT THE ROOT DOMAIN OF YOUR SITE HERE]/

Now, so that you'll have a copy of all of the files to review offline with a good text editor, do the following:

Copy the config files to a directory called migrate in the /tmp directory: drush config:export --destination=/tmp/migrate
Copy only the files having to do with migration to a directory called migrate_files within your user's home directory: mkdir ~/migrate_files && cp /tmp/migrate/migrate_plus.migration.* /tmp/migrate/migrate_plus.migration_group.migrate_*.yml ~/migrate_files
Download that directory to your computer: scp -r USERNAME@SERVERNAME:~/SITENAME_migrate_files DIRECTORY_ON_YOUR_COMPUTER

Run the Migrations

Back in the root directory of the Drupal codebase, do the following:

drush migrate:import --tag=Configuration --execute-dependencies
drush migrate:import --tag=Content --execute-dependencies

It is very likely that there will be errors with one or both of these steps. At this point, debugging is the name of the game.

Errors and Solutions

Inline Entity Form

I ran into the error The "inline_entity_form_field_instance_settings" plugin does not exist. I honestly didn't think that the site I was working on used the Inline Entity Form module, so I hadn't installed it. Installing it did not resolve the issue, so I dove into the issue queue for that project and found a workaround at https://www.drupal.org/project/inline_entity_form/issues/3208995. That did the trick for me, but it looks like https://www.drupal.org/project/inline_entity_form/issues/3221074 might also be a good solution.

Google Analytics

The migrations related to the Google Analytics module failed, so I searched its issue queue, too. The solution was to uninstall and remove the module, then install the dev version and apply the patch at https://www.drupal.org/project/google_analytics/issues/3170816.

YouTube

The D7 version of the site has a content type with a field type of "Youtube," which was supplied by the YouTube Field module. I wasn't planning to use the YouTube Field module on the D9 version of the site, since D9 has a native Media field type that includes an option for embedding remote video files. But, since the module is supported for D8 and D9, I installed and enabled it. After that, the migration occurred without issue.

Photo by Rubaitul Azad on Unsplash

Making a Vocabulary List for Wheelock

2021-09-07T00:00:00Z

My colleagues and I wanted to have a table of all of the vocabulary words used in Wheelock's Latin that also showed the ranking of each word in terms of usage frequency as recorded in Dickinson College Commentaries' Latin Core Vocabulary list.

I used the helpful Google Doc of all of the vocabulary in Wheelock to get the list of words. DCC thoughtfully makes their Latin Core Vocabulary list available for free as a CSV (bene factum, DCC!). I did some preprocessing of the two sets of information to get two sets of data that I could compare. After that, I used the Python Pandas library to merge the two sets. Overkill? Definitely! But it beats doing the comparison manually!

If you're curious, you can see the repository with the data and the Python script at https://github.com/sjhuskey/latin-vocabulary.

Here's the table. It's sorted by Frequency Rank. You can also download it as a CSV.

Latin Word	Definition	Wheelock Chapter	Part of Speech	Semantic Group	Frequency Rank
sum, esse, fui, futurum	to be, exist	4	Verb: Irregular	Life and Being	2
qui, quae, quod	(relative pronoun) who, which, what, that	17	Pronoun	Pronouns/Interrogatives	3
hic, haec, hoc	this; the latter; (at times) he, she, it	9	Pronoun	Pronouns/Interrogatives	7
ille, illa, illud	that; the former; the famous; (at times) he, she, it	9	Pronoun	Pronouns/Interrogatives	8
tu, tui	you	11	Pronoun	Pronouns/Interrogatives	9
ego, mei	I	11	Pronoun	Pronouns/Interrogatives	11
is, ea, id	he, she, it	11	Pronoun	Pronouns/Interrogatives	13
ad (+acc)	to(ward), up to, near	8	Preposition	Place	14
omnis, omne	every, all	16	Adjective: 3rd Declension	Measurement	18
nec	and not, nor (neque/nec . . . neque/nec	11	Conjunction	Conjunctions/Adverbs	19
a/ab (+abl)	away from, from; by	14	Preposition	Place	21
ipse, ipsa, ipsum	(intensive pronoun) myself, yourself, him/her/itself, etc; the very, the actual	13	Pronoun	Pronouns/Interrogatives	22
possum, posse, potui	to be able, can, could, have power	6	Verb: Irregular	Making/Doing	23
magnus, magna, magnum	great, large; important	2	Adjective: 1st and 2nd Declension	Measurement	25
suus, sua, suum	his own, her own, its own, their own	13	Adjective: 1st and 2nd Declension	Pronouns/Interrogatives	27
do, dare, dedi, datum	to give, offer	1	Verb: 1st Conjugation	Social Life	28
video, vidēre, vidi, visum	to see; observe, understand	1	Verb: 2nd Conjugation	Vision	31
facio, facere, feci, factum	to make, do, accomplish	10	Verb: 3rd Conjugation -iō	Making/Doing	32
dico, dicere, dixi, dictum	to say; tell, speak; name, call	10	Verb: 3rd Conjugation -ō	Speech/Oratory	33
atque/ac	and, and also, and even	21	Conjunction	Conjunctions/Adverbs	35
ac	and, and also, and even	21	Conjunction	Conjunctions/Adverbs	36
alius, alia, aliud	other, another	9	Adjective: 1st and 2nd Declension	Pronouns/Interrogatives	37
res, rei (f)	thing, matter, business, affair	22	Noun: 5th Declension	Life and Being	38
habeo, habēre, habui, habitum	to have, hold, possess; consider, regard	3	Verb: 2nd Conjugation	Other Senses	39
animus, animi (m)	soul, spirit, mind; heart, mind, intellect, courage	5	Noun: 2nd Declension	Life and Being	40
meus, mea, meum	my	2	Pronoun	Pronouns/Interrogatives	41
deus, dei (m)	god	6	Noun: 2nd Declension	Religion	42
multus, multa, multum	many	2	Adjective: 1st and 2nd Declension	Measurement	43
tuus, tua, tuum	your (singular)	2	Adjective: 1st and 2nd Declension	Pronouns/Interrogatives	44
fero, ferre, tuli, latum	to bear, bring; suffer, endure, tolerate, say, report	31	Verb: Irregular	Verbs of Transport	45
ne		5	Conjunction	Conjunctions/Adverbs	47
manus, manus (f)	hand; handwriting; band	20	Noun: 4th Declension	The Body	48
nullus, nulla, nullum	not any; no, none	9	Adjective: 1st and 2nd Declension	Pronouns/Interrogatives	49
noster, nostra, nostrum	our	5	Pronoun	Pronouns/Interrogatives	52
unus, una, unum	one, single, alone	9	Adjective: 1st and 2nd Declension	Measurement	53
dies, diei (m)	day	22	Noun: 5th Declension	Lengths of Time	54
idem, eadem, idem	the same	11	Pronoun	Pronouns/Interrogatives	59
rex, regis (m)	king	7	Noun: 3rd Declension	The City	60
locus, loci (m)	place; passage in literature	9	Noun: 2nd Declension	Geography	62
venio, venire, veni, ventum	to come	10	Verb: 4th Conjugation	Motion	63
pars, partis (f)*	part, share; direction	14	Noun: 3rd Declension	Measurement	65
volo, velle, volui	to wish, want, be willing, will	32	Verb: Irregular	Emotions	66
bonus, bona, bonum	good, kind	4	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	68
ago, agere, egi, actum	to drive, lead, do, act; pass, spend	8	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	69
terra, terrae (f)	land, earth, ground, country	7	Noun: 1st Declension	Earth and Water	70
pater, patris (m)	father	12	Noun: 3rd Declension	The Household	71
neque/nec	and not, nor (neque/nec . . . neque/nec	11	Conjunction	Conjunctions/Adverbs	72
domus, domus (-i) (f)	home, house	37	Noun: 4th Declension	The House	73
corpus, corporis (n)	body	7	Noun: 3rd Declension	The Body	75
aliquis, aliquid	someone, somebody, something	23	Pronoun	Pronouns/Interrogatives	77
totus, tota, totum	whole, entire	9	Adjective: 1st and 2nd Declension	Measurement	78
hic, haec, hoc	this; the latter; (at times) he, she, it	9	Adverb	Place	80
iste, ista, istud	that of yours, that; (sometimes pejorative: that despicable, that wretched)	9	Pronoun	Pronouns/Interrogatives	81
urbs, urbis (f)*	city	14	Noun: 3rd Declension	The City	82
peto, petere, petivi, petitum	to seek, aim at, beseech	23	Verb: 3rd Conjugation -ō	Motion	83
iubeo, iubēre, iussi, iussum	to order, bid, command	21	Verb: 2nd Conjugation	Justice	84
vir, viri (m)	man, hero, husband	3	Noun: 2nd Declension	People	85
bellum, belli (n)	war	4	Noun: 2nd Declension	War and Peace	86
vita, vitae (f)	life; mode of life	2	Noun: 1st Declension	Life and Being	87
homo, hominis (m)	human being, man	7	Noun: 3rd Declension	People	88
tempus, temporis (n)	time; occasion, opportunity	7	Noun: 3rd Declension	Time	89
primus, prima, primum	first, foremost, chief, principal	27	Adjective: 1st and 2nd Declension	Time	91
hostis, hostis (m)*	an enemy (of the state); (plural = the enemy)	18	Noun: 3rd Declension	War and Peace	93
mors, mortis (f)*	death	14	Noun: 3rd Declension	Life and Being	95
eo, ire, ii, itum	to go (also: abeo, adeo, exeo, ineo, obeo, pereo, redeo)	37	Verb: Irregular	Motion	97
arma, armorum (n)	arms, weapons	28	Noun: 2nd Declension	War and Peace	98
superus, supera, superum	above, upper	27	Adjective: 1st and 2nd Declension	Religion	99
vinco, vincere, vici, victum	to conquer, overcome	8	Verb: 3rd Conjugation -ō	War and Peace	101
pono, ponere, posui, positum	to put, place, set	27	Verb: 3rd Conjugation -ō	Verbs of Transport	102
tantus, tanta, tantum	so large, so great, of such a size	29	Adjective: 1st and 2nd Declension	Measurement	105
teneo, tenere, tenui, tentum	to hold, keep, possess; restrain	14	Verb: 2nd Conjugation	Other Senses	106
causa, causae (f)	cause, reason; case, situation. (in ablative + preceding genitive: for the sake of)	21	Noun: 1st Declension	Speech/Oratory	107
sequor, sequi, secutus sum	to follow	34	Verb: Deponent	Motion	108
credo, credere, credidi, creditum	to believe, trust	25	Verb: 3rd Conjugation -ō	Education/Knowledge	109
accipio, accipere, accepi, acceptum	to take (to one’s self), receive, accept	24	Verb: 3rd Conjugation -iō	Social Life	110
virtus, virtutis (f)	manliness, courage; excellence, character, worth, virtue	7	Noun: 3rd Declension	Personality Traits/Characteristics	111
quaero, quaerere, quaesivi, quaesitum	to seek, look for, strive for; ask, inquire, inquire into	24	Verb: 3rd Conjugation -ō	Education/Knowledge	113
mitto, mittere, misi, missum	to send, let go	11	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	114
vis, vis (f)	force, power, violence (plural = strength)	14	Noun: 3rd Declension	War and Peace	115
amor, amoris (m)	love	7	Noun: 3rd Declension	Love	116
caelum, caeli (n)	sky	5	Noun: 2nd Declension	Air and Fire	117
sub (+abl with verbs of rest, +acc with verbs of motion)	under, up under, close to, at the foot of	7	Preposition	Place	118
nox, noctis (f)*	night	26	Noun: 3rd Declension	Lengths of Time	119
populus, populi (m)	people, the people, a nation	3	Noun: 2nd Declension	The City	122
caput, capitis (n)	head; leader; beginning; life; heading; chapter	11	Noun: 3rd Declension	The Body	124
mare, maris (n)*	sea	14	Noun: 3rd Declension	Earth and Water	125
quidam, quaedam, quiddam	certain, some	26	Pronoun	Pronouns/Interrogatives	126
mater, matris (f)	mother	12	Noun: 3rd Declension	The Household	127
quisquis, quidquid	whoever, whatever	23	Pronoun	Pronouns/Interrogatives	129
capio, capere, cepi, captum	to take, capture, seize, get	10	Verb: 3rd Conjugation -iō	War and Peace	131
duco, ducere, duxi, ductum	to lead, consider, regard; prolong	8	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	133
nomen, nominis (n)	name	7	Noun: 3rd Declension	Social Life	135
miser, misera, miserum	sad, wretched, miserable, unfortunate	15	Adjective: 1st and 2nd Declension	Emotions	137
fortuna, fortunae (f)	fortune, luck	2	Noun: 1st Declension	Religion	138
novus, nova, novum	new; strange	7	Adjective: 1st and 2nd Declension	Time	139
gravis, grave	heavy, weighty; serious, important; severe, grievous	19	Adjective: 3rd Declension	Measurement	140
longus, longa, longum	long	16	Adjective: 1st and 2nd Declension	Measurement	142
parvus, parva, parvum	small, little	4	Adjective: 1st and 2nd Declension	Measurement	143
relinquo, relinquere, reliqui, relictum	to leave behind, leave, abandon, desert	21	Verb: 3rd Conjugation -ō	Motion	144
fio, fieri, factus sum	to occur, happen; become; be made, be done	36	Verb: Irregular	Life and Being	146
os, oris (n)	mouth, face	14	Noun: 3rd Declension	The Body	147
alter, altera, alterum	the other (of two), second	9	Adjective: 1st and 2nd Declension	Measurement	148
ignis, ignis (m)*	fire	22	Noun: 3rd Declension	Air and Fire	151
timeo, timēre, timui	to be afraid, fear	15	Verb: 2nd Conjugation	Emotions	153
scelus, sceleris (n)	crime, wickedness, evil deed	19	Noun: 3rd Declension	Justice	154
debeo, debēre, debui, debitum	to owe; ought, must, should	1	Verb: 2nd Conjugation	Business/Money	155
vivo, vivere, vixi, victum	to live	10	Verb: 3rd Conjugation -ō	Life and Being	156
fatum, fati (n)	fate; death	29	Noun: 2nd Declension	Religion	157
voco, vocāre, vocavi, vocatum	to call, summon	1	Verb: 1st Conjugation	Speech/Oratory	158
paro, parāre, paravi, paratum	to prepare, provide; get, obtain	19	Verb: 1st Conjugation	Making/Doing	160
miles, militis (m)	soldier	23	Noun: 3rd Declension	War and Peace	161
medius, media, medium	middle, the middle of	22	Adjective: 1st and 2nd Declension	Place	162
audio, audire, audivi, auditum	to hear, listen to	10	Verb: 4th Conjugation	Other Senses	165
puto, putāre, putavi, putatum	to reckon, suppose, judge, think, imagine	25	Verb: 1st Conjugation	Education/Knowledge	166
annus, anni (m)	year	12	Noun: 2nd Declension	Lengths of Time	167
sto, stare, steti, statum	to stand, stand still, stand firm	13	Verb: 1st Conjugation	Life and Being	168
vox, vocis (f)	voice	34	Noun: 3rd Declension	Speech/Oratory	169
genus, generis (n)	origin; kind, type, sort, class	18	Noun: 3rd Declension	The Household	170
refero, referre, rettuli, relatum	to carry back, bring back; repeat, answer, report	31	Verb: Irregular	Verbs of Transport	171
scio, scire, scivi, scitum	to know	21	Verb: 4th Conjugation	Education/Knowledge	172
mens, mentis (f)*	mind, thought, intention	16	Noun: 3rd Declension	The Body	173
licet, licere, licuit (impersonal)	it is permitted, one may	37	Verb: Impersonal	Justice	175
solus, sola, solum	alone, only (non solum . . . sed etiam	9	Adjective: 1st and 2nd Declension	Measurement	176
fugio, fugere, fugi, fugiturum	to flee, hurry away; escape; go into exile; avoid, shun	10	Verb: 3rd Conjugation -iō	Travel	177
ullus, ulla, ulllum	any	9	Adjective: 1st and 2nd Declension	Pronouns/Interrogatives	178
nemo, nullius, nemini, neminem, nullo/nulla	no one, nobody	11	Pronoun	Pronouns/Interrogatives	179
natura, naturae (f)	nature	10	Noun: 1st Declension	Life and Being	180
mos, moris (m)	habit, custom, manner; (plural = character, morals)	7	Noun: 3rd Declension	Social Life	181
beneficium, beneficii (n)	benefit, kindness; favor	19	Noun: 2nd Declension	Social Life	182
pectus, pectoris (n)	breast, heart	35	Noun: 3rd Declension	The Body	183
fides, fidei (f)	faith, trust, trustworthiness, fidelity; promise, guarantee, protection	22	Noun: 5th Declension	Personality Traits/Characteristics	184
patior, pati, passus sum	to suffer, endure; permit	34	Verb: Deponent	Verbs of Compelling/Directing	185
cura, curae (f)	care, attention, caution, anxiety	4	Noun: 1st Declension	Love	186
ira, irae (f)	ire, anger	2	Noun: 1st Declension	Emotions	187
verbum, verbi (n)	word	5	Noun: 2nd Declension	Writing/Poetry	188
parens, parentis (m/f)	parent	28	Noun: 3rd Declension	The Household	190
puer, pueri (m)	boy	3	Noun: 2nd Declension	People	191
moveo, movēre, movi, motum	to move; arouse, affect	18	Verb: 2nd Conjugation	Motion	192
dolor, doloris (m)	pain, grief	38	Noun: 3rd Declension	Emotions	193
gens, gentis (f)*	clan, race, nation, people	21	Noun: 3rd Declension	The Household	194
modus, modi (m)	measure, bound, limit; manner, method, mode, way	22	Noun: 2nd Declension	Measurement	195
via, viae (f)	road, way, street	10	Noun: 1st Declension	Travel	196
quisque, quidque	each one, each person, each thing	13	Pronoun	Pronouns/Interrogatives	197
amicus, amica, amicum	friendly	11	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	198
pes, pedis (m)	lower leg, foot	38	Noun: 3rd Declension	The Body	199
imperium, imperii (n)	power to command, supreme power, authority, command, control, imperium	24	Noun: 2nd Declension	War and Peace	200
labor, laboris (m)	work, work, toil; a work, production	7	Noun: 3rd Declension	Business/Money	201
ingens (gen: ingentis)	huge	16	Adjective: 3rd Declension	Measurement	202
talis, tale	such, of such a sort	34	Adjective: 3rd Declension	Measurement	203
apud (+acc)	among, in the presence of, at the house of	31	Preposition	Place	205
oculus, oculi (m)	eye	4	Noun: 2nd Declension	The Body	206
vultus, vultus (m)	countenance, face	40	Noun: 4th Declension	The Body	209
cado, cadere, cecidi, casurum	to fall	12	Verb: 3rd Conjugation -ō	Violence	210
quis, quid [after: si, nisi, num, or ne]	anyone, anything, someone, something	33	Pronoun	Pronouns/Interrogatives	212
traho, trahere, traxi, tractum	to drag, draw; derive, acquire	8	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	213
metus, metus (m)	fear	20	Noun: 4th Declension	Emotions	215
consilium, consilii (n)	plan, purpose, counsel, advice, judgement, wisdom	4	Noun: 2nd Declension	The City	217
amo, amāre, amavi, amatum	to love	1	Verb: 1st Conjugation	Love	219
levis, leve	light, trivial	17	Adjective: 3rd Declension	Measurement	220
poena, poenae (f)	penalty, punishment	2	Noun: 1st Declension	Justice	223
frater, fratris (m)	brother	8	Noun: 3rd Declension	The Household	225
malus, mala, malum	bad, wicked, evil	4	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	227
iaceo, iacēre, iacui	to lie; lie prostrate; lie dead	25	Verb: 2nd Conjugation	The House	228
liber, libera, liberum	free	5	Adjective: 1st and 2nd Declension	Justice	229
liber, libri (m)	book	6	Adjective: 1st and 2nd Declension	Justice	229
iter, itineris (n)	journey; route, road	37	Noun: 3rd Declension	Travel	230
ferrum, ferri (n)	iron; sword	22	Noun: 2nd Declension	Violence	231
spes, spei (f)	hope	22	Noun: 5th Declension	Emotions	232
puella, puellae (f)	girl	2	Noun: 1st Declension	People	233
finis, finis (m)*	end, limit, boundary; purpose	21	Noun: 3rd Declension	Geography	236
gero, gerere, gessi, gestum	to carry; carry on, manage, conduct, wage	8	Verb: 3rd Conjugation -ō	War and Peace	237
ne		5	Adverb	Pronouns/Interrogatives	238
dux, ducis (m)	leader; guide; commander, general	23	Noun: 3rd Declension	War and Peace	239
premo, premere, pressi, pressum	to press; press hard, pursue	23	Verb: 3rd Conjugation -ō	War and Peace	240
dominus, domini (n)	master	40	Noun: 2nd Declension	The Household	241
mons, montis (m)*	mountain	20	Noun: 3rd Declension	Geography	242
litus, litoris (n)	shore, coast	23	Noun: 3rd Declension	Geography	245
soleo, solēre, solitus sum	to be accustomed	37	Verb: 2nd Conjugation	Personality Traits/Characteristics	246
equus, equi (m)	horse	23	Noun: 2nd Declension	Animals/Plants	248
durus, dura, durum	hard, harsh, rough, stern, unfeeling, hardy, difficult	29	Adjective: 1st and 2nd Declension	Other Senses	249
cogo, cogere, coegi, coactum (cum + ago)	to drive/bring together, force, compel	36	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	250
morior, mori, mortuus sum	to die	34	Verb: Deponent	Life and Being	253
carmen, carminis (n)	song, poem	7	Noun: 3rd Declension	Writing/Poetry	254
ratio, rationis (f)	reckoning, account; reason, judgement, consideration; system; manner, method	8	Noun: 3rd Declension	Education/Knowledge	256
ars, artis (f)*	art, skill	14	Noun: 3rd Declension	Education/Knowledge	258
dexter, dextra, dextrum	right, right	20	Adjective: 1st and 2nd Declension	Place	260
signum, signi (n)	sign, signal, indication; seal	13	Noun: 2nd Declension	War and Peace	261
lex, legis (f)	law, statute	26	Noun: 3rd Declension	Justice	264
periculum, periculi (n)	danger, risk	4	Noun: 2nd Declension	Violence	265
nascor, nasci, natus sum	to be born; spring forth arise	34	Verb: Deponent	Life and Being	266
exercitus, exercitus (m)	army	32	Noun: 4th Declension	War and Peace	267
ventus, venti (m)	wind	39	Noun: 2nd Declension	Air and Fire	269
audeo, audēre, ausus sum	to dare	7	Verb: 2nd Conjugation	Personality Traits/Characteristics	270
aqua, aquae (f)	water	14	Noun: 1st Declension	Earth and Water	272
rapio, rapere, rapui, raptum	to seize, snatch, carry away	21	Verb: 3rd Conjugation -iō	Violence	273
tristis, triste	sad, sorrowful; joyless, grim, severe	26	Adjective: 3rd Declension	Emotions	275
fama, famae (f)	rumor, report; fame	2	Noun: 1st Declension	Speech/Oratory	278
par (gen: paris) (+dat)	equal (to), like	32	Adjective: 3rd Declension	Measurement	281
vester, vestra, vestrum	your (plural)	6	Adjective: 1st and 2nd Declension	Pronouns/Interrogatives	282
flumen, fluminis (n)	river	18	Noun: 3rd Declension	Earth and Water	283
certus, certa, certum	definite, sure, certain, reliable	19	Adjective: 1st and 2nd Declension	Measurement	285
fortis, forte	brave, strong	16	Adjective: 3rd Declension	Personality Traits/Characteristics	286
placeo, placēre, placui, placitum (+dat)	to be pleasing to, please	35	Verb: 2nd Conjugation	Social Life	287
verto, vertere, verti, versum	to turn; change	23	Verb: 3rd Conjugation -ō	Motion	288
servo, servāre, servavi, servatum	to save, preserve, keep, guard, protect	1	Verb: 1st Conjugation	The Household	289
honor, honoris (m)	honor, esteem; public office	30	Noun: 3rd Declension	The City	290
dignus, digna, dignum	(+abl.) worthy, worthy of	29	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	291
tollo, tollere, sustuli, sublatum	to raise up, lift up; take away, remove, destroy	22	Verb: Irregular	Violence	293
nego, negāre, negavi, negatum	to deny, to say that . . . not	25	Verb: 1st Conjugation	Speech/Oratory	294
vetus (gen: veteris)	old	39	Adjective: 3rd Declension	Time	295
trado, tradere, tradidi, traditum	to give over, surrender; hand down, transmit, teach (trans + do)	33	Verb: 3rd Conjugation -ō	Business/Money	297
lux, lucis (f)	light	26	Noun: 3rd Declension	Air and Fire	299
sentio, sentire, sensi, sensum	to feel, perceive, think, experience	11	Verb: 4th Conjugation	Other Senses	302
cedo, cedere, cessi, cessum	to go, withdraw; yield to, grant, submit	28	Verb: 3rd Conjugation -ō	War and Peace	304
saxum, saxi (n)	rock	40	Noun: 2nd Declension	Earth and Water	306
-ve	or (suffix)	33	Conjunction	Conjunctions/Adverbs	307
aetas, aetatis (f)	period of life, life, age, an age, time	16	Noun: 3rd Declension	Lengths of Time	308
felix (gen: felicis)	lucky, fortunate, happy	22	Adjective: 3rd Declension	Personality Traits/Characteristics	309
loquor, loqui, locutus sum	to speak, say, tell	34	Verb: Deponent	Speech/Oratory	310
quantus, quanta, quantum	how large, how great, how much	30	Pronoun	Pronouns/Interrogatives	311
coepi, coepisse, coeptum	began	17	Verb: Irregular	Time	312
ius, iuris (n)	right, justice, law	14	Noun: 3rd Declension	Justice	314
muto, mutāre, mutavi, mutatum	to change, alter; exchange	14	Verb: 1st Conjugation	Making/Doing	315
invenio, invenire, inveni, inventum	to find, come upon, discover	10	Verb: 4th Conjugation	Travel	316
princeps (gen: principis)	chief, foremost	28	Adjective: 3rd Declension	The City	317
ops, opis (f)	help, aid	33	Noun: 3rd Declension	Business/Money	318
recipio, recipere, recepi, receptum	to take back, regain; admit, receive	24	Verb: 3rd Conjugation -iō	Verbs of Transport	319
sol, solis (m)	sun	27	Noun: 3rd Declension	Air and Fire	320
consul, consulis (m)	consul	11	Noun: 3rd Declension	The City	321
turba, turbae (f)	uproar, disturbance; mob, crowd, multitude	14	Noun: 1st Declension	The City	323
ager, agri (m)	field, farm	3	Noun: 2nd Declension	Animals/Plants	324
vitium, vitii (n)	fault, crime, vice	6	Noun: 2nd Declension	Justice	326
vulnus, vulneris (n)	wound	24	Noun: 3rd Declension	Violence	327
senatus, senatus (m)	senate	20	Noun: 4th Declension	The City	329
utor, uti, usus sum (+abl)	to use; enjoy, experience	34	Verb: Deponent	Making/Doing	330
copia, copiae (f)	supply, abundance (plural = supplies, troops, forces)	8	Noun: 1st Declension	War and Peace	331
opus, operis (n)	work, task; deed, accomplishment	38	Noun: 3rd Declension	Business/Money	332
numerus, numeri (m)	number	3	Noun: 2nd Declension	Measurement	338
cognosco, cognoscere, cognovi, cognitum	to become acquainted with, learn, recognize	30	Verb: 3rd Conjugation -ō	Education/Knowledge	339
patria, patriae (f)	fatherland, native land, homeland	2	Noun: 1st Declension	Geography	342
civitas, civitatis (f)	state, citizenship	7	Noun: 3rd Declension	The City	346
eripio, eripere, eripui, ereptum	to snatch away, take away, rescue	22	Verb: 3rd Conjugation -iō	Verbs of Transport	349
mundus, mundi (m)	world, universe	21	Noun: 2nd Declension	Earth and Water	350
cursus, cursus (m)	running, race; course	28	Noun: 4th Declension	Athletics	351
navis, navis (f)*	ship, boat	21	Noun: 3rd Declension	Travel	353
lacrima, lacrimae (f)	tear	40	Noun: 1st Declension	Emotions	354
humanus, humana, humanum	pertaining to man, human; humane, kind, refined, cultivated	4	Adjective: 1st and 2nd Declension	People	355
sidus, sideris (n)	constellation, star	29	Noun: 3rd Declension	Air and Fire	359
gloria, gloriae (f)	glory	5	Noun: 1st Declension	Social Life	360
auris, auris (f)*	ear	14	Noun: 3rd Declension	The Body	366
taceo, tacēre, tacui, tacitum	to be silent, leave unmentioned	28	Verb: 2nd Conjugation	Other Senses	369
ostendo, ostendere, ostendi, ostentum	to exhibit, show, display	23	Verb: 3rd Conjugation -ō	Other Senses	371
turpis, turpe	ugly; shameful, base, disgraceful	26	Adjective: 3rd Declension	Other Senses	377
voluptas, voluptatis (f)	pleasure	10	Noun: 3rd Declension	Social Life	378
iniuria, inuriae (f)	injury, injustice, wrong	39	Noun: 1st Declension	Justice	381
dulcis, dulce	sweet, pleasant, agreeable	16	Adjective: 3rd Declension	Other Senses	383
ingenium, ingenii (n)	nature, innate talent	29	Noun: 2nd Declension	Education/Knowledge	387
pax, pacis (f)	peace	7	Noun: 3rd Declension	War and Peace	388
iuvo, iuvāre, iuvi, iutum	to help	4	Verb: 1st Conjugation	Social Life	390
doceo, docēre, docui, doctum	to teach	8	Verb: 2nd Conjugation	Education/Knowledge	393
excipio, excipere, excepi, exceptum	to take out, except; take, receive, capture	24	Verb: 3rd Conjugation -iō	Verbs of Transport	394
clarus, clara, clarum	clear, bright, famous, renowned, illustrious	18	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	395
mora, morae (f)	delay	4	Noun: 1st Declension	Time	399
erro, errāre, erravi, erratum	to err, go astray, make a mistake, be mistaken; wander	1	Verb: 1st Conjugation	Travel	402
gaudeo, gaudēre, gavisus sum	to rejoice, be glad	23	Verb: 2nd Conjugation	Emotions	407
beatus, beata, beatum	happy, fortunate, blessed	10	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	408
verus, vera, verum	true, real, proper	4	Adjective: 1st and 2nd Declension	Speech/Oratory	410
incipio, incipere, incepi, inceptum	to begin	17	Verb: 3rd Conjugation -iō	Time	411
parco, parcere, peperci, parsurum (+dat)	to be lenient to; spare	35	Verb: 3rd Conjugation -ō	War and Peace	412
similis, simile	(+ gen. or dat.) similar (to), like, resembling	27	Adjective: 3rd Declension	Personality Traits/Characteristics	414
virgo, virginis (f)	maiden, virgin, young woman	7	Noun: 3rd Declension	People	418
lego, legere, legi, lectum	to read; pick out, choose, select	18	Verb: 3rd Conjugation -ō	Writing/Poetry	419
forma, formae (f)	form, shape; beauty	2	Noun: 1st Declension	Other Senses	422
praesto, praestāre, praestiti, praestitum	to excel; exhibit, show, offer, supply, furnish	28	Verb: 1st Conjugation	Other Senses	423
misceo, miscēre, miscui, mixtum	to mix, stir up, disturb	18	Verb: 2nd Conjugation	Earth and Water	425
transeo, transire, transii, transitum	to go across, cross; pass over, ignore	39	Verb: Irregular	Travel	431
ultimus, -a, -um	farthest, extreme; last, final	25	Adjective: 1st and 2nd Declension	Geography	432
gratus, grata, gratum	grateful; pleasing, agreeable	37	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	434
laudo, laudāre, laudavi, laudatum	to praise	1	Verb: 1st Conjugation	Social Life	435
somnus, somni (m)	sleep	26	Noun: 2nd Declension	Life and Being	438
cupio, cupere, cupivi, cupitum	to desire, wish, long for	17	Verb: 3rd Conjugation -iō	Love	441
exspecto, expsectāre, exspectavi, exspectatum	to look for, expect, await	15	Verb: 1st Conjugation	Vision	442
laus, laudis (f)	praise	8	Noun: 3rd Declension	Social Life	444
studium, studii (n)	zeal, eagerness, pursuit, study	9	Noun: 2nd Declension	Emotions	450
facilis, facile	easy, agreeable	16	Adjective: 3rd Declension	Personality Traits/Characteristics	451
sapiens (gen: sapientis)	wise, judicious	25	Adjective: 3rd Declension	Education/Knowledge	453
nolo, nolle, nolui	to not . . . wish, be unwilling	32	Verb: Irregular	Emotions	458
plenus, plena, plenum	full, abundant, generous	6	Adjective: 1st and 2nd Declension	Measurement	459
adversus, adversa, adversum	opposite, adverse	34	Adverb	War and Peace	460
carus, cara, carum	dear	11	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	462
disco, discere, didici	to learn	8	Verb: 3rd Conjugation -ō	Education/Knowledge	465
arbor, arboris (f)	tree	38	Noun: 3rd Declension	Animals/Plants	468
eo, ire, ii, itum	to go (also: abeo, adeo, exeo, ineo, obeo, pereo, redeo)	37	Adverb	Place	470
civis, civis (m/f)*	citizen	14	Noun: 3rd Declension	The City	471
specto, spectāre, spectavi, spectatum	to look at, watch, see	34	Verb: 1st Conjugation	Vision	473
donum, doni (n)	gift, present	4	Noun: 2nd Declension	Social Life	476
amitto, amittere, amisi, amissum	to lose, let go	12	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	486
anima, animae (f)	soul, spirit	34	Noun: 1st Declension	Life and Being	493
libertas, libertatis (f)	freedom, liberty	8	Noun: 3rd Declension	The City	495
servus, servi (m) or serva, servae (f)	slave	24	Noun: 2nd Declension	The Household	496
soror, sororis (f)	sister	8	Noun: 3rd Declension	The Household	497
exigo, exigere, exegi, exactum (ex + ago)	to drive out, force out, exact; drive through, complete, perfect	36	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	500
femina, feminae (f)	woman	3	Noun: 1st Declension	People	501
miror, mirāri, miratus sum	to marvel at, admire, wonder	35	Verb: Deponent	Emotions	504
sedeo, sedēre, sedi, sessum	to sit	34	Verb: 2nd Conjugation	The House	506
noceo, nocēre, nocui, nocitum (+dat)	to do harm to, harm, injure	35	Verb: 2nd Conjugation	Violence	509
intellego, intellegere, intellexi, intellectum	to understand	11	Verb: 3rd Conjugation -ō	Education/Knowledge	512
iungo, iungere, iunxi, iunctum	to join	13	Verb: 3rd Conjugation -ō	Making/Doing	513
cogito, cogitāre, cogitavi, cogitatum	to think, ponder, consider, plan	1	Verb: 1st Conjugation	Education/Knowledge	515
limen, liminis (n)	threshold	26	Noun: 3rd Declension	The House	516
dubito, dubitāre, dubitavi, dubitatum	to doubt, hesitate	30	Verb: 1st Conjugation	Education/Knowledge	521
odium, odii (n)	hatred	38	Noun: 2nd Declension	Emotions	522
nescio, nescire, nescivi, nescitum	not to know, to be ignorant	25	Verb: 4th Conjugation	Education/Knowledge	525
pecunia, pecuniae (f)	money	2	Noun: 1st Declension	Business/Money	530
tango, tangere, tetigi, tactum	to touch	21	Verb: 3rd Conjugation -ō	Other Senses	534
respondeo, respondēre, respondi, responsum	to answer	29	Verb: 2nd Conjugation	Speech/Oratory	535
timor, timoris (m)	fear	10	Noun: 3rd Declension	Emotions	536
valeo, valēre, valui, valiturum	to be strong, have power; be well	1	Verb: 2nd Conjugation	Social Life	539
condo, condere, condidi, conditum	to put together/into, store; found, establish	29	Verb: 3rd Conjugation -ō	The City	540
auxilium, auxilii (n)	help, aid	31	Noun: 2nd Declension	War and Peace	543
auctor, auctoris (m)	increaser, author, originator	19	Noun: 3rd Declension	Writing/Poetry	546
animal, animalis (n)*	animal, living creature	14	Noun: 3rd Declension	Animals/Plants	547
salus, salutis (f)	health, safety; greeting	21	Noun: 3rd Declension	Life and Being	549
pateo, patēre, patui	to be open, lie open; be accessible; be evident	32	Verb: 2nd Conjugation	Geography	550
rogo, rogāre, rogavi, rogatum	to ask	30	Verb: 1st Conjugation	Speech/Oratory	551
uxor, uxoris (f)	wife	7	Noun: 3rd Declension	The Household	552
rego, regere, rexi, rectum	to rule, guide, direct	16	Verb: 3rd Conjugation -ō	The City	554
senex (gen: senis)	old, aged	16	Noun: 3rd Declension	People	558
curro, currere, cucurri, cursum	to run, rush, move quickly	14	Verb: 3rd Conjugation -ō	Athletics	562
pello, pellere, pepuli, pulsum	to strike, push; drive out, banish	24	Verb: 3rd Conjugation -ō	Violence	563
potens (gen: potentis)	powerful	16	Adjective: 3rd Declension	Personality Traits/Characteristics	567
scribo, scribere, scripsi, scriptum	to write, compose	8	Verb: 3rd Conjugation -ō	Writing/Poetry	568
pulcher, pulchra, pulchrum	beautiful	5	Adjective: 1st and 2nd Declension	Vision	569
surgo, surgere, surrexi, surrectum	to get up, arise	29	Verb: 3rd Conjugation -ō	Earth and Water	570
careo, carēre, carui, cariturum (+abl)	to be without, to be deprived of, want, lack; be free from	20	Verb: 2nd Conjugation	Business/Money	572
praebeo, praebēre, praebui, praebitum	to offer, provide	32	Verb: 2nd Conjugation	Verbs of Transport	584
sententia, sententiae (f)	feeling, though, opinion, vote, sentence	2	Noun: 1st Declension	Education/Knowledge	586
acer, acris, acre	sharp, keep, eager; severe, fierce	16	Adjective: 3rd Declension	Other Senses	587
brevis, breve	short, small, brief	16	Adjective: 3rd Declension	Measurement	589
cornu, cornus (n)	horn	20	Noun: 4th Declension	Animals/Plants	591
moenia, moenium (n)	city walls	29	Noun: 3rd Declension	The City	593
vinculum, vinculi (n)	chain, bond, fetter	36	Noun: 2nd Declension	War and Peace	594
malo, malle, malui	to want (something) more, instead; prefer	32	Verb: Irregular	Emotions	598
impero, imperāre, imperavi, imperatum (+dat)	to give orders to, command	35	Verb: 1st Conjugation	War and Peace	602
prohibeo, prohibēre, prohibui, prohibitum	to keep (back), prevent, hinder, restrain	20	Verb: 2nd Conjugation	Verbs of Compelling/Directing	604
officium, officii (n)	duty, service	4	Noun: 2nd Declension	The City	607
committo, committere, comisi, comissum	to entrust, commit	15	Verb: 3rd Conjugation -ō	Social Life	608
cresco, crescere, crevi, cretum	to increase	34	Verb: 3rd Conjugation -ō	Animals/Plants	609
aequus, aequa, aequum	level, even; calm, equal, just; favorable	22	Adjective: 1st and 2nd Declension	Justice	610
factum, facti (n)	deed, act, achievement	13	Noun: 2nd Declension	Making/Doing	611
accedo, accedere, accessi, accessum	to come (to), approach	36	Verb: 3rd Conjugation -ō	Motion	614
contemno, contemnere, contempsi, contemptum	to despise, scorn	36	Verb: 3rd Conjugation -ō	Emotions	615
antiquus, antiqua, antiquum	ancient, old	2	Adjective: 1st and 2nd Declension	Lengths of Time	617
memoria, memoriae (f)	memory, recollection	15	Noun: 1st Declension	Education/Knowledge	627
arx, arcis (f)*	citadel, stronghold	23	Noun: 3rd Declension	The City	638
vinum, vini (n)	wine	31	Noun: 2nd Declension	Animals/Plants	640
confero, conferre, contuli, collatum	to bring together, compare; confer, bestow	31	Verb: Irregular	Verbs of Transport	645
spero, sperāre, speravi, speratum	to hope for, hope	25	Verb: 1st Conjugation	Emotions	648
plebs, plebis (f)	the common people, populace, plebeians	33	Noun: 3rd Declension	The City	649
defendo, defendere, defendi, defensum	to ward off; defend, protect	20	Verb: 3rd Conjugation -ō	War and Peace	653
cerno, cernere, crevi, cretum	to distinguish, discern, perceive	22	Verb: 3rd Conjugation -ō	Education/Knowledge	655
superbus, superba, superbum	arrogant, overbearing, haughty, proud	26	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	656
adversus, adversa, adversum	opposite, adverse	34	Adjective: 1st and 2nd Declension	War and Peace	657
morbus, morbi (m)	disease, sickness	9	Noun: 2nd Declension	The Body	658
communis, commune	common, general, of/for the community	20	Adjective: 3rd Declension	The City	660
hora, horae (f)	hour, time	10	Noun: 1st Declension	Lengths of Time	664
supero, superāre, superavi, superatum	to be above, have the upper hand, surpass; overcome, conquer	5	Verb: 1st Conjugation	War and Peace	668
vulgus, vulgi (n)	the common people, mob, rabble	21	Noun: 2nd Declension	The City	675
praemium, praemii (n)	reward, prize	35	Noun: 2nd Declension	Business/Money	680
fateor, fatēri, fassus sum	to confess, admit	34	Verb: Deponent	Justice	689
amicitia, amicitiae (f)	friendship	10	Noun: 1st Declension	Social Life	690
os, oris (n)	mouth, face	14	Noun: 3rd Declension	The Body	696
interficio, interficere, interfeci, interfectum	to kill, murder	37	Verb: 3rd Conjugation -iō	Violence	699
appello, appellāre, appellavi, appellatum	to speak to, address (as), call, name	14	Verb: 1st Conjugation	Social Life	700
spiritus, spiritus (m)	breath, breathing; spirit, soul	20	Noun: 4th Declension	Life and Being	703
terreo, terrēre, terrui, territum	to frighten, terrify	1	Verb: 2nd Conjugation	Emotions	705
invidia, invidiae (f)	jealousy	31	Noun: 1st Declension	Emotions	707
pugno, pugnāre, pugnavi, pugnatum	to fight	29	Verb: 1st Conjugation	Violence	708
littera, litterae (f)	a letter of the alphabet; (plural = letter, literature)	7	Noun: 1st Declension	Writing/Poetry	710
moneo, monēre, monui, monitum	to warn, remind, advise	1	Verb: 2nd Conjugation	Speech/Oratory	711
divitiae, divitiarum (f)	riches, wealth	13	Noun: 1st Declension	Business/Money	712
experior, experiri, expertus sum	to try, test; experience	39	Verb: Deponent	Education/Knowledge	713
otium, otii (n)	leisure, peace	4	Noun: 2nd Declension	Social Life	715
promitto, promittere, promisi, promissum	to send forth; promise	32	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	720
imperator, imperatoris (m)	general, commander-in-chief, emperor	24	Noun: 3rd Declension	War and Peace	723
discedo, discedere, discessi, discessum	to go away, depart	20	Verb: 3rd Conjugation -ō	Travel	726
caecus, -a, -um	blind	17	Adjective: 1st and 2nd Declension	Vision	728
lingua, linguae (f)	language; tongue	25	Noun: 1st Declension	The Body	732
for, fāri, fatus sum	to speak (prophetically), talk, foretell	40	Verb: Deponent	Speech/Oratory	739
humus, humi (f)	ground, earth; soil	37	Noun: 2nd Declension	Earth and Water	740
curo, curāre, curavi, curatum	to care for, attend to; heal, cure	36	Verb: 1st Conjugation	Love	743
aes, aeris (n)	bronze	40	Noun: 3rd Declension	Business/Money	744
celer, celeris, celere	quick, swift, rapid	16	Adjective: 3rd Declension	Time	745
mensa, mensae (f)	table	26	Noun: 1st Declension	The House	747
iudicium, iudicii (n)	judgement, decision, opinion; trial	19	Noun: 2nd Declension	Justice	749
victoria, victoriae (f)	victory	8	Noun: 1st Declension	War and Peace	750
tempestas, tempestatis (f)	period of time, season; weather; storm	15	Noun: 3rd Declension	Lengths of Time	753
oro, orāre, oravi, oratum	to speak, plead; beg, beseech, entreat, pray	36	Verb: 1st Conjugation	Religion	755
porta, portae (f)	gate, entrance	2	Noun: 1st Declension	The City	759
reperio, reperire, repperi, repertum	to find, discover, learn; get	40	Verb: 4th Conjugation	Education/Knowledge	765
culpa, culpae (f)	blame, fault	5	Noun: 1st Declension	Justice	769
iustus, iusta, iustum	just, right	40	Adjective: 1st and 2nd Declension	Justice	770
fluo, fluere, fluxi, fluxum	to flow	18	Verb: 3rd Conjugation -ō	Earth and Water	772
licet, licere, licuit (impersonal)	it is permitted, one may	37	Conjunction	Justice	778
probo, probāre, probavi, probatum	to approve, recommend; test	27	Verb: 1st Conjugation	Verbs of Compelling/Directing	784
doleo, dolēre, dolui, doliturum	to grieve, suffer, hurt, give pain	31	Verb: 2nd Conjugation	Emotions	785
odi, odisse, osum	to hate	20	Verb: Irregular	Emotions	790
sensus, sensus (m)	feeling, sense	20	Noun: 4th Declension	Emotions	793
exsilium, exsilii (n)	exile, banishment	31	Noun: 2nd Declension	Travel	794
sapientia, sapientiae (f)	wisdom	3	Noun: 1st Declension	Education/Knowledge	797
decerno, decernere,decrevi, decretum	to decide, settle, decree	36	Verb: 3rd Conjugation -ō	Education/Knowledge	800
occido, occidere, occidi, occasum	to fall down; die; set	31	Verb: 3rd Conjugation -ō	Violence	801
contineo, continēre, continui, contentum	to hold together, contain, keep, enclose	21	Verb: 2nd Conjugation	Verbs of Compelling/Directing	804
oportet, oportere, oportuit (impersonal)	it is proper, right, necessary	39	Verb: Impersonal	Social Life	806
forum, fori (n)	forum, marketplace	26	Noun: 2nd Declension	The City	811
offero, offere, obtuli, oblatum	to offer	31	Verb: Irregular	Verbs of Transport	812
alo, alere, alui, altum	to nourish, support, sustain, increase; cherish	13	Verb: 3rd Conjugation -ō	Life and Being	817
proficiscor, proficisci, profectus sum	to set out, start	34	Verb: Deponent	Travel	835
secundus, secunda, secundum	second; favorable	6	Adjective: 1st and 2nd Declension	Measurement	836
iudex, iudicis (m)	judge, juror	19	Noun: 3rd Declension	Justice	839
nimis or nimium	too, too much, excessively	9	Adverb	Personality Traits/Characteristics	841
pauper (gen: pauperis)	of small means, poor	32	Adjective: 3rd Declension	Business/Money	844
pareo, parēre, parui (+dat)	to be obedient to, obey	35	Verb: 2nd Conjugation	Verbs of Compelling/Directing	847
utilis, utile	useful, advantageous	27	Adjective: 3rd Declension	Making/Doing	850
pauci, paucae, pauca	few, a few	3	Adjective: 1st and 2nd Declension	Measurement	858
difficilis, difficile	difficult, hard, troublesome	16	Adjective: 3rd Declension	Personality Traits/Characteristics	861
initium, initii (n)	beginning, commencement	33	Noun: 2nd Declension	Time	865
consumo, consumere, consumpsi, consumptum	to consume, use up	30	Verb: 3rd Conjugation -ō	Life and Being	869
rideo, ridēre, risi, risum	to laugh, laugh at	24	Verb: 3rd Conjugation -ō	Emotions	874
rus, ruris (n)	the country, countryside	37	Noun: 3rd Declension	Geography	879
vito, vitāre, vitavi, vitatum	shun, avoid	14	Verb: 1st Conjugation	Social Life	881
servio, servire, servivi, servitum (+dat)	to be a slave to, serve	35	Verb: 4th Conjugation	The Household	883
vereor, verēri, veritus sum	to show reverence for, respect; be afraid of	40	Verb: Deponent	Emotions	884
hortor, hortāri, hortatus sum	to encourage, urge	34	Verb: Deponent	Speech/Oratory	887
perpetuus, perpetua, perpetuum	perpetual, lasting, uninterrupted, continuous	6	Adjective: 1st and 2nd Declension	Lengths of Time	891
desidero, desiderāre, desideravi, desideratum	to desire, long for, miss	17	Verb: 1st Conjugation	Love	892
iacio, iacere, ieci, iactum	to thow; hurl	15	Verb: 3rd Conjugation -iō	Athletics	899
laboro, laborāre, laboravi, laboratum	to labor; be in distress	21	Verb: 1st Conjugation	Business/Money	900
liber, libera, liberum	free	5	Noun: 2nd Declension	Writing/Poetry	901
liber, libri (m)	book	6	Noun: 2nd Declension	Writing/Poetry	901
luna, lunae (f)	moon	28	Noun: 1st Declension	Air and Fire	902
conor, conāri, conatus sum	to try, attempt	34	Verb: Deponent	Making/Doing	905
cupido, cupidinis (f)	desire, passion	36	Noun: 3rd Declension	Love	906
insula, insulae (f)	island	23	Noun: 1st Declension	Geography	908
filia, filiae (f)	daughter (filiabus: dat. and abl. pl.)	3	Noun: 1st Declension	The Household	909
narro, narrāre, narravi, narratum	to tell, report, narrate	24	Verb: 1st Conjugation	Speech/Oratory	910
egredior, egredi, egressus sum	to go out	34	Verb: Deponent	Travel	912
poeta, poetae (m)	poet	2	Noun: 1st Declension	Writing/Poetry	913
fructus, fructus (m)	fruit; profit, benefit, enjoyment	20	Noun: 4th Declension	Animals/Plants	927
magister, magistri (m) or magistra,	ae (f)	4	Noun: 2nd Declension	Education/Knowledge	933
stella, stellae (f)	star	28	Noun: 1st Declension	Air and Fire	934
educo, educāre, educavi, educatum	to bring up, educate	23	Verb: 3rd Conjugation -ō	Verbs of Compelling/Directing	935
suscipio, suscipere, suscepi, susceptum	to undertake	25	Verb: 3rd Conjugation -iō	Verbs of Transport	937
sacerdos, sacerdotis (m)	priest	23	Noun: 3rd Declension	Religion	939
vicinus, vicini (m)	neighbor	21	Adjective: 1st and 2nd Declension	Geography	940
familia, familiae (f)	household, family	19	Noun: 1st Declension	The Household	943
sanus, sana, sanum	sound, healthy, sane	5	Adjective: 1st and 2nd Declension	Life and Being	946
principium, principii (n)	beginning	12	Noun: 2nd Declension	Time	948
mortalis, mortale	mortal	18	Adjective: 3rd Declension	Life and Being	950
dignitas, dignitatis (f)	merit, prestige, dignity	38	Noun: 3rd Declension	Personality Traits/Characteristics	956
mulier, mulieris (f)	woman	39	Noun: 3rd Declension	People	961
arbitror, arbitrāri, arbitratus sum	to judge, think	34	Verb: Deponent	Education/Knowledge	963
fabula, fabulae (f)	story, tale; play	24	Noun: 1st Declension	Writing/Poetry	966
scientia, scientiae (f)	knowledge	18	Noun: 1st Declension	Education/Knowledge	971
diligo, diligere, dilexi, dilectum	to esteem, love	13	Verb: 3rd Conjugation -ō	Love	973
dormio, dormire, dormivi, dormitum	to sleep	31	Verb: 4th Conjugation	Life and Being	975
creo, creāre, creavi, creatum	to create	12	Verb: 1st Conjugation	Making/Doing	978
fidelis, fidele	faithful, loyal	25	Adjective: 3rd Declension	Personality Traits/Characteristics	979
studeo, studēre, studui (+dat)	to direct one’s zeal to, be eager for, study	35	Verb: 2nd Conjugation	Emotions	989
mundus, mundi (m)	world, universe	21	Adjective: 1st and 2nd Declension	Personality Traits/Characteristics	997
absens (gen: absentis)	absent	37
acerbus, acerba, acerbum	harsh, bitter, grievous	12
adfero, adferre, attuli, allatum	to bring to	31
admitto, admittere, admisi, admissum	to admit, receive, let in	17
adulescens, adulescentis (m/f)	young man or woman	12
adulescentia, adulescentiae (f)	youth, young manhood; youthfulness	5
aedificium, aedificii (n)	building, structure	39
aestas, aestatis (f)	summer	35
agricola, agricolae (m)	farmer	3
ait, aiunt	he says, they say	25
ambulo, ambulāre, ambulavi, ambulatum	to walk	39
amica, amicae (f) and amicus, amici (m)	friend	3
ante (+acc)	before, in front of	13
antepono, anteponere, anteposui, antepositum	to put before, prefer	35
argumentum, argumenti (n)	proof, evidence, argument	19
as, assis (m)	an as	31
Asia, Asiae (f)	Asia	12
asper, aspera, asperum	rough, harsh	21
at	but; but, mind you; but, you say (more emotional than sed)	19
Athenae, Athenarum (f)	Athens	37
auditor, auditoris (m)	hearer, listener; member of an audience	16
aut	or (aut . . . aut	17
autem	(post positive) however; moreover	11
avarus, avara, avarum	greedy, avaricious	3
basium, basii (n)	kiss	4
bellus, bella, bellum	pretty, handsome, charming	4
bene	well, satisfactorily, quite	11
bibo, bibere, bibi	to drink	30
Caesar, Caesaris (m)	(Gaius Julius) Caesar	12
candidatus, -a, -um	shining, bright, white; beautiful	33
carpo, carpere, carpsi, carptum	to harvest, pluck; seize	36
Carthago, Carthaginis (f)	Carthage	24
casa, casae (f)	house, cottage, hut	21
cena, cenae (f)	dinner	26
ceno, cenāre, cenavi, cenatum	to dine	5
centum	hundred	15
ceteri, ceterae, cetera	the remaining, the rest, the other, all the others	30
Cicero, Ciceronis (m)	(Marcus Tullius) Cicero	8
cito	quickly	17
clementia, clementiae (f)	mercy, mildness, gentleness	16
comprehendo, comprehendere, comprehendi, comprehensum	to grasp, seize, arrest; comprehend, understand	30
coniurati, coniuratorum (m)	conspirators	20
contendo, contendere, contendi, contentum	to strive, struggle, contend; hasten	29
contra (+acc)	against	19
contundo, contundere, contudi, contusum	to beat, crush, bruise, destroy	36
cotidie	daily, every day	36
cras	tomorrow	5
culpo, culpāre, culpavi, culpatum	to blame, censure	5
cum (+abl)	with	10
cum (+subjunctive) when, since, although; (+indicative) when		31
cupiditas, cupiditatis (f)	desire, longing, passion; avarice, cupidity	10
cupidus, cupida, cupidum	desirous, eager, fond; (often +gen.)	39
cur	why	18
custodia, custodiae (f)	protection, custody (pl: guards)	32
de (+ablative)	down from, from; concerning, about	3
dea, deae (f)	goddess	6
dedico, dedicāre, dedicavi, dedicatum	to dedicate	28
dehinc	then, next	25
deinde	then, next, thereupon	18
delectatio, delectationis (f)	delight, pleasure, enjoyment	27
delecto, delectāre, delectavi, delectatum	to delight, charm, please	19
deleo, delēre, delevi, deletum	to destroy, wipe out, erase	17
demonstro, demonstrāre, demonstravi, demonstratum	to point out, show	8
denique	finally, at last, lastly	29
digitus, digiti (m)	finger, toe	31
diligens	diligent, careful	27
discipula, discipulae (f) and discipulus, discipuli (m)	learner, pupil, student	6
dissimilis, dissimile	unlike, different	27
diu	for a long time	12
dives (gen: divitis or ditis)	rich	32
doctus, docta, doctum	taught, learned, skilled	13
dum	while, as long as	8
dummodo (+subjunctive)	provided that, so long as	32
egeo, egēre, egui	(+ abl. or gen.) to need, lack, want	28
elephantus, elephanti (m)	elephant	31
enim	(post positive) for; in fact, truly	9
erga (+acc)	toward	38
est	is	2
et	and (et . . . et	2
etiam	even, also	11
etsi	even if	38
ex (+abl)	out of, from, from within; by reason of, on account of	8
exitium, exitii (n)	destruction, ruin	4
expello, expellere, expuli, expulsum	to drive out, expel, banish	24
expleo, explēre, explevi, expletum	to fill, fill up, complete	28
explico, explicāre, explicavi, explicatum	to unfold; explain; spread out, deploy	40
expono, exponere, exposui, expositum	to set forth, explain, expose	30
fatigo, fatigāre, fatigavi, fatigatum	to weary, tire out	40
fenestra, fenestrae (f)	window	21
ferox	fierce, savage	25
filius, filii (m)	son	3
firmus, firma, firmum	firm, strong; reliable	38
foris	out of doors, outside	37
fortasse	perhaps	36
fortunatus, fortunata, fortunatum	forunate, lucky, happy	13
foveo, fovēre, fovi, fotum	to comfort, nurture, cherish	35
furtim	stealthily, secretly	30
geminus, -a, -um	twin	25
genu, genus (n)	knee	20
gracilis, gracile	slender, thin	27
Graecia, Graeciae (f)	Greece	19
Graecus, Graeca, Graecum	Greek	6
hasta, hastae (f)	spear	23
heri	yesterday	5
heu	ah! alas!	33
hīc	here	25
hodie	today	3
humilis, humile	humble, lowly	27
iam	now, already, soon	19
ianua, ianuae (f)	door	35
ibi	there	6
idoneus, idonea, idoneum	suitable, fit, appropriate	37
igitur	(post positive) therefore, consequently	5
ignosco, ignoscere, ignovi, ignotum (+dat)	to grant pardon to, forgive	35
immortalis, immortale	not subject to death, immortal	19
immotus, immota, immotum	unmoved; unchanged; unrelenting	37
in (+ablative)	in, on	3
in (+acc)	into, on to, toward; against	9
incertus, incerta, incertum	uncertain, unsure, doubtful	22
infirmus, infirma, infirmum	not strong, weak, feeble	38
inquit	he says, he said	22
insidiae, insidiarum (f)	ambush, plot, treachery	6
inter (+acc)	between, among	15
invideo, invidēre, invidi, invisum	to be envious (+dat), to look at with envy, to envy, be jealous of	31
invito, invitāre, invitavi, invitatum	to entertain, invite; summon	26
iratus, irata, iratum	angry	35
ita	so thus	29
Italia, Italiae (f)	Italy	15
itaque	and so, therefore	15
iterum	again, a second time	21
iucundus, iucunda, iucundum	pleasant, delightful, agreeable, pleasing	16
Latinus, Latina, Latinum	Latin	22
lector, lectoris (m) & lectrix lectricis (f)	reader	36
libellus, libelli (m)	little book	17
libenter	with pleasure, gladly	38
liberalis, liberale	of, relating to a free person; worthy of a free man, decent, liberal; generous	39
libero, liberāre, liberavi, liberatum	to free, set free, liberate	19
libo, libāre, libavi, libatum	to pour a libation on; pour ritually; sip; touch gently	39
ludus, ludi (m)	game, sport; school	18
magnanimus, magnanima, magnanimum	great-hearted, brave, magnanimous	23
maior, maius	greater; older	27
me	me, myself (accusative case)	1
medicus, medici (m)	doctor, physician	12
mediocris, mediocre	ordinary, moderate, mediocre	31
merus, -a, -um	pure, undiluted	33
meta, metae (f)	turning point, goal; limit, boundary	40
mille	thousand	15
minuo, minuere, minui, minutum	to lessen, diminish	30
mirabilis, mirabile	amazing, wondrous	38
molior, moliri, molitus sum	to work at, build, undertake, plan	34
mollio, mollire, mollivi, mollitum	to soften; make calm, make less hostile	29
monumentum, monumenti (n)	monument	40
mortuus, mortua, mortuum	dead	28
mox	soon	30
nam	for	13
nasus, nasi (m)	nose	40
nata, natae (f)	daughter	29
nauta, nautae (m)	sailor	2
navigo, navigāre, navigavi, navigatum	to sail, navigate	17
ne	(+subjunct) not, in order that . . . not, that . . . not, in order not to	28
necesse	necessary, inevitable	39
neco, necāre, necavi, necatum	to kill, murder	7
neglego, neglegere, neglexi, neglectum	to neglect, disregard	17
nepos, nepotis (m)	grandson, descendant	27
neuter, neutra neutrum	neither, not either	9
nihil	nothing	1
nihil	nothing	4
nimium	too, too much, excessively	9
nisi	if . . . not, unless	19
non	not	1
nonne	introduces question anticipating a “yes”	40
nubes, nubis (f)*	cloud	14
nubo, nubere, nupsi, nuptum	to cover, veil; (+dat) to be married to, marry	35
num	1. introduces question anticipating a “no”. 2. introduces indirect questions and means “whether.”	40
numquam	never	8
nunc	now	6
nuntio, nuntiāre, nuntiavi, nuntiatum	to announce, report, relate	25
nuper	recently	12
oblecto, oblectāre, oblectavi, oblectatum	to please, amuse, delight; pass time pleasantly	36
occasio, occasionis (f)	occasion, opportunity	28
olim	at that time, once, formerly; in the future	13
omnino	wholly, entirely, altogether	40
opinor, opināri, opinatus sum	to suppose	40
opprimo, opprimere, oppressi, oppressum	to suppress, overwhelm, overpower, check	23
oppugno, oppugnāre, oppugnavi, oppugnatum	to fight against, attack, assault, assail	39
orator, oratoris (m)	orator; speaker	23
orno, ornāre, ornavi, ornatum	to equip, furnish, adorn	39
osculum, osculi (n)	kiss	29
patefacio, patefacere, patefeci, patefactum	to make open, open; disclose, expose	25
patientia, patientiae (f)	suffering; patience, endurance	12
paupertas, paupertatis (f)	poverty	32
per (+acc)	through	13
peregrinor, peregrinari, peregrinatus sum	to travel abroad, wander	37
perfugium, perfugii (n)	refuge, solace, shelter	24
pernocto, pernoctāre, pernoctavi, pernoctatum	to spend the night	39
persuadeo, persuadēre, persuasi, persuasum (+dat)	to succeed in urging, persuade, convince	35
philosophia, philosophiae (f)	philosophy	2
philosophus, philosophi (m)	philosopher	33
post (+acc)	after, behind	7
postea	afterwards	24
postremum	after all, finally; for the last time	40
prae (+abl)	in front of, before	26
praeter (+acc)	besides, except; beyond, past	40
primo	at first, at the beginning	30
pristinus, pristina, pristinum	ancient; former, previous	38
pro (+abl)	in front of, before, on behalf of, for the sake of, in return for, instead of, for, as	12
probitas, probitatis (f)	uprightness, honesty	18
pronuntio, pronuntiāre, pronuntiavi, pronuntiatum	to proclaim, announce, declaim; pronounce	20
propter (+accusative)	on account of, because of	5
protinus	immediately	22
pudicus, pudica, pudicum	modest, chaste	26
quam	how	16
quam	than	26
quando	when	5
quare	because of which thing, therefore, wherefore, why	6
quasi	as if, as it were	39
que	and (suffix added to the end a word, joining it to the previous)	6
qui? quae? quod?	(interrogative adj)	19
quid	what	1
quidem	indeed, certainly, at least, even	29
quin	indeed, in fact	40
quis? quid?	(interrogative pronoun) who? whose? whom? what? which?	19
quod	because	11
quondam	formerly, once	22
quoniam	since, inasmuch as	10
quoque	also, too	17
quot	how many, as many as	27
recito, recitāre, recitavi, recitatum	to read aloud, recite	17
recreo, recreāre, recreavi, recreatum	to restore, revive; refresh, cheer	36
recuso, recusāre, recusavi, recusatum	to refuse	33
regina, reginae (f)	queen	7
remaneo, remanēre, remansi, remansum (or maneo)	to remain, stay; stay behind, abide, continue	5
remedium, remedii (n)	cure, remedy	4
remissio, remissionis (f)	letting go, release; relaxation	34
repente	suddenly	30
requiesco, requiescere, requievi, requietum	to rest	37
requiro, requirere, requisivi, requisitum	to seek, ask for; miss, need, require	36
res publica, rei publicae (f) state, commonwealth, republic		22
ridiculus, ridicula, ridiculum	laughable, ridiculous	30
Roma, Romae (f)	Rome	14
Romanus, Romana, Romanum	Roman	3
rosa, rosae (f)	rose	2
rumor, rumoris (m)	rumor, gossip	31
rusticor, rusticāri, rusticatus sum	to live in the country	34
saepe	often	1
sal, salis (m)	salt; wit	33
salveo, salvēre	to be well, be in good health	1
salvus, salva, salvum	safe, sound	6
sapio, sapere, sapivi	to have good taste; have good sense, be wise	35
satio, satiāre, satiavi, satiatum	to satisfy, sate	3
satis	enough, sufficient	5
sator, satoris (m)	sower, planter; begetter, father; founder	38
satura, saturae (f)	satire	16
sauvis, suave	sweet	33
scriptor, scriptoris (m)	writer, author	8
sed	but	2
semel	a single time, once, once and for all, simultaneously	31
semper	always	3
senectus, senectutis (f)	old age	10
sereno, serenāre, serenavi, serenatum	to make clear, brighten; cheer up, soothe	36
servitus, servitutis (f)	slavery, servitude	20
si	if	1
sic	so thus	29
sine (+ablative)	without	2
sinister, sinistra, sinistrum	left, left	20
solacium, solacii (n)	comfort, relief	24
speculum, speculi (n)	mirror	33
stultus, stulta, stultum	foolish	4
subito	suddenly	33
sublimis, sublime	elevated, lofty; heroic, noble	38
subrideo, subridēre, subrisi, subrisum	to smile (down) upon	35
sui	(reflexive pronoun) him/her/itself, themselves	13
Syracusae, Syracusarum (f)	Syracuse	37
tam	so, to such a degree (tam . . quam	29
tamen	nevertheless, still	8
tantum	only	26
te	you (accusative)	5
tolero, tolerāre, toleravi, toleratum	to bear, endure	6
tot	so many	40
trans (+acc)	across	14
transitus, transitus (m)	passing over, transit; transition	39
Troia, Troiae (f)	Troy	21
tum	then, at that time; thereupon, in the next place	5
tyrannus, tyranni (m)	absolute ruler, tyrant	6
ubi	where, when	6
ultra (+acc)	beyond, on the other side of	22
umquam	ever, at any time	23
unde	whence, from what/which place, from which, from whom	30
urbanus, urbana, urbanum	of the city, urban; urbane, elegant	26
usque	all the way up (to), even (to), continuously, always	31
ut	(+indic) as, just as, when	24
ut	(+indic) as, when; (+subjunct) in order that, so that, that, in order to, so as to, to	28
uter, utra, utrum	either, which (of two)	9
utrum . . . an	whether . . . or	30
vae (often +dat)	alas, woe to	34
veritas, veritatis (f)	truth	10
vero	in truth, indeed, to be sure, however	29
versus, versus (m)	line of verse, verse	20
vesper, vesperis/vesperi (m)	evening; evening star	28
videor, vidēri, visus sum	to be seen; seem, appear	18
vivus, viva, vivum	living, alive	30

Photo by Artturi Jalli on Unsplash

Updating Composer

2021-06-25T00:00:00Z

I decided to upgrade my Composer because I was tired of seeing the following notice every time I used it:

Warning from https://repo.packagist.org: Support for Composer 1 is deprecated and some packages will not be available. You should upgrade to Composer 2. See https://blog.packagist.com/deprecating-composer-1-support/

Since I was upgrading Composer for use with a Drupal site, I used the directions at https://www.drupal.org/docs/develop/using-composer/preparing-your-site-for-composer-2 to guide me along the way. Here is what I encountered.

The instructions warned me that I would receive errors if my current composer version was too old. However, the suggestions there did not resolve this error:

[Composer\Downloader\FilesystemException] Filesystem exception: Composer update failed: "/usr/local/bin/composer" could not be written. rename(/home/sjhuskey/.cache/composer/composer-temp.phar,/usr/local/bin/composer): Permission denied

I remembered encountering this before, however. Following the suggestion of Boss COTIGA resolved the issue. Here's what I did:

sudo rm /usr/local/bin/composer
cd ~/.cache/composer
chmod 755 composer-temp.phar
sudo mv composer-temp.phar /usr/local/bin/composer

I also ran into this error:

[UnexpectedValueException] Your github oauth token for github.com contains invalid characters:

I've seen that before, too. My github oauth token is fine, but Composer has a bug that makes it think otherwise. Fortunately, rafaelbitten has a solution. His first step, however, is a doozy: "Find the composer/auth.json file." For me, that's in ~/.config/composer, not in ~/.composer, as it might be for some. After I found my auth.json file, I copied the oauth part (actually, it was the only thing in the file), pasted it somewhere for the moment, and replaced it with {} so that Composer wouldn't throw another error: Expected one of: 'STRING', 'NUMBER', 'NULL', 'TRUE', 'FALSE', '{', '['. Of course, after I did that, I ran into the Filesystem exception error from above when I did composer selfupdate, so I repeated the Boss COTIGA's process.

After that, composer selfupdate showed that I was using the most current stable version.

Photo by Marius Masalar on Unsplash

Verify a Downloaded File

2021-06-22T00:00:00Z

Sometimes it's necessary to download a file to install, update, or upgrade something on your computer. Whenever you download anything from the internet, you should take steps to verify that it is what you expected—and nothing more.

Many software providers give you a way to verify that the file you're downloading has not been altered. They do this by "signing" the file with a unique code. If the file has been altered in some way (e.g., with the addition of a virus or other malware), then its signature will change.

You can verify the signature by comparing it to the signature posted by the provider. Some will include a separate file to download that contains the verification code. Others will simply post the code on the same page as the file you're downloading.

But those signatures are really long, so comparing the file's signature to the one you copied from the site is an error-prone, time-consuming task. It's a perfect opportunity for automation!

There are many ways to do this, but the easiest (for me, anyway) is to use the shasum tool that is typically bundled with Linux distributions.

Let's say that you want to download Solr. You'll find there something like this:

solr-8.11.1.tgz [PGP] [SHA512]

That is, a link to the archive of the latest distribution of Solr and some links to the PHP and SHA512 hashes.

If you download the archive and the SHA512 file (which you might have to right click to get) to the same directory, you can then do the following:

shasum -c solr-8.11.1.tgz.sha512

Sometimes you can't download the SHA file because the vendor just gives you the hash in an html file. In that case, you can copy the hash and paste it into echo, then pipe the input to shasum:

echo "file_hash_here  file_name" | shashum --check

It's important to insert TWO spaces between the hash and the file name; otherwise, it won't work.

You might have to wait a second or two, but then, if everything is as it should be, you'll get the message:

solr-8.11.1.tgz: OK

If you don't get that message, don't open the archive file. Something is wrong.

Photo by Paul Carroll on Unsplash. Penguins, get it?

The settings.php file for Drupal 9

2021-06-08T00:00:00Z

Here are some few useful tidbits I've learned about the settings.php file in my adventures with Drupal 8 and 9. All of this assumes that you are working on the command line and that your user is in the sudoers group.

First Steps

It's best to do the following things first:

Set up the files directory and give it the correct permissions: cd SITE/web/sites/default && sudo mkdir files && sudo chown USERNAME:apache files && sudo chmod a+w files Note: Change SITE and USERNAME to your site's name and your system username, respectively.
Create the settings.php file: cp default.settings.php settings.php && sudo chown USERNAME:USERNAME settings.php && sudo chmod ug=rwx,o=rw settings.php
Run install by going to the site at http://142.93.182.93/SITE/web/core/install.php.
Secure the permissions on settings.php: sudo chmod u=rw,go=r settings.php && sudo chmod a=rwx files
Make a private files directory: cd to the root of the installation and do sudo mkdir private && sudo chown USERNAME:USERNAME private && sudo chmod a+w private
Move the config directory out of web/sites/default/files and into the root of the site: cd web/sites/default/files and copy the name of the configuration file. Save that name because you'll need it a couple more times. sudo cp -r config_HASH ../../../../config_HASH (where HASH is the string appended to the config directory's name). After verifying that the config directory has been moved to the root of the site, do sudo rm -rf config_HASH inside of web/sites/default/files.

The settings.php file

Change to the web/sites/default directory and open settings.php using your favorite text editor. I use Nano even though I know it some purists will insist that Vim is the only way to go. To them I say, "Whatever."

Edit the "trusted_host_patterns"

Edit the trusted_host_patterns to include the root or host of your site. Using the find feature of your text editor, search for 'trusted_host', then enter the following in the space after the end of the commented portion:

$settings['trusted_host_patterns'] = [
    '^YOUR_HOST_PATTERN_HERE$',
];

Observe that the value is a Regular Expression, so "^" and "$" are important for marking the beginning and ending point. You will also have to escape some characters. For example, ^myniftysite\.org$.

Tell Drupal where to find the private files directory

Search for "file_private_path" and add this after the end of the commented portion:

$settings['file_private_path'] = $app_root . '/../private';

That will tell Drupal to look outside of the web root for the private files directory.

Tell Drupal where to find the config directory.

Search for "config_sync_directory" and add this after the end of the commented portion:

$settings['config_sync_directory'] = $app_root . '/../config_HASH/sync';

Note that you must replace "HASH" here with the actual hash that is appended after "config_". Don't for get to add "/sync", either!

Generate a .htaccess file for the private files directory

Navigate in the browser to admin/config/media/file-system and click 'Save configuation' to generate the .htaccess file.

If you are going to do a migration:

If you are going to do a migration, add the following at the end of your settings.php file to connect to the migration database. NOTE: It's important to name the key 'migrate'.

$databases['migrate']['default'] = array (
  'database' => 'DBNAME',
  'username' => 'DBUSER',
  'password' => 'DBPASSWORD',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);

Of course, DBNAME, DBUSER, AND DBPASSWORD have to be replaced with real values.

Photo by Rubaitul Azad on Unsplash