The following steps can be followed to get things running for the first time:
1. Copy the `.env.example` file to `.env` and configure its values as required.
2. Create a new database named whatever you've set `DB_DATABASE` to in the `.env` file.
3. Run the `init.sh` script and wait for it to complete.
### Environment File
The `.env` file includes deployment-specific configuration options, and Laravel has documentation explaining it in further detail [HERE](https://laravel.com/docs/configuration).
The `APP_ENV` and `APP_DEBUG` variables should be configured in one of the following combinations depending on the scenario:
* Local development should be configured with `APP_ENV=local` and `APP_DEBUG=true`.
* A remote staging server should be configured with `APP_ENV=staging` and `APP_DEBUG=true`.
* A remote production server should be configured with `APP_ENV=production` and `APP_DEBUG=false`.
### Init Script
The `init.sh` script is located in the root of the project and is used to keep the database and compiled assets in sync with the codebase.
It's the recommended way to handle the initial project setup, and can also be run manually or by deployment scripts to keep things up to date after pulling in changes.
The following steps are performed in this order when run:
1. Checks the local system for dependencies required by the script and exits with an error if any are missing.
2. Checks to see if the `.env` file exists and exits with an error if it doesn't.
3. (artisan) Puts the website in maintenance mode.
4. Downloads and updates non-development composer dependencies.
5. Checks to see if the `APP_KEY` variable in the `.env` file is empty, and if it is, generates a value for it.
6. Clears the route and blade cache to ensure everything will be build fresh against the current codebase and dependencies.
In the root of the project is a file named `gulpfile.js` that can be used by `gulp` to copy fonts, compile javascript and sass, and watch files for changes during development.
Reading through its contents is encouraged for a complete understanding of what it does, but the following commands should handle most of what it's needed for out of the box:
*`gulp`: Update the compiled javascript and css in `public/js` and `public/css`, and copy fonts to `public/fonts`.
*`gulp --production`: Does the same as `gulp` except the compiled javascript and css is minified, and console logging is removed from the javascript (good for production deployments).
*`gulp default watch`: Does the same as `gulp` but continues running to watch for changes to files so it can recompile updated assets and reload them in the browser using BrowserSync (good for development environments).
**NOTE**: If `gulp` isn't installed globally or its version is less than `4`, you should use the version included in `node_modules` by running `"$(npm bin)/gulp"` in place of the `gulp` command.
BrowserSync is used to keep the browser in sync with your code when running the `watch` task with gulp.
For this to work on browsers that aren't on the computer running gulp, the `BS_HOST` variable in the `.env` file should be set to the IP address of that computer.
*`resources/components/sections`: Section components (single-use per page) that should be imported into mixins or page components
*`resources/components/partials`: Partial components (multi-use per page or section) that should be imported into mixins and/or page and section components
The language cookie can be updated a number of ways:
* Visiting a link to `/language/{lang}` will update the language to whatever `{lang}` is set to and then reload the current page.
* Running `Language::setSessionLanguage($lang)` in PHP will update the language to whatever `$lang` is.
* Running `this.$store.commit("setAppLang", lang);` in a Vue.js component will update the language to whatever `lang` is as well as update component text to the current language on-the-fly.
A multi-language text block can be included in a number of ways depending where it's being done:
*`$dashboard_sort_direction`: When `$dashboard_reorder` is false this determines the sort direction (this can be `desc` for descending or `asc` ascending)
*`$dashboard_id_link`: Add a dashboard button linking to another list filtered by the current item by populating an array containing the following items in this order:
* The title
* The URL to link to where the id will come after the rest
*`type-new`: This takes the same options as `type` and overrides it when creating new items (eg: to allow input on a field during creation but not after)
*`options` (required by `select`) Takes an array of options that are either strings or arrays containing the keys `title` (for what will display with the option) and `value` (for what will be recorded)
