Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed documentation (2)

  • Loading branch information...
commit 5761c779a5812310fbcb476d258d240391c1fdd4 1 parent f63f2fe
@Akron authored
Showing with 155 additions and 1 deletion.
  1. +155 −1 Readme.pod
View
156 Readme.pod
@@ -25,7 +25,161 @@ Mojolicious::Plugin::Piwik - Use Piwik in Mojolicious
=head1 DESCRIPTION
L<Mojolicious::Plugin::Piwik> is a simple plugin for embedding
-L<Piwik|http://piwik.org/> acreate a configuration
+L<Piwik|http://piwik.org/> Analysis in your Mojolicious app.
+
+
+=head1 METHODS
+
+=head2 C<register>
+
+ # Mojolicious
+ $app->plugin(Piwik => {
+ url => 'piwik.khm.li',
+ site_id => 1
+ });
+
+ # Mojolicious::Lite
+ plugin 'Piwik' => {
+ url => 'piwik.khm.li',
+ site_id => 1
+ };
+
+ # Or in your config file
+ {
+ Piwik => {
+ url => 'piwik.khm.li',
+ site_id => 1
+ }
+ }
+
+
+Called when registering the plugin.
+Accepts the following parameters:
+
+=over 2
+
+=item C<url>
+
+URL of your Piwik instance.
+
+=item C<site_id>
+
+The id of the site to monitor. Defaults to 1.
+
+=item C<embed>
+
+Activates or deactivates the embedding of the script tag.
+Defaults to C<true> if Mojolicious is in production mode,
+defaults to C<false> otherwise.
+
+=item C<token_auth>
+
+Token for authentication. Used only for the Piwik API.
+
+=back
+
+All parameters can be set either on registration or
+as part of the configuration file with the key C<Piwik>.
+
+
+=head1 HELPERS
+
+=head2 C<piwik_tag>
+
+ %= piwik_tag
+ %= piwik_tag 1
+ %= piwik_tag 1, 'piwik.khm.li'
+
+Renders a script tag that asynchronously loads the Piwik
+javascript file from your Piwik instance.
+Accepts optionally a site id and the url of your Piwik
+instance. Defaults to the site id and the url given when the plugin
+was registered.
+
+This tag should be included at the bottom
+of the body tag of your website.
+
+
+=head2 C<piwik_api>
+
+ # In Controller - blocking ...
+ my $json = $c->piwik_api(
+ 'Actions.getPageUrl' => {
+ token_auth => 'MyToken',
+ idSite => [4,7],
+ period => 'day',
+ date => 'today'
+ }
+ );
+
+ # ... or async
+ $c->piwik_api(
+ 'Actions.getPageUrl' => {
+ token_auth => 'MyToken',
+ idSite => [4,7],
+ period => 'day',
+ date => 'today'
+ } => sub {
+ my $json = shift;
+ # ...
+ }
+ );
+
+Sends a Piwik API request and returns the response as a hash
+or array reference (the decoded JSON response).
+Accepts the API method, a hash reference
+with request parameters as described in the
+L<Piwik API|http://piwik.org/docs/analytics-api/>, and
+optionally a callback, if the request is meant to be non-blocking.
+
+In addition to the parameters of the API reference, the following
+parameters are allowed:
+
+=over 2
+
+=item C<url>
+
+The url of your Piwik instance.
+Defaults to the url given when the plugin was registered.
+
+=item C<secure>
+
+Boolean value that indicates a request using the https scheme.
+Defaults to false.
+
+=item C<api_test>
+
+Boolean value that indicates a test request, that returns the
+created request url instead of the JSON response.
+Defaults to false.
+
+=back
+
+C<idSite> is an alias of C<site_id> and defaults to the id
+of the plugin registration.
+Some parameters are allowed to be array references instead of string values,
+for example C<idSite> and C<date> (for ranges).
+
+ my $json = $c->piwik_api(
+ 'API.get' => {
+ site_id => [4,5],
+ period => 'range',
+ date => ['2012-11-01', '2012-12-01'],
+ secure => 1
+ });
+
+
+=head1 LIMITATIONS
+
+Currently the API requests always expect JSON, so it's not recommended
+for the C<ImageGraph> API.
+The plugin is also limited to the Analysis API and lacks support for
+eCommerce tracking.
+
+
+=head1 TESTING
+
+To test the plugin against your Piwik instance, create a configuration
file with the necessary information as a perl data structure in C<t/auth.pl>
and run C<make test>, for example:
Please sign in to comment.
Something went wrong with that request. Please try again.