Building Statamic Add-ons

An overview to Statamic add-on development for the workshop at PeersConf 2014.

Transcript

1. Building Statamic Add-ons @jason_varga - Peers 2014
2. What makes an add-on?
3. What makes an add-on? At least one of: » Plugins » Hooks » Tasks » Fieldtypes » Modifiers » API
4. Plugins » Template tags {{ entries:listing }} » Single tags and tag pairs » Outputs string or performs a task » They can have parameters
5. Hooks » Interconnectivity aspect » Forms post to these » Can ‘hook’ into system events
6. Tasks » Glue between the aspects of the add-on » All other add-on aspects can use tasks » Can be run automatically via cron » Important in keeping code DRY
7. Modifiers » Modifies data in templates » Chainable » One per add-on
8. Fieldtypes » Content entry in the control panel » One per add-on
9. API » Interface between your add-on and others » Works both ways
10. Tools at our disposal
11. Tools at our disposal » Statamic’s Internal API » Add-on class methods » Bundles » Documentation » PHP.net
12. Statamic's Internal API » Abstracted helper methods Content::getFoldersByURL(‘ blog’); » api.statamic.com Don’t use it » Look in the code. Don’t be scared of the /_app/ folder
13. Add-on class methods » Further abstracted methods Session::set('karma', 'var', $val); $this->session->set('var', $val); » /_app/core/extend/
14. Bundles » /_app/core/bundles/ » A bundle is an add-on » There are 123 of them
15. Documentation » http://statamic.com/learn » ‘Creating Add-Ons’ section
16. PHP.net » We've all been here. » It's helpful. Admit it.
17. The Essentials What you need to know
18. Add-on » Every aspect extends the Addon class » Its methods are available to every aspect » $this->config, $this- >fetchConfig » $this->log, cache, css, js, asset, addon
19. Plugin » $this->fetchParam() » $this->content » Parse::template() » Parse::tagLoop()
20. class Plugin_hello_world extends Plugin { public function index() { $name = $this->fetchParam('name', 'world'); return 'Hello '.$name.'!'; } } {{ hello_world name="Jack" }} => Hello Jack! {{ hello_world }} => Hello world!
21. Hooks » You hook into other events » You don’t create the hooks » Using /TRIGGER/ is just using a Statamic Hook » You can create a hook, but it can be from anywhere.
22. class Hooks_hello_world extends Hooks { public function hello_world__shout() { $name = array_get($_POST', 'name', 'world'); exit( 'Hello '.$name.'!' ); } } POST to: http://mysite.com/TRIGGER/hello_world/shout => Hello world!
23. From the core: $app->map( '/TRIGGER/:namespace/:hook(/:segments+)', function ($namespace, $hook, $segments = array()) use ($app) { Hook::run($namespace, $hook, null, null, $segments); })->via('GET', 'POST', 'HEAD');
24. Tasks » Any automation requires a define() method » $this->add(5, ’foo’) will run foo every 5 mins » To enable, enter this in crontab: * * * * * curl --silent http://example.com/TRIGGER/tasks/tick > /dev/null 2>&1 » Tasks can be called within define() automatically or with $this->tasks->method()
25. class Tasks_reminders extends Tasks { public function define() { $this->add(1440, 'sendReminders'); } public function sendReminders() { // send emails } } class Hooks_reminders extends Hooks { public function reminders__send() { $this->tasks->sendReminders(); } }
26. Fieldtype » Unlimited config options » $this->field_config, field_data, fieldname » Ascent is your friend » CSS is reusable – wow! » JS libraries in Ascent are available to you (jQuery, underscore.js, knockout.js) » Not limited to saving to one field
27. class Fieldtype_text extends Fieldtype { public function render() { $type = array_get($this->field_config, 'input_type', 'text'); $attributes = array( 'name' => $this->fieldname, 'id' => $this->field_id, 'tabindex' => $this->tabindex, 'value' => HTML::convertSpecialCharacters($this->field_data) ); return HTML::makeInput($type, $attributes, $this->is_required); } }
28. class Hooks_text extends Hooks { public function control_panel__add_to_foot() { if (URL::getCurrent() == '/publish') { return $this->js->link('text'); } } }
29. Modifier » String in, string out » Parameters - You get one... kinda
30. class Modifier_slugify extends Modifier { public function index($value, $parameters=array()) { $delimiter = array_get($parameters, 0, '-'); return Slug::make($value, array('delimiter' => $delimiter)); } } thing: this is a thing {{ thing|slugify }} => this-is-a-thing {{ thing|slugify:* }} => this*is*a*thing
31. class Modifier_slugify extends Modifier { public function index($value, $parameters=array()) { $parameters = explode(',', array_get($parameters, 0, array())); $first_param = $parameters[0]; $second_param = $parameters[1]; // return ... } }
32. Cache » File » Cookie » Session » Flash » Blink
33. File Based Cache » For stuff that will be sticking around. » Mainly used for content » Lives in /_cache/_add-ons/addon_name/ » Store anything, it's just text » YAML makes your life easier
34. This: $name = 'foobar'; $stuff = array( 'foo' => 'one', 'bar' => 'two', 'arr' => array( 'one' => 'uno', 'two' => 'dos' ) ); $this->cache->putYAML("stuff/$name", $stuff); // Saves to: /_cache/_add-ons/my_addon/stuff/foobar
35. Becomes this: foo: one bar: two arr: one: uno two: dos Read it with this: $this->cache->getYAML("stuff/foobar");
36. Cookie Based Cache » Saved to the user's browser » Read/write with JavaScript » Users can erase it
37. Set in Statamic $this->cookies->set('foo', 'bar', '1 week'); // $_COOKIE['addon_name__foo'] Read in Javascript $.cookie('addon_name__foo'); // => 'bar'
38. Session Based Cache » Stored on the server » Persistent across pages
39. Write $this->session->set('foo', 'bar'); Read $this->session->get('foo');
40. Flash » Persists for a single page load » Used for feedback messages
41. Write $this->flash->set('foo', 'bar'); Read $this->flash->get('foo');
42. Blink » Persists during runtime only » Useful for sharing data across methods
43. {{ entries:listing folder="blog" since="2 weeks ago" sort_by="author" }} ... {{ /entries:listing }} {{ entries:pagination folder="blog" since="2 weeks ago" sort_by="author" }} ... {{ /entries:pagination }}
44. Manipulating Content » Don't need to reinvent the wheel » Use ContentService to get a ContentSet » ContentSets can be filtered and sorted
45. // Grab all the content $content_set = ContentService::getContentByFolders('blog|events'); // Filter it $content_set->filter(array( 'type' => 'entries', 'show_past' => true, 'show_future' => true )); // Get it $content_set->get();
46. Creating an add-on
47. Creating an add-on » Analyze the brief » Scaffold » Fill in the gaps » Optimize & Simplify » Document
48. What we're building Why stop at one? Karma A 'points' add-on Bluebird A Twitter add-on
49. Karma » Members can assign points to other members » Display a points leaderboard » Pages can require points for access » A member can view a list of pages they can access » Reset points every week
50. Bluebird » Ability to select a tweet » Ability to convert a tweet status ID » Speed things up by adding caching
51. Get to work
52. Thanks! jason@pixelfear.com @jason_varga @builtwithbison