From 4704a15728f5d2b7aec62ef0ae736505ba1790a5 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Sat, 11 Mar 2023 14:01:46 +1100 Subject: [PATCH 01/14] Correcting typo and breakline tag --- _tutorials/module-anatomy/creating-item-action.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_tutorials/module-anatomy/creating-item-action.md b/_tutorials/module-anatomy/creating-item-action.md index be8c5fe..e582041 100644 --- a/_tutorials/module-anatomy/creating-item-action.md +++ b/_tutorials/module-anatomy/creating-item-action.md @@ -46,7 +46,7 @@ function edit_GET(Web $w) $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.
+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 in 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 @@ -104,4 +104,4 @@ function index_ALL(Web $w) ``` 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 +To view the table we need to add it to the index action template file. From ae1613227bcf531ec479fe498d20861befad1b76 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Sat, 11 Mar 2023 14:14:46 +1100 Subject: [PATCH 02/14] Editing the provided code sample The provided code sample had the two lines each with their own `` closing tags. This is not in the style of the other code examples provided in these tutorials, and if directly copied, results in an error. --- _tutorials/module-anatomy/add-item-table.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/_tutorials/module-anatomy/add-item-table.md b/_tutorials/module-anatomy/add-item-table.md index b7009a8..205518f 100644 --- a/_tutorials/module-anatomy/add-item-table.md +++ b/_tutorials/module-anatomy/add-item-table.md @@ -9,10 +9,12 @@ type: tute Adding the item table to the index template. -Open templates/index.tpl.php and add the following lines. +Open templates/index.tpl.php and add the line `echo $itemTable;`. Your templates/index.tpl.php file should now look like this: ```php - - + -Now we need to get our item action buttons to work properly. We will do this in the Edit Item Button section. \ No newline at end of file +Now we need to get our item action buttons to work properly. We will do this in the Edit Item Button section. From 92c2ef264de9402a6e6ce783f71485a000a1fdd1 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Sat, 11 Mar 2023 14:20:58 +1100 Subject: [PATCH 03/14] Making code sample fit the format of other samples All other code samples within the tutorial have the ` Add this code to the 'index.tpl.php'. -```html - +```php + Date: Tue, 14 Mar 2023 10:16:41 +1100 Subject: [PATCH 04/14] Adding whitespace to match format of other samples Adding whitespace after ` true, 'path' => 'modules', @@ -27,6 +28,7 @@ In the example module folder, create a file called config.php and insert the fol ```php true, 'path' => 'modules', @@ -40,4 +42,4 @@ Now clear the config cache and refresh the browser window. You should now see a Now that our module has a config we need to add some tables to the database. -If an error occurs follow the instructions in [The Models Folder] (theModelsFolder) and see if this rectifies the issue. \ No newline at end of file +If an error occurs follow the instructions in [The Models Folder] (theModelsFolder) and see if this rectifies the issue. From c663bdce3a1415347fa9af1aed1558e626c79ee9 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Tue, 14 Mar 2023 10:30:23 +1100 Subject: [PATCH 05/14] Fixing whitespace Inconsistent whitespace with spaces and some random tabs here and there --- .../module-anatomy/install-and-migrations.md | 47 +++++++++---------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/_tutorials/module-anatomy/install-and-migrations.md b/_tutorials/module-anatomy/install-and-migrations.md index a99a716..b231e20 100644 --- a/_tutorials/module-anatomy/install-and-migrations.md +++ b/_tutorials/module-anatomy/install-and-migrations.md @@ -48,35 +48,34 @@ Let's use the migration to add a database table for our module by editing the up ```php public function up() { - // UP - $column = parent::Column(); - $column->setName('id') - ->setType('biginteger') - ->setIdentity(true); - - } + // UP + $column = parent::Column(); + $column->setName('id') + ->setType('biginteger') + ->setIdentity(true); +} ``` The function already contains some code. This is the definition for the id column that each table will need. Let's now define a table for an example item that we want to store data against. ```php public function up() { - // UP - $column = parent::Column(); - $column->setName('id') - ->setType('biginteger') - ->setIdentity(true); + // UP + $column = parent::Column(); + $column->setName('id') + ->setType('biginteger') + ->setIdentity(true); - if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used - $this->table("example_item", [ // table names should be appended with 'ModuleName_' - "id" => false, - "primary_key" => "id" - ])->addColumn($column) // add the id column - ->addStringColumn('name') - ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' - ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' - ->addIntegerColumn('my_integer') - ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. - ->create(); + if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used + $this->table("example_item", [ // table names should be appended with 'ModuleName_' + "id" => false, + "primary_key" => "id" + ])->addColumn($column) // add the id column + ->addStringColumn('name') + ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' + ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' + ->addIntegerColumn('my_integer') + ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. + ->create(); } } ``` @@ -94,4 +93,4 @@ In the browser, navigate to the Cmfive migrations page, view by individual modul After running the migration we can verify that the table was created in the database.
To roll back we can click 'rollback to here' next to our migration. This will run the down function and the table will be removed. -Make sure the migration is run and we can now look at creating our item model and our module service class. \ No newline at end of file +Make sure the migration is run and we can now look at creating our item model and our module service class. From 5e3573af13e9f8a85cb4690fe3bc58c054f0d458 Mon Sep 17 00:00:00 2001 From: Dane Evans <98690514+Dane-2pi@users.noreply.github.com> Date: Mon, 13 Mar 2023 23:47:50 +0000 Subject: [PATCH 06/14] initial codespaces --- docker-compose.override.yml | 76 +++++++++++++++++++------------------ docker-compose.yml | 4 +- 2 files changed, 41 insertions(+), 39 deletions(-) diff --git a/docker-compose.override.yml b/docker-compose.override.yml index 0f264a6..6503fa4 100644 --- a/docker-compose.override.yml +++ b/docker-compose.override.yml @@ -6,54 +6,56 @@ version: '2.1' # SERVICES ################################################################################ -# # services: +# services: -# # # Custom setup for Docker image here: -# # builddocs: -# # image: jekyll/jekyll -# # hostname: builder - -# # command: jekyll ${JEKYLL_BUILD} ${JEKYLL_CONF_EXEC} -# # volumes: -# # - ${JEKYLL_PATH}:/srv/jekyll:rw${MOUNT_OPTIONS} -# # - jekyll-bundles:/usr/local/bundle:rw${MOUNT_OPTIONS} +# # # # Custom setup for Docker image here: +# jekyll: +# # image: jekyll/jekyll +# # hostname: jekyll +# ports: +# - '4000:4000' + + # command: jekyll ${JEKYLL_BUILD} ${JEKYLL_CONF_EXEC} + # volumes: + # - ${JEKYLL_PATH}:/srv/jekyll:rw${MOUNT_OPTIONS} + # - jekyll-bundles:/usr/local/bundle:rw${MOUNT_OPTIONS} -# # environment: -# # ## -# # ## Debug/Logging -# # ## -# # - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT} -# # - DEBUG_COMPOSE_ENTRYPOINT -# # - DOCKER_LOGS + # environment: + # ## + # ## Debug/Logging + # ## + # - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT} + # - DEBUG_COMPOSE_ENTRYPOINT + # - DOCKER_LOGS # # # End of custom Docker image # # # Custom setup for Docker image here: -# # httpsjekyll: -# # image: jekyll/jekyll -# # hostname: httpsjekyll -# # ports: -# # - '4000:4000' -# # networks: -# # app_net: -# # ipv4_address: 172.16.238.20 + # httpsjekyll: + # image: jekyll/jekyll + # hostname: httpsjekyll + # ports: + # - '4000:4000' + # networks: + # app_net: + # ipv4_address: 172.16.238.20 -# # command: "jekyll serve --ssl-key ./assets/hostconfig/localhost-key.pem --ssl-cert ./assets/hostconfig/localhost.pem --trace --config _config.yml,assets/jekyllconfig/_config_development.yml" -# # volumes: -# # - ${JEKYLL_PATH}:/srv/jekyll:rw${MOUNT_OPTIONS} -# # - jekyll-bundles:/usr/local/bundle:rw${MOUNT_OPTIONS} + # command: "jekyll serve --ssl-key ./assets/hostconfig/localhost-key.pem --ssl-cert ./assets/hostconfig/localhost.pem --trace --config _config.yml,assets/jekyllconfig/_config_development.yml" + # volumes: + # - ${JEKYLL_PATH}:/srv/jekyll:rw${MOUNT_OPTIONS} + # - jekyll-bundles:/usr/local/bundle:rw${MOUNT_OPTIONS} -# # environment: -# # ## -# # ## Debug/Logging -# # ## -# # - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT} -# # - DEBUG_COMPOSE_ENTRYPOINT -# # - DOCKER_LOGS -# # - JEKYLL_ENV=docker + # environment: + # ## + # ## Debug/Logging + # ## + # - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT} + # - DEBUG_COMPOSE_ENTRYPOINT + # - DOCKER_LOGS + # - JEKYLL_ENV=docker # # # End of custom Docker image diff --git a/docker-compose.yml b/docker-compose.yml index 11f151f..74c10cc 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -46,8 +46,8 @@ services: jekyll: image: jekyll/jekyll:4.0.1 hostname: jekyll - #ports: - #- '4000:4000' + ports: + - '4000:4000' networks: doc_app_net: ipv4_address: 172.20.238.80 From a61e4477b58a70f3561e76b0c0c3cb25a3b3fcf6 Mon Sep 17 00:00:00 2001 From: Dane Evans <98690514+Dane-2pi@users.noreply.github.com> Date: Mon, 13 Mar 2023 23:51:29 +0000 Subject: [PATCH 07/14] new devcontainer --- .devcontainer/devcontainer.json | 1 + 1 file changed, 1 insertion(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..76edfa6 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1 @@ +{"image":"mcr.microsoft.com/devcontainers/universal:2"} \ No newline at end of file From 6bbef75690ff1a2b9bfd94588104bc858ca18772 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Tue, 14 Mar 2023 00:25:34 +0000 Subject: [PATCH 08/14] Cleaning up code snippet formatting --- .devcontainer/devcontainer.json | 1 + _tutorials/module-anatomy/actions.md | 10 ++++++---- _tutorials/module-anatomy/config.md | 2 ++ _tutorials/module-anatomy/creating-index-action.md | 1 + _tutorials/module-anatomy/creating-item-action.md | 2 ++ .../module-anatomy/install-and-migrations.md | 2 +- _tutorials/module-anatomy/install.md | 13 ++++++------- _tutorials/module-anatomy/models.md | 1 + _tutorials/module-anatomy/templates.md | 8 +++++--- _tutorials/module-anatomy/theModelsFolder.md | 14 ++++++++------ 10 files changed, 33 insertions(+), 21 deletions(-) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..76edfa6 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1 @@ +{"image":"mcr.microsoft.com/devcontainers/universal:2"} \ No newline at end of file diff --git a/_tutorials/module-anatomy/actions.md b/_tutorials/module-anatomy/actions.md index 53ad1f3..5e5abb6 100644 --- a/_tutorials/module-anatomy/actions.md +++ b/_tutorials/module-anatomy/actions.md @@ -12,7 +12,8 @@ The following example is of an index action located in module_folder -> actions ```php ctx("title", "Example Module"); - } ``` The code above we use the 'ctx' or context function on our Web object to set the title for our index action. Our index action is now accessible through the Cmfive UI, click on the 'Example' menu item in Cmfive to view the index action. @@ -48,10 +48,12 @@ Now create a new file in our 'item' submodule and call it 'edit.php'. In this fi function edit_GET(Web $w) { + } function edit_POST(Web $w) { + } ``` Let's continue by focussing on the GET method.
diff --git a/_tutorials/module-anatomy/config.md b/_tutorials/module-anatomy/config.md index 1cbea45..92aab44 100644 --- a/_tutorials/module-anatomy/config.md +++ b/_tutorials/module-anatomy/config.md @@ -8,6 +8,7 @@ type: tute ```php true, 'path' => 'modules', @@ -29,6 +30,7 @@ In the example module folder, create a file called config.php and insert the fol ```php true, 'path' => 'modules', diff --git a/_tutorials/module-anatomy/creating-index-action.md b/_tutorials/module-anatomy/creating-index-action.md index c81090a..451ce96 100644 --- a/_tutorials/module-anatomy/creating-index-action.md +++ b/_tutorials/module-anatomy/creating-index-action.md @@ -14,6 +14,7 @@ The following example is of an index action located in module_folder -> actions function index_ALL(Web $w) { + } ``` The function name before the underscore must match the file name. This is followed by the method, GET, POST or ALL. Finally, all actions need to be passed the Web $w object. diff --git a/_tutorials/module-anatomy/creating-item-action.md b/_tutorials/module-anatomy/creating-item-action.md index e582041..6cb97df 100644 --- a/_tutorials/module-anatomy/creating-item-action.md +++ b/_tutorials/module-anatomy/creating-item-action.md @@ -14,10 +14,12 @@ Now create a new file in our 'item' submodule and call it 'edit.php'. In this fi function edit_GET(Web $w) { + } function edit_POST(Web $w) { + } ``` Let's continue by focussing on the GET method.
diff --git a/_tutorials/module-anatomy/install-and-migrations.md b/_tutorials/module-anatomy/install-and-migrations.md index b231e20..ffa02af 100644 --- a/_tutorials/module-anatomy/install-and-migrations.md +++ b/_tutorials/module-anatomy/install-and-migrations.md @@ -63,7 +63,7 @@ public function up() $column = parent::Column(); $column->setName('id') ->setType('biginteger') - ->setIdentity(true); + ->setIdentity(true); if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used $this->table("example_item", [ // table names should be appended with 'ModuleName_' diff --git a/_tutorials/module-anatomy/install.md b/_tutorials/module-anatomy/install.md index e15c26f..890d754 100644 --- a/_tutorials/module-anatomy/install.md +++ b/_tutorials/module-anatomy/install.md @@ -52,13 +52,12 @@ Let's use the migration to add a database table for our module by editing the up ```php public function up() { - // UP - $column = parent::Column(); - $column->setName('id') - ->setType('biginteger') - ->setIdentity(true); - - } + // UP + $column = parent::Column(); + $column->setName('id') + ->setType('biginteger') + ->setIdentity(true); +} ``` The function already contains some code. This is the definition for the id column that each table will need. Let's now define a table for an example item that we want to store data against. ```php diff --git a/_tutorials/module-anatomy/models.md b/_tutorials/module-anatomy/models.md index ccc5b5e..04d8254 100644 --- a/_tutorials/module-anatomy/models.md +++ b/_tutorials/module-anatomy/models.md @@ -22,6 +22,7 @@ Open the file and add the class definition. class ExampleService extends DbService { + } ``` Let's add two functions to our service class that will be used to retrieve data for our example items. These functions will use GetObject functions from Cmfive's DbService class. Add these functions to the service class. diff --git a/_tutorials/module-anatomy/templates.md b/_tutorials/module-anatomy/templates.md index 3dcdd80..75ddb40 100644 --- a/_tutorials/module-anatomy/templates.md +++ b/_tutorials/module-anatomy/templates.md @@ -23,10 +23,12 @@ Now refresh the example index page to view the button. Notice that the URL uses Adding the item table to the index template. -Open templates/index.tpl.php and add the following lines. +Open templates/index.tpl.php and modify it so it looks like this: ```php - - + Now we need to get our item action buttons to work properly. We will do this back in the actions section. Resume the actions tutorial [here](actions#tutorial-part-3) \ No newline at end of file diff --git a/_tutorials/module-anatomy/theModelsFolder.md b/_tutorials/module-anatomy/theModelsFolder.md index e948340..2c3c562 100644 --- a/_tutorials/module-anatomy/theModelsFolder.md +++ b/_tutorials/module-anatomy/theModelsFolder.md @@ -18,19 +18,22 @@ Open the file and add the class definition. ```php GetObjects('ExampleItem',['is_deleted'=>0]); } // returns a single example item matching the given id -public function GetItemForId($id) { +public function GetItemForId($id) +{ return $this->GetObject('ExampleItem',$id); } ``` @@ -41,13 +44,12 @@ Let's start defining our model properties in our 'ExampleItem.php' file. ```php Date: Tue, 14 Mar 2023 00:53:48 +0000 Subject: [PATCH 09/14] Dealing with whitespace ... --- _tutorials/module-anatomy/actions.md | 1 - .../module-anatomy/creating-index-action.md | 2 +- .../module-anatomy/creating-item-action.md | 2 +- .../module-anatomy/install-and-migrations.md | 40 +++++++++---------- 4 files changed, 22 insertions(+), 23 deletions(-) diff --git a/_tutorials/module-anatomy/actions.md b/_tutorials/module-anatomy/actions.md index 5e5abb6..d923d32 100644 --- a/_tutorials/module-anatomy/actions.md +++ b/_tutorials/module-anatomy/actions.md @@ -80,7 +80,6 @@ function edit_GET(Web $w) // sending the form to the 'out' function bypasses the template. $w->out(Html::multiColForm($formData, 'example-item/edit')); - } ``` Now that we have the form, let's add to the POST function where we will save the data to the database. diff --git a/_tutorials/module-anatomy/creating-index-action.md b/_tutorials/module-anatomy/creating-index-action.md index 451ce96..514b4b3 100644 --- a/_tutorials/module-anatomy/creating-index-action.md +++ b/_tutorials/module-anatomy/creating-index-action.md @@ -14,7 +14,7 @@ The following example is of an index action located in module_folder -> actions function index_ALL(Web $w) { - + } ``` The function name before the underscore must match the file name. This is followed by the method, GET, POST or ALL. Finally, all actions need to be passed the Web $w object. diff --git a/_tutorials/module-anatomy/creating-item-action.md b/_tutorials/module-anatomy/creating-item-action.md index 6cb97df..fb6edf9 100644 --- a/_tutorials/module-anatomy/creating-item-action.md +++ b/_tutorials/module-anatomy/creating-item-action.md @@ -19,7 +19,7 @@ function edit_GET(Web $w) function edit_POST(Web $w) { - + } ``` Let's continue by focussing on the GET method.
diff --git a/_tutorials/module-anatomy/install-and-migrations.md b/_tutorials/module-anatomy/install-and-migrations.md index ffa02af..b38cf87 100644 --- a/_tutorials/module-anatomy/install-and-migrations.md +++ b/_tutorials/module-anatomy/install-and-migrations.md @@ -48,34 +48,34 @@ Let's use the migration to add a database table for our module by editing the up ```php public function up() { - // UP - $column = parent::Column(); - $column->setName('id') - ->setType('biginteger') - ->setIdentity(true); + // UP + $column = parent::Column(); + $column->setName('id') + ->setType('biginteger') + ->setIdentity(true); } ``` The function already contains some code. This is the definition for the id column that each table will need. Let's now define a table for an example item that we want to store data against. ```php public function up() { - // UP - $column = parent::Column(); - $column->setName('id') - ->setType('biginteger') + // UP + $column = parent::Column(); + $column->setName('id') + ->setType('biginteger') ->setIdentity(true); - if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used - $this->table("example_item", [ // table names should be appended with 'ModuleName_' - "id" => false, - "primary_key" => "id" - ])->addColumn($column) // add the id column - ->addStringColumn('name') - ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' - ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' - ->addIntegerColumn('my_integer') - ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. - ->create(); + if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used + $this->table("example_item", [ // table names should be appended with 'ModuleName_' + "id" => false, + "primary_key" => "id" + ])->addColumn($column) // add the id column + ->addStringColumn('name') + ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' + ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' + ->addIntegerColumn('my_integer') + ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. + ->create(); } } ``` From 0f60103c46ac33f19a323a99a59aa16a9dfc52f3 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Tue, 14 Mar 2023 00:57:59 +0000 Subject: [PATCH 10/14] more whitespace pain --- .../module-anatomy/install-and-migrations.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/_tutorials/module-anatomy/install-and-migrations.md b/_tutorials/module-anatomy/install-and-migrations.md index b38cf87..be819f8 100644 --- a/_tutorials/module-anatomy/install-and-migrations.md +++ b/_tutorials/module-anatomy/install-and-migrations.md @@ -61,21 +61,21 @@ public function up() { // UP $column = parent::Column(); - $column->setName('id') - ->setType('biginteger') - ->setIdentity(true); + $column->setName('id') + ->setType('biginteger') + ->setIdentity(true); - if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used - $this->table("example_item", [ // table names should be appended with 'ModuleName_' - "id" => false, - "primary_key" => "id" - ])->addColumn($column) // add the id column - ->addStringColumn('name') - ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' - ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' - ->addIntegerColumn('my_integer') - ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. - ->create(); + if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used + $this->table("example_item", [ // table names should be appended with 'ModuleName_' + "id" => false, + "primary_key" => "id" + ])->addColumn($column) // add the id column + ->addStringColumn('name') + ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' + ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' + ->addIntegerColumn('my_integer') + ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. + ->create(); } } ``` From f65b2fe4c2aa9782198ed2ba0d3a6a5a6747ec80 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Tue, 14 Mar 2023 00:59:40 +0000 Subject: [PATCH 11/14] =?UTF-8?q?yt=F0=9F=8C=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../module-anatomy/install-and-migrations.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/_tutorials/module-anatomy/install-and-migrations.md b/_tutorials/module-anatomy/install-and-migrations.md index be819f8..cdf108e 100644 --- a/_tutorials/module-anatomy/install-and-migrations.md +++ b/_tutorials/module-anatomy/install-and-migrations.md @@ -67,15 +67,15 @@ public function up() if (!$this->hasTable("example_item")) { //it can be helpful to check that the table name is not used $this->table("example_item", [ // table names should be appended with 'ModuleName_' - "id" => false, - "primary_key" => "id" - ])->addColumn($column) // add the id column - ->addStringColumn('name') - ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' - ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' - ->addIntegerColumn('my_integer') - ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. - ->create(); + "id" => false, + "primary_key" => "id" + ])->addColumn($column) // add the id column + ->addStringColumn('name') + ->addBooleanColumn('is_checked') //boolean columns need to be appended with 'is_' + ->addDateTimeColumn('dt_started') // Datetime columns need to be appended with 'dt_' + ->addIntegerColumn('my_integer') + ->addCmfiveParameters() // this function adds some standard columns used in cmfive. dt_created, dt_modified, creator_id, modifier_id, and is_deleted. + ->create(); } } ``` From c7eb587897e63addc082e5c40f610d7cf291644a Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Wed, 15 Mar 2023 00:30:44 +0000 Subject: [PATCH 12/14] Dealing with Markdown, correcting whitespace rendering --- _tutorials/additional-configuration/emails.md | 65 +++++++++++-------- _tutorials/additional-configuration/logs.md | 28 ++++---- .../additional-configuration/uploads.md | 56 +++++++++------- _tutorials/installation/installation.md | 4 +- 4 files changed, 89 insertions(+), 64 deletions(-) diff --git a/_tutorials/additional-configuration/emails.md b/_tutorials/additional-configuration/emails.md index 500d0a1..9f0be2d 100644 --- a/_tutorials/additional-configuration/emails.md +++ b/_tutorials/additional-configuration/emails.md @@ -11,43 +11,52 @@ Cmfive supports two different types of email transports to best suit your needs. - The AWS Transport uses various AWS services to make sending email faster and more reliable. Note, to enable the AWS Transport uploads must also stored in S3. See the uploads [tutorial](/tutorials/additional-configuration/uploads) for setup. - The SwiftMailer transport uses the SwiftMailer library. -## AWS Transport +[comment]: # (The code snippets are indented so they work with the rendering of the numbered list of steps) +## AWS Transport 1. Add the following entries into the config.php file in the root directory of your Cmfive project. -```php -Config::append("email", [ - "layer" => "aws", -]); -Config::set("admin.mail.aws", [ - "queue_url" => "SQS_QUEUE_URL", - "region" => "SQS_QUEUE_REGION", -]); -``` + ```php + Config::append("email", [ + "layer" => "aws", + ]); + + Config::set("admin.mail.aws", [ + "queue_url" => "SQS_QUEUE_URL", + "region" => "SQS_QUEUE_REGION", + ]); + ``` + 2. If you're developing on Cmfive locally, also add the following. Note, when system.environment is set to production [AWS IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) must be used to authenticate with AWS as this is best practice for security. -```php -Config::set("admin.mail.aws.credentials", [ - "key" => "IAM_KEY", - "secret" => "IAM_SECRET", -]); -Config::set("system.environment", "development"); -``` + ```php + Config::set("admin.mail.aws.credentials", [ + "key" => "IAM_KEY", + "secret" => "IAM_SECRET", + ]); + + Config::set("system.environment", "development"); + ``` + 3. Replace SQS_QUEUE_URL and SQS_QUEUE_REGION with their respective values as well as IAM_KEY and IAM_SECRET if system.environment is set to development. + 4. Make sure to clear your config cache to apply your changes. + 5. Clone the Cmfive-Mail-Service-CDK [repository](https://github.com/2pisoftware/Cmfive-Mail-Service-CDK) and follow the steps outlined in the README.md file to deploy the CDK stack. ## SwiftMailer Transport 1. Add the following entries into the config.php file in the root directory of your Cmfive project. -```php -Config::append("email", [ - "layer" => "smtp", - "command" => "", - "host" => "EMAIL_HOST", - "port" => PORT_NUMBER, - "auth" => true, - "username" => "EMAIL_USERNAME", - "password" => "EMAIL_PASSWORD", -]); -``` + ```php + Config::append("email", [ + "layer" => "smtp", + "command" => "", + "host" => "EMAIL_HOST", + "port" => PORT_NUMBER, + "auth" => true, + "username" => "EMAIL_USERNAME", + "password" => "EMAIL_PASSWORD", + ]); + ``` + 2. Replace EMAIL_HOST, PORT_NUMBER, EMAIL_USERNAME and EMAIL_PASSWORD with their respective values. + 3. Make sure to clear your config cache to apply your changes. \ No newline at end of file diff --git a/_tutorials/additional-configuration/logs.md b/_tutorials/additional-configuration/logs.md index b6a677c..29fa978 100644 --- a/_tutorials/additional-configuration/logs.md +++ b/_tutorials/additional-configuration/logs.md @@ -11,11 +11,13 @@ Cmfive supports two different types of log targets to best suit your needs. - The AWS Target provides a more reliable solution with the option to specify a retention period (in days). - The File Target is enabled by default and requires no further setup. +[comment]: # (The code snippets are indented so they work with the rendering of the numbered list of steps) + ## AWS Target 1. Add the following entries into the config.php file in the root directory of your Cmfive project. -```php -Config::set("admin.logging", [ + ```php + Config::set("admin.logging", [ "target" => "aws", "retention_period" => RETENTION_PERIOD, "cloudwatch" => [ @@ -24,15 +26,19 @@ Config::set("admin.logging", [ "region" => "CLOUDWATCH_REGION", "version" => "latest", ] -]); -``` + ]); + ``` + 2. If you're developing on Cmfive locally, also add the following. Note, when system.environment is set to production [AWS IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) must be used to authenticate with AWS as this is best practice for security. -```php -Config::set("admin.logging.cloudwatch.credentials", [ - "key" => "IAM_KEY", - "secret" => "IAM_SECRET", -]); -Config::set("system.environment", "development"); -``` + ```php + Config::set("admin.logging.cloudwatch.credentials", [ + "key" => "IAM_KEY", + "secret" => "IAM_SECRET", + ]); + + Config::set("system.environment", "development"); + ``` + 3. Replace RETENTION_PERIOD, GROUP_NAME, APP_NAME, CLOUDWATCH_REGION with their respective values as well as IAM_KEY and IAM_SECRET if system.environment is set to development. + 4. Make sure to clear your config cache to apply your changes. \ No newline at end of file diff --git a/_tutorials/additional-configuration/uploads.md b/_tutorials/additional-configuration/uploads.md index 31b60dd..3f3fafc 100644 --- a/_tutorials/additional-configuration/uploads.md +++ b/_tutorials/additional-configuration/uploads.md @@ -11,35 +11,43 @@ Cmfive supports two different types of file adapters for uploads to best suit yo - The Local Adapter is enabled by default and requires no further setup. - The S3 Adapter provides a more available and reliable solution. +[comment]: # (The code snippets are indented so they work with the rendering of the numbered list of steps) + ## S3 Adapter 1. Add the following entries into the config.php file in the root directory of your Cmfive project. -```php -Config::set("file.adapters.local.active", false); -Config::set("file.adapters.s3", [ - "active" => true, - "region" => "S3_BUCKET_REGION", - "version" => "2006-03-01", - "credentials" => [ - "key" => "IAM_KEY", - "secret" => "IAM_SECRET", - ], - "bucket" => "S3_BUCKET_NAME", - "options" => [ - "directory" => "uploads", - "create" => true - ], -]); -``` + ```php + Config::set("file.adapters.local.active", false); + + Config::set("file.adapters.s3", [ + "active" => true, + "region" => "S3_BUCKET_REGION", + "version" => "2006-03-01", + "credentials" => [ + "key" => "IAM_KEY", + "secret" => "IAM_SECRET", + ], + "bucket" => "S3_BUCKET_NAME", + "options" => [ + "directory" => "uploads", + "create" => true + ], + ]); + ``` + 2. If you're developing on Cmfive locally, also add the following. Note, when system.environment is set to production [AWS IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) must be used to authenticate with AWS as this is best practice for security. -```php -Config::set("file.adapters.s3.credentials", [ - "key" => "IAM_KEY", - "secret" => "IAM_SECRET", -]); -Config::set("system.environment", "development"); -``` + ```php + Config::set("file.adapters.s3.credentials", [ + "key" => "IAM_KEY", + "secret" => "IAM_SECRET", + ]); + + Config::set("system.environment", "development"); + ``` + 3. Replace S3_BUCKET_REGION, IAM_KEY, IAM_SECRET and S3_BUCKET_NAME with their respective values as well as IAM_KEY and IAM_SECRET if system.environment is set to development. + 4. Make sure to clear your config cache to apply your changes. + 5. If you have any files stored locally from prior to using the S3 Adapter you can run file transfer tool in the admin module from within Cmfive to move them to S3. ![File Transfer Tool](/assets/images/file_transfer_tool.png) \ No newline at end of file diff --git a/_tutorials/installation/installation.md b/_tutorials/installation/installation.md index 793fa6e..94cf1f1 100644 --- a/_tutorials/installation/installation.md +++ b/_tutorials/installation/installation.md @@ -25,8 +25,10 @@ Install the Docker extension by Microsoft (extension ID: ```ms-azuretools.vscode #### Step 3 - Building the containers Right-click on the ```docker-compose.yml``` file and select ```Compose Up``` (This will take a while) +[comment]: # (Docker Tab image has an extra line of whitespace before it, otherwise it renders inline with the text) #### Step 4 - Verify -When docker compose has finished, check that you have 3 containers ready by clicking on the Docker tab on the left +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 From 3d4fe854b3a365198db94067333f6e2a4f8a461a Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Fri, 17 Mar 2023 00:41:20 +0000 Subject: [PATCH 13/14] unify formatting across tuts/docs, adding clarity --- _documentation/cmfive-tests/enable-tests.md | 5 +- .../core-modules/insight/insight.md | 78 ++++++++++--------- _documentation/core-modules/report/report.md | 20 ++--- 3 files changed, 54 insertions(+), 49 deletions(-) diff --git a/_documentation/cmfive-tests/enable-tests.md b/_documentation/cmfive-tests/enable-tests.md index 4af93b5..d8ec78f 100644 --- a/_documentation/cmfive-tests/enable-tests.md +++ b/_documentation/cmfive-tests/enable-tests.md @@ -15,13 +15,14 @@ Enabling the test framework is simple. Edit the file: cmfive-boilerplate/config.php ``` Update the 'testrunner' setting to 'ENABLED'. + ```php //========== TestRunner Configuration ========================== //========== must be "ENABLED" to run ========================== //========== "config" will pass through to CmfiveSite helper === Config::append("tests", array( - "testrunner" => "ENABLED" , - 'config' => [ ] + "testrunner" => "ENABLED", + 'config' => [ ] )); ``` The Cmfive test libraries do not need any extra entries to be added in the TestRunner 'config' array setting. diff --git a/_documentation/core-modules/insight/insight.md b/_documentation/core-modules/insight/insight.md index 1584fe1..9f9504e 100644 --- a/_documentation/core-modules/insight/insight.md +++ b/_documentation/core-modules/insight/insight.md @@ -13,9 +13,12 @@ The insight's class will be the sort of insight it is, followed by Insight (e.g. ```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. +In this class, add the variables below 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"; @@ -26,72 +29,71 @@ 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. +Add the function below to your ExampleInsight class. ```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. - +The code shown below goes in your getFilters function. It is what generates the filter options the user may choose from. 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 - ], - ] - ] - ]; -} +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. - +Add the following function after 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. +First, the insight finds the correct data based on the filters you have chosen. Add the following code to the run function to get the relevant data for our example insight. ```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. - +After retrieving the data based on the selected filters, your run function must build its table(s). For our example, add the following code to the run function. ```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 = []; + $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; + 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.
diff --git a/_documentation/core-modules/report/report.md b/_documentation/core-modules/report/report.md index 84fd060..cd6792c 100644 --- a/_documentation/core-modules/report/report.md +++ b/_documentation/core-modules/report/report.md @@ -8,18 +8,20 @@ type: doc The report module allows users to write custom MYSQL reports that can be saved and run when needed. +[comment]: # (The code snippet is indented so it can render the tabs correctly within the numbered list) + ## 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" -]); -``` + ```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. From 232653e5082f47175a686be3ab71122611c2c096 Mon Sep 17 00:00:00 2001 From: dragonfly_enthusiast <102092516+dragonflyfree@users.noreply.github.com> Date: Fri, 17 Mar 2023 00:48:05 +0000 Subject: [PATCH 14/14] removing redundant text from tut --- _tutorials/module-anatomy/add-item-table.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/_tutorials/module-anatomy/add-item-table.md b/_tutorials/module-anatomy/add-item-table.md index 205518f..2132406 100644 --- a/_tutorials/module-anatomy/add-item-table.md +++ b/_tutorials/module-anatomy/add-item-table.md @@ -7,8 +7,6 @@ type: tute ## Adding The Item Table to The Index Template -Adding the item table to the index template. - Open templates/index.tpl.php and add the line `echo $itemTable;`. Your templates/index.tpl.php file should now look like this: ```php