286 lines
10 KiB
Markdown
286 lines
10 KiB
Markdown
# Depot
|
|
|
|
## Introduction
|
|
|
|
This project is also based on the desperation to sort and find my electronic
|
|
components. Some integrated circuits (ICs) accumulated in various boxes and
|
|
the question of whether I own that or the other IC, had to be painstakingly
|
|
researched. Above all, there were at one time several places where components
|
|
were stored or partly kept at a plant.
|
|
The idea was born, but it took long time to implement it.
|
|
Klosterneuburg, October 2023 Thomas Kuschel KW4NZ.
|
|
|
|
## Workflow (since 0.0.1)
|
|
|
|
In git we start to make a new branch named b1_basic_backend, where we start
|
|
developing our project. The first run with simply renaming entries from a
|
|
copy of the component **com_banners** did not work as expected.
|
|
So let us start at the very beginning:
|
|
|
|
### Adding basic files for component (b1_basic_backend)
|
|
|
|
With the git branch **b1_basic_backend**
|
|
Add the following basic six files:
|
|
|
|
1. admin
|
|
|
|
- src/Extension/DepotComponent.php: The main extension file for the component.
|
|
- services/provider.php: It tells Joomla how to initialize or boot the component.
|
|
- src/Controller/DisplayController.php: The default Controller for the component.
|
|
- src/View/Parts/HtmlView.php: The Html View for the "Parts" page.
|
|
- tmpl/parts/default.php: The layout file for the "Parts" page.
|
|
|
|
2. depot.xml: XML manifest file that tells Joomla! how to install the component.
|
|
|
|
#### Description of each file:
|
|
|
|
##### 1. DepotComponent.php
|
|
This file contains class for the extension. The class extends MVCComponent.
|
|
|
|
##### 2. provider.php
|
|
This is a special file that tells Joomla how to initialize the component - which
|
|
services it requires and how they should be provided.
|
|
|
|
The service provider file registers dependencies the component will use.
|
|
Here, we have included two dependencies:
|
|
|
|
- **DispatcherFactory** is needed to create the Dispatcher class instance,
|
|
and then Joomla will call dispatch() on this Dispatcher object, as the
|
|
next step in running the component.
|
|
|
|
- **MVCFactory** is needed to create the Controller, View, Model and Table class
|
|
instances on behalf of the component.
|
|
|
|
|
|
##### 3. DisplayController.php
|
|
This is a **default controller** for the component. It simply sets its default
|
|
view and leaves the rest to its parent.
|
|
|
|
When you view the component through URL, Joomla uses the **controller** to execute
|
|
the **task**. The task is the name of method in the controller file.
|
|
If you do not pass the controller or task in the URL, it defaults to Display
|
|
Controller and display Task.
|
|
|
|
The default view is the name of the component. So, here we need to override the
|
|
default view to `parts`.
|
|
|
|
##### 4. HtmlView.php
|
|
This file contains class HtmlView that extends BaseHtmlView. The BaseHtmlView is
|
|
the base class for a Joomla View.
|
|
|
|
The **view gets the data from the model to be output by the layout file.**
|
|
|
|
For example:
|
|
```php
|
|
$this->msg = $this->get('Msg');
|
|
```
|
|
|
|
This method converts the get('Msg') call into a getMsg() call on the model, which
|
|
is the method which you have to provide in the model.
|
|
|
|
The view file displays data using the template layout file - $tpl, which defaults
|
|
to default.php.
|
|
|
|
##### 5. default.php
|
|
This file holds the template for the page. When no specific layout is
|
|
requested for a view, Joomla will load the template in the **default.php** file.
|
|
|
|
```php
|
|
<h2>Welcome to Depot Component!</h2>
|
|
```
|
|
|
|
##### 6. depot.xml
|
|
This file tells Joomla how to install the component and what file are included.
|
|
|
|
In the administration part, we include a link to the menu and include files
|
|
and folders (services, src, tmpl and so on) which are in the parent folder
|
|
admin of the component. While installing the component, these will get copied
|
|
to the Joomla administrator/components/com_depot.
|
|
|
|
#### Installation the component
|
|
Create a **.zip** file of the com_depot directory. Then inside the Joomla
|
|
Administration upload this .zip package.
|
|
|
|
Now you should see a new link "Depot" in the "Compnents" section of the menu.
|
|
If you click it, you should see the default "Depot" page.
|
|
|
|
#### Language files
|
|
We create two language files for the system and the component **Depot** at
|
|
the directory /admin/language/en-GB/ naming it
|
|
|
|
- com_depot.ini
|
|
- 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.
|
|
|
|
---
|