From 92c597ca1cd0d93df7246eb2f81f84bcb08673ce Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 00:12:18 +0100 Subject: Allow doc string extraction and use for pluginapi. Allow us to extract docstrings from our sources using the sphinx.ext.autodoc module. First use: Extract some of the docs for the pluginapi and provide it in a new "Plugin API" section. --- docs/source/pluginwriter/api.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/source/pluginwriter/api.rst (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst new file mode 100644 index 00000000..206c8b0b --- /dev/null +++ b/docs/source/pluginwriter/api.rst @@ -0,0 +1,23 @@ +.. MediaGoblin Documentation + + Written in 2013 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + + +========== +Plugin API +========== + +:mod:`pluginapi` Module +----------------------- + +.. automodule:: mediagoblin.tools.pluginapi + :members: get_config, register_routes, register_template_path -- cgit v1.2.3 From 75621003af128969c322d11aff74ec0c425a9ff4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 30 Jan 2013 13:27:40 -0600 Subject: Added register_template_hooks and get_hook_templates to the plugin api auto module documentation. --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 206c8b0b..f700e161 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -20,4 +20,4 @@ Plugin API ----------------------- .. automodule:: mediagoblin.tools.pluginapi - :members: get_config, register_routes, register_template_path + :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates -- cgit v1.2.3 From cf41e7d7444fb9d19a777a4720d9b00684e6fe7b Mon Sep 17 00:00:00 2001 From: Elrond Date: Thu, 31 Jan 2013 20:57:03 +0100 Subject: Improve formatting for hook template docs. --- docs/source/pluginwriter/api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index f700e161..42dc3a3d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -20,4 +20,5 @@ Plugin API ----------------------- .. automodule:: mediagoblin.tools.pluginapi - :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates + :members: get_config, register_routes, register_template_path, + register_template_hooks, get_hook_templates -- cgit v1.2.3 From 36748921c27deb3f8c9d88f9b7a3c368a427d418 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 11 Apr 2013 16:57:11 -0500 Subject: adding callable_runone and callable_runall to the docs --- docs/source/pluginwriter/api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 42dc3a3d..44ffd6e8 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -21,4 +21,5 @@ Plugin API .. automodule:: mediagoblin.tools.pluginapi :members: get_config, register_routes, register_template_path, - register_template_hooks, get_hook_templates + register_template_hooks, get_hook_templates, + callable_runone, callable_runall -- cgit v1.2.3 From 4d0191dcb8b43f82bfacc77ed8c92d0d3c573d8a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 19 Apr 2013 13:22:03 -0500 Subject: A warning about the plugin API being unstable. --- docs/source/pluginwriter/api.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 44ffd6e8..85870d28 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -16,6 +16,15 @@ Plugin API ========== +This documents the general plugin API. + +Please note, at this point OUR PLUGIN HOOKS MAY AND WILL CHANGE. +Authors are encouraged to develop plugins and work with the +MediaGoblin community to keep them up to date, but this API will be a +moving target for a few releases. + +Please check the release notes for updates! + :mod:`pluginapi` Module ----------------------- -- cgit v1.2.3 From 51d5d3aa20b5f2d7dbe9c88e7d8c21db7ea172d1 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 19 Apr 2013 16:29:03 -0500 Subject: changing the things to document in api.rst --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 85870d28..3a75d455 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -31,4 +31,4 @@ Please check the release notes for updates! .. automodule:: mediagoblin.tools.pluginapi :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates, - callable_runone, callable_runall + hook_handle, hook_runall, hook_transform, -- cgit v1.2.3 From b835e15319882477e71c7b03db2c1565dd674a96 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 30 Apr 2013 00:24:45 +0200 Subject: Add warning about crypt/itsdangeroussecret.bin. You should not leak that file, really. --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 3a75d455..6323f713 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -31,4 +31,4 @@ Please check the release notes for updates! .. automodule:: mediagoblin.tools.pluginapi :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates, - hook_handle, hook_runall, hook_transform, + hook_handle, hook_runall, hook_transform -- cgit v1.2.3 From f65bf8983611b18ec3a6a042404c50b8558529df Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 8 May 2013 10:57:23 -0500 Subject: Documenting plugin configuration This commit sponsored by David Krupicz. Thanks, David! --- docs/source/pluginwriter/api.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 6323f713..df933511 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -32,3 +32,19 @@ Please check the release notes for updates! :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates, hook_handle, hook_runall, hook_transform + +Configuration +------------- + +Your plugin may define its own configuration defaults. + +Simply add to the directory of your plugin a config_spec.ini file. An +example might look like:: + + [plugin_spec] + some_string = string(default="blork") + some_int = integer(default=50) + +This means that when people enable your plugin in their config you'll +be able to provide defaults as well as type validation. + -- cgit v1.2.3 From b312d2cd83dbbfb32adc30c5eb3a9a4cc6ae9295 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 14 May 2013 16:09:55 -0500 Subject: Added documentation on view specific hooks This commit sponsored by Matthew Woodward. Thank you! --- docs/source/pluginwriter/api.rst | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index df933511..0d5c82d8 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -48,3 +48,65 @@ example might look like:: This means that when people enable your plugin in their config you'll be able to provide defaults as well as type validation. + +Context Hooks +------------- + +View specific hooks ++++++++++++++++++++ + +You can hook up to almost any template called by any specific view +fairly easily. As long as the view directly or indirectly uses the +method ``render_to_response`` you can access the context via a hook +that has a key in the format of the tuple:: + + (view_symbolic_name, view_template_path) + +Where the "view symbolic name" is the same parameter used in +``request.urlgen()`` to look up the test. So say we're wanting to add +something to the context of the user's homepage. We look in +mediagoblin/user_pages/routing.py and see:: + + add_route('mediagoblin.user_pages.user_home', + '/u//', + 'mediagoblin.user_pages.views:user_home') + +Aha! That means that the name is ``mediagoblin.user_pages.user_home``. +Okay, so then we look at the view at the +``mediagoblin.user_pages.views:user_home`` method:: + + @uses_pagination + def user_home(request, page): + # [...] whole bunch of stuff here + return render_to_response( + request, + 'mediagoblin/user_pages/user.html', + {'user': user, + 'user_gallery_url': user_gallery_url, + 'media_entries': media_entries, + 'pagination': pagination}) + +Nice! So the template appears to be +``mediagoblin/user_pages/user.html``. Cool, that means that the key +is:: + + ("mediagoblin.user_pages.views:user_home", + "mediagoblin/user_pages/user.html") + +The context hook uses ``hook_transform()`` so that means that if we're +hooking into it, our hook will both accept one argument, ``context``, +and should return that modified object, like so:: + + def add_to_user_home_context(context): + context['foo'] = 'bar' + return context + + hooks = { + ("mediagoblin.user_pages.views:user_home", + "mediagoblin/user_pages/user.html"): add_to_user_home_context} + + +Global context hook ++++++++++++++++++++ + + -- cgit v1.2.3 From 1344c561a0da28290bab860e7e628998463fca15 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 15 May 2013 10:37:41 -0500 Subject: Adding global context hooks & fixing method names->symbolic view names in docs This commit sponsored by Sheila Miguez. Thanks Sheila! --- docs/source/pluginwriter/api.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 0d5c82d8..b411fa4d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -73,7 +73,7 @@ mediagoblin/user_pages/routing.py and see:: Aha! That means that the name is ``mediagoblin.user_pages.user_home``. Okay, so then we look at the view at the -``mediagoblin.user_pages.views:user_home`` method:: +``mediagoblin.user_pages.user_home`` method:: @uses_pagination def user_home(request, page): @@ -90,7 +90,7 @@ Nice! So the template appears to be ``mediagoblin/user_pages/user.html``. Cool, that means that the key is:: - ("mediagoblin.user_pages.views:user_home", + ("mediagoblin.user_pages.user_home", "mediagoblin/user_pages/user.html") The context hook uses ``hook_transform()`` so that means that if we're @@ -102,11 +102,26 @@ and should return that modified object, like so:: return context hooks = { - ("mediagoblin.user_pages.views:user_home", + ("mediagoblin.user_pages.user_home", "mediagoblin/user_pages/user.html"): add_to_user_home_context} Global context hook +++++++++++++++++++ +If you need to add something to the context of *every* view, it is not +hard; there are two hooks hook that also uses hook_transform (like the +above) but make available what you are providing to *every* view. +Note that there is a slight, but critical, difference between the two. + +The most general one is the ``'template_global_context'`` hook. This +one is run only once, and is read into the global context... all views +will get access to what are in this dict. + +The slightly more expensive but more powerful one is +``'template_context_prerender'``. This one is not added to the global +context... it is added to the actual context of each individual +template render right before it is run! Because of this you also can +do some powerful and crazy things, such as checking the request object +or other parts of the context before passing them on. -- cgit v1.2.3 From 0553976187a4ec870f944d2d4d17a4951075d2a8 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 15 May 2013 11:10:25 -0500 Subject: Hook->hooks since there's more than one of them :) --- docs/source/pluginwriter/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index b411fa4d..56aaac77 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -106,8 +106,8 @@ and should return that modified object, like so:: "mediagoblin/user_pages/user.html"): add_to_user_home_context} -Global context hook -+++++++++++++++++++ +Global context hooks +++++++++++++++++++++ If you need to add something to the context of *every* view, it is not hard; there are two hooks hook that also uses hook_transform (like the -- cgit v1.2.3 From 38ebd05d1a759c3a057ab041124c313cf5724dc4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 15 May 2013 11:29:43 -0500 Subject: Simple tyop, view->test... I was writing too many tests at the time :) --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 56aaac77..5e0568fd 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -63,7 +63,7 @@ that has a key in the format of the tuple:: (view_symbolic_name, view_template_path) Where the "view symbolic name" is the same parameter used in -``request.urlgen()`` to look up the test. So say we're wanting to add +``request.urlgen()`` to look up the view. So say we're wanting to add something to the context of the user's homepage. We look in mediagoblin/user_pages/routing.py and see:: -- cgit v1.2.3 From d6d2c771bdc111cd26186b1bc42b44f2b3197e05 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 16 May 2013 10:38:45 -0500 Subject: Start of ability to have plugins provide static resources! Note I have not tested any of this yet ;) But we're already on our way: - We've got docs - The hook is there Lots to do still though. But, progress! :) This commit sponsored by Laura Arjona Reina. Thanks larjona! --- docs/source/pluginwriter/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 5e0568fd..cd06cbc5 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -125,3 +125,22 @@ context... it is added to the actual context of each individual template render right before it is run! Because of this you also can do some powerful and crazy things, such as checking the request object or other parts of the context before passing them on. + + +Adding static resources +----------------------- + +It's possible to add static resources for your plugin. Say your +plugin needs some special javascript and images... how to provide +them? Then how to access them? MediaGoblin has a way! + + +Attaching to the hook ++++++++++++++++++++++ + +First, you need to register your plugin's resources with the hook. +This is pretty easy actually: you just need to provide a function that +passes back a PluginStatic object. + +.. automodule:: mediagoblin.tools.staticdirect + :members: PluginStatic -- cgit v1.2.3 From 505b4b39b8ca7b273294e5d42d278dd1b89960ea Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 22 May 2013 11:51:46 -0500 Subject: Document assetlink and staticdirect usage for plugins. Still a bit to clean up around what the command to be run actually is, since that will likely change. This commit sponsored by David Decker. Thank you! --- docs/source/pluginwriter/api.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index cd06cbc5..1cfd65d7 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -144,3 +144,34 @@ passes back a PluginStatic object. .. automodule:: mediagoblin.tools.staticdirect :members: PluginStatic + + +Running plugin assetlink +++++++++++++++++++++++++ + +.. TODO: Fix this command when it lands elsewhere ;) + +In order for your plugin assets to be properly served by MediaGoblin, +your plugin's asset directory needs to be symlinked into the directory +that plugin assets are served from. To set this up, run:: + + ./bin/gmg theme assetlink + + +Using staticdirect +++++++++++++++++++ + +Once you have this, you will want to be able to of course link to your +assets! MediaGoblin has a "staticdirect" tool; you want to use this +like so in your templates:: + + staticdirect("css/monkeys.css", "mystaticname") + +Replace "mystaticname" with the name you passed to PluginStatic. The +staticdirect method is, for convenience, attached to the request +object, so you can access this in your templates like: + +.. code-block:: html + + A funny bunny -- cgit v1.2.3 From 24ede04415df1a79da83e2716ab3c714e2080563 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 23 May 2013 13:43:04 -0500 Subject: Documentation changes to reflect new plugin assetlink stuff - updated old theme assetlink section to reflect new location of ./bin/gmg assetlink and removed comment about the plugin command being temporary. - Added a new section to the standard config file on where to put the plugin_static section - Added release notes about said section This commit sponsored by Thomas Webber. Thanks, Dad! --- docs/source/pluginwriter/api.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 1cfd65d7..06295c77 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -149,13 +149,11 @@ passes back a PluginStatic object. Running plugin assetlink ++++++++++++++++++++++++ -.. TODO: Fix this command when it lands elsewhere ;) - In order for your plugin assets to be properly served by MediaGoblin, your plugin's asset directory needs to be symlinked into the directory that plugin assets are served from. To set this up, run:: - ./bin/gmg theme assetlink + ./bin/gmg assetlink Using staticdirect -- cgit v1.2.3 From 5de402781f9b5e9f4167d7d0d565e0c3ec8c4451 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 23 May 2013 15:56:07 -0500 Subject: Moving statcdirect automodule doc reference to autoclass per Elrond's suggestion. Cleaner! --- docs/source/pluginwriter/api.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 06295c77..44411965 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -142,8 +142,7 @@ First, you need to register your plugin's resources with the hook. This is pretty easy actually: you just need to provide a function that passes back a PluginStatic object. -.. automodule:: mediagoblin.tools.staticdirect - :members: PluginStatic +.. autoclass:: mediagoblin.tools.staticdirect.PluginStatic Running plugin assetlink -- cgit v1.2.3 From d861ffc9ad5118f251fa669028bf774d98b0b451 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 14:10:07 -0500 Subject: Link to the plugin api stuff and the database plugin sections from the quickstart. This commit sponsored by Nathan Stephenson. Thank you! --- docs/source/pluginwriter/api.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 44411965..dc6bcc98 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -11,6 +11,7 @@ Dedication along with this software. If not, see . +.. _plugin-api-chapter: ========== Plugin API -- cgit v1.2.3 From b21220e931e80fa9005f71c026eaa66f5ea225f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 14:13:12 -0500 Subject: Actually link to the release notes when we say "see the release notes". This commit sponsored by Brian Kemp. Thank you! --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index dc6bcc98..819fac2d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -24,7 +24,7 @@ Authors are encouraged to develop plugins and work with the MediaGoblin community to keep them up to date, but this API will be a moving target for a few releases. -Please check the release notes for updates! +Please check the :ref:`release-notes` for updates! :mod:`pluginapi` Module ----------------------- -- cgit v1.2.3 From 8ae5d20f197291a1cd2e211e4e5d5ede92718f52 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 15:35:37 -0500 Subject: Where do you find hooks? How do you add them? An explaination! This commit about talking to community members sponsored by community member Aeva Palecek. Thanks! --- docs/source/pluginwriter/api.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 819fac2d..33bb70c4 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -26,6 +26,26 @@ moving target for a few releases. Please check the :ref:`release-notes` for updates! + +How are hooks added? Where do I find them? +------------------------------------------- + +Much of this document talks about hooks, both as in terms of regular +hooks and template hooks. But where do they come from, and how can +you find a list of them? + +For the moment, the best way to find available hooks is to check the +source code itself. (Yes, we should start a more official hook +listing with descriptions soon.) But many hooks you may need do not +exist yet: what to do then? + +The plan at present is that we are adding hooks as people need them, +with community discussion. If you find that you need a hook and +MediaGoblin at present doesn't provide it at present, please +`http://mediagoblin.org/pages/join.html `_! We'll +evaluate what to do from there. + + :mod:`pluginapi` Module ----------------------- -- cgit v1.2.3 From baf2c1c96ec4dbcbb74518852ffdf516d670347c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 15:57:58 -0500 Subject: Additional hook tips! Documentation on how to modify a wtforms form. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit sponsored by Gian-Maria Daffré. Thank you! --- docs/source/pluginwriter/api.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 33bb70c4..2a7f3c2d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -193,3 +193,36 @@ object, so you can access this in your templates like: A funny bunny + + +Additional hook tips +-------------------- + +This section aims to explain some tips in regards to adding hooks to +the MediaGoblin repository. + +WTForms hooks +============= + +We haven't totally settled on a way to tranform wtforms form objects, +but here's one way. In your view:: + + from mediagoblin.foo.forms import SomeForm + + def some_view(request) + form_class = hook_transform('some_form_transform', SomeForm) + form = form_class(request.form) + +Then to hook into this form, do something in your plugin like:: + + import wtforms + + class SomeFormAdditions(wtforms.Form): + new_datefield = wtforms.DateField() + + def transform_some_form(orig_form): + class ModifiedForm(orig_form, SomeFormAdditions) + return ModifiedForm + + hooks = { + 'some_form_transform': transform_some_form} -- cgit v1.2.3 From 40019095748fef60ad08d10cbe69437f20d63735 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 16:12:24 -0500 Subject: Actually use the right underlining for the wtforms hooks section --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 2a7f3c2d..e5ac8df5 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -202,7 +202,7 @@ This section aims to explain some tips in regards to adding hooks to the MediaGoblin repository. WTForms hooks -============= ++++++++++++++ We haven't totally settled on a way to tranform wtforms form objects, but here's one way. In your view:: -- cgit v1.2.3 From 9d881aeeb4df2e9f02c4c1fea7d6435273081fdb Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 17:21:15 -0500 Subject: Provide a tip on how to do interfaces via our plugin API. Uses a frogputer science approach to frobbing as an example (which is total nonsense, but fun). This commit sponsored by Ryan Kelln. Thank you! --- docs/source/pluginwriter/api.rst | 66 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index e5ac8df5..3bb5f445 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -226,3 +226,69 @@ Then to hook into this form, do something in your plugin like:: hooks = { 'some_form_transform': transform_some_form} + + +Interfaces +++++++++++ + +If you want to add a pseudo-interface, it's not difficult to do so. +Just write the interface like so:: + + class FrobInterface(object): + """ + Interface for Frobbing. + + Classes implementing this interface should provide defrob and frob. + They may also implement double_frob, but it is not required; if + not provided, we will use a general technique. + """ + + def defrob(self, frobbed_obj): + """ + Take a frobbed_obj and defrob it. Returns the defrobbed object. + """ + raise NotImplementedError() + + def frob(self, normal_obj): + """ + Take a normal object and frob it. Returns the frobbed object. + """ + raise NotImplementedError() + + def double_frob(self, normal_obj): + """ + Frob this object and return it multiplied by two. + """ + return self.frob(normal_obj) * 2 + + + def some_frob_using_method(): + # something something something + frobber = hook_handle(FrobInterface) + frobber.frob(blah) + + # alternately you could have a default + frobber = hook_handle(FrobInterface) or DefaultFrobber + frobber.defrob(foo) + + +It's fine to use your interface as the key instead of a string if you +like. + +Then a plugin providing your interface can be like:: + + from mediagoblin.foo.frobfrogs import FrobInterface + from frogfrobber import utils + + class FrogFrobber(FrobInterface): + """ + Takes a frogputer science approach to frobbing. + """ + def defrob(self, frobbed_obj): + return utils.frog_defrob(frobbed_obj) + + def frob(self, normal_obj): + return utils.frog_frob(normal_obj) + + hooks = { + FrobInterface: lambda: return FrogFrobber} -- cgit v1.2.3 From ea49f37821410e4b46179853965cd9ac4f2b9688 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 18:10:09 -0500 Subject: Explained more clearly why it's okay for interface classes to be keys. This commit sponsored by Nick Glynn. Thank you! --- docs/source/pluginwriter/api.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/source/pluginwriter/api.rst') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 3bb5f445..66def173 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -273,7 +273,9 @@ Just write the interface like so:: It's fine to use your interface as the key instead of a string if you -like. +like. (Usually this is messy, but since interfaces are public and +since you need to import them into your plugin anyway, interfaces +might as well be keys.) Then a plugin providing your interface can be like:: -- cgit v1.2.3