Navigation

Building extensions
   - Introduction
  - Life cycle & Execution mode
  - Content Page Extension
  - Examples
  - Interact with extensions
  - Interact with SMMenu
  - Interact with SMPages
  - Debugging

Building design templates
   - Introduction
  - Place holders
  - Repeating blocks
  - Examples

Framework API
   - Introduction
  - Simple data attributes
  - Authentication
  - Configuration manager
  - Data Sources (DB)
  - Environment data
  - Extension base class
  - The extension context
  - The extension manager
  - Filesystem functions
  - The Form component
  - Image provider
  - Key Value Collections
  - Language handling
  - Logging and error handling
  - GUIDs & Random numbers
  - Various utilities
  - Send and receive data
  - Template engine
  - Text files
  - Strongly typed

GUI Controls
   - Introduction
  - Input types
  - Option list
  - Link button
  - Tree menu
  - Grid view
  - Fieldset (sub form)
  - JavaScript library

Receiving payments
   - Introduction
  - PayPal and Ewire

More help
   - Forum

Data sources

Sitemagic CMS supports two diffent types of data storage; XML files and the MySQL database server. Since an XML file does not qualify as a real DataBase Management System like MySQL, we use the general term Data Source.

The free version of Sitemagic CMS comes with the data source layer for XML files. The Enterprise version comes with a data source layer for the MySQL database, that replaces the XML data source layer. If you are a developer, you may request a free version of the Enterprise version by contacting us.

It is recommended to use the data source layers to perform data manipulation, since the code will support both the free version of Sitemagic CMS, which uses XML files, and the Enterprise version using the MySQL database. The following examples demonstrates how easy it is, to perform basic operations such as inserting data, selecting data, updating data and remove data.

$ds = new SMDataSource("Persons");
$data = null;

// Insert data (add Casper)

$data = new SMKeyValueCollection();
$data["name"] = "Casper";
$data["age"] = "29";
$data["sex"] = "Male";

$ds->Insert($data);

// Select data (* = get data from all columns)

$persons = $ds->Select("*");

foreach ($persons as $person)
    echo $person["name"] . " is " . $person["age"] . " years old";

// Update data (change age for Casper)

$data = new SMKeyValueCollection();
$data["age"] = "30";

$ds->Update($data, "name = 'Casper'");

// Delete data (remove all males)

$ds->Delete("sex = 'Male'");
The examples above will work out-of-the-box on a Sitemagic CMS installation using the XML based data source layer. A table must be created on the MySQL database server when using the MySQL data source layer. The following snippet is the table definition for the Persons table used in the example above.

CREATE TABLE IF NOT EXISTS Persons
(
    `name`            varchar(250)            DEFAULT NULL,
    `age`               integer                    DEFAULT NULL,
    `sex`               varchar(6)                DEFAULT NULL
) ENGINE = InnoDB CHARACTER SET latin1 COLLATE latin1_swedish_ci;
All fields must default to NULL, to be compatible with the XML based data source, which returns NULL, when trying to access a field that is not defined. The engine used must be InnoDB, since all database operations are transaction based (more details on this later). Furthermore an ISO-8859-1 (latin1) compatible encoding must be used.


Consistency

Using the data source layers will automatically ensure data consistency. The system goes from one consistent state to another. If an extension should fail, all changes to the data sources are rolled back, unless a manual commit has been performed (see description of Commit function in class definition further down this page).


Limitations

The data source layers are intended for simple data processing (select, insert, update, delete). If more advanced features are required, such as joins, the build-in MySQL API might be a better choice.



SMDataSource class

Function
 Return type
 Description
__construct($source:string)
Create instance of a data source.
Select()
 SMKeyValueCollection[]
 Select all records with all fields/columns from data source.
Select($select:string) SMKeyValueCollection[] Select all records with the specified list of fields/columns (ie "*" or "field1, field2, field3").
Select($select:string, $where:string) SMKeyValueCollection[] See description for Select($select:string). Specify condition(s) that must be met for records to be included (ie "field1 = 12 AND field2 = 'Casper' OR field2 = 'Michael').
Valid operators: = | != | < | > | <= | >= | IS NULL | IS NOT NULL | LIKE | NOT LIKE
Select($select:string, $where:string, $orderby:string) SMKeyValueCollection[] See description for Select($select:string, $where:string). Specify field(s) by which records are ordered (ie "field1, field2").
Select($select:string, $where:string, $orderby:string, $limit:integer) SMKeyValueCollection[] See description for Select($select:string, $where:string, $orderby:string). Specify a maximum number of records included.
Select($select:string, $where:string, $orderby:string, $limit:integer, $offset:integer) SMKeyValueCollection[] See description for Select($select:string, $where:string, $orderby:string, $limit:integer). Specify an offset from where records are included.
Count()
 Integer
 Count all records in data source
Count($where:string)
 Integer
 Count all records matching specified WHERE statement. See description for Select($select:string, $where:string) for valid operators.
Count($where:string, $limit:integer) Integer See description for Count($where:string). Specify a maximum of records included in count.
Count($where:string, $limit:integer, $offset:integer) Integer See description for Count($where:string, $limit:integer). Specify an offset from where records are included.
Insert($data:SMKeyValueCollection)   Insert new record into data source.
Update($data:SMKeyValueCollection) Integer Update fields in SMKeyValueCollection for all records in data source. The number of updated records is returned.
Update($data:SMKeyValueCollection, $where:string) Integer See description for Update($data:SMKeyValueCollection). Only update records matching the specified WHERE condition. See description for Select($select:string, $where:string) for valid operators.
Update($data:SMKeyValueCollection, $where:string, $orderby:string) Integer See description for Update($data:SMKeyValueCollection, $where:string). Update records in the specified order. This is usually used in conjunction with a limit - see Update($data:SMKeyValueCollection, $where:string $orderby:string, $limit:integer).
Update($data:SMKeyValueCollection, $where:string, $orderby:string, $limit:integer) Integer See description for Update($data:SMKeyValueCollection, $where:string $orderby:string). Specify a limit for number of records to be updated.
Update($data:SMKeyValueCollection, $where:string, $orderby:string, $limit:integer, $offset:integer) Integer
 See description for Update($data:SMKeyValueCollection, $where:string $orderby:string, $limit:integer). Specify an offset from where records are updated.
Delete()
 Integer
 Delete all records from data source. The number of deleted records is returned.
Delete($where:string) Integer
 See description for Delete(). Delete records matching the specified WHERE statement. See description for Select($select:string, $where:string) for valid operators.
Delete($where:string, $orderby:string) Integer
 See description for Delete($where:string). Delete records in the specified order. This is usually used in conjunction with a limit - see Delete($where:string $orderby:string, $limit:integer).
Delete($where:string, $orderby:string, $limit:integer) Integer See description for Delete($where:string, $orderby:string). Specify a limit for number of records to be deleted.
Delete($where:string, $orderby:string, $limit:integer, $offset:integer) Integer See description for Delete($where:string, $orderby:string, $limit:integer). Specify an offset from where records are removed.
Verify()   Returns True if data can safely be committed. This function was introduced to work around a bug in PHP allowing invalid characters to be written to the XML based Data Source, which corrupted the data.
Commit()   Commit data to data source - all changes are made permanenet. If Commit() is not invoked manually, the data source will be automatically committed between Unload and Finalize in the life cycle. It is recommended to let auto commit handle this, unless it is absolutely vital that the given data is not lost.
RollBack()   Cancel all changes made to the given data source. Have in mind that multiple extension may have made changes to the data source. These changes will be lost too.
Reload()   Discard all changes and reload data
Lock()
Lock entire data source so that only one session can change it. The locking is advisory, meaning that all accessing code must call this function to respect the lock. If the data source is already locked, the given session will wait for the lock to be released. This function should not be used lightly - it will have a negative impact on performance if not used correctly. Release the lock as soon as possible by invoking Commit() or Unlock(). Also notice that locking a data source will cause data to be re-loaded to ensure most recent changes.
SetUseCache($value:boolean)
Deprecated - see Reload()
Enable (default) or disable caching. Caching improves performance significantly, especially when using the XML based data source. Disabling the caching is primarily used when one wants to ensure the most recent data, for instance modifications from another session.
Notice that changes made to the data source will be lost, when caching is disabled. To avoid this, invoke Commit() before SetUseCache(false).
GetUseCache()
 Boolean
 Deprecated
Get a value indicating whether caching is enabled or not.
SetEscapeData($value)
Set value True to have data automatically escaped if required by data source. Automatic escaping is enabled by default. The escaping is only applied to data, not WHERE statements!
GetEscapeData()
 Boolean
 Get value indicating whether escaping is enabled or not.
Escape($value:string)
 String
 Returns escaped string. This is useful for escaping data, if automatic escaping of data has not been enabled - see SetEscapeData($value). Should be used for WHERE statements containing user input)
GetDataSourceType()
 SMDataSourceType
 Get data source type. Will return SMDataSourceType::$Xml if the XML based data source is being used, SMDataSourceType::$MySql if the MySQL based data source is being used.

Important note: The MySQL based Data Source does NOT support MySQL Safe Mode (mysql.safe_mode). Also the number of connection links cannot be limited (mysql.max_links)