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 + docs/source/pluginwriter/database.rst | 9 ++++++--- docs/source/pluginwriter/quickstart.rst | 6 ++++-- 3 files changed, 11 insertions(+), 5 deletions(-) (limited to 'docs/source') 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 diff --git a/docs/source/pluginwriter/database.rst b/docs/source/pluginwriter/database.rst index 58edf3a0..603a19eb 100644 --- a/docs/source/pluginwriter/database.rst +++ b/docs/source/pluginwriter/database.rst @@ -12,9 +12,12 @@ . -======== -Database -======== +.. _plugin-database-chapter: + + +=========================== +Database models for plugins +=========================== Accessing Existing Data diff --git a/docs/source/pluginwriter/quickstart.rst b/docs/source/pluginwriter/quickstart.rst index b5a63f79..6d45ea36 100644 --- a/docs/source/pluginwriter/quickstart.rst +++ b/docs/source/pluginwriter/quickstart.rst @@ -178,8 +178,10 @@ That's it for the quick start! Where to go from here ===================== -See the documentation on the plugin API for code samples and other -things you can use when building your plugin. +See the documentation on the :ref:`plugin-api-chapter` for code +samples and other things you can use when building your plugin. If +your plugin needs its own database models, see +:ref:`plugin-database-chapter`. See `Hitchhiker's Guide to Packaging `_ for more information on -- 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 +- docs/source/siteadmin/relnotes.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/source') 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 ----------------------- diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index d25771d3..9c9d311c 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -11,6 +11,8 @@ Dedication along with this software. If not, see . +.. _release-notes: + ============= Release Notes ============= -- 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') 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') 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') 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') 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') 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