--------------------------------
Scalar Installation Instructions
--------------------------------

Scalar is a PHP and MySQL application built with CodeIgniter.
 
*** 
An important note on .htaccess:
For Scalar to work properly, it is essential that mod_rewrite -- .htaccess -- be enabled in your Apache config.
If .htaccess is not enabled, Scalar's URL rewriting will not operate; you'll know this is the case because clicking
on links such as 'sign in' or 'register' will not take you to those pages (rather, the home page will reload).
In addition, some FTP clients will interpret .htaccess as a hidden file and not copy them to the server by default.  
There are a few .htaccess files included in the Scalar build, therefore please make sure that these files are copied.
***

***
If PHP's short_open_tag (<? vs <?php) is turned off, CodeIgniter is supposed to make them operational, but this feature doesn't
seem to be working properly. So, make sure short_open_tag is turned on in PHP :)
***

***
The Scalar webroot needs to be writable by the web server in order to create Books. 

    chmod 0775 ./(scalar root folder)
    
When Scalar creates the book folders it should chmod the newly created folders to 0775 (or whatever is set in system/application/config/local_settings.php
***

***
Go ahead and download the most recent Release at: https://github.com/anvc/scalar/releases. Releases have been tested by the Scalar team on development and live environments (e.g., scalar.usc.edu).  To update an existing Scalar install, see UPDATE.txt.
***

***
Scalar supports servers running SSL (https) out of the box.  If needed we have a template in the root folder's .htaccess file to force 
all requests through https. Be aware, though, running Scalar under https might cause conflicts with plugins or media players that are 
running under http, meaning, websites running https generally can't embed content running under http.
***

1)

Create a new MySQL database (e.g., "scalar_store"), and a user that has permission to create tables and create temporary tables. 
Set the collation of the new database to "utf8_general_ci" unless you would like to support additional 4-byte UTF-8 characters (such 
as emojis) in which case select "utf8mb4_general_ci".

Import this SQL file into the new database:

system/application/config/scalar_store.sql (standard MySQL 3-byte UTF-8)
OR
system/application/config/scalar_store_utf8mb4.sql (extended 4-byte UTF-8 support)

Update database fields (hostname, database, username and password) at:

system/application/config/database.php OR you can set the following environment variables:

    SCALAR_DB_HOSTNAME
    SCALAR_DB_USERNAME
    SCALAR_DB_PASSWORD
    SCALAR_DB_DATABASE

If using the extended 4-byte UTF-8 character set, in the same database.php file update these two fiels to:

$db['default']['char_set'] = 'utf8mb4';
$db['default']['dbcollat'] = 'utf8mb4_general_ci';

2)

Add a new SALT string, reCAPTCHA key (for your domain, http://www.google.com/recaptcha/whyrecaptcha), 
registration key, SoundCloud key, and a few other keys:

system/application/config/local_settings.php OR you can set the following environment variables:

    SCALAR_SHASALT
    SCALAR_RECAPTCHA_PUBLIC_KEY
    SCALAR_RECAPTCHA_PRIVATE_KEY
    SCALAR_SOUNDCLOUD_ID
    SCALAR_DPLA_KEY
    SCALAR_FLOWPLAYER_KEY
    SCALAR_GOOGLE_MAPS_KEY
    SCALAR_EMAIL_REPLYTO_ADDRESS
    SCALAR_EMAIL_REPLYTO_NAME
    SCALAR_SMTP_HOST
    SCALAR_SMTP_USERNAME
    SCALAR_SMTP_PASSWORD

Add session encryption key ($config['encryption_key']) and cookie/session variable ($config['cookie_prefix']) at:

system/application/config/config.php OR you can set the following environment variables:

    SCALAR_ENCRYPTION_KEY
    SCALAR_COOKIE_PREFIX
    SCALAR_COOKIE_DOMAIN

3) 

By default, the home page (book index) will display "Scalar" as the page title; this can be updated at:

system/application/language/en/content_lang.php OR you can set the following environment variables:

    SCALAR_INSTALL_NAME

4) 

All should be set to visit your site at its URL and see a basic home page with the Scalar title at left and login at right.

If you experience MySQL connection problems (say, there was a typo in the the connection parameters), correct, then refresh your page,
you might notice an error from Session.php involving num_rows().  In this case, clear your browser cache & cookies and refresh.

5) 

You can register your new account using the 'register' link.

To make your user (after it is registered) a "super admin" requires direct access to MySQL (e.g., phpMyAdmin).  
In the database table "scalar_db_users" edit your user row then set the "is_super" bit to 1. After refreshing  
Scalar, you will have access to all Scalar books and additional admin tabs in the "Dashboard" area. Note that  
even super admins can't save changes to others' books unless they are explicitly provided "author" privilege  
in the "Users" tab of the book's "Dashboard" area.  

Make sure to read through the Scalar 2 Guide, particularly the Advanced Topics section, for useful information
including how to keep unwanted users from registering on your Scalar install: http://scalar.usc.edu/works/guide2/advanced-topics

In the event your users wish to transfer Scalar books from other installs into your Scalar install, we have a  
Scalar Transfer Tool available in a different repository: https://github.com/Michael628/scalar-book-transfer-tool   
Simply download the package then place the ZIP's contents into the system/application/plugins/transfer folder.   
It will then be available to users at Dashboard > Import/Export.  

Enjoy!

-------------------------------------
Setting up a local development server
-------------------------------------

DDEV is a helpful resource for setting up and managing a local development environment with Docker containers.

Prerequisites:
- Docker(https://docs.docker.com/get-docker/)
- Git(https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- DDEV(https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/)

From your terminal, clone the Scalar codebase and enter the directory

    git clone https://github.com/anvc/scalar
    cd scalar

Configure your local development for Scalar

    ddev config --project-type php --php-version 7.4 --webserver-type apache-fpm 
        --database mysql:5.7 --web-environment="SCALAR_ENCRYPTION_KEY=scalar,
        SCALAR_DB_HOSTNAME=db,SCALAR_DB_USERNAME=db,SCALAR_DB_PASSWORD=db,
        SCALAR_DB_DATABASE=db"

DDEV will create a new folder titled `.ddev`, where additional configurations can be made. Update PHP's configuration to enable open short tags.

    mkdir .ddev/php && echo 'short_open_tag = ON;' > .ddev/php/my-php.ini

Start the DDEV containers

    ddev start

Import the Scalar SQL database

    ddev import-db --src=system/application/config/scalar_store.sql

Create an admin user

    echo 'INSERT INTO db.scalar_db_users (email, fullname, password, is_super) VALUES
        ("admin@scalar.dev", "admin", SHA2("password", 512), 1)' | ddev mysql

Launch your browser to access the development server

    ddev launch

-------------------------------------------------------------------------------------------
Updates we've made to incorporated libraries, kept here for reference if they need updating
-------------------------------------------------------------------------------------------

CodeIgniter:
1) In system/core/Input.php->_clean_input_keys(), change regex "/^[a-z0-9:_\/-]+$/i" to "/^[a-z0-9:_\/\-~@]+$/i"

ARC2 (updated 2021-01-27 from https://github.com/semsol/arc2):
1) ARC2_Resource.php->getProps(): comment out "if (!isset($this->index[$s])) $this->fetchData($s);"
2) ARC2_Store.php->hasHashColumn(): look for 'false' rather than 'null' from fetchRow() to keep the id2val table in check
3) ARC2_StoreLoadQueryHandler.php->getStoredTermID(): replace "if (false !== empty($binaryValue))" with "if (1)" to keep the id2val table in check

Template (libraries/Template.php):
1) Added add_meta() and supporting updates to regions arrays

rdfQuery (views/arbors/HTML5_RDFa/js/jquery.rdfquery.rules-1.0.js):
1) Replaced "elem.contents().each(function () {" with "elem.contents(':not(iframe)').each(function () {"

CKEditor (views/widgets/ckeditor/.../):
A few updates to core/htmlparser files, found by searching for 'Updated by Craig Dietrich'

Annotorious:
1) Replaced "Add a Comment..." with "Enter annotation title..." (views/widgets/mediaelement/annotorious.debug.js)
2) Replaced the "canvas" selector with "canvas.annotorious-item" and the "canvas.hidden" selector with "canvas.annotorious-item.hidden" (views/widgets/mediaelement/css/annotorious.css)
3) Updated a line in annotorious.debug.js that seems to resolve a touch event problem on Win10 without disrupting touch events on iOS