TextCritical.net

h1. Design Notes

h2. AJAX content loading caching system

The content for the reading pages is cached in order to reduce the loading time of the chapters. This is necessary because rendering is expensive. This works by:

# Caching the current page on the server

# Pre-loading the next page so that it is pre-cached

The way that this works is that the template for the page will only return the non-content part of the page if the request is not an AJAX request. This will _not_ be cached.

On the other hand. if the request is for an AJAX request, then only the content part of the page will be returned. This _will_ be cached.

h2. ajaxify: what does it do?

The ajaxify decorator changes the page that will be returned such that it is a shell that will request the actual page. This is useful in order to show content to a user quickly with a progress-bar instead of showing a white screen while the content is prepared.

h2. How the type-ahead system in the search works

# The search-query uses the Bootstrap type-ahead component to invoke a call to get_works_search_typeahead_hints()

# get_works_search_typeahead_hints() obtains the type-ahead hints for Bootstrap

# On submitting the search query, jump_to_searched_text() will be used to jump directly to the matching work

h2. How are related works identified in the importer?

The RelatedWork model function autodiscover() attempts to find related works and link them. It considers them comparable when:

#  The number of authors are the same and the authors names are the same and in the same order

#  The number of editors are the same and the editors names are the same and in the same order

# The divisions are the same (same number of them and the descriptors are the same and in the same order)

h2. How search indexes get re-populated

There is a built-in command to re-index works. For example:

<pre>

python manage.py make_search_indexes -w lxx

</pre>

If you want to clear the existing index for a work before indexing it, then include the -f option:

<pre>

python manage.py make_search_indexes -f -w lxx

</pre>

You can clear the index entirely with:

<pre>

python manage.py make_search_indexes -c

</pre>

You can re-create the index entirely with:

<pre>

python manage.py make_search_indexes

</pre>

h2. How to populate related works

The following will be compared to see if two works are equivalent:

# TItles

# Count of authors

# Author names

# Count of editors (optionally)

# Editor names (optionally)

# Divisions (optionally)

This can be done in code with the following:

<pre>

from reader.models import RelatedWork

RelatedWork.autodiscover()

</pre>

You can also use the autodiscover_related_works command to link related works. Generally, I suggest starting with the test parameter to see what would be linked:

<pre>

python manage.py autodiscover_related_works -w the-histories-greek --test

</pre>

If you want the linkage to be created, then run the command without the test parameter:

<pre>

python manage.py autodiscover_related_works -w the-histories-greek

</pre>

h2. How can I import Perseus works?

You can batch import Perseus works by running the batch_import_perseus command against a directory of Perseus works:

<pre>

python manage.py batch_import_perseus -d var/import_queue/

</pre>

The command above will import the work according to the import policy (thus using the recommended settings).

h2. What is the purpose of the Perseus import policy?

The import policy indicates if a work will be imported and what settings will be used. Here is how the importer uses the policy:

# Gets import policy. Stop is there is no matching import policy.

# The PerseusTextImporter is called with the import policy

# The is imported unless the file doesn't already exist or is directed to force update

Similar works are linked using the autodiscover() function in the RelatedWork class. This needs to be called manually since the import process doesn't do this automatically.

h2. How does the AJAH system work?

The intention of this system is to quickly load a loading page and then get the main content a bit later.

* *ajaxify*: renders a page which in turns will get the content asynchronously

* *ajah_redirect.html*: a template that loads the HTML holder page and calls TextCritical.load_ajah() to get the main content.

* "TextCritical.load_ajah()": The main content will be retrieved with the argument necessary to only get the main content, not the surrounding page.