Welcome to my second Gallery2 Module Development tutorial. This time i will talk with you about using the database (maps) in g2. I know I'll skip quite an amount of basics with this tutorial, but don't worry.. I will write the other basic tutorials soon enough.

The reason why I'm writing this tutorial is simply because there are much questions about working with the database in g2.

While making this tutorial i will talk about creating tables. I will talk about the rest in another tutorial, this tutorial alone is already quite some text.

Before I will start with explaining how to make a database, there is something you really should know. There are 2 ways of making a database. First, the a bit more difficult but good way. Second, the easy but wrong way.

The good way: Make!
The right way is by using a file called gnumakefile to make the DB files. You need to make a .xml file where you tell the gnumakefile file what fields you want in your table. When you've made the xml file, you need to run "make" or "gmake" in the folder where gnumakefile is located. (there are some needed details about this, i will write about that in a minute) Then gnumakefile is called by make (or gmake), and two files are made. An .INC file, and a .TPL file. (which will be located in a new folder that's also newly made)

The filename of the .inc file depends about the type of storage you are using, a map or an entity. You can read what the difference is in my first tutorial. (Click) When you want a map type of table, the file will be called Maps.inc. (notice the capital M) And an entity type of table will be named Entities.inc. (again with the capital E)

The .tpl file will be stored in a new folder called GalleryStorage. The tpl itself is called schema.tpl.

When you activate a new module, g2 will search the schema.tpl file, and reads the data in the file.. Followed by creating a brand new custom table!

So, lets stop our little chit chat and make ourself a custom table!

I will talk about making a Map type table in this tutorial, making a entity shouldn't be much different.

The files for the database are stored in a new folder. So go over to your module folder, and create a new folder called classes. (ex. /modules/mymodule/classes) Then make a new .xml file called Maps.xml.

The xml file look a bit like this:

php

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

<!DOCTYPE maps SYSTEM "../../../lib/tools/dtd/MapsDefinition2.0.dtd"> <maps> <map> <map-name>ModuleNameMap</map-name> <schema> <schema-major>1</schema-major> <schema-minor>0</schema-minor> </schema> <member> <member-name>itemId</member-name> <member-type>INTEGER</member-type> <primary/> </member> <member> <member-name>stringStorage</member-name> <member-type>STRING</member-type> <member-size>MEDIUM</member-size> <required/> </member> </map> </maps>

I think this would make sense right?

- <map-name>ModuleNameMap</map-name> Defines your table name.
- <member>...</member> Defines a new field.
- <member-name>itemId</member-name> Defines a field name.
- <member-type>INTEGER</member-type> Defines the type of field.
- <member-size>MEDIUM</member-size> Defines the size of the field.


Save the file, and run gnumakefile in the /modules/mymodule/classes folder. You can get gnumakefile from from the /modules/comment/classes module. Or download it from Combined-Minds.net. (the version that came with 2.1 development edition.. if this version doesn't work with the current version of g2, please reply to this tutorial)

If this worked, upload the new files to your server and install/activate the module. And the database is build.

Ah, and now some of you got a problem right? Your using Windows and don't have make or gmake? Well there are some things you can do..

- Download cygwin, a linux emulator to still be able to use linux stuff on windows
- Run the make file on the server by using SSH
- Being a bad boy and go over to the wrong side of this tutorial


You are still reading this tutorial? Ah, so you've chosen to do it the wrong way?

The bad way: Create the files yourself!
Today (22-feb-07) i had a kind of discussion with on of the main developers of the g2 project. We were talking about how creating a table in g2. I told him that i make tables by using the technique that i will explain in a few minutes. He actually became a bit irritated when i said i would write a tutorial, and talk about the wrong way of making a table.

The reason why this way is wrong, is because you don't know if the files you will create will work on all servers. And the way of making the files with the make file won't change, but the way i will talk about in a minute will probably change in a few g2 versions. (don't worry, i will update the tutorial)

So, only use the following way if the good way doesn't work.

The bad technique is writing the 2 files needed yourself. It's not difficult at all, so lets start at looking at an example.

Maps.inc

php
1 2 3 4 5 6 7 8 9 10 11 12	<?php $mapInfo['ModuleNameMap'] = array( 'itemId'=>array( 'type'=>STORAGE_TYPE_INTEGER, 'size'=>STORAGE_SIZE_MEDIUM, 'notNull'=>true), 'stringStorage'=>array( 'type'=>STORAGE_TYPE_STRING, 'size'=>STORAGE_SIZE_MEDIUM, 'notNull'=>true) ); ?>

This basically is the same as the Maps.xml shown before. But written on a different way.

schema.tpl (remember that this file should be located in a new folder named GalleryStorage)

php
1 2 3 4 5 6 7 8 9 10 11 12 13	## mysql # ModuleNameMap CREATE TABLE DB_TABLE_PREFIXModuleNameMap ( DB_COLUMN_PREFIXitemId int(11) NOT NULL, DB_COLUMN_PREFIX stringStorage varchar(128) NOT NULL ) TYPE=DB_TABLE_TYPE /*!40100 DEFAULT CHARACTER SET utf8 */;   INSERT INTO DB_TABLE_PREFIXSchema ( DB_COLUMN_PREFIXname, DB_COLUMN_PREFIXmajor, DB_COLUMN_PREFIXminor ) VALUES('PersoonNaamMap', 1, 0);

Again very simple, plain SQL. But notice DB_COLUMN_PREFIX. This is just a define that contains the prefix for the database. You are already working at a wrong way, so you can remove DB_COLUMN_PREFIX and add the prefix yourself if you want.

When you're done, save the files and upload it to your g2 installation. Install, or reactivate your module, and the table should be made!

Again please remember this way isn't like its meant. Always try to use the make file way!

When i will release part 2 of this tutorial i will talk about inserting, searching, deleting and updating.