params.json

{"name":"How to create a The DataTank extension","tagline":"Extending The DataTank's functionality without touching the core","body":"# tdtext\r\n\r\nHave you as well been dreaming about a world where it is possible for anyone to write a The DataTank extension and amaze the world of Open Data?\r\n\r\nWith tdtext, this becomes possible. Just like people can easily create ckan extensions (ckanext, see what we did there?) with a minimum of documentation, you are able to create The DataTank extensions which plug into the core workflow. The DataTank extension systems is built for the ease of developers. Once a The DataTank is installed, it should be a breeze to install: scrapers, extra formatters, extra visualizations, strategies to read data, and so on.\r\n\r\n## Architecture ##\r\n\r\nWe have one singleton class called `TdtextNotifier`. This class will be updated by tdt/core whenever something happens: the routes are loaded, the formatters are loaded, the documentation is updated, and so on. `TdtextNotifier` will collect all updates and will direct then to registered tdtext classes. These classes can be added to the configuration. What event will go to which class is decided based on the interfaces they inherit from.\r\n\r\n## A new github organisation\r\n\r\nhttp://github.com/tdtext\r\n\r\nThis is the organisation where we will add all official extensions for The DataTank and a barebone repository which everyone can fork to start its own tdtextension.\r\n\r\nIt also contains these docs at http://tdtext.github.io/ which can be edited at http://github.com/tdtext/tdtext.github.io.\r\n\r\n## Installing extensions using composer\r\n\r\nIf you're not familiar with composer, check out http://getcomposer.org/doc/00-intro.md.\r\n\r\n```bash\r\ncd /path/to/tdt/root/\r\ncomposer require tdtext/${extensionname}\r\ncomposer update # this will also trigger the code to enable the extension. You can disable it in your config.\r\n```\r\n\r\n## Writing a tdt extension\r\n\r\n* Fork the barebone tdtextension at http://github.com/tdtext/barebone \r\n* (Re)Name your git repository towards tdtext-{extensionname} (this will make your extension discoverable through https://packagist.org)\r\n* Add the description of your extension in composer.json\r\n* run composer update\r\n* Edit your class and start creating your extension\r\n\r\nOnce you have tested it by installing it locally, you can add it to packagist: https://packagist.org/packages/submit\r\n\r\n### The Interfaces (the hard way)\r\n\r\n#### tdt/core/tdtext/IRoutesEditor\r\n\r\nWith the route mapper you can add a controller for a specific route. This comes in handy if you want to go past all tdt controller handling. This is not recommended if you're going to be handling data through here. It is recommended if you want to implement your own brand new functionality for certain URI patterns.\r\n\r\nFor example:\r\n```php\r\nclass MyOwnRouteController implements IRoutesEditor {\r\n\r\n    function editRoutes(&$routes){\r\n        //key of routes is divided by a |\r\n        //the first part is the HTTP Method use, the second part is a regular expression\r\n        $routes[\"GET | about/(?P<person>[^?]+)\"] = get_class($this);\r\n    }\r\n\r\n    function GET($matches){\r\n        echo \"A page about \" . urldecode($matches[\"person\"]);\r\n    }\r\n}\r\n```\r\n\r\n#### tdt/core/tdtext/IDefinitionsEditor\r\n\r\nCalled when the documentation in tdt/core is ready\r\n\r\nYou can add your own documentation for a new resource if you want to have your own configuration in there. You can use it to define new configurations without them being stored in the database.\r\n\r\nFor example:\r\n```php\r\nclass NewDefinitionAdder IDefinitionsEditor {\r\n    function editDefinitions(&$definitions){\r\n        $definitions[...] = ...;\r\n    }\r\n}\r\n```\r\n\r\n#### tdt/core/tdtext/IFormattersEditor\r\n\r\nAdd your own formatter to the list\r\n\r\n```php\r\nInterface IFormattersEditor {\r\n    /**\r\n    * Add or edit formatters in this array\r\n    */\r\n    abstract function editFormatters(&$formatters);\r\n}\r\n```\r\n\r\n#### tdt/core/tdtext/ITransformer\r\n\r\nA transformer transforms an object after it is read into memory.\r\n\r\n```php\r\nInterface ITransformer {\r\n   /**\r\n    * Add or edit an object from the moment is read into memory\r\n    * @param $resourceconfiguration contains the identifier of a resource and the configuration\r\n    * @param $object is the data object\r\n    */\r\n    abstract function transform($resourceconfiguration, &$object);\r\n}\r\n```\r\n\r\n\r\n...WIP\r\n\r\n### Using an abstract class (recommended - it's there if you don't know about The DataTank internals\r\n\r\n#### tdt/core/tdtext/AFormatter\r\n\r\nWrite a new behaviour for a certain format.\r\n\r\nFor example:\r\n```php\r\nclass YAMLFormatter extends \\tdt\\core\\tdtext\\AFormatter {\r\n    public function __construct(){\r\n        $this->name = \"YAML\"; //you can also override the behaviour for for example XML or JSON\r\n    }\r\n\r\n    function getGETParameters(){\r\n        return array();\r\n    }\r\n\r\n    function print($resourceconfiguration, $parameters, $object){\r\n        //YAML print code\r\n    }\r\n}\r\n```\r\n\r\n#### tdt/core/tdtext/AScraper\r\n\r\nWriting a scraper can be done easily by extending the AScraper class. Use this class if you want to have a certain URI in The DataTank to scrape data from a certain source.\r\n\r\nExample can be found in the barebone repository which can be forked to start your own: http://github.com/tdtext/barebone\r\n\r\n#### tdt/core/tdtext/AStrategy\r\n\r\nIf you want to implement a new strategy next to the standard ones for reading a certain source (e.g. a NoSQL cluster or a certain data format), extend this abstract class.\r\n\r\n\r\nDraft:\r\n```php\r\nabstract class AStrategy implements ... {\r\n\r\n    /**\r\n     * Returns an array according to the discovery API of parameter objects.\r\n     * They include the parameters needed to read a resource which's source uses this strategy.\r\n     */\r\n    abstract function getGETParameters();\r\n\r\n    /**\r\n     * Returns an array according to the discovery API of parameter objects.\r\n     * They include documentation about whether the parameter is required or not when configuring a source of this strategy type through a PUT request.\r\n     */\r\n    abstract function getConfigParameters();\r\n\r\n    /**\r\n     * when reading the a resource configured with this strategy, this is what's going to happen.\r\n     * The resourceconfiguration contains the resourceidentifier and the config parameters (as defined by the getConfigParameters() function)\r\n     */\r\n    abstract function read($resourceconfiguration, $parameters);\r\n}\r\n```","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}