Creating New Tables and GalleryStorage

Hello, I'm a little confused with how to create new tables in the database.

I am coding a custom module and would like to have a table where some related data would be stored.

I've studied other modules and would like to use comment module for asking some questions.

I've seen this directory for comment:

modules/comment/classes/GalleryStorage

There are other directories inside: DatabaseStorage, schema, platform, xml-src and some .sql files for different DBMS.

The file corresponding to MySQL have some kind of pseudo SQL like this:

    -- This file was automatically generated from an XSL template, which is
    -- why it looks so ugly.  Editing it by hand would be a bad idea.
    --

    CREATE TABLE DB_TABLE_PREFIXComment (
  DB_COLUMN_PREFIXid
      int(11)
    
    NOT NULL
  
      ,
    DB_COLUMN_PREFIXcommenterId
      int(11)
    
    NOT NULL
  
      ,
    DB_COLUMN_PREFIXhost
      varchar(
      
          128
        
      )
    
    NOT NULL
  
      ,
    DB_COLUMN_PREFIXsubject
      varchar(
      
          128
        
      )
    
      ,
    DB_COLUMN_PREFIXcomment
      text
    
      ,
    DB_COLUMN_PREFIXdate
      int(11)
    
    NOT NULL
  
    , 
  
      PRIMARY KEY (DB_COLUMN_PREFIXid)
    
    , 
  
    INDEX (DB_COLUMN_PREFIXdate)
    

    ) TYPE=DB_TABLE_TYPE;

    INSERT INTO DB_TABLE_PREFIXSchema (
      DB_COLUMN_PREFIXname,
      DB_COLUMN_PREFIXmajor,
      DB_COLUMN_PREFIXminor
      ) VALUES (
      'Comment',
      1,
      0
      );

Is it needed that I use something like this if I want to create my own MySQL tables for my custom modules?, if so I would like to know how to create these files (or where to read more to understand what you are doing here, and why ).

Another doubt I have is how the actual database operations are called from a module, insert.update, delete, select. I see there is a class GalleryStorage but in all the comment module code I just see one reference to a $storage object in GalleryCommentSearch.class:

$storage =& $gallery->getStorage();

which I see it's using a method from Gallery.class which actually creates a GalleryStorage object:

    function &getStorage() {
	if (!isset($this->_storage)) {
	    GalleryCoreApi::relativeRequireOnce('modules/core/classes/GalleryStorage.class');
	    GalleryCoreApi::relativeRequireOnce('modules/core/classes/GallerySearchResults.class');
	    $this->_storage = new GalleryStorage();
	}

	return $this->_storage;
    }

I think I'm almost there but I need to "connect the dots" to completely understand the logic of the application, any directions you could give me will be greatly appreciated.

Regards!

Alexis Bellido - Ventanazul web solutions

Wow, thanks Valiant, that needed to be said , I will continue my work with G2.1 and keep learning so I can help later with the documentation project.

Regards.

Alexis Bellido - Ventanazul web solutions

- Insert:
maps: use GalleryCoreApi::addMapEntry() to insert 1 or more rows
entities: use GalleryCoreApi::newFactoryInstance and similar methods to get an instance, then call $entity->create(); set a few attributes with $entity->setColor('red'); or something like that and finally call $entitiy->save();
- Update:
maps: use GalleryCoreApi::updateMapEntry()
entities: $entity->save();
- Delete:
maps: GalleryCoreApi::removeMapEntry() or GalleryCoreApi::removeAllMapEntries();
entities: GalleryCoreApi::deleteEntityById() or $entity->delete();
- Select / free form queries:
entities: GalleryCoreApi::loadEntitiesById() or free form sql to get ids and then load with loadEntitiesById()
maps: $gallery->search($query, $data, $options); always use ? as a placeholder for actual values and all values should go into $data. the query language is a DMBS-independent, abstracted SQL
e.g. SELECT g_id, g_title FROM g2_Item WHERE g_summary = 'at the beach'; should be
$query = 'SELECT [GalleryItem::id], [GalleryItem::title] FROM [GalleryItem] WHERE [GalleryItem::summary] = ?';
$data = array('at the beach');
list ($ret , $results) = $gallery->search($query, $data);
reasons:
- by "binding" parameters in the db abstraction layer we make sure there are no db injections vulnerabilities in G2
- by using [GalleryItem] and [GalleryItem::id] instead of the actual database table / column names we can add the table / column prefix independently and we could do other parsing
- if you need things as string concatenation or other DBMS specific SQL, use $storage->getFunctionSql()

hint:
if you need to use $gallery->search(), make sure your parameter values in $data are all correctly typed. they need to match the db column type. e.g. (int) for integer columns and (stirng) for varchar / text columns.

new entity.. after create() you still need to do save()

So now with gallery 2.1 I don't need to run gmake or have any GNUmakefiles to generate the required tables and inc files to accompany my class files?

This is all done automagically now?, and if I add

$storage =& $gallery->getStorage();
$ret = $storage->configureStore($this->getId(), array('MyModuleItem:1.0'));

to the upgrade portion in my module.inc, these will get rebuilt everytime i increment my version numbers in module.inc?

is there somewhere I can get the makefiles needed to create my module, I had some from version 2.0 when i first built my module but they seem to be corrupt now(they access stuff that doesn't exist and fail).

Damn, looks like I need to do quite a bit to make my module compatible with the latest version of gallery, is it just me or do I need to replace all my get and set functions with direct access to the data members?

	//set
	$this->setOffset($offsetVal);
	//get
	offsetVal = $this->getOffset();

would be come

	//set
	$this->Offset = $offsetVal;
	//get
	offsetVal = $this->Offset;

-- or --

	//set
	$this['Offset'] = $offsetVal;
	//get
	offsetVal = $this['Offset'];

and maybe the save function (or something else) will update this in the database?

that's right, you need to add the get/set functions in the entity class. save() will save those changes, assuming a 'make' has been run to generate Entities.inc
if you still have trouble, perhaps post your code..

yes, add the get/set functions in the entity .class file yourself. then do $entity->setFieldname('value'); and $entity->save(); just like in 2.0.x
no, you don't need to include Entities.inc yourself, nor should you edit it. the @g2 markers in your entity .class file are all you need.

You never make Maps.inc or Entities.inc, these are generated by the makefiles.

If you want to make a new entity type (has a php class, with get/set methods and a save() function) then define the class and use @g2 comments to define the db structure. Otherwise use Maps.xml to define a table that you can use for anything you like.. there are get/add/update/removeMapEntry functions in GalleryCoreApi. you can also use $gallery->search for more complex queries of your table (with joins, etc).

http://codex.gallery2.org/index.php/Gallery2:Module_Development_Tutorial#Working_With_the_Database

sometimes you must use an entity, for example to make a new type of item stored in the gallery.. this will need to extend GalleryItem. other times both might work.. comments module uses an entity as a child of items (conveniently they are deleted when the item is deleted), but a map probably could have worked too.

I am making a little headway, trying to wrap my head around how Gallery works. I'm not sure if there is something I need to register or if I have to have a helper class between my get and set statements and the .inc file. How do I use the get and set functions with this, I guess is the question.