matomo-org / developer-documentation Goto Github PK

http://developer.piwik.org/img/myplugin_new_report_display.png throws 404.

I think there used to be a Changelog link in the top menu of developer.piwik.org. Is it possible to add this there again as it is very important. Maybe we could remove "Home" and / or "Develop Piwik" (which doesn't contain so much useful anyway) instead? Also "Community & Support" could be renamed to "Support"

If on a method or class a @ since annotation is set, we should display since when the method/class/property/... is available

Clean URLs for APIs pages is good to have.

Suggested: Database schema guide change URL to /guides/database-schema old URL would redirect to new one.

The api-reference does currently not show inherited methods and properties. See for instance http://developer.piwik.org/api-reference/Piwik/Plugin/Dimension/VisitDimension which inherits http://developer.piwik.org/api-reference/Piwik/Columns/Dimension .

This also results in some not working links such as $columnName and $columnType on the VisitDimension page.

Currently deprecated events such as the Menu events or Widgets, Tasks are displayed in the documentation.

Maybe these events could be removed from documentation? I guess I like the idea of having a smaller list of events, slowly removing some that are useless (Convention over Configuration ftw) and refactoring code to need less events.

Found a missing link on this paragraph for the Live link:
We'll be using data returned by the Live! plugin so we won't have to do much processing ourselves.

:- http://developer.piwik.org/docs/real-time/#the-real-time-live-widget returns 404

A user asked for this via the feedback link. I remember we talked about this in the past already but didn't create an issue. We should definitely provide a guide for this.

This will also help us to identify whether there are problems with the current JS tracker when using it in single page applications. I'm sure there are things that can be improved or that are problematic currently.

It would be good to extend the current guide about Exposing API Methods with an example how to implement an API Report method.

Maybe one example that creates a DataTable from a simple array and runs a filter on it? The filter is maybe not needed but we should explain why not simply return the plain array: Because the dataTable allows to use all our query parameters like limit, showColumns, filter_*, ...

Then maybe another simple example that fetches an existing report, runs a filter on it to customize the report and returns it.

I'm not 100% sure whether it is a good idea but think so.

We currently have one guide for Commands which handles how to use the console and one tiny section how to generate a command. This section is tiny as we have not merged the blog post yet which will be done in refs #44

The console is a crucial tool for developers as they will use it to generate all sort of things, to activate plugins, to clear caches, to enable the developer mode etc. Maybe we can move the current guide to Getting started between Setting up and Distributing your plugin? The title could be "Piwik on the command line". We do link to this from many blog posts already. Then add a new guide named "Commands" under Plugin Basics where it is currently positioned as well. This guide will only explain how to generate and develop new commands.

• How to test a page (with UI tests). We only have to mention it in a section and can link to the guide
• We need to link to the Check permission guide and mention they have to take care of it if needed
• Explain what they can do with pages (pretty much anything) (refs #80)
• Explain how to place a page under the User section (extend user.twig in template)
• Explain how to create a blank page (no extends *.twig) at the beginning of the template
• Explain how to access $_GET and $_POST parameters via Common::getRequestVar
• Not sure if it is needed how to call API methods via Request::processRequest. Probably rather not, this would be a separate guide maybe under Utils named "API Requests"? Shall we create an issue for this?

Parts of it can be maybe used from http://developer.piwik/guides/controllers

Something like this:

but this one is not correct, I think there is a layer between API and MySQL.

The goal of this project is a medium term goal that you review each page of the Developer website. The goal is to make the documentation from OK quality to good or even very good (!) when possible.

Project description:

• Docs to review: https://github.com/piwik/developer-documentation/tree/master/docs
• There are about 40 pages some of them maybe un-necessary, some can be improved, some could be maybe merged or split.
• Good resource: http://jacobian.org/writing/great-documentation/

See also the related issue in piwik/piwik

Assigned to at least @mnapoli and @mattab who will review content of each page

• Integrate
  • #61 The Javascript Tracking Client
  • #41 Tracking API Clients
  • 60b521d All About Tracking
  • #65 Content Tracking
  • #66 Reporting API Tutorial: Get your top 10 keywords
  • #66 Querying the Reporting API
• Develop
  • #25 Getting Started Part I
  • #26 Getting Started Part II
  • 97ad26c Getting Started Part III
  • #49 Distributing Your Plugin
  • #32 How Piwik Works
  • #64 All About Analytics Data
  • #60 Piwik's Extensibility Points
  • b94d9c6 MVC in Piwik
  • #48 Pages
  • #48 Menus
  • #48 Widgets
  • #69 JavaScript and CSS
  • #59 Visualizing Report Data
  • #43 Piwik INI Configuration (moved as sub-article of Piwik Configuration)
  • #43 Piwik Configuration (extracted "Plugin Settings" into sub-article)
  • #43 Plugin Settings
  • #56 Persistence & the MySQL Backend
  • #36 Security best practices
  • #48 Permissions
  • #37 Internationalization
  • #38 Tests
  • #63 Piwik's Reporting API
  • #50 Scheduled tasks
  • #52 Piwik on the Command Line
  • #53 Contributing to Piwik Core
  • #30 Core Team Workflow
  • #70 Theming

The goal of this issue is to make the stats for developer.piwik.org publicly available in our piwik demo here: https://demo.piwik.org/index.php?module=CoreHome&action=index&idSite=36&period=day&date=yesterday

When going to the Integrate page we see a couple of Tracking guides. The first two links "JS Tracking Client" and "Tracking API Clients" list clients that access the HTTP Tracking API. The third link is a guide how to use Content-Tracking via the HTTP Tracking API but there is actually no guide how to use the HTTP Tracking API which would be helpful if people want to write a client or if they want to track data in their application without using any of those clients.

I don't think we need a huge guide here but we need to explain some basics and the link to the Tracking API Reference.

At the end of the API Reference there is for example one part "Debugging the Tracker" which could be part of the guide. How to construct an example request could be moved there as well and explained in steps. We also need to explain when authentication is needed and how they can test it etc.

So far we have 3 reports related to the Reporting API:

• API-Reference: Reporting API Reference
• Integrate: Reporting API Tutorial
• Integrate: Querying the Reporting API
• Piwik In Depth: Reporting HTTP API

None of those guides explains on one page what the Reporting API is, what it can be used for, and how to query it step by step. I'm currently writing a blog post about "How to expose new methods in the Reporting API" but noticed I can actually not link to any of those pages for people who don't know much about it. The In Depth Guide seems to be the only one who explains in a sentence what it is but then it follows be unrelated DataTable Filters etc. The Querying the Reporting API contains only 2 bigger examples but not much explanations etc. Also the second part of this guide should be rather in a separate guide and we need to discuss whether it is actually a good idea to recommend to load index.php to do that. I will create a separate issue on piwik/piwik for this. The Tutorial is a good start but doesn't explain what it is, what it can be used for, doesn't mention authentication etc.

The API-Reference is purely a list of parameters and methods but doesn't explain anything (which is good).

Maybe we can write a single page that explains what it is, what it can be used for, and how to make a successful call with authentication if needed and maybe explain a few more basics like period and date. Then we can link to the API-Reference. We could also write a small section about Segmentation and Metadata API and link to their pages on developer.piwik.org. A while ago I wrote an article for a German PHP Magazine maybe we could reuse some parts or the structure of it in some way.

as reported in forums: http://forum.piwik.org/read.php?15,125630

in https://developer.piwik.org/guides/piwiks-extensibility-points there is a broken link to "Events" section, it should be pointing to https://developer.piwik.org/guides/events but currently points to https://developer.piwik.org/guide/events (please notice the missing "s" at the end og "guides"

In some guides we already write what they will learn but not for what the components can be used for. For all guides under Develop => Plugin Basics it would be nice to give developers ideas what they can do with the API's. This could be always like a simple list of 3-5 items.

Also useful for the guides Integrate/Tracking API (refs #78), Integrate/Reporting API (refs #76), Develop/Plugin Settings and Develop/Extending the Database

We will change many API's for Piwik 3.0.0 and it would be nice to be able to select between the versions "Latest 2.X" and "Latest 3.0". At least till 3.0.0 is released but it might be even useful afterwards.

Without having the possibility to see the docs for 3.0.0 developers won't be able to migrate their plugin to 3.0.0 upfront.

The automated docs are already automatically created for master and the latest stable see https://github.com/piwik/developer-documentation/tree/master/docs/generated but there's no selection for it. Ideally we would also show the related guides when selecting "2.x" so we could maybe at some point just copy everything in docs into a "2.X" folder and leave them there until maybe 6 months after the 3.0 release.

I mean the pages when clicking on a top menu item eg "Integrate Piwik", "Develop plugins"...

There is first the big banner on every overview page saying eg "Develop plugin" which just duplicates the highlighted menu item again. I think I added this initially but it is only disturbing. Give it a try in dev tools and see how it looks without it. I think it's much better :) We should not remove it on the home page though.

Then below this header the sections and links are quite "large". Maybe we can reduce the size a bit so that one can easier get an overview? I'm personally a huge fun of the Redis website where you can get a nice overview of the available guides etc http://redis.io/documentation . It looks a bit more friendly.

In order to detect the 404 pages, we can add the following tag on 404 pages:

<!-- Piwik -->
<script type="text/javascript">
  var _paq = _paq || [];
  _paq.push(["setCustomVariable", 1, "error404", "1", "page"]);
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//demo.piwik.org/";
    _paq.push(['setTrackerUrl', u+'piwik.php']);
    _paq.push(['setSiteId', 36]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<noscript><p><img src="//demo.piwik.org/piwik.php?idsite=36" style="border:0;" alt="" /></p></noscript>
<!-- End Piwik Code -->

If you go to this page
https://github.com/piwik/developer-documentation/blob/master/docs/distributing-your-plugin.md
you will find a link in About this guide part named: Getting Started Extending Piwik
This is for creating Piwik plugins. When you click the link , it comes back to the same page. Is this a link mistake, because I am not able to find any info on creating plugins in this page.

Today I was wondering whether our blog post series already has a positive effect on developer.piwik.org and was analyzing the traffic a bit. During this I noticed we do not track the keywords used in our search.

Goal of this ticket would be to see what people are searching for. This can be useful to know to be able to decide about which topics we should write more and which topics should be covered in a blog post next etc

• "Piwik data" to "Piwik database schema"
• "Plugin data" to "Extending the database"

Reproduce:

• Search for contrib
• Expected to see in dropdown the page: http://developer.piwik.org/guides/contributing-to-piwik-core
• Got: no result instead.

Note: it works for almost the same query contr finds the results.

To create a new plugin, the doc say to use CLI (./console generate:plugin) then enable the plugin in the web interface. Using the CLI would be more consistent and easier.

This is kinda crucial for "Extending the database" as at some point there will be updates needed.

For a beginning we could just add a section about Updates to the "Extending the database" guide explaining they can create an update via ./console generate:update. We could close this ticket after this is done.

In the next step we maybe need a separate guide for this. We will probably write a blog post about this anyway, afterwards we can merge the blog post to a guide.

See http://developer.piwik.org/guides/querying-the-reporting-api#call-the-piwik-api-in-php

We need to explain that doing this actually bootstraps most of the Piwik, eg it loads the config, it loads the plugins, it checks the database etc. We need to warn people about this. Also we need to make sure there is no exit in the code etc eg as in handleMaintenanceMode. If people include this in their application we might kill their app etc. Also we should in general not recommend this way of calling API requests from any other application.

It recommends to verify the token auth, it should use the Nonce instead

In http://developer.piwik.org/guides/logging we could explain to plugin developers and core devs that the WARNS/ERRORS will be displayed on screen to users in the notifications.

To log messages and not have them viewed by users, other levels should be used such as notice or info etc.

Current problems:

• the Javascript Tracking client API reference is very long and is a mix of "API reference" and "User guide"
• the "Track your application" section in Integrate Piwik doesn't have much content, all the content is in user guides

Solution:

Split the current API reference into:

• a user guide that will be in "Integrate Piwik"
• an API reference that will stay where it is

Given this article is linked to a lot, we need to add a visible link at the beginning of the API reference to make users aware that a detailed user guide exist.

Dupes between http://piwik.org/docs/tracking-api/ and http://developer.piwik.org/guides/tracking-api-clients

I'm removing this content:

## iOS SDK 

If you are building iOS apps, you can use the Objective-C PiwikTracker client to send tracking data to your Piwik server.

Learn more and download Piwik iOS SDK on Github at [github.com/piwik/piwik-sdk-ios][6]

## Android SDK

If you are building Android apps, you can use the Android Java client to send tracking data to your Piwik server.

Learn more and download Piwik Android SDK on Github at [github.com/piwik/piwik-sdk-android][14]

## PHP client

The default client is the PHP PiwikTracker, learn more at: [developer.piwik.org/api-reference/PHP-Piwik-Tracker][2]

## Java client

A Java client for the Piwik Tracking API is available on Github: [github.com/piwik/piwik-java-tracking ][3]

## Python client

A complete Python client implementation of the Tracking API is available on Github at [github.com/piwik/piwik-python-api][4]

## C# client 

A C# client implementation of the Tracking API is available on Github at [github.com/piwik/piwik-dotnet-tracker][5]

## Appcelerator Titanium Module 

If you are building Mobile apps using Appcelerator Titanium, use the Piwik Analytics Module for Titanium to measure how users are navigating and consuming your apps. Learn more and download the Piwik Module for Titanium at [github.com/manumaticx/ti.piwik][15]

@mnapoli can you check this is added and synced in http://developer.piwik.org/guides/tracking-api-clients

It was reported in the forums:

I've gone through both guides to theming, and unfortunately they seemed to be a little lacking of covering some basic content. I did some digging and reverse engineering of the code and have some notes I wanted to post in hopes it may help others in the future.

The goal of this issue is to review the Theming guide with the feedback from this user in mind, and try to create a simple and useful Theming guide.

On the page: http://developer.piwik.org/api-reference/segmentation

• expected to see a left box with the links to headers in this page, as well as the API Reference box.
• got instead: only the API Reference box is displayed.

Document fixtures, etc.

I was wondering if we actually need the metadata defined in the beginning of docs/*.md files?

category: Develop
previous: tests-ui
next: tests-travis
subGuides:
  - plugin-settings
  - piwiks-ini-configuration

In theory this information is already present in the category classes, isn't it? For example here: https://github.com/piwik/developer-documentation/blob/master/app/helpers/Content/Category/DevelopCategory.php

Depending on the path or filename of the markdown file we know the category. Currently, when moving a page to another category I do have to update the PHP category classes and update the related markdown file.

Also previous and next could be maybe automatically generated for all pages and not needed to be defined in the markdown files since we have that information already in the category class? Meaning we can find out whether there is a previous or next sibling.

With subGuides I was confused why it is sometimes defined in the markdown file and sometimes in a category class. I think we could just remove it and for simplicity always define it in the category class so one can immediately see the whole structure there and change things in one place.

Of course we'd have to create all category classes to know all this information but that should be fast. Especially since we cache pages.

• How to create a custom theme in Piwik
• How to create a scheduled task
• How to create a widget
• How to add new pages and menu items to Piwik
• How to make your plugin configurable: merged into Plugin Settings
• How to publish your plugin or theme on the Piwik Marketplace
• How to create a command
• Generating test data
• How to make your plugin multilingual
• How to write UI tests for your plugin
• How to verify user permissions
• How to write unit tests
• How to expose new API methods (published soon)

Document testEnvironment.configOverride which can be used in UI tests to override INI config options.

Just opened the website and noticed the website is pretty slow. It takes over 4s to load and the JS and font files are never cached. The site used to load in under 500ms. It's also a bit annoying since sometimes some content is there but it takes 2 or 3 more seconds until the titles are rendered (because they use a custom font now). My internet connection is 2Mbit/s, testing with Chrome.

JS and fonts should be loaded from cache, ideally they would be loaded async.

Some code blocks have big padding but should not. For example see this:

Source: http://developer.piwik.org/api-reference/tracking-javascript

The goal of this issue is to modify all such code blocks and make them look good without extra padding.

In the page: docs/piwik-on-the-command-line.md and other pages of the site we use the character … but it is not rendered correctly eg. to ease development… in http://developer.piwik.org/guides/piwik-on-the-command-line

Goal is to either fix the bug if possible or change characters to three dots characters as a hack.

Steps to reproduce:

• Open http://developer.piwik.org/api-reference/reporting-api#Overlay
• Got: title Overlay is behind top bar
• expected: visible Overlay below top bar

See http://developer.piwik.org/guides/persistence-and-the-mysql-backend#the-mysql-backend maybe we can remove all the CREATE table statements etc? Some might be outdated and it is not that important / helpful there I guess.

• Mention how to check for permissions and that they need to check for permissions in Menu and for example in the Controller as well as it would be otherwise still possible to execute the controller via URL
• Menus are often needed in combination with Pages therefore we should mention Pages (Controllers) and link to them
• How to rename Menu items
• How to delete Menu items (I think for both delete & rename there is a configure method in the Menu class otherwise we need to explain the events)
• Explain that they need to find the translation key to rename/delete menu items and how they can find it (switch language to Development or under Admin => Translation search)
• Update Admin and User menu screen
• Explain at the beginning what Menus are good for (restrict items to certain users / user-groups etc, remove unneeded items etc) refs #80

https://github.com/piwik/developer-documentation/#adding-a-new-guide

For privacy reasons we prefer not to load any fonts from google domains. Let's move the font from http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,400,300,600&subset=latin,cyrillic-ext,greek-ext,greek,vietnamese,latin-ext,cyrillic to locally on developer.piwik.org

cc @mnapoli

Problems with the current parser:

• doesn't support fenced code blocks (à la GitHub):
  • indented code blocks are a pain to write with some editors
  • syntax highlighting is random because autodetected, which leads to very weird highlighting (fenced code blocks allow to set a language explicitly)
• hacked all over the place

Parsedown is probably the best choice. The main difficulty now is try to understand what all those hacks do and see if they can be ported to Parsedown.

In the page http://developer.piwik.org/integration

it makes sense to add a link to this page: http://piwik.org/integrate/

Many developers will expect to find the link there. +1 @tzi for suggestion