Framework Reference – Functions

  1. Existing Piwik Plugins
This page aims to list the different functions you can use when programming plugins for Piwik.
Be careful, the following APIs may change in the near future as Piwik is still in development.

General

Accessible from your plugin controller

$this->date = current selected Piwik_Date object (class)
$period = Piwik_Common::getRequestVar("period"); - Get the current selected period
$idSite = Piwik_Common::getRequestVar("idSite"); - Get the selected idSite
$site = new Piwik_Site($idSite); - Build the Piwik_Site object (class)
$this->str_date = current selected date in YYYY-MM-DD format

Misc

Piwik_AddMenu( $mainMenuName, $subMenuName, $url ); - Adds an entry to the menu in the Piwik interface (See the example in the UserCountry Plugin file)
Piwik_AddWidget( $widgetCategory, $widgetName, $controllerName, $controllerAction, $customParameters = array()); - Adds a widget that users can add in the dashboard, or export using the Widgets link at the top of the screen. See the example in the UserCountry Plugin file or any other plugin)
Piwik_Common::prefixTable("site") = piwik_site

User access

Piwik::getCurrentUserLogin() = anonymous
Piwik::isUserHasSomeAdminAccess() = false
Piwik::isUserHasAdminAccess( array $idSites = array(1,2) ) = false
Piwik::isUserHasViewAccess( array $idSites = array(1) ) = false
Piwik::isUserIsSuperUser() = false

Execute SQL queries

Piwik_FetchOne("SELECT token_auth FROM piwik_user WHERE login = ?", array("anonymous")) = 'anonymous'

$query = Piwik_Query("SELECT token_auth FROM piwik_user WHERE login = ?", array("anonymous"))
$fetched = $query->fetch();
At this point, we have: $fetched['token_auth'] == 'anonymous'

Example Sites information API

Piwik_SitesManager_API::getInstance()->getSitesWithViewAccess() = 
array (
  0 => 
  array (
    'idsite' => '3',
    'name' => 'virtual-drums.com',
    'main_url' => 'http://www.virtual-drums.com',
    'ts_created' => '2008-01-27 01:41:53',
    'timezone' => 'UTC',
    'currency' => 'USD',
    'excluded_ips' => '',
    'excluded_parameters' => '',
    'excluded_user_agents' => '',
    'sitesearch' => '1',
    'sitesearch_keyword_parameters' => '',
    'sitesearch_category_parameters' => '',
    'group' => '',
    'keep_url_fragment' => '0',
    'ecommerce' => '0',
  ),
  1 => 
  array (
    'idsite' => '7',
    'name' => 'Piwik Forums',
    'main_url' => 'http://forum.piwik.org',
    'ts_created' => '2008-12-01 11:50:20',
    'timezone' => 'UTC',
    'currency' => 'USD',
    'excluded_ips' => '',
    'excluded_parameters' => 'act,CODE,prune_day,sort_by,sort_key,topicfilter,st,gopid,s',
    'excluded_user_agents' => '',
    'sitesearch' => '0',
    'sitesearch_keyword_parameters' => '',
    'sitesearch_category_parameters' => '',
    'group' => '',
    'keep_url_fragment' => '0',
    'ecommerce' => '0',
  ),
  2 => 
  array (
    'idsite' => '32',
    'name' => 'Crowdfunding',
    'main_url' => 'http://crowdfunding.piwik.org',
    'ts_created' => '2012-12-23 11:37:43',
    'timezone' => 'UTC',
    'currency' => 'USD',
    'excluded_ips' => '',
    'excluded_parameters' => '',
    'excluded_user_agents' => '',
    'sitesearch' => '1',
    'sitesearch_keyword_parameters' => 'q,query,s,search,searchword,k,keyword',
    'sitesearch_category_parameters' => '',
    'group' => '',
    'keep_url_fragment' => '0',
    'ecommerce' => '0',
  ),
)

Piwik_SitesManager_API::getInstance()->getSitesWithAdminAccess() = 
array (
)

Example API Users information

View the list of API methods you can call on API reference
For example you can try Piwik_UsersManager_API::getInstance()->getUsersSitesFromAccess("view"); or Piwik_UsersManager_API::getInstance()->deleteUser("userToDelete");

Javascript in Piwik

i18n internationalization

In order to translate strings within Javascript code, you can use the javascript function _pk_translate( token );.
  • The "token" parameter is the string unique key found in the translation file. For this token string to be available in Javascript, you must suffix your token by "_js" in the language file. For example, you can add 'Goals_AddGoal_js' => 'Add Goal', in the lang/en.php file
  • You then need to instruct Piwik to load your Javascript translations for your plugin; by default, all translation strings are not loaded in Javascript for performance reasons. This can be done by calling a custom-made Smarty modifier before the Javascript code requiring translations, eg. {loadJavascriptTranslations plugins='$YOUR_PLUGIN_NAME'}. In our previous example, the $YOUR_PLUGIN_NAME being Goals, we would write {loadJavascriptTranslations plugins='Goals'}
  • You can then print this string from your JS code by doing _pk_translate('Goals_AddGoal_js');.

Reload a widget in the dashboard

It is sometimes useful to reload one widget in the dashboard (for example, every 20 seconds for a real time widget, or after a setting change). You can easily force your widget to reload in the dashboard by calling the helper function $(this).parents('[widgetId]').dashboardWidget('reload');.

Smarty plugins

There are some builtin plugins for Smarty especially developped for Piwik.
You can find them on the Git at /core/SmartyPlugins.
More documentation to come about smarty plugins.

Existing Piwik Plugins

  • Have a look at the already long Piwik plugins list bundled with the Piwik package. It will help you build yours!

Feedback on this page

Have you found an error in this page, or do you think some information is missing or not clear? We appreciate you taking the time to send us your suggestions and feedback on this page.

2012 © Piwik.org.
Contact Us

Leading Open Source Web Analytics
Design by clearcode
And built on Free Software!