Gruntle Enterprise

To begin, you must create your module. You can do most of the work by hand, by copying the relevant files from other modules, or you can fire up the create module tool provided by gallery2, which generates the basic skeleton for a new module. Check it out:

php lib/tools/creator/create-module.php [module name]­

You must have a G2 developer package or install from svn/nightly snapshot to get lib/tools/creator.

More information about the structure of the module directory and the roles of each file can be found on the Gallery2 website.

The first thing you must determine about your data model is whether you should use the so called Maps or the Enties to manage the data. If you only want to store data that is independent of the rest of the database structure, that is, it has no relation to any other tables, then you should use the Entities model. If you need to link tables with foreign keys as you would using straight SQL, the you should use the Maps structure. That is my understanding, so correct me if i am wrong.

As I wanted to link the Items data model to a new data model that would store information about downloads, I opted for the Maps structure. After studying various Maps.xml files from the Ratings module, and the Gallery2 core, I came up with the following Map.xml structure:

<maps>
  <map>
    <map-name>DownloadsMap</map-name>
    <schema>
      <schema-major>1</schema-major>
      <schema-minor>0</schema-minor>
    </schema>
    <member>
      <member-name>downloadId</member-name>
      <member-type>INTEGER</member-type>
      <primary/>
    </member>
    <member>
      <member-name>itemId</member-name>
      <member-type>INTEGER</member-type>
      <indexed/>
      <required/>
    </member>
    <member>
      <member-name>parentId</member-name>
      <member-type>INTEGER</member-type>
      <indexed/>
      <required/>
    </member>
    <member>
      <member-name>downloadCount</member-name>
      <member-type>INTEGER</member-type>
    </member>
    <index>
      <member-name>downloadCount</member-name>
      <member-name>itemId</member-name>
      <member-name>parentId</member-name>
    </index>
  </map>
</maps>

Basically you have:

<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. 

The documentation for the XML structure of Maps files is more or less non-existent, so you have to study the examples and go from there. I accidentally included a "primary" element with an "indexed" element, and mysql told me how stupid I was to do so but accepted the structure nonetheless.

Once you have the XML file, you must build it using the GNU make files that were automatically generated when you created your module or copied everything from an exisiting module:

cd modules/[modulename]/classes/ && make && make install

This will generate the Maps.inc file in classes and the schema.tpl file in the GalleryStorage sub-directory of classes, the later of which contains the raw SQL that Gallery2 will use to create the tables when you activate your module in the Site Admin area. If you are making changes to an exisiting module, you must change the version number in models.inc and update the module in the Site Admin section for the database changes to take affect.

In terms of setup, that is pretty much all you need to do. In the next installment, I will provide concrete examples on how to manage your data by outlining the customisations I made to the statistics module.

0 Comments, 0 trackbacks (Trackback URL)