Nate Lewis


FWS::V2::Database - Framework Sites version 2 data management


Version 1.13091122


    use FWS::V2;

    # Create FWS with MySQL connectivity
    my $fws = FWS::V2->new(
                DBName      => 'theDBName',
                DBUser      => 'myUser',
                DBPassword  => 'myPass'

    # create FWS with SQLite connectivity
    my $fws2 = FWS::V2->new(
                DBType      => 'SQLite',
                DBName      => '/home/user/your.db'


Framework Sites version 2 common methods that connect, read, write, reorder or alter the database itself.



In FWS database tables there is a field named extra_value. This field holds a hash that is to be appended to the return hash of the record it belongs to.

    # If we have an extra_value field and a real hash lets combine them together
    %dataHash = $fws->mergeExtra( $extra_value, %dataHash );

Note: If anything but stored extra_value strings are passed, the method will throw an error


Return an array of the admin users. The hash array will contain name, userId, and guid.

    # get a reference to the hash array
    my $adminUserArray = $fws->adminUserArray( ref => 1 );


Return an array of the admin users. The hash array will contain name, userId, and guid.

    # get a reference to the hash
    my $dataHashRef = $fws->adminUserHash( guid => 'someGUIDOfAnAdminUser', ref => 1 );


It is not recommended you would use the alterTable method outside of its intended core database creation and maintenance routines but is here for completeness. Some of the internal table definitions alter data based on its context and will be unpredictable. For work with table structures not directly tied to the FWS 2 core schema, use FWS::Lite in a non web rendered script.

    # retrieve a reference to an array of data we asked for
    # Note: It is not recommended to change the data structure of
    # FWS default tables
    print $fws->alterTable(
        table   => 'table_name', # case sensitive table name
        field   => 'field_name', # case sensitive field name
        type    => 'char(255)',  # Any standard cross platform type
        key     => '',           # MUL, PRIMARY KEY, FULL TEXT
        default => '',           # '0000-00-00', 1, 'default value'...


Return a hash array of make, model, and year from the default automotive tables if they are installed.

    # get a list of autos make model and year based on year
    my @autoArray = $fws->autoArray( year => '1994' );
    for my $i (0 .. $#autoArray) {
        print $autoArray[$i]{make} . "\t" . $autoArray[$i]{model} . "\n";


Do the initial database connection via MySQL or SQLite. This method will return back the DBH it creates, but it is only here for completeness and would normally never be used. For FWS database routines this is not required as it will be implied when executing those methods.


If you want to pass DBType, DBName, DBHost, DBUser, and DBPassword as a hash, the global FWS DBH will not be passed, and the DBH it creates will be returned from the method.

The first time this is ran, it will cache the DBH and not ask for another. If you are running multipule data sources you will need to add noCache=>1. This will not cache the DBH, nor use the the cached DBH used as the default return.


Make a copy of data hash giving it a unique guid, and appending (Copy) text to name and title if you pass the extra key of addTail.

    # duplicate a data record
    my %newHash = $fws->copyData( %dataHash );

    # do the same thing but add (Copy) to the end of the name and title
    my %copyHash = $fws->copyData( addTail => 1, %dataHash );


Change the email of a user throught the system.

    my $failMessage = $fws->changeUserEmail( '', '' );

Fail message will be blank if it worked.


Retrieve a hash array based on any combination of keywords, type, guid, or tags

    my @dataArray = $fws->dataArray( guid => $someParentGUID );
    for my $i ( 0 .. $#dataArray ) {
         $valueHash{html} .= $dataArray[$i]{name} . "<br/>";

Any combination of the following parameters will restrict the results. At least one is required.

  • guid: Retrieve any element whose parent element is the guid

  • keywords: A space delimited list of keywords to search for

  • tags: A comma delimited list of element tags to search for

  • type: Match any element which this exact type

  • containerId: Pull the data from the data container

  • childGUID: Retrieve any element whose child element is the guid (This option can not be used with keywords attribute)

  • showAll: Show active and inactive records. By default only active records will show

Note: guid and containerId cannot be used at the same time, as they both specify the parent your pulling the array from


Retrieve a hash or hash reference for a data matching the passed guid. This can only be used after setSiteValues() because it required $fws->{siteGUID} to be defined.

    # get the hash itself
    my %dataHash     = $fws->dataHash( guid => 'someguidsomeguidsomeguid' );

    # get a reference to the hash
    my $dataHashRef = $fws->dataHash( guid => 'someguidsomeguidsomeguid', ref => 1 );


Delete something from the data table. %dataHash must contain guid and either containerId or parent. By passing noOrphanDelete with a value of 1, any data orphaned from the act of this delete will also be deleted.

    my %dataHash;
    $dataHash{noOrphanDelete} = '0';
    $dataHash{guid}           = 'someguid123123123';
    $dataHash{parent}         = 'someparentguid';
    my %dataHash $fws->deleteData( %dataHash );


Remove a hash based on its guid from FWS hash object.


Delete a user by passing the guid in as a hash key


Delete from the message and process queue

    my %queueHash;
    $queueHash{guid} = 'someQueueGUID';
    my %queueHash $fws->deleteQueue( %queueHash );


Return the elements from the database. This will not pull elements from plugins!


Return the hash for an element from cache, plugin for element database


Return a hash array in a csv format.

    my $csv = $fws->exportCSV( dataArray => [@someArray] );


Delete all cached data and rebuild it from scratch. Will return the number of records it optimized. If no siteGUID was passed then the one from the current site being rendered is used

    print $fws->flushSearchCache( $fws->{siteGUID} );

This also will set the parent id of the data record if it is not already set


Get the site GUID for a site by passing the SID of that site. If the SID does not exist it will return an empty string.

    print $fws->getSiteGUID( 'somesite' );

NOTE: This should not be used and will eventually be pulled in as a FWS internal method only, but is available for legacy reasons.


Return a FWS Hash in its array format.


Do a new database check and then create the base records for a new install of FWS if the database doesn't have an admin record. The return is the HTML that would render for a browser to let them know what just happened.

This will auto trigger a flag to only it allow it to execute once so it doesn't recurse itself.


Return a hash array of the current items in the processing queue.


Return a hash or reference to the a queue hash.


Return a hash array of the history items from the processing queue.

Parmeters to constrain data:

  • limit

    Maximum number of records to return.

  • email

    Only items that were sent to or from an email account specified.

  • synced

    Only items that match the sync flaged that is passed. [0|1]

  • userGUID

    Only items created from this user.

  • directoryGUID

    Only items referencing this directory record.


Return a hash or reference to the a queue history hash. History hashes will be referenced by passing a guid key or if present a queueGUID key from the derived queue record it was created from.


Process the internal sending queue

    # process the internal queue


Return an reference to an array that contains the results of the SQL ran. In addition if you pass noUpdate => 1 the method will not run updateDatabase on errors. This is important if you doing something that could create a recursion problem.

    # retrieve a reference to an array of data we asked for
    my $dataArray = $fws->runSQL( SQL => "select id,type from id_and_type_table" );     # Any SQL statement or query

    # loop though the array
    while ( @$dataArray ) {

        # collect the data each row at a time
        my $id      = shift @{$dataArray};
        my $type    = shift @{$dataArray};

        # display or do something with the data
        print "ID: " . $id . " - " . $type . "\n";


Update or create a new data record. If guid is not provided then a new record will be created. If you pass "newGUID" as a parameter for a new record, the new guid will not be auto generated, newGUID will be used.

    %dataHash = $fws->saveData( %dataHash );

Required hash keys if the data is new:

  • parent: This is the reference to where the data belongs

  • name: This is the reference id for the record

  • type: A valid element type

Not required hash keys:

  • $active: 0 or 1. Default is 0 if not specified

  • newGUID: If this is a new record, use this guid (Note: There is no internal checking to make sure this is unique)

  • lang: Two letter language definition. (Not needed for most multi-lingual sites, only if the code has a requirement that it is splitting language based on other criteria in the control)

  • ... Any other extended data fields you want to save with the data element

Example of adding a data record

    my %paramHash;
    $paramHash{parent}         = $fws->formValue( 'guid' );
    $paramHash{active}         = 1;
    $paramHash{name}           = $fws->formValue( 'name' );
    $paramHash{title}          = $fws->formValue( 'title' );
    $paramHash{type}           = 'site_myElement';
    $paramHash{color}          = 'red';

    %paramHash = $fws->saveData(%paramHash);

Example of adding the same data record to a "data container"

    my %paramHash;
    $paramHash{containerId}    = 'thisReference';
    $paramHash{active}         = 1;
    $paramHash{name}           = $fws->formValue( 'name' );
    $paramHash{type}           = 'site_thisType';
    $paramHash{title}          = $fws->formValue( 'title' );
    $paramHash{color}          = 'red';

    %paramHash = $fws->saveData(%paramHash);

Note: If the containerId does not match or exist, then one will be created in the root of your site, and the data will be added to the new one.

Example of updating a data record:

    $guid = 'someGUIDaaaaabbbbccccc';
    # get the original hash
    my %dataHash = $fws->dataHash(guid=>$guid);
    # make some changes
    $dataHash{name}     = "New Reference Name";
    $dataHash{color}    = "blue";
    # Give the altered hash to the update procedure
    $fws->saveData( %dataHash );


Save data that is part of the extra hash for a FWS table.

        table       => 'table_name',
        siteGUID    => 'site_guid_not_required',
        guid        => 'some_guid',
        field       => 'table_field',
        value       => 'the value we are setting it to'


Save a generic hash to a hash object in the same fasion as other FWS save objects. If the object exists already it will udpate it, or add a new one if it did not exist

    # add a new object
    $someHash{someArray} = $fws->saveHash( hashArray  => $someHash{someArray},
                                           date       => $fws->dateTime( format => 'SQL' ),

    # update a object that contains its perspective guid
    $someHash{someArray} = $fws->saveHash( hashArray  => $someHash{someArray}, %existingDataThatIsUpdated );


Save a hash to the process and message queue.

    %queueHash = $fws->saveQueue( %queueHash );


Save a hash to the process and message queue history.

    %queueHash = $fws->saveQueueHistory( %queueHash );


Save a user and return its hash.

    %userHash = $fws->saveUser( %userHash );


Return the schema hash for an element. You can pass either the guid or the element type.

    my %schemaHash = $fws->schemaHash( 'someGUIDorType' );


Set a sites cache index for its site. you can bas a siteGUID as a hash parameter if you wish to update the index for a site not currently being rendered.



Return a sorted array reference by passing the array reference, what key to sort by, and numrical or alpha sort.

    # type: alpha|number
    # key: the key you are sorting by
    # array: an array reference
    my $arrayRef = $fws->sortArray( key => 'id', type => 'alpha', array => \@someArray );


Return a multi-dimensional hash of all the fields in a table with its properties. This usually isn't used by anything but internal table alteration methods, but it could be useful if you are making conditionals to determine the data structure before adding or changing data. The method is CPU intensive so it should only be used when performance is not a requirement.

    $tableFieldHashRef = $fws->tableFieldHash( 'the_table' );

The return dump will have the following structure:


If the field is indexed it will return a unique table field combination key equal to MUL or FULLTEXT:



Return a hash array of all the templates available.


Return a hash of all the information about a template.


Update the cache version of the data record. This is called automatically when saveData is called.



Return an array or reference to an array of the users on an installation. You can pass the keywords parameter and it will look though name and email address.


Return the hash for a user.

    %userHash = $fws->userHash( guid => 'guid' );


Return the hash for a user group by passing the groups guid.

    %userGroupHash = $fws->userGroupHash('somegroupguid');


Return the hash array for all of the user groups;

    my @userGroupArray = $fws->userGroupArray();


Alter the database to match the schema for FWS 2. The return will print the SQL statements used to adjust the tables.

    print $fws->updateDatabase()."\n";

This method is automatically called when on the web optimized version of FWS when rendering the 'System' screen. This will also auto trigger a flag to only it allow it to execute once so it doesn't recurse itself.


Update the modified date of the page a dataHash element resides on.


Note: By updating anything that is persistant against multiple pages all pages will have thier date updated as it is considered a site wide change.


Return the guid for the home page. Without any paramanters it will return the home page guid for the current site.


need doc


need doc


need doc


Nate Lewis, <nlewis at>


Please report any bugs or feature requests to bug-fws-v2 at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc FWS::V2::Database

You can also look for information at:



Copyright 2013 Nate Lewis.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.