blog documentation FAQ followers forum marketplace services youtube

datastores

The Jamroom Network » Documentation » Module Developer Guide » datastores

Table of Contents:


Overview
Key:Value pairs
Writing SQL for a datastore item
schema.php
non-datastore tables
example

  • Overview

    A datastore is a special storage unit that each module has the option of having.

    It has the advantage of being structureless in that you don't need to define how the data is stored before storing it.

    With each module using a datastore for the main information it uses, this gives the entire system much more flexibility for data exchange.

    An example of a data store in use is "Audio file information stored in the jrAudio modules datastore."

  • Key:Value pairs

    The data in a datastore is stored in Key:Value in a simlar way to how an associative array stores its data
    "audio_title":"we all live in a yellow submarine"
    "audio_xxxxxx":"xxxxxxxxxxx"

    Since data is stored in this structure, as many key:value pairs as are needed can be used.

    Functionally this mean that the jrAudio can add in all the "audio_xxx":"xxxx" items it needs, and the another module can also add in extra values. eg: the jrTags module adds in some extra tags to the audio modules item for it "audio_tags":"funky,hip,happy,fast"

  • Writing SQL for a datastore item

    You don't.

    If you want to access a datastore item, you do not write SQL for it in the same way you would for a standard table.

    All datastore item data will be accessed via built in functions:

    functions to create/update/delete
    jrCore_db_create_item() //create
    jrCore_db_update_item() //update
    jrCore_db_delete_item() //delete

    are the main 3. You pass in an array and the database updating is done for you. There are a couple of other ones too for doing batch processing. Take a look in the code and the code docblock's to see the additional functions.

    functions to get/search
    jrCore_db_get_item() //create
    jrCore_db_search_items() //update

    The docblocks in the code for these are really well documented so if your using a modern IDE (like phpStorm ) you will see all the available comments and alternatives in the auto-completion and hinting.



  • Each module only gets 1 datastore. One datastore per module.

  • schema.php

    If you need additional normal tables you can use the standard MySQL database tables by defining them in addition to your datastore in your modules schema.php file.

    To construct a datastore for your module, put this code in your schema.php file:

    function xxYourModule_db_schema()
{
    jrCore_db_create_datastore('xxYourModule', 'yourmodule');
    return true;
}

  • non-datastore tables

    If you want additional normal tables, you can add them in your schema.php file too.

    Here is an example from the jrBanned module that blocks users who are un-wanted.

    The jrBanned module does not use a datastore, but could if it wanted by defining that as well. 
    /**
 * db_schema
 */
function jrBanned_db_schema()
{
    // Banned Item

    $_tmp = array(
        "ban_id INT(10) UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY",
        "ban_updated INT(10) UNSIGNED NOT NULL DEFAULT '0'",
        "ban_type VARCHAR(32) NOT NULL DEFAULT ''",
        "ban_value VARCHAR(128) NOT NULL DEFAULT ''",
        "UNIQUE ban_key (ban_type,ban_value)"
    );
    jrCore_db_verify_table('jrBanned','banned',$_tmp,'MyISAM');
}

  • example

    a usage example 
    // an example of how to put something into a datastore:

// our schema.php file contains jrCore_db_create_datastore('xxFoo', 'foo');

// so our array prefix is 'foo'

$_sv = array(
    'foo_title'    => "The title of this item",
    'foo_category' => "An item thats called category",
    'foo_elephant' => "some other value you want stored",
);

// We want to save it to our datastore

$id = jrCore_db_create_item('xxFoo', $_sv);

// in $id is the item_id of the item that was just created.


// so to retreive that info you can use the item_id and

$_temp = jrCore_db_get_item('xxFoo', $id);

// now $_temp should contain the same info as $_sv plus the _user_id,

// _profile_id and any info any other modules may have added.


// to add some more stuff to the item

$_more = array(
    'foo_color'  => "red",
    'foo_flavor' => "strawberry",
    'foo_heat'   => "warm",
);

jrCore_db_update_item('xxFoo', $id, $_more);

// the $more array will be added to item and if the key exists that item will be updated.

Tags