Feature/installation updates and help

.github/workflows/main.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, develop ]
   pull_request:
     branches: [ master ]
 
@@ -12,4 +12,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - uses: rojopolis/spellcheck-github-actions@0.22.1
+    - uses: rojopolis/spellcheck-github-actions@v0

.spellcheck.yml

@@ -9,10 +9,10 @@ matrix:
   pipeline:
   - pyspelling.filters.markdown:
   - pyspelling.filters.html:
-    comments: false
-    ignores:
-    - code
-    - pre
+      comments: false
+      ignores:
+      - code
+      - pre
   sources:
   - '**/*.md|!assets/**'
   default_encoding: utf-8

.wordlist.txt

@@ -238,4 +238,19 @@ polyfill
 skel
 unsplash
 TODO
-th
+th
+WSL
+GitLens
+CMFive
+ExampleInsight
+pdf
+CSV
+InsightReportInterface
+convertedData
+getExamples
+getFilters
+AuditInsight
+WSL
+webserver
+theModelsFolder
+DBObject

_data/doc_menu.yml

@@ -36,6 +36,8 @@
       link:
     - name: Inbox
       link:
+    - name: Insight
+      link: "/documentation/core-modules/insight/insight"
     - name: Install
       link:
     - name: Main

_data/tute_menu.yml

@@ -8,6 +8,8 @@
       link: "/tutorials/installation/installation"
 - name: "Help"
   children:
+    - name: "Creating MySQL Users"
+      link: "/tutorials/help_module/mysql-users"
     - name: "Set Up cmfive-core"
       link: "/tutorials/help_module/cmfive-core-setup"
     - name: "Set Up Debug"
@@ -20,10 +22,10 @@
       link: "/tutorials/module-anatomy/introduction"
     - name: "Creating A Config"
       link: "/tutorials/module-anatomy/creating-a-config"
-    - name: "Install And Migrations"
-      link: "/tutorials/module-anatomy/install-and-migrations"
     - name: "The Models Folder"
       link: "/tutorials/module-anatomy/theModelsFolder"
+    - name: "Install And Migrations"
+      link: "/tutorials/module-anatomy/install-and-migrations"
     - name: "Creating Index Action"
       link: "/tutorials/module-anatomy/creating-index-action"
     - name: "Creating Index Template"

_documentation/core-modules/insight/insight.md

@@ -0,0 +1,109 @@
+---
+title: Writing Insights
+layout: page
+type: doc
+---
+
+## Writing Insight Classes
+
+The insight module allows users to write insights that can be saved, exported, and run when needed.<br>
+This page will go over the primary pieces of code that each insight needs to work correctly in all the above ways.
+
+The insight's class will be the sort of insight it is, followed by Insight (e.g. the audit insight is AuditInsight). All insights must extend Insight Base Class.
+
+```php
+class ExampleInsight extends InsightBaseClass
+```
+
+Below this, give the variables for the insight's name and description. These will appear in the insight list, the first page seen in CMFive when you click on the insight module.
+
+```php
+public $name = "Example Insight";
+public $description = "This insight is being used to show correct insight syntax in the docs";
+```
+These variables will indicate to users which insight is which.
+
+All insights will contain a getFilters function and a run function. The getFilters function will be called when a user clicks on the View button next to the insight. The run function is called when the user clicks Run from the view screen.
+
+getFilters will be an array, which sets up the parameters the user can choose. Before running an insight, the user may specify it to only show information from specific dates, for certain users, etc.<br>
+Add the below code underneath your name and description variables.
+
+```php
+public function getFilters(Web $w, $parameters = []): array
+{
+```
+
+The filters you choose for the user to select from will depend on the insight you are creating.<br>
+The below code shows the code that goes in your getFilters function. This example has filters for choosing the date to and from that the insight shows.
+
+```php
+    return [
+                "Options" => [
+                    [
+                        [
+                            "Date From", "date", "dt_from", array_key_exists('dt_from', $parameters) ? $parameters['dt_from'] : null
+                        ],
+                        [
+                            "Date To", "date", "dt_to", array_key_exists('dt_to', $parameters) ? $parameters['dt_to'] : null
+                        ],
+                    ]
+                ]
+            ];
+}
+```
+
+You will notice that both filters contain an array_key_exists function. This is required on all filters in your insight. When you click the Change Insight Parameters button, the options you chose that session previously will be pre-filled for you.
+
+The run function will also be an array. It will find data based on the selected filters and then organise it into the appropriate columns for each table in the insight.<br>
+Place the below code under your getFilters function.
+
+```php
+public function run(Web $w, $parameters = []): array
+{
+```
+First, the insight finds the correct data based on the filters you have chosen. The data variable for our Example Insight will look like the code below.
+
+```php
+$data = ExampleService::getInstance($w)->getExamples(($parameters['dt_from']), ($parameters['dt_to']));
+```
+
+The getExamples function refers to a where array. In most cases you will not have to build one. Variables for all your data required for your insights tables can usually be created using existing service functions.
+
+After retrieving the data based on the selected filters, your run function must build its table(s). It will look something like this.
+
+```php
+if (!$data) {
+             $results[] = new InsightReportInterface('Example Report', ['Results'], [['No data returned for selections']]);
+        } else {
+            // convert $data from list of objects to array of values
+            $convertedData = [];
+
+            foreach ($data as $datarow) {
+                $row = [];
+                $row['module'] = $datarow->module;
+                $row['url'] = $datarow->path;
+                $row['class'] = $datarow->db_class;
+                $row['action'] = $datarow->db_action;
+                $row['db_id'] = $datarow->db_id;
+                $convertedData[] = $row;
+            }
+             $results[] = new InsightReportInterface('Example Report', ['Module', 'URL', 'Class', 'Action', 'DB Id'], $convertedData);
+        }
+        return $results;
+    }
+}
+```
+
+The first few rows indicate what the insight will display if no data comes back.<br>
+The rows below use the Insight Report Interface to build a table. Each of the rows are built using the where array in the service class. The column names and insight title are given in the line before return.<br> 
+The above insight's table is titled Example Report. It contains the five columns: Module, URL, Class, Action, and DB Id.<br>
+The function then returns the data in the table(s) as results.
+
+## Notes on Export Requirements
+
+There are a few brief things that need to be checked for the two export types.
+
+For exporting to CSV, check that your first php tag in your insight is on line 1. Any empty space in your insight before it will create blank rows in exported CSV files.
+
+When Exporting to PDF, you will be asked to select a template from a drop-down list. Templates can be created for your insights in the Admin module of CMFive.<br>
+You will notice that only specific templates appear in the drop-down list. Your template's category must be the insight class, followed by _pdf, to make sure your template appears (This is the insight class readable by a computer, not the human-readable name.) Your templates category will be something like 'ExampleInsight_pdf'. This ensures that only templates created for PDF exports for the insight you are currently viewing are shown in the drop-down list.

_documentation/core_modules/report/report.md

@@ -0,0 +1,28 @@
+---
+title: Report
+layout: page
+type: doc
+---
+
+## Introduction
+
+The report module allows users to write custom MYSQL reports that can be saved and run when needed.
+
+## Setup
+
+1. Before you learn how to use reports you'll need to make sure your config is setup correctly. Add the following entries into the <b>config.php</b> file in the root directory of your Cmfive project.
+```php
+Config::set("report.database", [
+    "hostname"  => "DB_HOSTNAME",
+    "username"  => "DB_USERNAME",
+    "password"  => "DB_PASSWORD",
+    "database"  => "DB_NAME",
+    "driver"    => "mysql"
+]);
+```
+2. Replace <b>DB_HOSTNAME</b>, <b>DB_USERNAME</b>, <b>DB_PASSWORD</b> and <b>DB_NAME</b> with their respective values.
+3. To clear your config cache to apply your changes.
+
+## Writing Reports
+
+## Running Reports

_tutorials/help_module/cmfive-core-setup.md

@@ -10,7 +10,7 @@ To start you will need to clone the cmfive-boilerplate. Go to the 2pi Software a
 
 Now open your Git application, and choose to clone a repository from GitHub. Make sure it will save on your device in the folder that your web server points to. Use the copied URL in the relevant box and hit clone.
 
-When you clone the boilerplate, cmfive-core can be installed by following the instructions under [Installation](/tutorials/installation). The next step is to set this up separately in your Git application.
+When you clone the boilerplate, cmfive-core can be installed by following the instructions under [Installation](/tutorials/installation/installation). The next step is to set this up separately in your Git application.
 
 Open your Git application choose to open a repository. Find where you cloned the boilerplate to. Go to the following path **composer/vendor/2pisoftware/cmfive-core** composer folder in boilerplate.
 
@@ -33,6 +33,7 @@ eg:
 /etc/apache2/sites-available/000-default.conf:  SSLEngine on
 
 Add these entries to the files:
+
 ```php
 SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
 SSLHonorCipherOrder on

_tutorials/help_module/logs.md

@@ -8,7 +8,7 @@ type: tute
 
 If you get an error message at any point when you display your code in localhost, Cmfive will diagnose it for you using the logs.
 
-Finding the logs is simple. First, open the boilerplate. Go to the .build folder, the storage folder, and the logs folder. The files here store information about every time the Cmfive database has been accessed.
+Finding the logs is simple. First, open the boilerplate. Go to the storage folder, and then the logs folder. The files here store information about every time the Cmfive database has been accessed.
 
 Note that each of the log names have cmfive, followed by a date, and are appended by '.log'. To find the log for your error, select the log that has today's date in the name (this should be at the bottom of the list). All entries in the log files start with a date and time stamp in square brackets. Scroll down to the last entry of your file.
 

_tutorials/help_module/mysql-users.md

@@ -0,0 +1,43 @@
+---
+title: MySQL User Creation and Checking
+layout: page
+type: tute
+---
+
+## Using The Terminal To Create a MySQL User
+
+<!--Creating MySQL user-->
+<!-- Use config_hostname photo-->
+Connect a shell to the mysql container (labelled mysql:5.7.21 or similar) by right clicking and choosing ```Attach Shell```.
+
+Type the following command into the terminal:
+```sh
+mysql -u root -p
+```
+
+It will ask you for a password. This is just 'root'.
+
+You are now logged in as the root user who has full access to all the databases. This is the user used for your cmfive set up. However, we never do our coding using the root MySQL user as it is insecure. It is unlikely, but even if you want full access to all of the databases, it is best practice to create another user who also has these permissions. 
+
+Type the following in to the terminal to create your new user.
+
+```bash
+CREATE USER 'cmfive'@'mysql-5.7' IDENTIFIED BY 'cmfive';
+```
+
+The first part in inverted commas ('') is the name of our user. The second part is the hostname. mysql-5.7 is the host we set for the cmfive database under the [installation instructions](/tutorials/installation/installation). The last word in inverted commas is the password for our new user.<br>
+Our new user, cmfive, will need access to the cmfive database. Type the below command into the terminal to grant this.
+
+```bash
+GRANT ALL PRIVILEGES ON cmfive . * TO 'cmfive'@'mysql-5.7';
+```
+
+The first cmfive in the above command refers to the cmfive database. The '*" is in the table position of the command. '*' means all in the terminal, so the above command is granting the user access and all privileges on all the tables in the cmfive database.
+
+Whenever you make changes to the database permissions you need to flush privileges
+
+```bash
+FLUSH PRIVILEGES;
+```
+
+Your changes will now be in effect.

_tutorials/help_module/permissions.md

@@ -0,0 +1,33 @@
+---
+title: Permissions Error
+layout: page
+type: tute
+---
+
+## Permissions Error - I Can't Log In
+
+<!--check logs-->
+In the files tab go to /system/log. The log files record any errors that users encounter and can help us to see when they are cropping up. How to read the entries in the log files is explained in the the [logs help page](logs).<br>
+The last file in the logs folder will have today's date. This is the one you want to check for the errors you just encountered. The most recent activity will be at the bottom of this file.
+<!--system/modules/auth/actions/login.php ha important info on logging in-->
+
+<!--Using inspect in Firefox. Look up for Windows and Linux as well as Mac-->
+Now we need to inspect the element.<br>
+Firefox users right click and choose Inspect at the bottom of the pop-up.<br>
+Safari users right click and choose Inspect Element at the bottom of the pop-up.
+
+<!--delete config cache after changing config-->
+You will need to purge the config cache after making changes to the configuration file. you can see how to do this on the Creating a Config page under the Learning Cmfive menu.
+
+<!--attach shell to boilerplate-->
+Click on this tab on the left hand side of VSCode.<br>
+![Docker tab](/assets/images/docker.png)<br>
+Right click on the container called cmfive-boilerplate and select attach a shell. The VSCode terminal at the bottom of the screen is now a cmfive-boilerplate bash shell.
+<!--Get mkcert
+https://kifarunix.com/how-to-create-self-signed-ssl-certificate-with-mkcert-on-ubuntu-18-04/
+Config changes
+
+
+This goes in installation
+Config::set('system.environment', 'development');
+-->

_tutorials/installation/installation.md

@@ -27,6 +27,7 @@ Right-click on the ```docker-compose.yml``` file and select ```Compose Up``` (Th
 
 #### Step 4 - Verify
 When docker compose has finished, check that you have 3 containers ready by clicking on the Docker tab on the left
+![Docker Tab](/assets/images/docker.png)
 
 #### Step 5 - Connect to database container
 Right click on the MySQL container and click ```Attach Shell```. Connect to MySQL in the container by running ```mysql -u root -p``` with password ```root```
@@ -50,6 +51,11 @@ Config::set('system.encryption', [
     'iv'  => ''
 ]);
 ```
+The system environment section of this file should be set to development.
+
+```php
+Config::set('system.environment', 'development');
+```
 
 #### Step 8 - Connect to PHP container
 Right click on the ```nginx-php``` container and click ```Attach Shell```.
@@ -141,3 +147,36 @@ Config::set('system.environment', 'development');
 ```
 
 You should now be able to log in
+
+## Trouble Shooting 
+
+If you still have trouble logging in, check some of the commands under MySQL Users in the Database below to make sure the correct user is set, and has all their permissions.
+
+Please check out the Help pages for further support. Some operating systems may run into further issues and we can't always offer support.
+
+## MySQL Users in the Database
+
+The following command will show you the change owner options.
+```bash
+chown --help
+```
+
+To change the owner and group for all of the files:
+```bash
+chown -R www-data:www-data storage/
+```
+
+Copy the following bash commands into your terminal one at a time and click enter.
+
+```bash
+use cmfive;
+```
+
+```bash
+MySQL> select * from user;
+```
+
+The ‘*’ means ‘all’, so you are asking to see all the information on the current user. 
+
+The output will give you a table of information about the user. 
+