Site:Integration

Revision as of 19:26, 9 June 2012

Integration

Integration into Metrixstream is necessary when developing features outside the core platform. This can be done through a GitHub.com account. Once you have your account setup and repository created, contact support@metrixstream.com, so that we can configure your license so it fetches resources from GitHub.com for your extensions.

Class Autoloader

Metristream uses a class autoloader to make integration easier. As long as you place your files in the right location, then your classes can be accessed from other classes without any file inclusion. This means that you should always be wrapping your code inside a class rather than using global functions.

Good

class InputHelper {
  public static function filterInteger($value) {
    return intval($value);
  }
}

Bad

function filterInteger($value) {
  return intval($value);
}

Code Location

/query/backend

This code location houses all of the BackendQueries. Each class in this location must be derived from the BackendQuery interface.

/query/api

This code location houses all of the ApiQueries. Each class in this location must be derived from the ApiQuery interface.

/output/backend

This code location houses all of the backend output factory classes. These output factory classes transform a Database object into a BackendOutput.

/tasks/background

This code location houses all of the BackgroundTasks. Each class in this location must be derived from the BackgroundTask.

/includes/db

This code location houses all of the database objects. A Database object is a PHP class that represents the appropriate database table.

/includes/misc

This code location is the catch-all for all classes that aren't big enough for their own directory. Helper classes typically reside here.

Backend Query

A BackendQuery are a major component of the site engine. You can create your own Backend Query by simply extending the BackendQuery interface.

ExampleQuery

Below is ExampleQuery, which simply is accepting a value via URL through the "hello" parameter. It then takes that parameter and sets it into it's HDF object.

class ExampleQuery extends BackendQuery {
  public function getInternalName() {
    return "example";
  }

  public function getDisplayName() {
    return "My Example Context";
  }

  public function isDependentOnScope($scopeKey) {
    return false;
  }

  public function getConsumableParams() {
    return Array("hello");
  }

  public function filterParam($paramName, $paramValue, $whitelist = Array()) {
    switch($paramName) {
      case "hello": return $paramValue;
    }
    return null;
  }

  public function isCacheable() {
    return true;
  }

  public function execute(BackendContext $Backend, ScopeContext &$Scope, BackendOutputFactory $OutputFactory) {
    $App =& $this->getApplicationContext();

    $params = Array(
      "hello" => $this->getParam($Page, "hello", "")
    );

    $Output =& $OutputFactory->create();
    $Output->set("hello", $params["hello"]);
    return $Output;
  }
}

Code Location

Each BackendQuery class must be placed within the query/backend folder. Each class file must also have the same name as the return value of the getInternalName() function along with a ".php" extension.

Make sure your class name ends with "Query" and that the beginning of your class name is the same as the result of getInternalName().

Here is a sample of this would look inside Github. https://github.com/metrixsean/Metrixstream-Sample-Integration/blob/master/query/backend/example.php

Page Integration

Once your new BackendQuery is checked into Github, you need to go to the Metrixstream Setup Panel, click on Shortcuts -> License Manager, and then click the "UPDATE GITHUB" button. This will cause all of your servers to get the latest updates from Github.

Now you can choose your new BackendQuery on a sitepage within the system.

Within your Site, choose "ADD PAGE". Give your page a name and then scroll down to the Backend Context section. Make sure to pick "My Example" and click the "SAVE" button.

Within your Site Page, you can now access the HDF key that you set in your context. This is as simple as the following:

Hello... my new context lets me reference the following key:

MS.hello = <?cs var:MS.hello ?>

ApiQuery

An ApiQuery is another major component of the site engine. ApiQueries generally go hand in hand with a BackendQuery. A BackendQuery lets us display information on a page and an ApiQuery lets us manipulate that information.

Code Location

Each ApiQuery class must be placed within the query/api folder. Each class file must also have the same name as the return value of the getInternalName() function along with a ".php" extension.

Make sure your class name ends with "Query" and that the beginning of your class name is the same as the result of getInternalName().

Here is a sample of this would look inside Github. https://github.com/metrixsean/Metrixstream-Sample-Integration/blob/master/query/api/updatelastlogintimestamp.php

UpdateLastLoginTimestampQuery

class UpdateLastLoginTimestampQuery extends ApiQuery {
  public function getInternalName() {
    return "authuser_updatelastlogintimestamp";
  }

  public function execute(ApiContext &$Api, ApiOutputFactory &$OutputFactory) {
    $App =& $this->getApplicationContext();
    $Auth =& $App->getAuthContext();

    if (!$Auth->hasUser()) {
      return $OutputFactory->error("This is an authenticated request.");
    }

    $User =& $Auth->getUser();
    $User->last_login = time();
    $ret = $User->updateParams(Array("last_login"), true);
    if (!$ret) {
      $OutputFactory->error("Unable to update user.");
    }

    return $OutputFactory->success();
  }
}

iSystemHook

The iSystemHook interface allows you to hook into various mechanisms of Metrixstream and provide custom functionality.

Code Location

Your SystemHook class must be placed within the hook directory. Your class must also be named "SystemHook" and stored in the file "system.php".

Here is an example of a SystemHook stored in GitHub: https://github.com/metrixsean/Metrixstream-Sample-Integration/blob/master/hook/system.php

Overridable Functions

To provide your own implementation, simply extend the iSystemHook abstract class and override any of the functions below.

updateDatabase(DatabaseContext db)

this function is called when a build update is performed. You can use this to perform custom database operations outside of the core Metrixstream framework.