# -*- coding: utf-8 -*- """ flaskbb.plugins.spec ~~~~~~~~~~~~~~~~~~~~~~~ This module provides the core FlaskBB plugin hook definitions :copyright: (c) 2017 by the FlaskBB Team. :license: BSD, see LICENSE for more details. """ from pluggy import HookspecMarker spec = HookspecMarker('flaskbb') # Setup Hooks @spec def flaskbb_extensions(app): """Hook for initializing any plugin loaded extensions.""" @spec def flaskbb_load_translations(): """Hook for registering translation folders.""" @spec def flaskbb_load_migrations(): """Hook for registering additional migrations.""" @spec def flaskbb_load_blueprints(app): """Hook for registering blueprints. :param app: The application object. """ @spec def flaskbb_request_processors(app): """Hook for registering pre/post request processors. :param app: The application object. """ @spec def flaskbb_errorhandlers(app): """Hook for registering error handlers. :param app: The application object. """ @spec def flaskbb_jinja_directives(app): """Hook for registering jinja filters, context processors, etc. :param app: The application object. """ @spec def flaskbb_additional_setup(app, pluggy): """Hook for any additional setup a plugin wants to do after all other application setup has finished. For example, you could apply a WSGI middleware:: @impl def flaskbb_additional_setup(app): app.wsgi_app = ProxyFix(app.wsgi_app) :param app: The application object. :param pluggy: The pluggy object. """ @spec def flaskbb_cli(cli, app): """Hook for registering CLI commands. For example:: @impl def flaskbb_cli(cli): @cli.command() def testplugin(): click.echo("Hello Testplugin") return testplugin :param app: The application object. :param cli: The FlaskBBGroup CLI object. """ @spec def flaskbb_shell_context(): """Hook for registering shell context handlers Expected to return a single callable function that returns a dictionary or iterable of key value pairs. """ # Event hooks @spec def flaskbb_event_post_save_before(post): """Hook for handling a post before it has been saved. :param flaskbb.forum.models.Post post: The post which triggered the event. """ @spec def flaskbb_event_post_save_after(post, is_new): """Hook for handling a post after it has been saved. :param flaskbb.forum.models.Post post: The post which triggered the event. :param bool is_new: True if the post is new, False if it is an edit. """ @spec def flaskbb_event_topic_save_before(topic): """Hook for handling a topic before it has been saved. :param flaskbb.forum.models.Topic topic: The topic which triggered the event. """ @spec def flaskbb_event_topic_save_after(topic, is_new): """Hook for handling a topic after it has been saved. :param flaskbb.forum.models.Topic topic: The topic which triggered the event. :param bool is_new: True if the topic is new, False if it is an edit. """ # Form hooks @spec def flaskbb_form_new_post(form): """Hook for modifying the :class:`~flaskbb.forum.forms.ReplyForm`. For example:: @impl def flaskbb_form_new_post(form): form.example = TextField("Example Field", validators=[ DataRequired(message="This field is required"), Length(min=3, max=50)]) :param form: The :class:`~flaskbb.forum.forms.ReplyForm` class. """ @spec def flaskbb_form_new_post_save(form): """Hook for modifying the :class:`~flaskbb.forum.forms.ReplyForm`. This hook is called while populating the post object with the data from the form. The post object will be saved after the hook call. :param form: The form object. :param post: The post object. """ @spec def flaskbb_form_new_topic(form): """Hook for modifying the :class:`~flaskbb.forum.forms.NewTopicForm` :param form: The :class:`~flaskbb.forum.forms.NewTopicForm` class. """ @spec def flaskbb_form_new_topic_save(form, topic): """Hook for modifying the :class:`~flaskbb.forum.forms.NewTopicForm`. This hook is called while populating the topic object with the data from the form. The topic object will be saved after the hook call. :param form: The form object. :param topic: The topic object. """ # Template Hooks @spec def flaskbb_tpl_navigation_before(): """Hook for registering additional navigation items. in :file:`templates/layout.html`. """ @spec def flaskbb_tpl_navigation_after(): """Hook for registering additional navigation items. in :file:`templates/layout.html`. """ @spec def flaskbb_tpl_user_nav_loggedin_before(): """Hook for registering additional user navigational items which are only shown when a user is logged in. in :file:`templates/layout.html`. """ @spec def flaskbb_tpl_user_nav_loggedin_after(): """Hook for registering additional user navigational items which are only shown when a user is logged in. in :file:`templates/layout.html`. """ @spec def flaskbb_tpl_form_registration_before(form): """This hook is emitted in the Registration form **before** the first input field but after the hidden CSRF token field. in :file:`templates/auth/register.html`. :param form: The form object. """ @spec def flaskbb_tpl_form_registration_after(form): """This hook is emitted in the Registration form **after** the last input field but before the submit field. in :file:`templates/auth/register.html`. :param form: The form object. """ @spec def flaskbb_tpl_form_user_details_before(form): """This hook is emitted in the Change User Details form **before** an input field is rendered. in :file:`templates/user/change_user_details.html`. :param form: The form object. """ @spec def flaskbb_tpl_form_user_details_after(form): """This hook is emitted in the Change User Details form **after** the last input field has been rendered but before the submit field. in :file:`templates/user/change_user_details.html`. :param form: The form object. """ @spec def flaskbb_tpl_profile_settings_menu(): """This hook is emitted on the user settings page in order to populate the side bar menu. Implementations of this hook should return a list of tuples that are view name and display text. The display text will be provided to the translation service so it is unnecessary to supply translated text. A plugin can declare a new block by setting the view to None. If this is done, consider marking the hook implementation with `trylast=True` to avoid capturing plugins that do not create new blocks. For example:: @impl(trylast=True) def flaskbb_tpl_profile_settings_menu(): return [ (None, 'Account Settings'), ('user.settings', 'General Settings'), ('user.change_user_details', 'Change User Details'), ('user.change_email', 'Change E-Mail Address'), ('user.change_password', 'Change Password') ] Hookwrappers for this spec should not be registered as FlaskBB supplies its own hookwrapper to flatten all the lists into a single list. in :file:`templates/user/settings_layout.html` """ @spec def flaskbb_tpl_admin_settings_menu(user): """This hook is emitted in the admin panel and used to add additional navigation links to the admin menu. Implementations of this hook should return a list of tuples that are view name, display text and optionally an icon. The display text will be provided to the translation service so it is unnecessary to supply translated text. For example:: @impl(trylast=True) def flaskbb_tpl_admin_settings_menu(): # only add this item if the user is an admin if Permission(IsAdmin, identity=current_user): return [ ("myplugin.foobar", "Foobar", "fa fa-foobar") ] Hookwrappers for this spec should not be registered as FlaskBB supplies its own hookwrapper to flatten all the lists into a single list. in :file:`templates/management/management_layout.html` :param user: The current user object. """ @spec def flaskbb_tpl_profile_sidebar_stats(user): """This hook is emitted on the users profile page below the standard information. For example, it can be used to add additional items such as a link to the profile. in :file:`templates/user/profile_layout.html` :param user: The user object for whom the profile is currently visited. """ @spec def flaskbb_tpl_post_author_info_before(user, post): """This hook is emitted before the information about the author of a post is displayed (but after the username). in :file:`templates/forum/topic.html` :param user: The user object of the post's author. :param post: The post object. """ @spec def flaskbb_tpl_post_author_info_after(user, post): """This hook is emitted after the information about the author of a post is displayed (but after the username). in :file:`templates/forum/topic.html` :param user: The user object of the post's author. :param post: The post object. """ @spec def flaskbb_tpl_post_content_before(post): """Hook to do some stuff before the post content is rendered. in :file:`templates/forum/topic.html` :param post: The current post object. """ @spec def flaskbb_tpl_post_content_after(post): """Hook to do some stuff after the post content is rendered. in :file:`templates/forum/topic.html` :param post: The current post object. """ @spec def flaskbb_tpl_post_menu_before(post): """Hook for inserting a new item at the beginning of the post menu. in :file:`templates/forum/topic.html` :param post: The current post object. """ @spec def flaskbb_tpl_post_menu_after(post): """Hook for inserting a new item at the end of the post menu. in :file:`templates/forum/topic.html` :param post: The current post object. """ @spec def flaskbb_tpl_topic_controls(topic): """Hook for inserting additional topic moderation controls. in :file:`templates/forum/topic_controls.html` :param topic: The current topic object. """ @spec def flaskbb_tpl_form_new_post_before(form): """Hook for inserting a new form field before the first field is rendered. For example:: @impl def flaskbb_tpl_form_new_post_after(form): return render_template_string( \"""
{{ form.example(class="form-control", placeholder=form.example.label.text) }} {%- for error in form.example.errors -%} {{error}} {%- endfor -%}
\""" in :file:`templates/forum/new_post.html` :param form: The form object. """ @spec def flaskbb_tpl_form_new_post_after(form): """Hook for inserting a new form field after the last field is rendered (but before the submit field). in :file:`templates/forum/new_post.html` :param form: The form object. """ @spec def flaskbb_tpl_form_new_topic_before(form): """Hook for inserting a new form field before the first field is rendered (but before the CSRF token). in :file:`templates/forum/new_topic.html` :param form: The form object. """ @spec def flaskbb_tpl_form_new_topic_after(form): """Hook for inserting a new form field after the last field is rendered (but before the submit button). in :file:`templates/forum/new_topic.html` :param form: The form object. """