Installation and use

EVT 3 can be used to prepare an edition right away, immediately after downloading the release package on your hard drive: see the ​Installation and management of the edition data section first, then Configuration​, to understand how EVT works and how you can use it to publish your editions.

If, on the other hand, you are interested in ​developing a specific functionality in EVT 3, or in modifying an existing one, we suggest that you clone the project as it is.​ The ​README.md explains how to install and configure the development environment needed for this purpose. This step is only needed if you want to start working with EVT source code, so it is in no way necessary for basic users. See Development section and subsections for further information on development guidelines.

Installation and management of the edition data

Installation is quite simple, in fact it is not an actual installation in the traditional sense: you just need to download the compressed archive from the release page (or the EVT home page), unzip it in a suitable location on your hard drive, and you are ready to use it with your edition files. Within the main folder there are only two folders which should be modified by the user:

• assets/config​: here you will find four different configuration files which can be used to properly configure EVT as needed (see the Configuration section for further details;
• assets/data​: here you will put all of your edition data, including the TEI-encoded documents, images, and other edition files.

Everything else should not be modified, unless you know what you are doing very well. It is in fact possible to modify the JavaScript parsers, but doing so directly in an EVT release is very difficult, because everything is minified and uglified for performance reasons, and also less efficient than doing it on the development version. Since EVT is an open source tool, you are welcome to fork it, change the existing parsers and/or add your own parsers and eventually open a Pull Request so that your changes will be integrated in the main version of EVT.

Before moving to the configuration, you should have the different edition components ready. As you will see during configuration, the paths to the resources are completely configurable, thus there is no strict obligation to follow the default structure to organize your files; however we would like to suggest and recommend the default structure to you as a specific way to organize your files, one which will allow you to keep the different contents well separated from each other.

In the assets/data folder you can create one folder for each type of data (images, text, etc.). For example:

• data/text => put your textual data here, possibly further organized in subfolders such as documents, schema, sources, witnesses, etc.
• data/images => put your images here, you will find some sub-folders (e.g. data/images/single​, ​data/images/hotspot etc.), create more if needed
• data/models => put your 3D models here, again you will find the ​multires and singleres​ subfolders.
• data/viscoll => put all VisColl-related files here.

To have your edition parsed and loaded in the browser by EVT you have to point to it explicitly modifying the file_config.json file in the ​config directory and specifying the name of the main file: "dataUrls": ["data/text/My_edition.xml"]. While this is the most important configuration option, since it tells EVT where to start with your edition, note that there are several other options available in that file, so that you can customize the layout and appearance of your edition (see the (Configuration)[https://github.com/evt-project/evt-viewer-angular/wiki/Configuration] section). Also note that some configuration options may be necessary to make desired features available, for instance to add a required edition level, so make sure you read the following section and check the default configuration file.

Open your edition

In order to locally access your edition (for test/study purposes, before publishing it on a web server) you need to enable local files access in your browser. In fact, browsers such as Chrome, Firefox (since v. 67), Safari, etc., have adopted a security-conscious policy that forbids loading local files (= documents available on the user’s computer drive) in the browser as a result of the execution of JavaScript programs. The goal is to improve global security when browsing the Web, but the unpleasant collateral effect is that of preventing the loading of digital editions based on EVT, or similar software, from local folders. Fortunately there are several workarounds that can be used to test EVT editions that are located on your hard drive:

• option no. 1: close every window of Chrome and launch it from the command line with the --allow-file-access-from-files parameter​; then open the ​index.html file;

  • Windows

  cd C:\Program Files (x86)\Google\Chrome\Application
  chrome.exe --allow-file-access-from-files
  

  • Linux

  google-chrome --allow-file-access-from-files
  

  • MacOSX

  open -a "Google Chrome" --args --allow-file-access-from-files
  

  NB: this option doesn't seem to work anymore with EVT 3.

• option no. 2: download and install Firefox ESR v. 60: this version predates the new security policy adopted in FF v. 67 and, furthermore, it can be installed in parallel with any other version of Firefox;

• option no. 3: install an extension providing a local web server on Firefox or Chrome, f.i. there is ​this one​ available for Chrome;

• option no. 4: use http-server, a simple, zero-configuration command-line static HTTP server that can be downloaded from npm and brew registry (see https://github.com/http-party/http-server and note that you need NodeJs or Brew to be installed first).

  NB: note that there may be problems with other web server stacks such as MAMP and XAMPP, again for loading of local EVT 3 instances. If that is the case, there is a simple fix: open index.html with an editor, at line 4 change from <base href="/"> to <base href="./">. The alternative being to put everything in the server root instead of the evt3_1.0.0-alpha directory, but that wouldn't be convenient.

Note again that this problem only affects local testing: after the edition has been uploaded on a server there are no problems in accessing it with any of the major browsers.