ADD database tables b_2

2023-10-04 18:06:13 +02:00 · 2023-10-04 18:06:13 +02:00 · 4e75af67ed
commit 4e75af67ed
parent f9004e46cb
5 changed files with 235 additions and 18 deletions
--- a/README.md
+++ b/README.md
@ -112,3 +112,174 @@ the directory /admin/language/en-GB/ naming it
 - com_depot.sys.ini

 ---
+
+### Creating and managing Joomla database (b2_database)
+
+With the new git branch **b2_database** we continue our workflow.
+
+Joomla usually manage its content with a database. In our component, we use
+a MariaDB database. At the time of development of this component we have PHP8.2,
+and we use Mariadb database with version from 11.1,
+client 15.2 for Linux (x86_64) using readline 5.1
+We support MySQL and MariaDB; not tested support for PostgreSQL.
+
+In the manifest file \<component_name\>.xml, here the file **depot.xml**,
+there are installation instructions to "install", "uninstall", and 
+"update" the Joomla extension/component.
+
+The SQL plain text files are stored in and as:
+
+- admin/sql/
+	- install.mysql.utf8.sql
+	- uninstall.mysql.utf8.sql
+
+- admin/sql/updates/mysql/
+	- 0.0.1.sql
+	- 0.0.4.sql
+	- 0.0.5.sql
+
+#### Database table installation
+1. When the component is installed for the first time, the file
+**install.mysql.utf8.sql** is executed.
+1. If the component is already installed, the update
+scenario comes into play, the folder **admin/sql/updates/mysql/**:  Only the files with higher version
+numbers than the installed version of the component will be
+executed in ascending order.<br>
+Hint: The version of the installed component is stored in the
+Joomla's table "#__schemas".
+
+The "#__"-prefix is substituted automatically with the database prefix, (e.g. "jm_") which is defined in the configuration file (configuration.php) of the installed Joomla version as parameter $dbprefix.
+
+**install.mysql.utf8.sql**
+```sql
+DROP TABLE IF EXISTS `#__depot`;
+CREATE TABLE `#__depot`(
+	`id` SERIAL,
+	`component_name` VARCHAR(1024) CHARACTER SET ascii COLLATE ascii_general_ci NULL DEFAULT NULL
+		COMMENT 'unique component name (ASCII characters only)',
+	`alias` VARCHAR(1024) NOT NULL DEFAULT '',
+	`description` VARCHAR(4000) NOT NULL DEFAULT '',
+	`quantity` INT(10) UNSIGNED NOT NULL DEFAULT 0,
+	`quantity_exp` INT(11) NOT NULL DEFAULT 0
+		COMMENT 'Exponent of the quantity (10^x of the number, usually 0 i.e. 10⁰)',
+	`asset_id` INT(10) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'FK to the #__assets table.',
+	`created` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
+	`created_by` INT(10) UNSIGNED NOT NULL DEFAULT 0,
+	`checked_out` INT(11) NOT NULL DEFAULT 0,
+	`checked_out_time` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
+	`modified` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
+	`modified_by` INT(10) UNSIGNED NOT NULL DEFAULT 0,
+	`path` VARCHAR(400) NOT NULL DEFAULT '',
+	`state` TINYINT(4) NOT NULL DEFAULT 0
+		COMMENT 'Published=1,Unpublished=0,Archived=2,Trashed=-2',
+	`access` TINYINT(4) NOT NULL DEFAULT 0,
+	`params` VARCHAR(1024) NOT NULL DEFAULT '',
+	`image` VARCHAR(1024) NOT NULL DEFAULT '',
+	`ordering` INT(11) NOT NULL DEFAULT 0,
+	`version` int unsigned NOT NULL DEFAULT 1,
+	-- references to other tables:
+	`category_id` INT(11) NOT NULL DEFAULT 0,
+	`datasheet_id` INT(11) NOT NULL DEFAULT 0,
+	`datasheet_alt` VARCHAR(1024) NOT NULL DEFAULT '',
+	`manufacturer_id` INT(11) NOT NULL DEFAULT 0,
+	`stock_id` INT(11) NOT NULL DEFAULT 0,
+	PRIMARY KEY (`id`),
+	KEY `idx_state` (`state`),
+	KEY `idx_stock_id` (`stock_id`),
+	KEY `idx_manufacturer` (`manufacturer_id`),
+	UNIQUE KEY `aliasindex` (`alias`,`manufacturer_id`,`stock_id`)
+)	ENGINE=InnoDB
+	AUTO_INCREMENT=0
+	DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+INSERT INTO `#__depot` (`component_name`,`alias`,`description`,`quantity`,`created`,
+ `ordering`,`state`,`manufacturer_id`) VALUES
+ ('1N5404','1n5404','diode, rectifier 3A',9,'2023-09-25 15:00:00',1,1,1),
+ ('1N4148','1n4148','diode, general purpose',1234,'2023-09-25 15:15:15',2,1,2);
+```
+The table is created in the database when the component is installed.
+Also two lines of sample data are inserted into the table "#__depot".
+
+#### Database table uninstallation
+When the component is uninstalled the
+**uninstall.mysql.utf8 sql** is executed.
+We drop the used tables from the database.
+
+**install.mysql.utf8.sql**
+```sql
+DROP TABLE IF EXISTS `#__depot`;
+```
+#### Database table update
+When the component is updated the
+**admin/sql/updates/mysql** folder with its files is executed.
+
+Even if you do not need a database update, you can add an empty file in admin/sql/updates/mysql/0.0.2.sql to initialize the schema version.
+
+In future versions, if you plan to use database tables, the update can be performed automatically.
+We create an empty file, just with a comment "-- version 0.0.2"
+**admin/sql/updates/mysql/0.0.2.sql**
+
+```sql
+-- version 0.0.2
+```
+
+#### Manifest file for extensions
+The sql files are only executed if they exist in the \<component_name\>.xml manifest file. We add this after the namespace tag, just before the files information tag:
+```php
+<install> <!-- Runs on install -->
+	<sql>
+		<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
+	</sql>
+</install>
+<uninstall> <!-- Runs on uninstall -->
+	<sql>
+		<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
+	</sql>
+</uninstall>
+<update>
+	<schemas>
+		<schemapath type="mysql">sql/updates/mysql</schemapath>
+	</schemas>
+</update>
+```
+The **\<version\> tag** of the manifest must be updated to 0.0.2 and
+also add the sql folder in the administration files section.
+
+#### Table class
+**src/table/DepotTable.php**
+
+For each database table, you have to define a table class. The model
+asks the table to get information or perform database operations.
+
+This table class has to be defined in admin/src/Table/DepotTable.php file.
+
+```php
+<?php
+namespace KW4NZ\Component\Depot\Administrator\Table;
+
+use Joomla\CMS\Table\Table;
+use Joomla\Database\DatabaseDriver;
+
+\defined('_JEXEC') or die;
+
+class DepotTable extends Table
+{
+	function __contruct(DatabaseDriver $db)
+	{
+		parent::__contruct('#__depot', 'id', $db);
+	}
+}
+```
+Joomla uses the **Table Object** to get item or record, insert records,
+update or delete records for the database operations.
+
+Methods in the table objects are:
+
+1. **load()** to load the existing record from the database, passing
+			the primary key of the record.
+1. **bind()** to set the new values for the fields.
+1. **check()** to perform any validation.
+1. **store()** to save the new values to the database.
+1. **delete()** to delete the record from the database.
+
+---
--- a/admin/sql/install.mysql.utf8.sql
+++ b/admin/sql/install.mysql.utf8.sql
@ -3,7 +3,7 @@
 -- @author		Thomas Kuschel <thomas@kuschel.at>
 -- @copyright	(C) 2023 KW4NZ, <https://www.kuschel.at>
 -- @license		GNU General Public License version 2 or later; see LICENSE.md
-- @since		0.0.1
+-- @since		0.0.2

 DROP TABLE IF EXISTS `#__depot`;
 CREATE TABLE `#__depot`(
@ -13,7 +13,8 @@ CREATE TABLE `#__depot`(
 	`alias` VARCHAR(1024) NOT NULL DEFAULT '',
 	`description` VARCHAR(4000) NOT NULL DEFAULT '',
 	`quantity` INT(10) UNSIGNED NOT NULL DEFAULT 0,
-	`quantity_exp` INT(11) NOT NULL DEFAULT 0 COMMENT 'Exponent of the quantity (10^x of the number, usually 0 i.e. 10⁰)',
+	`quantity_exp` INT(11) NOT NULL DEFAULT 0
+		COMMENT 'Exponent of the quantity (10^x of the number, usually 0 i.e. 10⁰)',
 	`asset_id` INT(10) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'FK to the #__assets table.',
 	`created` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
 	`created_by` INT(10) UNSIGNED NOT NULL DEFAULT 0,
@ -22,7 +23,8 @@ CREATE TABLE `#__depot`(
 	`modified` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
 	`modified_by` INT(10) UNSIGNED NOT NULL DEFAULT 0,
 	`path` VARCHAR(400) NOT NULL DEFAULT '',
-	`state` TINYINT(4) NOT NULL DEFAULT 0 COMMENT 'Published=1,Unpublished=0,Archived=2,Trashed=-2',
+	`state` TINYINT(4) NOT NULL DEFAULT 0
+		COMMENT 'Published=1,Unpublished=0,Archived=2,Trashed=-2',
 	`access` TINYINT(4) NOT NULL DEFAULT 0,
 	`params` VARCHAR(1024) NOT NULL DEFAULT '',
 	`image` VARCHAR(1024) NOT NULL DEFAULT '',
--- a/admin/sql/uninstall.mysql.utf8.sql
+++ b/admin/sql/uninstall.mysql.utf8.sql
@ -3,6 +3,6 @@
 -- @author		Thomas Kuschel <thomas@kuschel.at>
 -- @copyright	(C) 2023 KW4NZ, <https://www.kuschel.at>
 -- @license		GNU General Public License version 2 or later; see LICENSE.md
-- @since		0.0.1
+-- @since		0.0.2

 DROP TABLE IF EXISTS `#__depot`;
--- a/admin/src/Table/DepotTable
+++ b/admin/src/Table/DepotTable
@ -0,0 +1,24 @@
+<?php
+/**
+ * @package		Depot.Administrator
+ * @subpackage	com_depot
+ * @author		Thomas Kuschel <thomas@kuschel.at>
+ * @copyright	(C) 2023 KW4NZ, <https://www.kuschel.at>
+ * @license		GNU General Public License version 2 or later; see LICENSE.md
+ * @since		0.0.2
+ */
+
+namespace KW4NZ\Component\Depot\Administrator\Table;
+
+use Joomla\CMS\Table\Table;
+use Joomla\Database\DatabaseDriver;
+
+\defined('_JEXEC') or die;
+
+class DepotTable extends Table
+{
+	function __contruct(DatabaseDriver $db)
+	{
+		parent::__contruct('#__depot', 'id', $db);
+	}
+}
--- a/depot.xml
+++ b/depot.xml
@ -2,14 +2,29 @@
 <extension type="component" method="upgrade">
 	<name>Depot</name>
 	<author>KW4NZ</author>
-	<creationDate>2023-10-02</creationDate>
+	<creationDate>2023-10-04</creationDate>
 	<copyright>(C) KW4NZ Thomas Kuschel</copyright>
 	<license>GPL v2 +; see LICENSE.md</license>
 	<authorEmail>thomas@kuschel.at</authorEmail>
 	<authorUrl>https://kuschel.at</authorUrl>
-	<version>0.0.1</version>
+	<version>0.0.2</version>
 	<description>COM_DEPOT_XML_DESCRIPTION</description>
 	<namespace path="src/">KW4NZ\Component\Depot</namespace>
+	<install> <!-- Runs on install -->
+		<sql>
+			<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
+		</sql>
+	</install>
+	<uninstall> <!-- Runs on uninstall -->
+		<sql>
+			<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
+		</sql>
+	</uninstall>
+	<update>
+		<schemas>
+			<schemapath type="mysql">sql/updates/mysql</schemapath>
+		</schemas>
+	</update>
 	<files folder="site/">
 		<file>CODING_STANDARDS.md</file>
 		<file>LICENSE.md</file>
@ -20,9 +35,24 @@
 			Note that all & must be escaped to &amp; for the file to be valid
 			XML and be parsed by the installer
 		-->
-		<menu>COM_DEPOT_MENU</menu>
+		<menu img="class:barcode">COM_DEPOT_MENU</menu>
 		<submenu>
-			<menu link="option=com_depot">COM_DEPOT_MENU</menu>
+			<menu
+				link="option=com_depot"
+				view="parts"
+				img="class:depot"
+				alt="Depot/Parts"
+				>
+				COM_DEPOT_MENU
+			</menu>
+			<menu
+				link="option=com_depot"
+				view="stocks"
+				img="class:depot-stocks"
+				alt="Depot/Stocks"
+				>
+				COM_DEPOT_STOCK_MENU
+			</menu>
 		</submenu>
 		<files folder="admin">
 			<folder>services</folder>
@ -35,14 +65,4 @@
 			<language tag="en-GB">en-GB/com_depot.sys.ini</language>
 		</languages>
 	</administration>
-	<install> <!-- Runs on install -->
-		<sql>
-			<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
-		</sql>
-	</install>
-	<uninstall> <!-- Runs on uninstall -->
-		<sql>
-			<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
-		</sql>
-	</uninstall>
 </extension>