diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3b8a2f5..f5fd60c 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/.spellcheck.yml b/.spellcheck.yml index 70a306c..04821b0 100644 --- a/.spellcheck.yml +++ b/.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 \ No newline at end of file diff --git a/.wordlist.txt b/.wordlist.txt index 1aaedf8..9395b0a 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -238,4 +238,19 @@ polyfill skel unsplash TODO -th \ No newline at end of file +th +WSL +GitLens +CMFive +ExampleInsight +pdf +CSV +InsightReportInterface +convertedData +getExamples +getFilters +AuditInsight +WSL +webserver +theModelsFolder +DBObject \ No newline at end of file diff --git a/_data/doc_menu.yml b/_data/doc_menu.yml index a2325c8..fa23141 100644 --- a/_data/doc_menu.yml +++ b/_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 diff --git a/_data/tute_menu.yml b/_data/tute_menu.yml index a07de32..c8af9a4 100644 --- a/_data/tute_menu.yml +++ b/_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" diff --git a/_documentation/core-modules/insight/insight.md b/_documentation/core-modules/insight/insight.md new file mode 100644 index 0000000..1584fe1 --- /dev/null +++ b/_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.
+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.
+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.
+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.
+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.
+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.
+The above insight's table is titled Example Report. It contains the five columns: Module, URL, Class, Action, and DB Id.
+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.
+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. \ No newline at end of file diff --git a/_documentation/core_modules/report/report.md b/_documentation/core_modules/report/report.md new file mode 100644 index 0000000..84fd060 --- /dev/null +++ b/_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 config.php 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 DB_HOSTNAME, DB_USERNAME, DB_PASSWORD and DB_NAME with their respective values. +3. To clear your config cache to apply your changes. + +## Writing Reports + +## Running Reports \ No newline at end of file diff --git a/_tutorials/help_module/cmfive-core-setup.md b/_tutorials/help_module/cmfive-core-setup.md index f360c2d..791a6a0 100644 --- a/_tutorials/help_module/cmfive-core-setup.md +++ b/_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 diff --git a/_tutorials/help_module/logs.md b/_tutorials/help_module/logs.md index bd77f25..ac24593 100644 --- a/_tutorials/help_module/logs.md +++ b/_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. diff --git a/_tutorials/help_module/mysql-users.md b/_tutorials/help_module/mysql-users.md new file mode 100644 index 0000000..f49aa62 --- /dev/null +++ b/_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 + + + +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.
+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. \ No newline at end of file diff --git a/_tutorials/help_module/permissions.md b/_tutorials/help_module/permissions.md new file mode 100644 index 0000000..091e6e7 --- /dev/null +++ b/_tutorials/help_module/permissions.md @@ -0,0 +1,33 @@ +--- +title: Permissions Error +layout: page +type: tute +--- + +## Permissions Error - I Can't Log In + + +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).
+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. + + + +Now we need to inspect the element.
+Firefox users right click and choose Inspect at the bottom of the pop-up.
+Safari users right click and choose Inspect Element at the bottom of the pop-up. + + +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. + + +Click on this tab on the left hand side of VSCode.
+![Docker tab](/assets/images/docker.png)
+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. + \ No newline at end of file diff --git a/_tutorials/installation/installation.md b/_tutorials/installation/installation.md index 2092fde..793fa6e 100644 --- a/_tutorials/installation/installation.md +++ b/_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. + diff --git a/_tutorials/installation/requirements.md b/_tutorials/installation/requirements.md index bfc87f1..a7accd4 100644 --- a/_tutorials/installation/requirements.md +++ b/_tutorials/installation/requirements.md @@ -6,8 +6,8 @@ type: tute Cmfive v3 requires PHP7.2.x and MySQL 5.5+ -Cmfive works best with Linux and works out of the box with the Apache web server. Cmfive can also work with Windows and other web servers (like IIS and Nginx) but may require additional configuration. - +Cmfive works best with Linux and works out of the box with the Apache web server. Cmfive can also work with Windows and other web servers (like IIS and Nginx) but may require additional configuration. This may include setting up a virtual machine and installing your coding software on that. + Cmfive requires the following PHP extensions: - CLI - CURL @@ -17,4 +17,17 @@ Cmfive requires the following PHP extensions: - MySQL - Readline - XML -- ZIP \ No newline at end of file +- ZIP +- GIT +- Docker Desktop +- mkcert + +The version of Docker Desktop you want to install is the 64-bit PC desktop image. You can find this version of Docker Desktop [here](https://releases.ubuntu.com/18.04.5/?_ga=2.67351829.527945484.1625616788-786732526.1625616788). + +You will also need the following extensions in you coding software: +- Docker extension by Microsoft (extension ID: ```ms-azuretools.vscode-docker```) +- Docker Compose +- Git +- GitLens + +The deployment section has additional instructions to help you with installation of some of these requirements. \ No newline at end of file diff --git a/_tutorials/module-anatomy/creating-a-config.md b/_tutorials/module-anatomy/creating-a-config.md index 5cfb8c1..70f27c5 100644 --- a/_tutorials/module-anatomy/creating-a-config.md +++ b/_tutorials/module-anatomy/creating-a-config.md @@ -23,7 +23,7 @@ Cmfive caches config files to aid with page loading times. Changes to config fil ![Clear configuration cache](/assets/images/config_refresh.png) -In the example module folder, create a file called config.php and insert the following text. +In the example module folder, create a file called config.php and insert the following text (this is different to the config.php file changed in the instructions under the installation menu). ```php ``` -Now refresh the example index page to view the button. Notice that the URL uses the 'modulename-submodulename/action' format. This indicates that the link is directing to the 'item' submodule of the 'example' module. We now need to add this action to our module. Go to the Creating Item Action section by clicking Next below. \ No newline at end of file +Now refresh the example index page to view the button. Notice that the URL uses the 'modulename-submodulename/action' format. This indicates that the link is directing to the 'item' submodule of the 'example' module. We now need to add this action to our module. Go to the Creating Item Action section by clicking Next below. + +Please note that a button is only one html element which can be added using a template. more can be found in the html.php file in the system folder. \ No newline at end of file diff --git a/_tutorials/module-anatomy/creating-item-action.md b/_tutorials/module-anatomy/creating-item-action.md index ea84dd0..be8c5fe 100644 --- a/_tutorials/module-anatomy/creating-item-action.md +++ b/_tutorials/module-anatomy/creating-item-action.md @@ -27,7 +27,6 @@ function edit_GET(Web $w) { //add a title to the action $w->ctx('title','Add new item'); - ctxService::getInstance($w)->("title","Add new item"); // this array is the form definition $formData = [ @@ -44,11 +43,11 @@ function edit_GET(Web $w) ]; // sending the form to the 'out' function bypasses the template. - $w->out(Html::multiColForm($formData, 'example-item/edit')); - outService::getInstance($w)->(Html::multiColForm($formData, 'example-item/edit')); - + $w->out(Html::multiColForm($formData, 'edit')); } ``` +Note that we render the form without the template in the above 'out' function. This is because the form is the only thing displayed on the page. It is only a single HTML element which is to be rendered. When more than one HTML element is to be rendered we use the template, as seen i the last code block on this page.
+ Now that we have the form, let's add to the POST function where we will save the data to the database. ```php function edit_POST(Web $w) @@ -103,4 +102,6 @@ function index_ALL(Web $w) $w->ctx('itemTable', Html::table($table,'item_table','tablesorter',$tableHeaders)); } ``` +Here we use the 'ctx' function to send our table to the template. This is because the index page will display the item table, and the button to add a new item. When rendering two or more HTML elements, the template is useful as it gives us greater control. + To view the table we need to add it to the index action template file. \ No newline at end of file diff --git a/_tutorials/module-anatomy/edit-item-button.md b/_tutorials/module-anatomy/edit-item-button.md index 4a7eb74..30f8346 100644 --- a/_tutorials/module-anatomy/edit-item-button.md +++ b/_tutorials/module-anatomy/edit-item-button.md @@ -78,7 +78,7 @@ function edit_POST(Web $w) We can now make changes to our existing items. Test this by changing some of the values of the items in your list. Our next task will be to create the delete action that will remove items from our list.
-Create a new file in actions/item called delete.php and add the following code. +Create a new file in actions/item called delete.php. The delete button we added to our item list in [Creating Item Action](creating-item-action). Add the following code to your new file. ```php error('No item found for id','example'); - ctxService::getInstance($w)->error("No item found for id","example"); } // delete the item $item->delete(); // redirect the user back to the item list with a message $w->msg('Item deleted','example'); } -``` \ No newline at end of file +``` + +Save this action, and test it by going to your item list and clicking the delete button next to one of your items. \ No newline at end of file diff --git a/_tutorials/module-anatomy/install-and-migrations.md b/_tutorials/module-anatomy/install-and-migrations.md index 33666f2..a99a716 100644 --- a/_tutorials/module-anatomy/install-and-migrations.md +++ b/_tutorials/module-anatomy/install-and-migrations.md @@ -8,7 +8,7 @@ type: tute The Install folder holds the scripts required for all installation needs of the module. These may be database migrations, database seeds, report sql files, templates, and others. -Migrations are used to make changes to the database structure. Migration files are generated through the UI and are timestamped to ensure they run in the correct order. +Migrations are used to make changes to the database structure (i.e. tables). Migration files are generated through the UI and are timestamped (the year, month, day, and time to the second. It will look something like 20210721022033) to ensure they run in the correct order. These timestamps allow us to rollback and run migrations in order as needed. ```php public function up() @@ -80,6 +80,7 @@ public function up() } } ``` + It is important to ensure that your migration undoes any database changes in the down function. In this case we have created a table in our up function so we will remove it in our down function. ```php public function down() diff --git a/_tutorials/module-anatomy/introduction.md b/_tutorials/module-anatomy/introduction.md index 6d4264b..93e81ef 100644 --- a/_tutorials/module-anatomy/introduction.md +++ b/_tutorials/module-anatomy/introduction.md @@ -6,6 +6,8 @@ type: tute ## Working with modules +This tutorial will walk you through creating a module for your project 'example'. This module will be used to make tables for your database. The tutorial will then show you how to add information to theses tables that can then be accessed by your site. + Cmfive modules consist of a fixed structure and are located in the boilerplate modules folder. To get started you can either create a module repository directly in the cmfive-boilerplate/modules folder or create a symbolic link to your external module repository. The module name must be all lower case and must match the name in the module config and service class. This will be explained further. diff --git a/_tutorials/module-anatomy/theModelsFolder.md b/_tutorials/module-anatomy/theModelsFolder.md index 2e66529..e948340 100644 --- a/_tutorials/module-anatomy/theModelsFolder.md +++ b/_tutorials/module-anatomy/theModelsFolder.md @@ -52,4 +52,6 @@ class ExampleItem extends DbObject { ``` The model properties must be named according to the column names on the database table. +If you go to /system/classes and look at the DBObject.php file, you can see some further standard model properties that can be used, or will appear in all of your tables. + Now that we have our model and service class we can start creating some actions for our module. \ No newline at end of file diff --git a/assets/images/closing_mysql_shell.png b/assets/images/closing_mysql_shell.png new file mode 100644 index 0000000..687ba0b Binary files /dev/null and b/assets/images/closing_mysql_shell.png differ diff --git a/assets/images/cmfive_login.png b/assets/images/cmfive_login.png new file mode 100644 index 0000000..c7cbdec Binary files /dev/null and b/assets/images/cmfive_login.png differ diff --git a/assets/images/docker.png b/assets/images/docker.png new file mode 100644 index 0000000..aa463fa Binary files /dev/null and b/assets/images/docker.png differ diff --git a/index.md b/index.md index 2ce7c78..2909d65 100644 --- a/index.md +++ b/index.md @@ -1,11 +1,11 @@ --- layout: home title: Home -landing-title: 'A framework designed for fast ERP solutions' +landing-title: 'A framework designed for fast ERP and CRM business software solutions' description: null image: null author: null show_tile: false --- -Check out our getting started guide \ No newline at end of file +Check out our getting started guide