# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2013, Various
# This file is distributed under the same license as the Elgg package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Elgg master\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2021-07-09 15:46+0200\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: ../../guides/access.rst:2
msgid "Access Control Lists"
msgstr ""

#: ../../guides/access.rst:4
msgid "An Access Control List (or ACL) can grant one or more users access to an entity or annotation in the database."
msgstr ""

#: ../../guides/access.rst:8
#: ../../guides/actions.rst:16
#: ../../guides/ajax.rst:8
#: ../../guides/database.rst:8
#: ../../guides/email.rst:10
#: ../../guides/events-list.rst:8
#: ../../guides/file-system.rst:6
#: ../../guides/guidelines.rst:18
#: ../../guides/helpers.rst:6
#: ../../guides/javascript.rst:6
#: ../../guides/menus.rst:12
#: ../../guides/notifications.rst:10
#: ../../guides/plugins.rst:8
#: ../../guides/plugins/bootstrap.rst:13
#: ../../guides/plugins/dependencies.rst:8
#: ../../guides/search.rst:7
#: ../../guides/settings.rst:6
#: ../../guides/themes.rst:14
#: ../../guides/views.rst:6
#: ../../guides/web-services.rst:24
#: ../../guides/web-services/result.rst:6
#: ../../guides/widgets.rst:8
msgid "Contents"
msgstr ""

#: ../../guides/access.rst:12
msgid ":ref:`Database Access Control <database-access-control>`"
msgstr ""

#: ../../guides/access.rst:15
msgid "Creating an ACL"
msgstr ""

#: ../../guides/access.rst:17
msgid "An access collection can be create by using the function `create_access_collection()`."
msgstr ""

#: ../../guides/access.rst:26
msgid "ACL subtypes"
msgstr ""

#: ../../guides/access.rst:28
msgid "ACLs can have a subtype, this is to help differentiate between the usage of the ACL. It's higly recommended to set a subtype for an ACL."
msgstr ""

#: ../../guides/access.rst:31
msgid "Elgg core has three examples of subtype usage"
msgstr ""

#: ../../guides/access.rst:33
msgid "``group_acl`` an ACL owned by an ``ElggGroup`` which grants group members access to content shared with the group"
msgstr ""

#: ../../guides/access.rst:34
msgid "``friends`` an ACL owned by an ``ElggUser`` which grant friends of a user access to content shared with friends"
msgstr ""

#: ../../guides/access.rst:35
msgid "``friends_collection`` an ACL owned by an ``ElggUser`` which grant specific friends access to content shared with the ACL"
msgstr ""

#: ../../guides/access.rst:38
msgid "Adding users to an ACL"
msgstr ""

#: ../../guides/access.rst:40
msgid "If you have an ACL you still need to add users to it in order to grant those users access to content with the `access_id` of the ACLs `id`."
msgstr ""

#: ../../guides/access.rst:60
msgid "Removing users from an ACL"
msgstr ""

#: ../../guides/access.rst:62
msgid "If you no longer wish to allow access for a given user in an ACL you can easily remove that user from the list."
msgstr ""

#: ../../guides/access.rst:76
msgid "Retrieving an ACL"
msgstr ""

#: ../../guides/access.rst:78
msgid "In order to manage an ACL, or add the ID of an ACL to an access list there are several functions available to retrieve an ACL from the database."
msgstr ""

#: ../../guides/access.rst:112
msgid "Read access"
msgstr ""

#: ../../guides/access.rst:114
msgid "The access system of Elgg automaticly adds all the ACLs a user is a member of to the access checks. For example a user is a member of a group and is friends with 3 other users, all the corresponding ACLs are added in order to check access to entities when retrieving them (eg. listing all blogs)."
msgstr ""

#: ../../guides/access.rst:119
msgid "Ignoring access"
msgstr ""

#: ../../guides/access.rst:121
msgid "If for some case you need entities retrieved ignoring the access rules you can wrap your code in ``elgg_call``. There are different flags you can use."
msgstr ""

#: ../../guides/access.rst:124
msgid "ELGG_IGNORE_ACCESS: no access rules are applied"
msgstr ""

#: ../../guides/access.rst:125
msgid "ELGG_ENFORCE_ACCESS: access rules are forced to be applied"
msgstr ""

#: ../../guides/access.rst:126
msgid "ELGG_SHOW_DISABLED_ENTITIES: will retrieve entities that are disabled"
msgstr ""

#: ../../guides/access.rst:127
msgid "ELGG_HIDE_DISABLED_ENTITIES: will never retrieve entities that are disabled"
msgstr ""

#: ../../guides/access.rst:139
msgid "You can also combine flags."
msgstr ""

#: ../../guides/accessibility.rst:2
msgid "Accessibility"
msgstr ""

#: ../../guides/accessibility.rst:4
msgid "This page aims to list and document accessibility rules and best practices, to help core and plugins developpers to make Elgg the most accessible social engine framework that everyone dreams of."
msgstr ""

#: ../../guides/accessibility.rst:8
msgid "This is an ongoing work, please contribute on `Github <https://github.com/Elgg/Elgg>`_ if you have some skills in this field!"
msgstr ""

#: ../../guides/accessibility.rst:11
msgid "Resources + references"
msgstr ""

#: ../../guides/accessibility.rst:13
msgid "`Official WCAG Accessibility Guidelines Overview <http://www.w3.org/WAI/WCAG20/glance/>`_"
msgstr ""

#: ../../guides/accessibility.rst:14
msgid "`Official WCAG Accessibility Guidelines <http://www.w3.org/TR/WCAG/>`_"
msgstr ""

#: ../../guides/accessibility.rst:15
msgid "`Resources for planning and implementing for accessibility <http://www.w3.org/WAI/managing>`_"
msgstr ""

#: ../../guides/accessibility.rst:16
msgid "`Practical tips from the W3C for improving accessibility <http://www.w3.org/WAI/impl/improving>`_"
msgstr ""

#: ../../guides/accessibility.rst:17
msgid "`Preliminary review of websites for accessibility <http://www.w3.org/WAI/eval/preliminary.html>`_"
msgstr ""

#: ../../guides/accessibility.rst:18
msgid "`Tools for checking the accessibility of websites <http://www.w3.org/WAI/ER/tools/>`_"
msgstr ""

#: ../../guides/accessibility.rst:19
msgid "`List of practical techniques for implementing accessibility <http://www.w3.org/TR/WCAG20-TECHS/Overview.html#contents>`_ (It would be great if someone could go through this and filter out all the ones that are relevant to Elgg)"
msgstr ""

#: ../../guides/accessibility.rst:22
msgid "Tips for implementing accessibility"
msgstr ""

#: ../../guides/accessibility.rst:24
msgid "All accessibility-related tickets reported to trac should be tagged with \"a11y\", short for \"accessibility\""
msgstr ""

#: ../../guides/accessibility.rst:25
msgid "Use core views such as ``output/*``, and ``input/*`` to generate markup, since we can bake a11y concerns into these views"
msgstr ""

#: ../../guides/accessibility.rst:26
msgid "All images should have a descriptive ``alt`` attribute. Spacer or purely decorative graphics should have blank ``alt`` attributes"
msgstr ""

#: ../../guides/accessibility.rst:27
msgid "All ``<a>`` tags should have text or an accessible image inside. Otherwise screen readers will have to read the URL, which is a poor experience ``<a>`` tags should contain descriptive text, if possible, as opposed to generic text like \"Click here\""
msgstr ""

#: ../../guides/accessibility.rst:28
msgid "Markup should be valid"
msgstr ""

#: ../../guides/accessibility.rst:29
msgid "Themes should not reset \"outline\" to nothing. ``:focus`` deserves a special visual treatment so that handicapped users can know where they are"
msgstr ""

#: ../../guides/accessibility.rst:32
msgid "Tips for testing accessibility"
msgstr ""

#: ../../guides/accessibility.rst:34
msgid "Use the tools linked to from the resources section. `Example report for community.elgg.org on June 16, 2012 <http://try.powermapper.com/Reports/a6276098-0883-4d04-849e-8c05999812f2/report/map.htm>`_"
msgstr ""

#: ../../guides/accessibility.rst:35
msgid "Try different font-size/zoom settings in your browser and make sure the theme remains usable"
msgstr ""

#: ../../guides/accessibility.rst:36
msgid "Turn off css to make sure the sequential order of the page makes sense"
msgstr ""

#: ../../guides/accessibility.rst:39
msgid "Documentation objectives and principles"
msgstr ""

#: ../../guides/accessibility.rst:41
msgid "Main accessibility rules"
msgstr ""

#: ../../guides/accessibility.rst:42
msgid "collect and document best practices"
msgstr ""

#: ../../guides/accessibility.rst:43
msgid "Provide code examples"
msgstr ""

#: ../../guides/accessibility.rst:44
msgid "Keep the document simple and usable"
msgstr ""

#: ../../guides/accessibility.rst:45
msgid "Make it usable for both beginner developpers and experts (from most common and easiest changes to elaborate techniques)"
msgstr ""

#: ../../guides/actions.rst:2
msgid "Forms + Actions"
msgstr ""

#: ../../guides/actions.rst:4
msgid "Create, update, or delete content."
msgstr ""

#: ../../guides/actions.rst:6
msgid "Elgg forms submit to actions. Actions define the behavior for form submission."
msgstr ""

#: ../../guides/actions.rst:8
msgid "This guide assumes basic familiarity with:"
msgstr ""

#: ../../guides/actions.rst:10
#: ../../guides/themes.rst:9
msgid ":doc:`/admin/plugins`"
msgstr ""

#: ../../guides/actions.rst:11
#: ../../guides/themes.rst:10
msgid ":doc:`views`"
msgstr ""

#: ../../guides/actions.rst:12
msgid ":doc:`i18n`"
msgstr ""

#: ../../guides/actions.rst:19
msgid "Registering actions"
msgstr ""

#: ../../guides/actions.rst:21
msgid "Actions must be registered before use."
msgstr ""

#: ../../guides/actions.rst:23
msgid "There are two ways to register actions:"
msgstr ""

#: ../../guides/actions.rst:25
msgid "Using ``elgg_register_action()``"
msgstr ""

#: ../../guides/actions.rst:31
msgid "The ``mod/example/actions/example.php`` script will now be run whenever a form is submitted to ``http://localhost/elgg/action/example``."
msgstr ""

#: ../../guides/actions.rst:33
msgid "Use ``elgg-plugin.php``"
msgstr ""

#: ../../guides/actions.rst:59
msgid "A stumbling point for many new developers is the URL for actions. The URL always uses ``/action/`` (singular) and never ``/actions/`` (plural). However, action script files are usually saved under the directory ``/actions/`` (plural) and always have an extension. Use ``elgg_generate_action_url()`` to avoid confusion."
msgstr ""

#: ../../guides/actions.rst:64
msgid "Registering actions using plugin config file"
msgstr ""

#: ../../guides/actions.rst:65
msgid "You can also register actions via the :doc:`elgg-plugin</guides/plugins>` config file. To do this you need to provide an action section in the config file. The location of the action files are assumed to be in the plugin folder  ``/actions``."
msgstr ""

#: ../../guides/actions.rst:84
msgid "Permissions"
msgstr ""

#: ../../guides/actions.rst:85
msgid "By default, actions are only available to logged in users."
msgstr ""

#: ../../guides/actions.rst:87
msgid "To make an action available to logged out users, pass ``\"public\"`` as the third parameter:"
msgstr ""

#: ../../guides/actions.rst:93
msgid "To restrict an action to only administrators, pass ``\"admin\"`` for the last parameter:"
msgstr ""

#: ../../guides/actions.rst:100
msgid "Writing action files"
msgstr ""

#: ../../guides/actions.rst:102
msgid "Use the ``get_input()`` function to get access to request parameters:"
msgstr ""

#: ../../guides/actions.rst:108
msgid "You can then use the :doc:`database` api to load entities and perform actions on them accordingly."
msgstr ""

#: ../../guides/actions.rst:110
msgid "To indicate a successful action, use ``elgg_ok_response()``. This function accepts data that you want to make available to the client for XHR calls (this data will be ignored for non-XHR calls)"
msgstr ""

#: ../../guides/actions.rst:128
msgid "To indicate an error, use ``elgg_error_response()``"
msgstr ""

#: ../../guides/actions.rst:146
msgid "Customizing actions"
msgstr ""

#: ../../guides/actions.rst:148
msgid "Before executing any action, Elgg triggers a hook:"
msgstr ""

#: ../../guides/actions.rst:154
msgid "Where ``$action`` is the action being called. If the hook returns ``false`` then the action will not be executed. Don't return anything if your validation passes."
msgstr ""

#: ../../guides/actions.rst:158
msgid "Example: Captcha"
msgstr ""

#: ../../guides/actions.rst:160
msgid "The captcha module uses this to intercept the ``register`` and ``user/requestnewpassword`` actions and redirect them to a function which checks the captcha code. This check returns ``false`` if the captcha validation fails (which prevents the associated action from executing)."
msgstr ""

#: ../../guides/actions.rst:164
msgid "This is done as follows:"
msgstr ""

#: ../../guides/actions.rst:186
msgid "This lets a plugin extend an existing action without the need to replace the whole action. In the case of the captcha plugin it allows the plugin to provide captcha support in a very loosely coupled way."
msgstr ""

#: ../../guides/actions.rst:190
msgid "Actions available in core"
msgstr ""

#: ../../guides/actions.rst:193
msgid "``entity/delete``"
msgstr ""

#: ../../guides/actions.rst:195
msgid "If your plugin does not implement any custom logic when deleting an entity, you can use bundled delete action"
msgstr ""

#: ../../guides/actions.rst:211
msgid "You can customize the success message keys for your entity type and subtype, using ``\"entity:delete:$type:$subtype:success\"`` and ``\"entity:delete:$type:success\"`` keys."
msgstr ""

#: ../../guides/actions.rst:224
msgid "Forms"
msgstr ""

#: ../../guides/actions.rst:226
msgid "To output a form, use the elgg_view_form function like so:"
msgstr ""

#: ../../guides/actions.rst:232
msgid "Doing this generates something like the following markup:"
msgstr ""

#: ../../guides/actions.rst:243
msgid "Elgg does some things automatically for you when you generate forms this way:"
msgstr ""

#: ../../guides/actions.rst:245
msgid "It sets the action to the appropriate URL based on the name of the action you pass to it"
msgstr ""

#: ../../guides/actions.rst:246
msgid "It adds some anti-csrf tokens (``__elgg_ts`` and ``__elgg_token``) to help keep your actions secure"
msgstr ""

#: ../../guides/actions.rst:247
msgid "It automatically looks for the body of the form in the ``forms/example`` view."
msgstr ""

#: ../../guides/actions.rst:249
msgid "Put the content of your form in your plugin’s ``forms/example`` view:"
msgstr ""

#: ../../guides/actions.rst:260
msgid "Now when you call ``elgg_view_form('example')``, Elgg will produce:"
msgstr ""

#: ../../guides/actions.rst:277
msgid "Inputs"
msgstr ""

#: ../../guides/actions.rst:279
msgid "To render a form input, use one of the bundled input views, which cover all standard HTML input elements. See individual view files for a list of accepted parameters."
msgstr ""

#: ../../guides/actions.rst:296
msgid "The above example will render a dropdown select input:"
msgstr ""

#: ../../guides/actions.rst:305
msgid "To ensure consistency in field markup, use ``elgg_view_field()``, which accepts all the parameters of the input being rendered, as well as ``#label`` and ``#help`` parameters (both of which are optional and accept HTML or text)."
msgstr ""

#: ../../guides/actions.rst:324
msgid "The above will generate the following markup:"
msgstr ""

#: ../../guides/actions.rst:342
msgid "Input types"
msgstr ""

#: ../../guides/actions.rst:344
msgid "A list of bundled input types/views:"
msgstr ""

#: ../../guides/actions.rst:346
msgid "``input/text`` - renders a text input ``<input type=\"text\">``"
msgstr ""

#: ../../guides/actions.rst:347
msgid "``input/plaintext`` - renders a textarea ``<textarea></textarea>``"
msgstr ""

#: ../../guides/actions.rst:348
msgid "``input/longtext`` - renders a WYSIWYG text input"
msgstr ""

#: ../../guides/actions.rst:349
msgid "``input/url`` - renders a url input ``<input type=\"url\">``"
msgstr ""

#: ../../guides/actions.rst:350
msgid "``input/email`` - renders an email input ``<input type=\"email\">``"
msgstr ""

#: ../../guides/actions.rst:351
msgid "``input/checkbox`` - renders a single checkbox ``<input type=\"checkbox\">``"
msgstr ""

#: ../../guides/actions.rst:352
msgid "``input/checkboxes`` - renders a set of checkboxes with the same name"
msgstr ""

#: ../../guides/actions.rst:353
msgid "``input/radio`` - renders one or more radio buttons ``<input type=\"radio\">``"
msgstr ""

#: ../../guides/actions.rst:354
msgid "``input/submit`` - renders a submit button ``<button type=\"submit\">``"
msgstr ""

#: ../../guides/actions.rst:355
msgid "``input/button`` - renders a button ``<button></button>``"
msgstr ""

#: ../../guides/actions.rst:356
msgid "``input/file`` - renders a file input ``<input type=\"file\">``"
msgstr ""

#: ../../guides/actions.rst:357
msgid "``input/select`` - renders a select input ``<select></select>``"
msgstr ""

#: ../../guides/actions.rst:358
msgid "``input/hidden`` - renders a hidden input ``<input type=\"hidden\">``"
msgstr ""

#: ../../guides/actions.rst:359
msgid "``input/password`` - renders a password input ``<input type=\"password\">``"
msgstr ""

#: ../../guides/actions.rst:360
msgid "``input/number`` - renders a number input ``<input type=\"number\">``"
msgstr ""

#: ../../guides/actions.rst:361
msgid "``input/date`` - renders a jQuery datepicker"
msgstr ""

#: ../../guides/actions.rst:363
msgid "Elgg offers some helper input types"
msgstr ""

#: ../../guides/actions.rst:365
msgid "``input/access`` - renders an Elgg access level select"
msgstr ""

#: ../../guides/actions.rst:366
msgid "``input/tags`` - renders an Elgg tags input"
msgstr ""

#: ../../guides/actions.rst:367
msgid "``input/autocomplete`` - renders an Elgg entity autocomplete"
msgstr ""

#: ../../guides/actions.rst:368
msgid "``input/captcha`` - placeholder view for plugins to extend"
msgstr ""

#: ../../guides/actions.rst:369
msgid "``input/friendspicker`` - renders an Elgg friend autocomplete"
msgstr ""

#: ../../guides/actions.rst:370
msgid "``input/userpicker`` - renders an Elgg user autocomplete"
msgstr ""

#: ../../guides/actions.rst:371
msgid "``input/location`` renders an Elgg location input"
msgstr ""

#: ../../guides/actions.rst:374
msgid "Files and images"
msgstr ""

#: ../../guides/actions.rst:376
msgid "Use the ``input/file`` view in your form’s content view."
msgstr ""

#: ../../guides/actions.rst:383
msgid "If you wish to upload an icon for entity you can use the helper view ``entity/edit/icon``. This view shows a file input for uploading a new icon for the entity, an thumbnail of the current icon and the option to remove the current icon."
msgstr ""

#: ../../guides/actions.rst:387
msgid "The view supports some variables to control the output"
msgstr ""

#: ../../guides/actions.rst:389
msgid "``entity`` - the entity to add/remove the icon for. If provided based on this entity the thumbnail and remove option wil be shown"
msgstr ""

#: ../../guides/actions.rst:390
msgid "``entity_type`` - the entity type for which the icon will be uploaded. Plugins could find this usefull, maybe to validate icon sizes"
msgstr ""

#: ../../guides/actions.rst:391
msgid "``entity_subtype`` - the entity subtype for which the icon will be uploaded. Plugins could find this usefull, maybe to validate icon sizes"
msgstr ""

#: ../../guides/actions.rst:392
msgid "``icon_type`` - the type of the icon (default: icon)"
msgstr ""

#: ../../guides/actions.rst:393
msgid "``name`` - name of the input/file (default: icon)"
msgstr ""

#: ../../guides/actions.rst:394
msgid "``remove_name`` - name of the remove icon toggle (default: $vars['name'] . '_remove')"
msgstr ""

#: ../../guides/actions.rst:395
msgid "``required`` - is icon upload required (default: false)"
msgstr ""

#: ../../guides/actions.rst:396
msgid "``show_remove`` - show the remove icon option (default: true)"
msgstr ""

#: ../../guides/actions.rst:397
msgid "``show_thumb`` - show the thumb of the entity if available (default: true)"
msgstr ""

#: ../../guides/actions.rst:398
msgid "``thumb_size`` - the icon size to use as the thumb (default: medium)"
msgstr ""

#: ../../guides/actions.rst:400
msgid "If using the helper view you can use the following code in you action to save the icon to the entity or remove the current icon."
msgstr ""

#: ../../guides/actions.rst:410
msgid "Set the enctype of the form to ``multipart/form-data``:"
msgstr ""

#: ../../guides/actions.rst:420
msgid "The ``enctype`` of all forms that use the method ``POST`` defaults to ``multipart/form-data``."
msgstr ""

#: ../../guides/actions.rst:422
msgid "In your action file, use ``elgg_get_uploaded_file('your-input-name')`` to access the uploaded file:"
msgstr ""

#: ../../guides/actions.rst:429
msgid "Sticky forms"
msgstr ""

#: ../../guides/actions.rst:431
msgid "Sticky forms are forms that retain user input if saving fails. They are \"sticky\" because the user's data \"sticks\" in the form after submitting, though it was never saved to the database. This greatly improves the user experience by minimizing data loss. Elgg includes helper functions so you can make any form sticky."
msgstr ""

#: ../../guides/actions.rst:436
#: ../../guides/helpers.rst:2
msgid "Helper functions"
msgstr ""

#: ../../guides/actions.rst:438
msgid "Sticky forms are implemented in Elgg by the following functions:"
msgstr ""

#: ../../guides/actions.rst:440
msgid "``elgg_make_sticky_form($name)`` - Tells the engine to make all input on a form sticky."
msgstr ""

#: ../../guides/actions.rst:441
msgid "``elgg_clear_sticky_form($name)`` - Tells the engine to discard all sticky input on a form."
msgstr ""

#: ../../guides/actions.rst:442
msgid "``elgg_is_sticky_form($name)`` - Checks if ``$name`` is a valid sticky form."
msgstr ""

#: ../../guides/actions.rst:443
msgid "``elgg_get_sticky_values($name)`` - Returns all sticky values saved for ``$name`` by ``elgg_make_sticky_form($name)``."
msgstr ""

#: ../../guides/actions.rst:446
#: ../../guides/ajax.rst:11
#: ../../guides/i18n.rst:15
#: ../../guides/plugins/dependencies.rst:11
msgid "Overview"
msgstr ""

#: ../../guides/actions.rst:448
msgid "The basic flow of using sticky forms is:"
msgstr ""

#: ../../guides/actions.rst:450
msgid "Call ``elgg_make_sticky_form($name)`` at the top of actions for forms you want to be sticky."
msgstr ""

#: ../../guides/actions.rst:451
msgid "Use ``elgg_is_sticky_form($name)`` and ``elgg_get_sticky_values($name)`` to get sticky values when rendering a form view."
msgstr ""

#: ../../guides/actions.rst:452
msgid "Call ``elgg_clear_sticky_form($name)`` after the action has completed successfully or after data has been loaded by ``elgg_get_sticky_values($name)``."
msgstr ""

#: ../../guides/actions.rst:455
msgid "Example: User registration"
msgstr ""

#: ../../guides/actions.rst:457
msgid "Simple sticky forms require little logic to determine the input values for the form. This logic is placed at the top of the form body view itself."
msgstr ""

#: ../../guides/actions.rst:460
msgid "The registration form view first sets default values for inputs, then checks if there are sticky values. If so, it loads the sticky values before clearing the sticky form:"
msgstr ""

#: ../../guides/actions.rst:476
msgid "The registration action sets creates the sticky form and clears it once the action is completed:"
msgstr ""

#: ../../guides/actions.rst:493
msgid "Example: Bookmarks"
msgstr ""

#: ../../guides/actions.rst:495
msgid "The bundled plugin Bookmarks' save form and action is an example of a complex sticky form."
msgstr ""

#: ../../guides/actions.rst:497
msgid "The form view for the save bookmark action uses ``elgg_extract()`` to pull values from the ``$vars`` array:"
msgstr ""

#: ../../guides/actions.rst:511
msgid "The page handler scripts prepares the form variables and calls ``elgg_view_form()`` passing the correct values:"
msgstr ""

#: ../../guides/actions.rst:519
msgid "Similarly, ``mod/bookmarks/pages/edit.php`` uses the same function, but passes the entity that is being edited as an argument:"
msgstr ""

#: ../../guides/actions.rst:531
msgid "The library file defines ``bookmarks_prepare_form_vars()``. This function accepts an ``ElggEntity`` as an argument and does 3 things:"
msgstr ""

#: ../../guides/actions.rst:533
msgid "Defines the input names and default values for form inputs."
msgstr ""

#: ../../guides/actions.rst:534
msgid "Extracts the values from a bookmark object if it's passed."
msgstr ""

#: ../../guides/actions.rst:535
msgid "Extracts the values from a sticky form if it exists."
msgstr ""

#: ../../guides/actions.rst:574
msgid "The save action checks the input, then clears the sticky form upon success:"
msgstr ""

#: ../../guides/actions.rst:588
#: ../../guides/ajax.rst:2
#: ../../guides/hooks-list.rst:373
msgid "Ajax"
msgstr ""

#: ../../guides/actions.rst:590
msgid "See the :doc:`Ajax guide</guides/ajax>` for instructions on calling actions from JavaScript."
msgstr ""

#: ../../guides/actions.rst:593
#: ../../guides/web-services.rst:27
msgid "Security"
msgstr ""

#: ../../guides/actions.rst:595
msgid "For enhanced security, all actions require an CSRF token. Calls to action URLs that do not include security tokens will be ignored and a warning will be generated."
msgstr ""

#: ../../guides/actions.rst:598
msgid "A few views and functions automatically generate security tokens:"
msgstr ""

#: ../../guides/actions.rst:607
msgid "In rare cases, you may need to generate tokens manually:"
msgstr ""

#: ../../guides/actions.rst:614
msgid "You can also access the tokens from javascript:"
msgstr ""

#: ../../guides/actions.rst:621
msgid "These are refreshed periodically so should always be up-to-date."
msgstr ""

#: ../../guides/actions.rst:624
msgid "Security Tokens"
msgstr ""

#: ../../guides/actions.rst:626
msgid "On occasion we need to pass data through an untrusted party or generate an \"unguessable token\" based on some data. The industry-standard `HMAC <http://security.stackexchange.com/a/20301/4982>`_ algorithm is the right tool for this. It allows us to verify that received data were generated by our site, and were not tampered with. Note that even strong hash functions like SHA-2 should *not* be used without HMAC for these tasks."
msgstr ""

#: ../../guides/actions.rst:631
msgid "Elgg provides ``elgg_build_hmac()`` to generate and validate HMAC message authentication codes that are unguessable without the site's private key."
msgstr ""

#: ../../guides/actions.rst:655
msgid "Note: If you use a non-string as HMAC data, you must use types consistently. Consider the following:"
msgstr ""

#: ../../guides/actions.rst:668
msgid "Signed URLs"
msgstr ""

#: ../../guides/actions.rst:670
msgid "Signed URLs offer a limited level of security for situations where action tokens are not suitable, for example when sending a confirmation link via email. URL signatures verify that the URL has been generated by your Elgg installation (using site secret) and that the URL query elements were not tampered with."
msgstr ""

#: ../../guides/actions.rst:674
msgid "URLs a signed with an unguessable SHA-256 HMAC key. See `Security Tokens`_ for more details."
msgstr ""

#: ../../guides/actions.rst:688
msgid "Signed URLs do not offer CSRF protection and should not be used instead of action tokens."
msgstr ""

#: ../../guides/ajax.rst:4
msgid "The ``elgg/Ajax`` AMD module (introduced in Elgg 2.1) provides a set of methods for communicating with the server in a concise and uniform way, which allows plugins to collaborate on the request data, the server response, and the returned client-side data."
msgstr ""

#: ../../guides/ajax.rst:13
msgid "All the ajax methods perform the following:"
msgstr ""

#: ../../guides/ajax.rst:15
msgid "Client-side, the ``data`` option (if given as an object) is filtered by the hook ``ajax_request_data``."
msgstr ""

#: ../../guides/ajax.rst:16
msgid "The request is made to the server, either rendering a view or a form, calling an action, or loading a path."
msgstr ""

#: ../../guides/ajax.rst:17
msgid "The method returns a ``jqXHR`` object, which can be used as a Promise."
msgstr ""

#: ../../guides/ajax.rst:18
msgid "Server-echoed content is turned into a response object (``Elgg\\Services\\AjaxResponse``) containing a string (or a JSON-parsed value)."
msgstr ""

#: ../../guides/ajax.rst:19
msgid "The response object is filtered by the hook ``ajax_response``."
msgstr ""

#: ../../guides/ajax.rst:20
msgid "The response object is used to create the HTTP response."
msgstr ""

#: ../../guides/ajax.rst:21
msgid "Client-side, the response data is filtered by the hook ``ajax_response_data``."
msgstr ""

#: ../../guides/ajax.rst:22
msgid "The ``jqXHR`` promise is resolved and any ``success`` callbacks are called."
msgstr ""

#: ../../guides/ajax.rst:24
msgid "More notes:"
msgstr ""

#: ../../guides/ajax.rst:26
msgid "All hooks have a type depending on the method and first argument. See below."
msgstr ""

#: ../../guides/ajax.rst:27
msgid "By default the ``elgg/spinner`` module is automatically used during requests."
msgstr ""

#: ../../guides/ajax.rst:28
msgid "User messages generated by ``system_message()`` and ``register_error()`` are collected and displayed on the client."
msgstr ""

#: ../../guides/ajax.rst:29
msgid "Elgg gives you a default error handler that shows a generic message if output fails."
msgstr ""

#: ../../guides/ajax.rst:30
msgid "PHP exceptions or denied resource return HTTP error codes, resulting in use of the client-side error handler."
msgstr ""

#: ../../guides/ajax.rst:31
msgid "The default HTTP method is ``POST`` for actions, otherwise ``GET``. You can set it via ``options.method``."
msgstr ""

#: ../../guides/ajax.rst:32
msgid "If a non-empty ``options.data`` is given, the default method is always ``POST``."
msgstr ""

#: ../../guides/ajax.rst:33
msgid "For client caching, set ``options.method`` to ``\"GET\"`` and ``options.data.elgg_response_ttl`` to the max-age you want in seconds."
msgstr ""

#: ../../guides/ajax.rst:34
msgid "To save system messages for the next page load, set ``options.data.elgg_fetch_messages = 0``. You may want to do this if you intent to redirect the user based on the response."
msgstr ""

#: ../../guides/ajax.rst:35
msgid "To stop client-side API from requiring AMD modules required server-side with ``elgg_require_js()``, set ``options.data.elgg_fetch_deps = 0``."
msgstr ""

#: ../../guides/ajax.rst:36
msgid "All methods accept a query string in the first argument. This is passed on to the fetch URL, but does not appear in the hook types."
msgstr ""

#: ../../guides/ajax.rst:39
msgid "Performing actions"
msgstr ""

#: ../../guides/ajax.rst:41
msgid "Consider this action:"
msgstr ""

#: ../../guides/ajax.rst:60
msgid "To execute it, use ``ajax.action('<action_name>', options)``:"
msgstr ""

#: ../../guides/ajax.rst:77
msgid "Notes for actions:"
msgstr ""

#: ../../guides/ajax.rst:81
msgid "All hooks have type ``action:<action_name>``. So in this case, three hooks will be triggered:"
msgstr ""

#: ../../guides/ajax.rst:80
msgid "client-side ``\"ajax_request_data\", \"action:do_math\"`` to filter the request data (before it's sent)"
msgstr ""

#: ../../guides/ajax.rst:81
msgid "server-side ``\"ajax_response\", \"action:do_math\"`` to filter the response (after the action runs)"
msgstr ""

#: ../../guides/ajax.rst:82
msgid "client-side ``\"ajax_response_data\", \"action:do_math\"`` to filter the response data (before the calling code receives it)"
msgstr ""

#: ../../guides/ajax.rst:83
msgid "CSRF tokens are added to the request data."
msgstr ""

#: ../../guides/ajax.rst:84
msgid "The default method is ``POST``."
msgstr ""

#: ../../guides/ajax.rst:85
msgid "An absolute action URL can be given in place of the action name."
msgstr ""

#: ../../guides/ajax.rst:87
msgid "When setting ``data``, use ``ajax.objectify($form)`` instead of ``$form.serialize()``. Doing so allows the ``ajax_request_data`` plugin hook to fire and other plugins to alter/piggyback on the request."
msgstr ""

#: ../../guides/ajax.rst:91
msgid "Fetching data"
msgstr ""

#: ../../guides/ajax.rst:93
msgid "Consider this PHP script that runs at ``http://example.org/myplugin_time``."
msgstr ""

#: ../../guides/ajax.rst:117
msgid "To fetch its output, use ``ajax.path('<url_path>', options)``."
msgstr ""

#: ../../guides/ajax.rst:129
msgid "Notes for paths:"
msgstr ""

#: ../../guides/ajax.rst:131
msgid "The 3 hooks (see Actions above) will have type ``path:<url_path>``. In this case, \"path:myplugin_time\"."
msgstr ""

#: ../../guides/ajax.rst:132
msgid "If the page handler echoes a regular web page, ``output`` will be a string containing the HTML."
msgstr ""

#: ../../guides/ajax.rst:133
msgid "An absolute URL can be given in place of the path name."
msgstr ""

#: ../../guides/ajax.rst:136
msgid "Fetching views"
msgstr ""

#: ../../guides/ajax.rst:138
msgid "Consider this view:"
msgstr ""

#: ../../guides/ajax.rst:157
msgid "Since it's a PHP file, we must register it for Ajax first:"
msgstr ""

#: ../../guides/ajax.rst:165
msgid "To fetch the view, use ``ajax.view('<view_name>', options)``:"
msgstr ""

#: ../../guides/ajax.rst:180
msgid "Notes for views:"
msgstr ""

#: ../../guides/ajax.rst:182
msgid "The 3 hooks (see Actions above) will have type ``view:<view_name>``. In this case, \"view:myplugin/get_link\"."
msgstr ""

#: ../../guides/ajax.rst:183
#: ../../guides/ajax.rst:217
msgid "``output`` will be a string with the rendered view."
msgstr ""

#: ../../guides/ajax.rst:184
msgid "The request data are injected into ``$vars`` in the view."
msgstr ""

#: ../../guides/ajax.rst:185
#: ../../guides/ajax.rst:219
msgid "If the request data contains ``guid``, the system sets ``$vars['entity']`` to the corresponding entity or ``false`` if it can't be loaded."
msgstr ""

#: ../../guides/ajax.rst:189
#: ../../guides/ajax.rst:230
msgid "In ajax views and forms, note that ``$vars`` can be populated by client input. The data is filtered like ``get_input()``, but may not be the type you're expecting or may have unexpected keys."
msgstr ""

#: ../../guides/ajax.rst:194
msgid "Fetching forms"
msgstr ""

#: ../../guides/ajax.rst:196
msgid "Consider we have a form view. We register it for Ajax:"
msgstr ""

#: ../../guides/ajax.rst:203
msgid "To fetch this using ``ajax.form('<action_name>', options)``."
msgstr ""

#: ../../guides/ajax.rst:214
msgid "Notes for forms:"
msgstr ""

#: ../../guides/ajax.rst:216
msgid "The 3 hooks (see Actions above) will have type ``form:<action_name>``. In this case, \"form:myplugin/add\"."
msgstr ""

#: ../../guides/ajax.rst:218
msgid "The request data are injected into ``$vars`` in your form view."
msgstr ""

#: ../../guides/ajax.rst:223
msgid "Only the request data are passed to the requested form view (i.e. as a third parameter accepted by ``elgg_view_form()``). If you need to pass attributes or parameters of the form element rendered by the ``input/form`` view (i.e. normally passed as a second parameter to ``elgg_view_form()``), use the server-side hook ``view_vars, input/form``."
msgstr ""

#: ../../guides/ajax.rst:235
msgid "Submitting forms"
msgstr ""

#: ../../guides/ajax.rst:237
msgid "To submit a form using Ajax, simply pass ``ajax`` parameter with form variables:"
msgstr ""

#: ../../guides/ajax.rst:245
msgid "Redirects"
msgstr ""

#: ../../guides/ajax.rst:247
msgid "Use ``ajax.forward()`` to start a spinner and redirect the user to a new destination."
msgstr ""

#: ../../guides/ajax.rst:257
msgid "Piggybacking on an Ajax request"
msgstr ""

#: ../../guides/ajax.rst:259
msgid "The client-side ``ajax_request_data`` hook can be used to append or filter data being sent by an ``elgg/Ajax`` request."
msgstr ""

#: ../../guides/ajax.rst:261
msgid "Let's say when the view ``foo`` is fetched, we want to also send the server some data:"
msgstr ""

#: ../../guides/ajax.rst:277
msgid "This data can be read server-side via ``get_input('bar');``."
msgstr ""

#: ../../guides/ajax.rst:279
msgid "If data was given as a string (e.g. ``$form.serialize()``), the request hooks are not triggered."
msgstr ""

#: ../../guides/ajax.rst:281
msgid "The form will be objectified as ``FormData``, and the request content type will be determined accordingly."
msgstr ""

#: ../../guides/ajax.rst:284
msgid "Piggybacking on an Ajax response"
msgstr ""

#: ../../guides/ajax.rst:286
msgid "The server-side ``ajax_response`` hook can be used to append or filter response data (or metadata)."
msgstr ""

#: ../../guides/ajax.rst:288
msgid "Let's say when the view ``foo`` is fetched, we want to also send the client some additional data:"
msgstr ""

#: ../../guides/ajax.rst:311
msgid "To capture the metadata send back to the client, we use the client-side ``ajax_response`` hook:"
msgstr ""

#: ../../guides/ajax.rst:330
msgid "Only ``data.value`` is returned to the ``success`` function or available via the `Deferred` interface."
msgstr ""

#: ../../guides/ajax.rst:332
msgid "Elgg uses these same hooks to deliver system messages over ``elgg/Ajax`` responses."
msgstr ""

#: ../../guides/ajax.rst:335
msgid "Handling errors"
msgstr ""

#: ../../guides/ajax.rst:337
msgid "Responses basically fall into three categories:"
msgstr ""

#: ../../guides/ajax.rst:339
msgid "HTTP success (200) with status ``0``. No ``register_error()`` calls were made on the server."
msgstr ""

#: ../../guides/ajax.rst:340
msgid "HTTP success (200) with status ``-1``. ``register_error()`` was called."
msgstr ""

#: ../../guides/ajax.rst:341
msgid "HTTP error (4xx/5xx). E.g. calling an action with stale tokens, or a server exception. In this case the ``done`` callbacks are not called."
msgstr ""

#: ../../guides/ajax.rst:343
msgid "The first and third case are the most common cases in the system. Use the ``done`` and ``fail`` callbacks to differentiate behaviour on success and error."
msgstr ""

#: ../../guides/ajax.rst:354
msgid "Requiring AMD modules"
msgstr ""

#: ../../guides/ajax.rst:356
msgid "Each response from an Ajax service will contain a list of AMD modules required server side with `elgg_require_js()`. When response data is unwrapped, these modules will be loaded asynchronously - plugins should not expect these modules to be loaded in their `$.done()` and `$.then()` handlers and must use `require()` for any modules they depend on. Additionally AMD modules should not expect the DOM to have been altered by an Ajax request when they are loaded - DOM events should be delegated and manipulations on DOM elements should be delayed until all Ajax requests have been resolved."
msgstr ""

#: ../../guides/authentication.rst:2
msgid "Authentication"
msgstr ""

#: ../../guides/authentication.rst:4
msgid "Elgg provides everything needed to authenticate users via username/email and password out of the box, including:"
msgstr ""

#: ../../guides/authentication.rst:7
msgid "remember-me cookies for persistent login"
msgstr ""

#: ../../guides/authentication.rst:8
msgid "password reset logic"
msgstr ""

#: ../../guides/authentication.rst:9
msgid "secure storage of passwords"
msgstr ""

#: ../../guides/authentication.rst:10
msgid "logout"
msgstr ""

#: ../../guides/authentication.rst:11
msgid "UIs for accomplishing all of the above"
msgstr ""

#: ../../guides/authentication.rst:13
msgid "All that's left for you to do as a developer is to use the built-in authentication functions to secure your pages and actions."
msgstr ""

#: ../../guides/authentication.rst:17
msgid "Working with the logged in user"
msgstr ""

#: ../../guides/authentication.rst:19
msgid "Check whether the current user is logged in with ``elgg_is_logged_in()``:"
msgstr ""

#: ../../guides/authentication.rst:27
msgid "Check if the current user is an admin with ``elgg_is_admin_logged_in()``:"
msgstr ""

#: ../../guides/authentication.rst:35
msgid "Get the currently logged in user with ``elgg_get_logged_in_user_entity()``:"
msgstr ""

#: ../../guides/authentication.rst:41
msgid "The returned object is an ``ElggUser`` so you can use all the methods and properties of that class to access information about the user. If the user is not logged in, this will return ``null``, so be sure to check for that first."
msgstr ""

#: ../../guides/authentication.rst:48
msgid "Gatekeepers"
msgstr ""

#: ../../guides/authentication.rst:50
msgid "Gatekeeper functions allow you to manage how code gets executed by applying access control rules."
msgstr ""

#: ../../guides/authentication.rst:52
msgid "Forward a user to the front page if they are not logged in with ``elgg_gatekeeper()``:"
msgstr ""

#: ../../guides/authentication.rst:60
msgid "Forward a user to the front page unless they are an admin with ``elgg_admin_gatekeeper()``:"
msgstr ""

#: ../../guides/authentication.rst:69
msgid "Pluggable Authentication Modules"
msgstr ""

#: ../../guides/authentication.rst:71
msgid "Elgg has support for pluggable authentication modules (PAM), which enables you to write your own authentication handlers. Whenever a request needs to get authenticated the system will call ``elgg_authenticate()`` which probes the registered PAM handlers until one returns success."
msgstr ""

#: ../../guides/authentication.rst:73
msgid "The preferred approach is to create a separate Elgg plugin which will have one simple task: to process an authentication request. This involves setting up an authentication handler in the plugin's :doc:`Bootstrap <plugins>` class, and to register it with the PAM module so it will get processed whenever the system needs to authenticate a request."
msgstr ""

#: ../../guides/authentication.rst:75
msgid "The authentication handler is a function and takes a single parameter. Registering the handler is being done by ``register_pam_handler()`` which takes the name of the authentication handler, the importance and the policy as parameters. It is advised to register the handler in the plugin's init function, for example:"
msgstr ""

#: ../../guides/authentication.rst:93
msgid "Importance"
msgstr ""

#: ../../guides/authentication.rst:95
msgid "By default an authentication module is registered with an importance of **sufficient**."
msgstr ""

#: ../../guides/authentication.rst:97
msgid "In a list of authentication modules; if any one marked *sufficient* returns ``true``, ``pam_authenticate()`` will also return ``true``. The exception to this is when an authentication module is registered with an importance of **required**. All required modules must return ``true`` for ``pam_authenticate()`` to return ``true``, regardless of whether all sufficient modules return ``true``."
msgstr ""

#: ../../guides/authentication.rst:100
msgid "Passed credentials"
msgstr ""

#: ../../guides/authentication.rst:102
msgid "The format of the credentials passed to the handler can vary, depending on the originating request. For example, a regular login via the login form will create a named array, with the keys ``username`` and ``password``. If a request was made for example via XML-RPC then the credentials will be set in the HTTP header, so in this case nothing will get passed to the authentication handler and the handler will need to perform steps on its own to authenticate the request."
msgstr ""

#: ../../guides/authentication.rst:105
msgid "Return value"
msgstr ""

#: ../../guides/authentication.rst:107
msgid "The authentication handle should return a ``boolean``, indicating if the request could be authenticated or not. One caveat is that in case of a regular user login where credentials are available as username and password the user will get logged in. In case of the XML-RPC example the authentication handler will need to perform this step itself since the rest of the system will not have any idea of either possible formats of credentials passed nor its contents. Logging in a user is quite simple and is being done by ``login()``, which expects an ``ElggUser`` object."
msgstr ""

#: ../../guides/context.rst:2
msgid "Context"
msgstr ""

#: ../../guides/context.rst:6
msgid "The contents of this page are outdated. While the functionality is still in place, using global context to determine your business logic is bad practice, and will make your code less testable and succeptive to bugs."
msgstr ""

#: ../../guides/context.rst:10
msgid "Within the Elgg framework, context can be used by your plugin's functions to determine if they should run or not. You will be registering callbacks to be executed when particular :doc:`events are triggered <events-list>`. Sometimes the events are generic and you only want to run your callback when your plugin caused the event to be triggered. In that case, you can use the page's context."
msgstr ""

#: ../../guides/context.rst:15
msgid "You can explicitly set the context with ``set_context()``. The context is a string and typically you set it to the name of your plugin. You can retrieve the context with the function ``get_context()``. It's however better to use ``elgg_push_context($string)`` to add a context to the stack. You can check if the context you want in in the current stack by calling ``elgg_in_context($context)``. Don't forget to pop (with ``elgg_pop_context()``) the context after you push one and don't need it anymore."
msgstr ""

#: ../../guides/context.rst:21
msgid "If you don't set it, Elgg tries to guess the context. If the page was called through the router, the context is set to the first segment of the current route, e.g. ``profile`` in ``profile/username``."
msgstr ""

#: ../../guides/context.rst:24
msgid "Sometimes a view will return different HTML depending on the context. A plugin can take advantage of that by setting the context before calling ``elgg_view()`` on the view and then setting the context back. This is frequently done with the search context."
msgstr ""

#: ../../guides/cron.rst:2
msgid "Cron"
msgstr ""

#: ../../guides/cron.rst:4
msgid "If you setup cron correctly as described in :doc:`/admin/cron` special hooks will be triggered so you can register for these hooks from your own code."
msgstr ""

#: ../../guides/cron.rst:7
msgid "The example below registers a function for the daily cron."
msgstr ""

#: ../../guides/cron.rst:15
msgid "If timing is important in your cron hook be advised that the functions are executed in order of registration. This could mean that your function may start (a lot) later then you may have expected. However the parameters provided in the hook contain the original starting time of the cron, so you can always use that information."
msgstr ""

#: ../../guides/cron.rst:28
msgid "Custom intervals"
msgstr ""

#: ../../guides/cron.rst:30
msgid "Plugin developers can configure there own custom intervals."
msgstr ""

#: ../../guides/cron.rst:34
msgid "It's **NOT** recommended to do this, as the users of your plugin may also need to configure your custom interval. Try to work with the default intervals. If you only need to do a certain task at for example 16:30 you can use the ``halfhour`` interval and check that ``date('G', $start_time) == 16`` and ``date('i', $start_time) == 30``"
msgstr ""

#: ../../guides/cron.rst:53
msgid ":doc:`/design/events` has more information about hooks"
msgstr ""

#: ../../guides/cron.rst:54
msgid "For more information about the supported cron interval definition see `the PHP Scheduler documentation`_"
msgstr ""

#: ../../guides/database.rst:2
msgid "Database"
msgstr ""

#: ../../guides/database.rst:4
msgid "Persist user-generated content and settings with Elgg's generic storage API."
msgstr ""

#: ../../guides/database.rst:11
msgid "Entities"
msgstr ""

#: ../../guides/database.rst:14
msgid "Creating an object"
msgstr ""

#: ../../guides/database.rst:16
msgid "To create an object in your code, you need to instantiate an ``ElggObject``. Setting data is simply a matter of adding instance variables or properties. The built-in properties are:"
msgstr ""

#: ../../guides/database.rst:20
msgid "**``guid``** The entity's GUID; set automatically"
msgstr ""

#: ../../guides/database.rst:21
msgid "**``owner_guid``** The owning user's GUID"
msgstr ""

#: ../../guides/database.rst:22
msgid "**``subtype``** A single-word arbitrary string that defines what kind of object it is, for example ``blog``"
msgstr ""

#: ../../guides/database.rst:24
msgid "**``access_id``** An integer representing the access level of the object"
msgstr ""

#: ../../guides/database.rst:26
msgid "**``title``** The title of the object"
msgstr ""

#: ../../guides/database.rst:27
msgid "**``description``** The description of the object"
msgstr ""

#: ../../guides/database.rst:29
msgid "The object subtype is a special property. This is an arbitrary string that describes what the object is. For example, if you were writing a blog plugin, your subtype string might be *blog*. It's a good idea to make this unique, so that other plugins don't accidentally try and use the same subtype. For the purposes of this document, let's assume we're building a simple forum. Therefore, the subtype will be *forum*:"
msgstr ""

#: ../../guides/database.rst:43
msgid "``access_id`` is another important property. If you don't set this, your object will be private, and only the creator user will be able to see it. Elgg defines constants for the special values of ``access_id``:"
msgstr ""

#: ../../guides/database.rst:47
msgid "**ACCESS_PRIVATE** Only the owner can see it"
msgstr ""

#: ../../guides/database.rst:48
msgid "**ACCESS_LOGGED_IN** Any logged in user can see it"
msgstr ""

#: ../../guides/database.rst:49
msgid "**ACCESS_PUBLIC** Even visitors not logged in can see it"
msgstr ""

#: ../../guides/database.rst:51
msgid "Saving the object will automatically populate the ``$object->guid`` property if successful. If you change any more base properties, you can call ``$object->save()`` again, and it will update the database for you."
msgstr ""

#: ../../guides/database.rst:55
msgid "You can set metadata on an object just like a standard property. Let's say we want to set the SKU of a product:"
msgstr ""

#: ../../guides/database.rst:62
msgid "If you assign an array, all the values will be set for that metadata. This is how, for example, you set tags."
msgstr ""

#: ../../guides/database.rst:65
msgid "Metadata cannot be persisted to the database until the entity has been saved, but for convenience, ElggEntity can cache it internally and save it when saving the entity."
msgstr ""

#: ../../guides/database.rst:70
msgid "Loading an object"
msgstr ""

#: ../../guides/database.rst:73
msgid "By GUID"
msgstr ""

#: ../../guides/database.rst:82
msgid "But what if you don't know the GUID? There are several options."
msgstr ""

#: ../../guides/database.rst:85
msgid "By user, subtype or site"
msgstr ""

#: ../../guides/database.rst:87
msgid "If you know the user ID you want to get objects for, or the subtype, you have several options. The easiest is probably to call the procedural function ``elgg_get_entities``:"
msgstr ""

#: ../../guides/database.rst:98
msgid "This will return an array of ``ElggEntity`` objects that you can iterate through. ``elgg_get_entities`` paginates by default, with a limit of 10; and offset 0."
msgstr ""

#: ../../guides/database.rst:102
msgid "You can leave out ``owner_guid`` to get all objects and leave out subtype or type to get objects of all types/subtypes."
msgstr ""

#: ../../guides/database.rst:105
msgid "If you already have an ``ElggUser`` – e.g. ``elgg_get_logged_in_user_entity``, which always has the current user's object when you're logged in – you can simply use:"
msgstr ""

#: ../../guides/database.rst:113
msgid "But what about getting objects with a particular piece of metadata?"
msgstr ""

#: ../../guides/database.rst:116
msgid "By properties"
msgstr ""

#: ../../guides/database.rst:118
msgid "You can fetch entities by their properties using ``elgg_get_entities``. Using specific parameters passed to ``$options`` array, you can retrieve entities by their attributes, metadata, annotations, private settings and relationships."
msgstr ""

#: ../../guides/database.rst:123
#: ../../guides/views.rst:433
msgid "Displaying entities"
msgstr ""

#: ../../guides/database.rst:125
msgid "In order for entities to be displayed in listing functions you need to provide a view for the entity in the views system."
msgstr ""

#: ../../guides/database.rst:128
msgid "To display an entity, create a view EntityType/subtype where EntityType is one of the following:"
msgstr ""

#: ../../guides/database.rst:131
msgid "object: for entities derived from ElggObject user: for entities derived from ElggUser site: for entities derived from ElggSite group: for entities derived from ElggGroup"
msgstr ""

#: ../../guides/database.rst:136
msgid "A default view for all entities has already been created, this is called EntityType/default."
msgstr ""

#: ../../guides/database.rst:142
msgid "Entity Icons"
msgstr ""

#: ../../guides/database.rst:144
msgid "Entity icons can be saved from uploaded files, existing local files, or existing ElggFile objects. These methods save the `master` size of the icon defined in the system. The other defined sizes will be generated when requested."
msgstr ""

#: ../../guides/database.rst:173
msgid "The following sizes exist by default:"
msgstr ""

#: ../../guides/database.rst:168
msgid "``master`` - 10240px at longer edge (not upscaled)"
msgstr ""

#: ../../guides/database.rst:169
msgid "``large`` - 200px at longer edge (not upscaled)"
msgstr ""

#: ../../guides/database.rst:170
msgid "``medium`` - 100px square"
msgstr ""

#: ../../guides/database.rst:171
msgid "``small`` - 40px square"
msgstr ""

#: ../../guides/database.rst:172
msgid "``tiny`` - 25px square"
msgstr ""

#: ../../guides/database.rst:173
msgid "``topbar`` - 16px square"
msgstr ""

#: ../../guides/database.rst:175
msgid "Use ``elgg_get_icon_sizes()`` to get all possible icon sizes for a specific entity type and subtype. The function triggers the ``entity:icon:sizes`` :ref:`hook <guides/hooks-list#other>`."
msgstr ""

#: ../../guides/database.rst:178
msgid "To check if an icon is set, use ``$object->hasIcon($size)``."
msgstr ""

#: ../../guides/database.rst:180
msgid "You can retrieve the URL of the generated icon with ``ElggEntity::getIconURL($params)`` method. This method accepts a ``$params`` argument as an array that specifies the size, type, and provide additional context for the hook to determine the icon to serve. The method triggers the ``entity:icon:url`` :ref:`hook <guides/hooks-list#other>`."
msgstr ""

#: ../../guides/database.rst:185
msgid "Use ``elgg_view_entity_icon($entity, $size, $vars)`` to render an icon. This will scan the following locations for a view and include the first match to ."
msgstr ""

#: ../../guides/database.rst:188
msgid "views/$viewtype/icon/$type/$subtype.php"
msgstr ""

#: ../../guides/database.rst:189
msgid "views/$viewtype/icon/$type/default.php"
msgstr ""

#: ../../guides/database.rst:190
msgid "views/$viewtype/icon/default.php"
msgstr ""

#: ../../guides/database.rst:192
#: ../../guides/database.rst:209
msgid "Where"
msgstr ""

#: ../../guides/database.rst:194
#: ../../guides/database.rst:211
msgid "$viewtype"
msgstr ""

#: ../../guides/database.rst:195
#: ../../guides/database.rst:212
msgid "Type of view, e.g. ``'default'`` or ``'json'``."
msgstr ""

#: ../../guides/database.rst:196
msgid "$type"
msgstr ""

#: ../../guides/database.rst:197
#: ../../guides/database.rst:216
msgid "Type of entity, e.g. ``'group'`` or ``'user'``."
msgstr ""

#: ../../guides/database.rst:199
msgid "$subtype"
msgstr ""

#: ../../guides/database.rst:199
msgid "Entity subtype, e.g. ``'blog'`` or ``'page'``."
msgstr ""

#: ../../guides/database.rst:201
msgid "You do not have to return a fallback icon from the hook handler. If no uploaded icon is found, the view system will scan the views (in this specific order):"
msgstr ""

#: ../../guides/database.rst:204
msgid "views/$viewtype/$icon_type/$entity_type/$entity_subtype.svg"
msgstr ""

#: ../../guides/database.rst:205
msgid "views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.gif"
msgstr ""

#: ../../guides/database.rst:206
msgid "views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.png"
msgstr ""

#: ../../guides/database.rst:207
msgid "views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.jpg"
msgstr ""

#: ../../guides/database.rst:213
msgid "$icon_type"
msgstr ""

#: ../../guides/database.rst:214
msgid "Icon type, e.g. ``'icon'`` or ``'cover_image'``."
msgstr ""

#: ../../guides/database.rst:215
msgid "$entity_type"
msgstr ""

#: ../../guides/database.rst:217
msgid "$entity_subtype"
msgstr ""

#: ../../guides/database.rst:218
msgid "Entity subtype, e.g. ``'blog'`` or ``'page'`` (or ``'default'`` if entity has not subtype)."
msgstr ""

#: ../../guides/database.rst:220
msgid "$size"
msgstr ""

#: ../../guides/database.rst:220
msgid "Icon size (note that we do not use the size with svg icons)"
msgstr ""

#: ../../guides/database.rst:222
msgid "Icon methods support passing an icon type if an entity has more than one icon. For example, a user might have an avatar and a cover photo icon. You would pass ``'cover_photo'`` as the icon type:"
msgstr ""

#: ../../guides/database.rst:237
msgid "Custom icon types (e.g. cover photos) only have a preset for `master` size, to add custom sizes use ``entity:<icon_type>:url`` :ref:`hook <guides/hooks-list#other>` to configure them."
msgstr ""

#: ../../guides/database.rst:240
msgid "By default icons will be stored in ``/icons/<icon_type>/<size>.jpg`` relative to entity's directory on filestore. To provide an alternative location, use the ``entity:<icon_type>:file`` :ref:`hook <guides/hooks-list#other>`."
msgstr ""

#: ../../guides/database.rst:244
msgid "Adding, reading and deleting annotations"
msgstr ""

#: ../../guides/database.rst:246
msgid "Annotations could be used, for example, to track ratings. To annotate an entity you can use the object's ``annotate()`` method. For example, to give a blog post a rating of 5, you could use:"
msgstr ""

#: ../../guides/database.rst:256
msgid "To retrieve the ratings on the blog post, use ``$blogpost->getAnnotations('rating')`` and if you want to delete an annotation, you can operate on the ``ElggAnnotation`` class, eg ``$annotation->delete()``."
msgstr ""

#: ../../guides/database.rst:261
msgid "Retrieving a single annotation can be done with ``get_annotation()`` if you have the annotation's ID. If you delete an ElggEntity of any kind, all its metadata, annotations, and relationships will be automatically deleted as well."
msgstr ""

#: ../../guides/database.rst:267
msgid "Extending ElggEntity"
msgstr ""

#: ../../guides/database.rst:269
msgid "If you derive from one of the Elgg core classes, you'll need to tell Elgg how to properly instantiate the new type of object so that get\\_entity() et al. will return the appropriate PHP class. For example, if I customize ElggGroup in a class called \"Committee\", I need to make Elgg aware of the new mapping. Following is an example class extension:"
msgstr ""

#: ../../guides/database.rst:288
msgid "In your plugins ``elgg-plugin.php`` file add the ``entities`` section."
msgstr ""

#: ../../guides/database.rst:305
msgid "The entities will be registered upon activation of the plugin."
msgstr ""

#: ../../guides/database.rst:307
msgid "Now if you invoke ``get_entity()`` with the GUID of a committee object, you'll get back an object of type Committee."
msgstr ""

#: ../../guides/database.rst:311
msgid "Advanced features"
msgstr ""

#: ../../guides/database.rst:314
msgid "Entity URLs"
msgstr ""

#: ../../guides/database.rst:316
msgid "Entity urls are provided by the ``getURL()`` interface and provide the Elgg framework with a common way of directing users to the appropriate display handler for any given object."
msgstr ""

#: ../../guides/database.rst:320
msgid "For example, a profile page in the case of users."
msgstr ""

#: ../../guides/database.rst:322
msgid "The url is set using the ``elgg\\_register\\_entity\\_url\\_handler()`` function. The function you register must return the appropriate url for the given type - this itself can be an address set up by a page handler."
msgstr ""

#: ../../guides/database.rst:329
msgid "The default handler is to use the default export interface."
msgstr ""

#: ../../guides/database.rst:332
msgid "Entity loading performance"
msgstr ""

#: ../../guides/database.rst:334
msgid "``elgg_get_entities`` has a couple options that can sometimes be useful to improve performance."
msgstr ""

#: ../../guides/database.rst:336
msgid "**preload_owners**: If the entities fetched will be displayed in a list with the owner information, you can set this option to ``true`` to efficiently load the owner users of the fetched entities."
msgstr ""

#: ../../guides/database.rst:337
msgid "**preload_containers**: If the entities fetched will be displayed in a list using info from their containers, you can set this option to ``true`` to efficiently load them."
msgstr ""

#: ../../guides/database.rst:338
msgid "**distinct**: When Elgg fetches entities using an SQL query, Elgg must be sure that each entity row appears only once in the result set. By default it includes a ``DISTINCT`` modifier on the GUID column to enforce this, but some queries naturally return unique entities. Setting the ``distinct`` option to false will remove this modifier, and rely on the query to enforce its own uniqueness."
msgstr ""

#: ../../guides/database.rst:340
msgid "The internals of Elgg entity queries is a complex subject and it's recommended to seek help on the Elgg Community site before using the ``distinct`` option."
msgstr ""

#: ../../guides/database.rst:343
msgid "Custom database functionality"
msgstr ""

#: ../../guides/database.rst:345
msgid "It is strongly recommended to use entities wherever possible. However, Elgg supports custom SQL queries using the database API."
msgstr ""

#: ../../guides/database.rst:348
msgid "Systemlog"
msgstr ""

#: ../../guides/database.rst:352
msgid "This section need some attention and will contain outdated information"
msgstr ""

#: ../../guides/database.rst:354
msgid "The default Elgg system log is a simple way of recording what happens within an Elgg system. It's viewable and searchable directly from the administration panel."
msgstr ""

#: ../../guides/database.rst:357
msgid "System log storage"
msgstr ""

#: ../../guides/database.rst:359
msgid "A system log row is stored whenever an event concerning an object whose class implements the :doc:`/design/loggable` interface is triggered. ``ElggEntity`` and ``ElggExtender`` implement :doc:`/design/loggable`, so a system log row is created whenever an event is performed on all objects, users, groups, sites, metadata and annotations."
msgstr ""

#: ../../guides/database.rst:361
msgid "Common events include:"
msgstr ""

#: ../../guides/database.rst:363
msgid "create"
msgstr ""

#: ../../guides/database.rst:364
msgid "update"
msgstr ""

#: ../../guides/database.rst:365
msgid "delete"
msgstr ""

#: ../../guides/database.rst:366
msgid "login"
msgstr ""

#: ../../guides/database.rst:369
msgid "Creating your own system log"
msgstr ""

#: ../../guides/database.rst:371
msgid "There are some reasons why you might want to create your own system log. For example, you might need to store a full copy of entities when they are updated or deleted, for auditing purposes. You might also need to notify an administrator when certain types of events occur."
msgstr ""

#: ../../guides/database.rst:373
msgid "To do this, you can create a function that listens to all events for all types of object:"
msgstr ""

#: ../../guides/database.rst:379
msgid "Your function can then be defined as:"
msgstr ""

#: ../../guides/database.rst:389
msgid "You can then use the extra methods defined by :doc:`/design/loggable` to extract the information you need."
msgstr ""

#: ../../guides/dont-modify-core.rst:2
msgid "Don't Modify Core"
msgstr ""

#: ../../guides/dont-modify-core.rst:6
msgid "In general, you shouldn't modify non-config files that come with third-party software like Elgg."
msgstr ""

#: ../../guides/dont-modify-core.rst:8
msgid "The best way to customize the behavior of Elgg is to :doc:`install Elgg as a composer dependency</intro/install>` and use a :doc:`plugin<plugins>` to store modifications specific to your application, and alter behavior through the rich Elgg plugin API."
msgstr ""

#: ../../guides/dont-modify-core.rst:12
msgid "If you'd like to share customizations between sites or even publish your changes as a reusable package for the community, create a :doc:`plugin<plugins>` using the same plugin APIs and file structure."
msgstr ""

#: ../../guides/dont-modify-core.rst:17
msgid "It makes it hard to get help"
msgstr ""

#: ../../guides/dont-modify-core.rst:19
msgid "When you don't share the same codebase as everyone else, it's impossible for others to know what is going on in your system and whether your changes are to blame. This can frustrate those who offer help because it can add considerable noise to the support process."
msgstr ""

#: ../../guides/dont-modify-core.rst:25
msgid "It makes upgrading tricky and potentially disastrous"
msgstr ""

#: ../../guides/dont-modify-core.rst:27
msgid "You will certainly want or need to upgrade Elgg to take advantage of"
msgstr ""

#: ../../guides/dont-modify-core.rst:29
msgid "security patches"
msgstr ""

#: ../../guides/dont-modify-core.rst:30
msgid "new features"
msgstr ""

#: ../../guides/dont-modify-core.rst:31
msgid "new plugin APIs"
msgstr ""

#: ../../guides/dont-modify-core.rst:32
msgid "new stability improvements"
msgstr ""

#: ../../guides/dont-modify-core.rst:33
msgid "performance improvements"
msgstr ""

#: ../../guides/dont-modify-core.rst:35
msgid "If you've modified core files, then you must be very careful when upgrading that your changes are not overwritten and that they are compatible with the new Elgg code. If your changes are lost or incompatible, then the upgrade may remove features you've added and even completely break your site."
msgstr ""

#: ../../guides/dont-modify-core.rst:40
msgid "This can also be a slippery slope. Lots of modifications can lead you to an upgrade process so complex that it's practically impossible. There are lots of sites stuck running old versions software due to taking this path."
msgstr ""

#: ../../guides/dont-modify-core.rst:45
msgid "It may break plugins"
msgstr ""

#: ../../guides/dont-modify-core.rst:47
msgid "You may not realize until much later that your \"quick fix\" broke seemingly unrelated functionality that plugins depended on."
msgstr ""

#: ../../guides/dont-modify-core.rst:51
#: ../../guides/river.rst:54
msgid "Summary"
msgstr ""

#: ../../guides/dont-modify-core.rst:54
msgid "Resist the temptation"
msgstr ""

#: ../../guides/dont-modify-core.rst:54
msgid "Editing existing files is quick and easy, but doing so heavily risks the maintainability, security, and stability of your site."
msgstr ""

#: ../../guides/dont-modify-core.rst:56
msgid "When receiving advice, consider if the person telling you to modify core will be around to rescue you if you run into trouble later!"
msgstr ""

#: ../../guides/dont-modify-core.rst:59
msgid "Apply these principle to software in general."
msgstr ""

#: ../../guides/dont-modify-core.rst:59
msgid "If you can avoid it, don't modify third party plugins either, for the same reasons: Plugin authors release new versions, too, and you will want those updates."
msgstr ""

#: ../../guides/email.rst:2
#: ../../guides/notifications.rst:197
msgid "Email"
msgstr ""

#: ../../guides/email.rst:4
msgid "Elgg has the ability to send out emails. This can be done directly using functions like ``elgg_send_email()`` and ``notify_user()`` or indirectly through the notifications system. Below an overview of the feature of the email system."
msgstr ""

#: ../../guides/email.rst:13
msgid "HTML Mail"
msgstr ""

#: ../../guides/email.rst:15
msgid "As an admin you can configure your site to have all outgoing emails to be HTML emails or just plain text emails. HTML emails are enabled by default. When enabled the email contents will be wrapped in HTML elements and some CSS will be applied. This allows theme developers to style the emails."
msgstr ""

#: ../../guides/email.rst:18
msgid "The appropriate views to format and style the emails can be found in ``views/default/email``."
msgstr ""

#: ../../guides/email.rst:20
msgid "The CSS will be inlined automatically so it will work in most email clients. If your email contains images, those images can be converted to inline base64 encoded images (default) or attachments. Converted images are the best way to have images show consistently in various clients."
msgstr ""

#: ../../guides/email.rst:24
msgid "Instead of having the message converted automatically to a HTML, you can also provide your own ``html_message`` in the ``params`` of a notification. The ``html_message`` can be either a ``Elgg\\Email\\HtmlPart`` or a ``string``. If it is a ``string`` Elgg will automatically try to inline provided CSS present in the ``css`` param. If you do not want to inline CSS you will need to set the ``convert_css`` param to ``false``. Below an example of a custom HTML part."
msgstr ""

#: ../../guides/email.rst:47
msgid "Attachments"
msgstr ""

#: ../../guides/email.rst:49
msgid "``notify_user()`` or enqueued notifications support attachments for e-mail notifications if provided in ``$params``. To add one or more attachments add a key ``attachments`` in ``$params`` which is an array of the attachments. An attachment should be in one of the following formats:"
msgstr ""

#: ../../guides/email.rst:52
msgid "An ``ElggFile`` which points to an existing file"
msgstr ""

#: ../../guides/email.rst:53
msgid "An array with the file contents"
msgstr ""

#: ../../guides/email.rst:54
msgid "An array with a filepath"
msgstr ""

#: ../../guides/email.rst:86
msgid "E-mail address formatting"
msgstr ""

#: ../../guides/email.rst:88
msgid "Elgg has a helper class to aid in getting formatted e-mail addresses: ``\\Elgg\\Email\\Address``."
msgstr ""

#: ../../guides/email.rst:106
msgid "There are some helper functions available"
msgstr ""

#: ../../guides/email.rst:108
msgid "``\\Elgg\\Email\\Address::fromString($string)`` Will return an ``\\Elgg\\Email\\Address`` class with e-mail and name set, provided a formatted string (eg. ``Example <example@elgg.org>``)"
msgstr ""

#: ../../guides/email.rst:110
msgid "``\\Elgg\\Email\\Address::fromEntity($entity)`` Will return an ``\\Elgg\\Email\\Address`` class with e-mail and name set based on the entity"
msgstr ""

#: ../../guides/email.rst:111
msgid "``\\Elgg\\Email\\Address::getFormattedEmailAddress($email, $name)`` Will return a formatted string provided an e-mail address and optionaly a name"
msgstr ""

#: ../../guides/errors.rst:2
msgid "Error Handling"
msgstr ""

#: ../../guides/errors.rst:4
msgid "Under the hood, Elgg uses Monolog_ for logging errors to the server's error log (and stdout for CLI commands)."
msgstr ""

#: ../../guides/errors.rst:9
msgid "Monolog_ comes with a number of tools that can help administrators keep track of errors and debugging information."
msgstr ""

#: ../../guides/errors.rst:11
msgid "You can add custom handlers (see Monolog_ documentation for a full list of handlers):"
msgstr ""

#: ../../guides/events-list.rst:2
msgid "List of events in core"
msgstr ""

#: ../../guides/events-list.rst:4
msgid "For more information on how events work visit :doc:`/design/events`."
msgstr ""

#: ../../guides/events-list.rst:12
msgid "Some events are marked with `(sequence)` this means those events also have a ``:before`` and ``:after`` event Also see :ref:`Event sequence <design/events#event-sequence>`"
msgstr ""

#: ../../guides/events-list.rst:16
msgid "System events"
msgstr ""

#: ../../guides/events-list.rst:19
msgid "**plugins_load, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:19
msgid "Triggered before the plugins are loaded. Rarely used. init, system is used instead. Can be used to load additional libraries."
msgstr ""

#: ../../guides/events-list.rst:22
msgid "**plugins_boot, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:22
msgid "Triggered just after the plugins are loaded. Rarely used. init, system is used instead."
msgstr ""

#: ../../guides/events-list.rst:25
msgid "**init, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:25
msgid "Plugins tend to use this event for initialization (extending views, registering callbacks, etc.)"
msgstr ""

#: ../../guides/events-list.rst:29
msgid "**ready, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:28
msgid "Triggered after the ``init, system`` event. All plugins are fully loaded and the engine is ready to serve pages."
msgstr ""

#: ../../guides/events-list.rst:33
msgid "**shutdown, system**"
msgstr ""

#: ../../guides/events-list.rst:32
msgid "Triggered after the page has been sent to the user. Expensive operations could be done here and not make the user wait."
msgstr ""

#: ../../guides/events-list.rst:35
msgid "Depending upon your server configuration the PHP output might not be shown until after the process is completed. This means that any long-running processes will still delay the page load."
msgstr ""

#: ../../guides/events-list.rst:39
msgid "This event is prefered above using ``register_shutdown_function`` as you may not have access to all the Elgg services (eg. database) in the shutdown function but you will in the event."
msgstr ""

#: ../../guides/events-list.rst:42
msgid "The Elgg session is already closed before this event. Manipulating session is not possible."
msgstr ""

#: ../../guides/events-list.rst:46
msgid "**regenerate_site_secret:before, system**"
msgstr ""

#: ../../guides/events-list.rst:45
msgid "Return false to cancel regenerating the site secret. You should also provide a message to the user."
msgstr ""

#: ../../guides/events-list.rst:49
msgid "**regenerate_site_secret:after, system**"
msgstr ""

#: ../../guides/events-list.rst:49
msgid "Triggered after the site secret has been regenerated."
msgstr ""

#: ../../guides/events-list.rst:53
msgid "**log, systemlog**"
msgstr ""

#: ../../guides/events-list.rst:52
msgid "Called for all triggered events by ``system_log`` plugin. Used internally by ``Elgg\\SystemLog\\Logger::log()`` to populate the ``system_log`` table."
msgstr ""

#: ../../guides/events-list.rst:57
msgid "**upgrade, system**"
msgstr ""

#: ../../guides/events-list.rst:56
msgid "Triggered after a system upgrade has finished. All upgrade scripts have run, but the caches are not cleared."
msgstr ""

#: ../../guides/events-list.rst:60
msgid "**upgrade:execute, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:60
msgid "Triggered when executing an ``ElggUpgrade``. The ``$object`` of the event is the ``ElggUpgrade``."
msgstr ""

#: ../../guides/events-list.rst:63
msgid "**activate, plugin**"
msgstr ""

#: ../../guides/events-list.rst:63
msgid "Return false to prevent activation of the plugin."
msgstr ""

#: ../../guides/events-list.rst:66
msgid "**deactivate, plugin**"
msgstr ""

#: ../../guides/events-list.rst:66
msgid "Return false to prevent deactivation of the plugin."
msgstr ""

#: ../../guides/events-list.rst:69
msgid "**init:cookie, <name>**"
msgstr ""

#: ../../guides/events-list.rst:69
msgid "Return false to override setting a cookie."
msgstr ""

#: ../../guides/events-list.rst:72
msgid "**cache:invalidate, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:72
msgid "Invalidate internal and external caches."
msgstr ""

#: ../../guides/events-list.rst:76
msgid "**cache:clear, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:75
msgid "Clear internal and external caches, by default including system_cache, simplecache, and memcache. One might use it to reset others such as APC, OPCache, or WinCache."
msgstr ""

#: ../../guides/events-list.rst:79
msgid "**cache:purge, system** `(sequence)`"
msgstr ""

#: ../../guides/events-list.rst:79
msgid "Purge internal and external caches. This is meant to remove old/stale content from the caches."
msgstr ""

#: ../../guides/events-list.rst:83
msgid "**send:before, http_response**"
msgstr ""

#: ../../guides/events-list.rst:82
msgid "Triggered before an HTTP response is sent. Handlers will receive an instance of `\\Symfony\\Component\\HttpFoundation\\Response` that is to be sent to the requester. Handlers can terminate the event and prevent the response from being sent by returning `false`."
msgstr ""

#: ../../guides/events-list.rst:87
msgid "**send:after, http_response**"
msgstr ""

#: ../../guides/events-list.rst:86
msgid "Triggered after an HTTP response is sent. Handlers will receive an instance of `\\Symfony\\Component\\HttpFoundation\\Response` that was sent to the requester."
msgstr ""

#: ../../guides/events-list.rst:90
msgid "**reload:after, translations**"
msgstr ""

#: ../../guides/events-list.rst:90
msgid "Triggered after the translations are (re)loaded."
msgstr ""

#: ../../guides/events-list.rst:93
msgid "User events"
msgstr ""

#: ../../guides/events-list.rst:96
msgid "**login:before, user**"
msgstr ""

#: ../../guides/events-list.rst:96
msgid "Triggered during login. Returning false prevents the user from logging"
msgstr ""

#: ../../guides/events-list.rst:99
msgid "**login:after, user**"
msgstr ""

#: ../../guides/events-list.rst:99
msgid "Triggered after the user logs in."
msgstr ""

#: ../../guides/events-list.rst:102
msgid "**login:first, user**"
msgstr ""

#: ../../guides/events-list.rst:102
msgid "Triggered after a successful login. Only if there is no previous login."
msgstr ""

#: ../../guides/events-list.rst:105
msgid "**logout:before, user**"
msgstr ""

#: ../../guides/events-list.rst:105
msgid "Triggered during logout. Returning false should prevent the user from logging out."
msgstr ""

#: ../../guides/events-list.rst:108
msgid "**logout:after, user**"
msgstr ""

#: ../../guides/events-list.rst:108
msgid "Triggered after the user logouts."
msgstr ""

#: ../../guides/events-list.rst:113
msgid "**validate, user**"
msgstr ""

#: ../../guides/events-list.rst:111
msgid "When a user registers, the user's account is disabled. This event is triggered to allow a plugin to determine how the user should be validated (for example, through an email with a validation link)."
msgstr ""

#: ../../guides/events-list.rst:116
msgid "**validate:after, user**"
msgstr ""

#: ../../guides/events-list.rst:116
msgid "Triggered when user's account has been validated."
msgstr ""

#: ../../guides/events-list.rst:119
msgid "**invalidate:after, user**"
msgstr ""

#: ../../guides/events-list.rst:119
msgid "Triggered when user's account validation has been revoked."
msgstr ""

#: ../../guides/events-list.rst:122
msgid "**profileupdate, user**"
msgstr ""

#: ../../guides/events-list.rst:122
msgid "User has changed profile"
msgstr ""

#: ../../guides/events-list.rst:125
msgid "**profileiconupdate, user**"
msgstr ""

#: ../../guides/events-list.rst:125
msgid "User has changed profile icon"
msgstr ""

#: ../../guides/events-list.rst:128
msgid "**ban, user**"
msgstr ""

#: ../../guides/events-list.rst:128
msgid "Triggered before a user is banned. Return false to prevent."
msgstr ""

#: ../../guides/events-list.rst:131
msgid "**unban, user**"
msgstr ""

#: ../../guides/events-list.rst:131
msgid "Triggered before a user is unbanned. Return false to prevent."
msgstr ""

#: ../../guides/events-list.rst:134
msgid "**make_admin, user**"
msgstr ""

#: ../../guides/events-list.rst:134
msgid "Triggered before a user is promoted to an admin. Return false to prevent."
msgstr ""

#: ../../guides/events-list.rst:137
msgid "**remove_admin, user**"
msgstr ""

#: ../../guides/events-list.rst:137
msgid "Triggered before a user is demoted from an admin. Return false to prevent."
msgstr ""

#: ../../guides/events-list.rst:140
msgid "Relationship events"
msgstr ""

#: ../../guides/events-list.rst:144
msgid "**create, relationship**"
msgstr ""

#: ../../guides/events-list.rst:143
msgid "Triggered after a relationship has been created. Returning false deletes the relationship that was just created."
msgstr ""

#: ../../guides/events-list.rst:148
msgid "**delete, relationship**"
msgstr ""

#: ../../guides/events-list.rst:147
msgid "Triggered before a relationship is deleted. Return false to prevent it from being deleted."
msgstr ""

#: ../../guides/events-list.rst:151
msgid "**join, group**"
msgstr ""

#: ../../guides/events-list.rst:151
msgid "Triggered after the user ``$params['user']`` has joined the group ``$params['group']``."
msgstr ""

#: ../../guides/events-list.rst:154
msgid "**leave, group**"
msgstr ""

#: ../../guides/events-list.rst:154
msgid "Triggered before the user ``$params['user']`` has left the group ``$params['group']``."
msgstr ""

#: ../../guides/events-list.rst:157
msgid "Entity events"
msgstr ""

#: ../../guides/events-list.rst:160
msgid "**create, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:160
msgid "Triggered for user, group, object, and site entities after creation. Return false to delete entity."
msgstr ""

#: ../../guides/events-list.rst:165
msgid "**update, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:163
msgid "Triggered before an update for the user, group, object, and site entities. Return false to prevent update. The entity method ``getOriginalAttributes()`` can be used to identify which attributes have changed since the entity was last saved."
msgstr ""

#: ../../guides/events-list.rst:170
msgid "**update:after, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:168
msgid "Triggered after an update for the user, group, object, and site entities. The entity method ``getOriginalAttributes()`` can be used to identify which attributes have changed since the entity was last saved."
msgstr ""

#: ../../guides/events-list.rst:173
msgid "**delete:before, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:173
msgid "Triggered before entity deletion. Return false to prevent deletion."
msgstr ""

#: ../../guides/events-list.rst:176
msgid "**delete, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:176
msgid "Triggered before entity deletion."
msgstr ""

#: ../../guides/events-list.rst:179
msgid "**delete:after, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:179
msgid "Triggered after entity deletion."
msgstr ""

#: ../../guides/events-list.rst:182
msgid "**disable, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:182
msgid "Triggered before the entity is disabled. Return false to prevent disabling."
msgstr ""

#: ../../guides/events-list.rst:185
msgid "**disable:after, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:185
msgid "Triggered after the entity is disabled."
msgstr ""

#: ../../guides/events-list.rst:188
msgid "**enable, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:188
msgid "Return false to prevent enabling."
msgstr ""

#: ../../guides/events-list.rst:191
msgid "**enable:after, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:191
msgid "Triggered after the entity is enabled."
msgstr ""

#: ../../guides/events-list.rst:194
msgid "Metadata events"
msgstr ""

#: ../../guides/events-list.rst:198
msgid "**create, metadata**"
msgstr ""

#: ../../guides/events-list.rst:197
msgid "Called after the metadata has been created. Return false to delete the metadata that was just created."
msgstr ""

#: ../../guides/events-list.rst:201
msgid "**update, metadata**"
msgstr ""

#: ../../guides/events-list.rst:201
msgid "Called after the metadata has been updated. Return false to *delete the metadata.*"
msgstr ""

#: ../../guides/events-list.rst:204
msgid "**delete, metadata**"
msgstr ""

#: ../../guides/events-list.rst:204
msgid "Called before metadata is deleted. Return false to prevent deletion."
msgstr ""

#: ../../guides/events-list.rst:207
msgid "**enable, metadata**"
msgstr ""

#: ../../guides/events-list.rst:207
msgid "Called when enabling metadata. Return false to prevent enabling."
msgstr ""

#: ../../guides/events-list.rst:210
msgid "**disable, metadata**"
msgstr ""

#: ../../guides/events-list.rst:210
msgid "Called when disabling metadata. Return false to prevent disabling."
msgstr ""

#: ../../guides/events-list.rst:213
msgid "Annotation events"
msgstr ""

#: ../../guides/events-list.rst:217
msgid "**annotate, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:216
msgid "Called before the annotation has been created. Return false to prevent annotation of this entity."
msgstr ""

#: ../../guides/events-list.rst:221
msgid "**create, annotation**"
msgstr ""

#: ../../guides/events-list.rst:220
msgid "Called after the annotation has been created. Return false to delete the annotation."
msgstr ""

#: ../../guides/events-list.rst:224
msgid "**update, annotation**"
msgstr ""

#: ../../guides/events-list.rst:224
msgid "Called after the annotation has been updated. Return false to *delete the annotation.*"
msgstr ""

#: ../../guides/events-list.rst:227
msgid "**delete, annotation**"
msgstr ""

#: ../../guides/events-list.rst:227
msgid "Called before annotation is deleted. Return false to prevent deletion."
msgstr ""

#: ../../guides/events-list.rst:230
msgid "**enable, annotation**"
msgstr ""

#: ../../guides/events-list.rst:230
msgid "Called when enabling annotations. Return false to prevent enabling."
msgstr ""

#: ../../guides/events-list.rst:233
msgid "**disable, annotations**"
msgstr ""

#: ../../guides/events-list.rst:233
msgid "Called when disabling annotations. Return false to prevent disabling."
msgstr ""

#: ../../guides/events-list.rst:236
msgid "River events"
msgstr ""

#: ../../guides/events-list.rst:239
msgid "**create:before, river**"
msgstr ""

#: ../../guides/events-list.rst:239
msgid "Called before the river item is saved to the database. Return ``false`` to prevent the item from being created."
msgstr ""

#: ../../guides/events-list.rst:242
msgid "**create:after, river**"
msgstr ""

#: ../../guides/events-list.rst:242
msgid "Called after a river item is created."
msgstr ""

#: ../../guides/events-list.rst:245
msgid "**delete:before, river**"
msgstr ""

#: ../../guides/events-list.rst:245
msgid "Triggered before a river item is deleted. Returning false cancels the deletion."
msgstr ""

#: ../../guides/events-list.rst:248
msgid "**delete:after, river**"
msgstr ""

#: ../../guides/events-list.rst:248
msgid "Triggered after a river item was deleted."
msgstr ""

#: ../../guides/events-list.rst:251
msgid "File events"
msgstr ""

#: ../../guides/events-list.rst:256
msgid "**upload:after, file**"
msgstr ""

#: ../../guides/events-list.rst:254
msgid "Called after an uploaded file has been written to filestore. Receives an instance of ``ElggFile`` the uploaded file was written to. The ``ElggFile`` may or may not be an entity with a GUID."
msgstr ""

#: ../../guides/events-list.rst:259
msgid "Notes"
msgstr ""

#: ../../guides/events-list.rst:261
msgid "Because of bugs in the Elgg core, some events may be thrown more than once on the same action. For example, ``update, object`` is thrown twice."
msgstr ""

#: ../../guides/file-system.rst:2
msgid "File System"
msgstr ""

#: ../../guides/file-system.rst:9
msgid "Filestore"
msgstr ""

#: ../../guides/file-system.rst:12
msgid "Location"
msgstr ""

#: ../../guides/file-system.rst:14
msgid "Elgg's filestore is located in the site's ``dataroot`` that is configured during installation, and can be modified via site settings in Admin interface."
msgstr ""

#: ../../guides/file-system.rst:19
msgid "Directory Structure"
msgstr ""

#: ../../guides/file-system.rst:21
msgid "The structure of the filestore is tied to file ownership by Elgg entities. Whenever the first file owned by an entity is written to the filestore, a directory corresponding to the entity GUID will be created within a parent bucket directory (buckets are bound to 5000 guids). E.g. files owned by user with guid 7777 will be located in ``5000/7777/``."
msgstr ""

#: ../../guides/file-system.rst:26
msgid "When files are created, filenames can contain subdirectory names (often referred to as `$prefix` throughout the code). For instance, avatars of the above user, can be found under ``5000/7777/profile/``."
msgstr ""

#: ../../guides/file-system.rst:32
msgid "File Objects"
msgstr ""

#: ../../guides/file-system.rst:35
msgid "Writing Files"
msgstr ""

#: ../../guides/file-system.rst:37
msgid "To write a file to the filestore, you would use an instance of ``ElggFile``. Even though ``ElggFile`` extends `ElggObject` and can be stored as an actual Elgg entity, that is not always necessary (e.g. when writing thumbs of an image)."
msgstr ""

#: ../../guides/file-system.rst:55
msgid "Reading Files"
msgstr ""

#: ../../guides/file-system.rst:57
msgid "You can read file contents using instanceof of ``ElggFile``."
msgstr ""

#: ../../guides/file-system.rst:84
msgid "Serving Files"
msgstr ""

#: ../../guides/file-system.rst:86
msgid "You can serve files from filestore using ``elgg_get_inline_url()`` and ``elgg_get_download_url()``. Both functions accept 3 arguments:"
msgstr ""

#: ../../guides/file-system.rst:89
msgid "**``file``** An instance of ``ElggFile`` to be served"
msgstr ""

#: ../../guides/file-system.rst:90
msgid "**``use_cookie``** If set to true, validity of the URL will be limited to current session"
msgstr ""

#: ../../guides/file-system.rst:91
msgid "**``expires``** Expiration time of the URL"
msgstr ""

#: ../../guides/file-system.rst:93
msgid "You can use ``use_cookie`` and ``expires`` arguments as means of access control. For example, users avatars in most cases have a long expiration time and do not need to be restricted by current session - this will allows browsers to cache the images and file service will send appropriate ``Not Modified`` headers on consecutive requests."
msgstr ""

#: ../../guides/file-system.rst:98
msgid "The default behaviour of ``use_cookie`` can be controlled on the admin security settings page."
msgstr ""

#: ../../guides/file-system.rst:100
msgid "For entities that are under Elgg's access control, you may want to use cookies to ensure that access settings are respected and users do not share download URLs with somebody else."
msgstr ""

#: ../../guides/file-system.rst:103
msgid "You can also invalidated all previously generated URLs by updating file's modified time, e.g. by using ``touch()``."
msgstr ""

#: ../../guides/file-system.rst:108
msgid "Embedding Files"
msgstr ""

#: ../../guides/file-system.rst:110
msgid "Please note that due to their nature inline and download URLs are not suitable for embedding. Embed URLs must be permanent, whereas inline and download URLs are volatile (bound to user session and file modification time)."
msgstr ""

#: ../../guides/file-system.rst:114
msgid "To embed an entity icon, use ``elgg_get_embed_url()``."
msgstr ""

#: ../../guides/file-system.rst:118
msgid "Handling File Uploads"
msgstr ""

#: ../../guides/file-system.rst:120
msgid "In order to implement an action that saves a single file uploaded by a user, you can use the following approach:"
msgstr ""

#: ../../guides/file-system.rst:158
msgid "If your file input supports multiple files, you can iterate through them in your action:"
msgstr ""

#: ../../guides/file-system.rst:183
msgid "If images are uploaded their is an automatic attempt to fix the orientation of the image."
msgstr ""

#: ../../guides/file-system.rst:186
msgid "Temporary files"
msgstr ""

#: ../../guides/file-system.rst:188
msgid "If you ever need a temporary file you can use ``elgg_get_temp_file()``. You'll get an instance of an ``ElggTempFile`` which has all the file functions of an ``ElggFile``, but writes it's data to the systems temp folder."
msgstr ""

#: ../../guides/file-system.rst:193
msgid "It's not possible to save the ``ElggTempFile`` to the database. You'll get an ``Elgg\\Exceptions\\Filesystem\\IOException`` if you try."
msgstr ""

#: ../../guides/group-tools.rst:2
msgid "Group Tools"
msgstr ""

#: ../../guides/group-tools.rst:4
msgid "Elgg groups allow group administrators to enable/disable various tools available within a group. These tools are provided by other plugins like blog or file."
msgstr ""

#: ../../guides/group-tools.rst:7
msgid "Plugins can access group tool register via ``elgg()->group_tools``."
msgstr ""

#: ../../guides/group-tools.rst:17
msgid "A registered tool will have an option to be toggled on the group edit form, and can have a profile view module associated with it. To add a profile module, simply add a corresponding view as ``groups/profile/module/<tool_name>``. This view will only be called if the tool is enabled."
msgstr ""

#: ../../guides/group-tools.rst:21
msgid "If you simply wish to list some content in the group you can use the ``groups/profile/module`` view with some additional parameters."
msgstr ""

#: ../../guides/group-tools.rst:23
msgid "``entity_type``: in combination with the ``entity_subtype`` it can generate everything the module needs"
msgstr ""

#: ../../guides/group-tools.rst:24
msgid "``entity_subtype``: in combination with the ``entity_type`` it can generate everything the module needs"
msgstr ""

#: ../../guides/group-tools.rst:25
msgid "``no_results``: custom no results found text"
msgstr ""

#: ../../guides/group-tools.rst:27
msgid "The following will be automaticly generated:"
msgstr ""

#: ../../guides/group-tools.rst:29
msgid "``title``: based on the the language key ``collection:<entity_type>:<entity_subtype>:group``"
msgstr ""

#: ../../guides/group-tools.rst:30
msgid "``content``: ``elgg_list_entities()`` based on given type/subtype"
msgstr ""

#: ../../guides/group-tools.rst:31
msgid "``all_link``: based on the route name ``collection:<entity_type>:<entity_subtype>:group``"
msgstr ""

#: ../../guides/group-tools.rst:32
msgid "``add_link``: based on the route name ``add:<entity_type>:<entity_subtype>:group`` and with a permissions check to the given type/subtype"
msgstr ""

#: ../../guides/group-tools.rst:49
msgid "Alternatively you can generate your own title and content"
msgstr ""

#: ../../guides/group-tools.rst:60
msgid "You can programmically enable and disable tools for a given group:"
msgstr ""

#: ../../guides/group-tools.rst:72
msgid "If you want to allow a certain feature in a group only if the group tool option is enabled, you can check this using ``\\ElggGroup::isToolEnabled($tool_option)``."
msgstr ""

#: ../../guides/group-tools.rst:74
msgid "It is also a possibility to use a gatekeeper function to prevent access to a group page based on an enabled tool."
msgstr ""

#: ../../guides/group-tools.rst:82
msgid "Read more about gatekeepers here: :ref:`authentication-gatekeepers`"
msgstr ""

#: ../../guides/group-tools.rst:84
msgid "If you need the configured group tool options for a specific group you can use the ``elgg()->group_tools->group($group)`` function."
msgstr ""

#: ../../guides/guidelines.rst:2
msgid "Plugin coding guidelines"
msgstr ""

#: ../../guides/guidelines.rst:4
msgid "In addition to the Elgg Coding Standards, these are guidelines for creating plugins. Core plugins are being updated to this format and all plugin authors should follow these guidelines in their own plugins."
msgstr ""

#: ../../guides/guidelines.rst:10
msgid "Be sure to follow the :doc:`plugins/plugin-skeleton` for your plugin's layout."
msgstr ""

#: ../../guides/guidelines.rst:14
msgid ":doc:`dont-modify-core`"
msgstr ""

#: ../../guides/guidelines.rst:21
msgid "Use standardized routing with page handlers"
msgstr ""

#: ../../guides/guidelines.rst:23
#: ../../guides/guidelines.rst:51
#: ../../guides/guidelines.rst:63
msgid "Example: Bookmarks plugin"
msgstr ""

#: ../../guides/guidelines.rst:40
msgid "Page handlers should accept the following standard URLs:"
msgstr ""

#: ../../guides/guidelines.rst:26
#: ../../guides/guidelines.rst:71
msgid "Purpose"
msgstr ""

#: ../../guides/guidelines.rst:26
#: ../../guides/guidelines.rst:71
msgid "URL"
msgstr ""

#: ../../guides/guidelines.rst:28
msgid "All"
msgstr ""

#: ../../guides/guidelines.rst:28
msgid "page_handler/all"
msgstr ""

#: ../../guides/guidelines.rst:30
msgid "User"
msgstr ""

#: ../../guides/guidelines.rst:30
msgid "page_handler/owner/<username>"
msgstr ""

#: ../../guides/guidelines.rst:32
msgid "User friends’"
msgstr ""

#: ../../guides/guidelines.rst:32
msgid "page_handler/friends/<username>"
msgstr ""

#: ../../guides/guidelines.rst:34
msgid "Single entity"
msgstr ""

#: ../../guides/guidelines.rst:34
msgid "page_handler/view/<guid>/<title>"
msgstr ""

#: ../../guides/guidelines.rst:36
#: ../../guides/guidelines.rst:73
msgid "Add"
msgstr ""

#: ../../guides/guidelines.rst:36
msgid "page_handler/add/<container_guid>"
msgstr ""

#: ../../guides/guidelines.rst:38
#: ../../guides/guidelines.rst:75
msgid "Edit"
msgstr ""

#: ../../guides/guidelines.rst:38
msgid "page_handler/edit/<guid>"
msgstr ""

#: ../../guides/guidelines.rst:40
msgid "Group list"
msgstr ""

#: ../../guides/guidelines.rst:40
msgid "page_handler/group/<guid>/owner"
msgstr ""

#: ../../guides/guidelines.rst:42
msgid "Include page handler scripts from the page handler. Almost every page handler should have a page handler script. (Example: ``bookmarks/all`` => ``mod/bookmarks/views/default/resources/bookmarks/all.php``)"
msgstr ""

#: ../../guides/guidelines.rst:43
msgid "Pass arguments like entity guids to the resource view via ``$vars`` in ``elgg_view_resource()``."
msgstr ""

#: ../../guides/guidelines.rst:44
msgid "Call ``elgg_gatekeeper()`` and ``elgg_admin_gatekeeper()`` in the page handler function if required."
msgstr ""

#: ../../guides/guidelines.rst:45
msgid "The group URL should use views like ``resources/groups/*.php`` to render pages."
msgstr ""

#: ../../guides/guidelines.rst:46
msgid "Page handlers should not contain HTML."
msgstr ""

#: ../../guides/guidelines.rst:49
msgid "Use standardized page handlers and scripts"
msgstr ""

#: ../../guides/guidelines.rst:52
msgid "Store page functionality in ``mod/<plugin>/views/default/resources/<page_handler>/<page_name>.php``"
msgstr ""

#: ../../guides/guidelines.rst:53
msgid "Use ``elgg_view_resource('<page_handler>/<page_name>')`` to render that."
msgstr ""

#: ../../guides/guidelines.rst:54
msgid "Use the default page layout in page handler scripts: ``$content = elgg_view_layout('default', $options);``"
msgstr ""

#: ../../guides/guidelines.rst:55
msgid "Page handler scripts should not contain HTML"
msgstr ""

#: ../../guides/guidelines.rst:56
msgid "Call ``elgg_push_breadcrumb()`` in the page handler scripts."
msgstr ""

#: ../../guides/guidelines.rst:57
msgid "No need to worry about setting the page owner if the URLs are in the standardized format"
msgstr ""

#: ../../guides/guidelines.rst:58
msgid "For group content, check the ``container_guid`` by using ``elgg_get_page_owner_entity()``"
msgstr ""

#: ../../guides/guidelines.rst:61
msgid "The object/<subtype> view"
msgstr ""

#: ../../guides/guidelines.rst:64
msgid "Make sure there are views for ``$vars['full_view'] == true`` and ``$vars['full_view'] == false``"
msgstr ""

#: ../../guides/guidelines.rst:65
msgid "Check for the object in ``$vars['entity']`` . Use ``elgg_instance_of()`` to make sure it’s the type entity you want. Return ``true`` to short circuit the view if the entity is missing or wrong."
msgstr ""

#: ../../guides/guidelines.rst:66
msgid "Use the new list body and list metadata views to help format. You should use almost no markup in these views."
msgstr ""

#: ../../guides/guidelines.rst:67
msgid "Update action structure - Example: Bookmarks plugin."
msgstr ""

#: ../../guides/guidelines.rst:68
msgid "Namespace action files and action names (example: ``mod/blog/actions/blog/save.php`` => ``action/blog/save``)"
msgstr ""

#: ../../guides/guidelines.rst:77
msgid "Use the following action URLs:"
msgstr ""

#: ../../guides/guidelines.rst:73
#: ../../guides/guidelines.rst:75
msgid "action/plugin/save"
msgstr ""

#: ../../guides/guidelines.rst:77
msgid "Delete"
msgstr ""

#: ../../guides/guidelines.rst:77
msgid "action/plugin/delete"
msgstr ""

#: ../../guides/guidelines.rst:79
msgid "Make the delete action accept ``action/<handler>/delete?guid=<guid>`` so the metadata entity menu has the correct URL by default"
msgstr ""

#: ../../guides/guidelines.rst:82
#: ../../guides/plugins/plugin-skeleton.rst:79
msgid "Actions"
msgstr ""

#: ../../guides/guidelines.rst:84
msgid "Actions are transient states to perform an action such as updating the database or sending a notification to a user. Used correctly, actions provide a level of access control and prevent against CSRF attacks."
msgstr ""

#: ../../guides/guidelines.rst:86
msgid "Actions require action (CSRF) tokens to be submitted via GET/POST, but these are added automatically by elgg_view_form() and by using the ``is_action`` argument of the ``output/url`` view."
msgstr ""

#: ../../guides/guidelines.rst:89
msgid "Action best practices"
msgstr ""

#: ../../guides/guidelines.rst:91
msgid "Action files are included within Elgg's action system; like views, they are *not* regular scripts executable by users. Do not boot the Elgg core in your file and direct users to load it directly."
msgstr ""

#: ../../guides/guidelines.rst:93
msgid "Because actions are time-sensitive they are not suitable for links in emails or other delayed notifications. An example of this would be invitations to join a group. The clean way to create an invitation link is to create a page handler for invitations and email that link to the user. It is then the page handler's responsibility to create the action links for a user to join or ignore the invitation request."
msgstr ""

#: ../../guides/guidelines.rst:95
msgid "Consider that actions may be submitted via XHR requests, not just links or form submissions."
msgstr ""

#: ../../guides/guidelines.rst:98
msgid "Directly calling a file"
msgstr ""

#: ../../guides/guidelines.rst:100
msgid "This is an easy one: **Don't do it**. With the exception of 3rd party application integration, there is not a reason to directly call a file in mods directory."
msgstr ""

#: ../../guides/guidelines.rst:103
msgid "Recommended"
msgstr ""

#: ../../guides/guidelines.rst:105
msgid "These points are good ideas, but are not yet in the official guidelines. Following these suggestions will help to keep your plugin consistent with Elgg core."
msgstr ""

#: ../../guides/guidelines.rst:107
msgid "Update the widget views (see the blog or file widgets)"
msgstr ""

#: ../../guides/guidelines.rst:108
msgid "Update the group profile “widget” using blog or file plugins as example"
msgstr ""

#: ../../guides/guidelines.rst:112
msgid "Update the forms"
msgstr ""

#: ../../guides/guidelines.rst:110
msgid "Move form bodies to ``/forms/<handler>/<action>`` to use Evan’s new ``elgg_view_form()``"
msgstr ""

#: ../../guides/guidelines.rst:111
msgid "Use input views in form bodies rather than html"
msgstr ""

#: ../../guides/guidelines.rst:112
msgid "Add a function that prepares the form (see ``mod/file/lib/file.php`` for example)"
msgstr ""

#: ../../guides/guidelines.rst:113
msgid "Integrate sticky forms (see the file plugin’s upload action and form prepare function)"
msgstr ""

#: ../../guides/guidelines.rst:114
msgid "Clean up CSS/HTML"
msgstr ""

#: ../../guides/guidelines.rst:115
msgid "Should be able to remove almost all CSS (look for patterns that can be moved into core if you need CSS)"
msgstr ""

#: ../../guides/guidelines.rst:116
msgid "Use hyphens rather than underscores in classes/ids"
msgstr ""

#: ../../guides/guidelines.rst:117
msgid "Do not use the ``bundled`` category with your plugins. That is for plugins distributed with Elgg"
msgstr ""

#: ../../guides/guidelines.rst:118
msgid "Don't use ``register_shutdown_function`` as you may not have access to certain Elgg parts anymore (eg database). Instead use the ``shutdown`` ``system`` event"
msgstr ""

#: ../../guides/helpers.rst:9
msgid "Input and output"
msgstr ""

#: ../../guides/helpers.rst:11
msgid "``get_input($name)`` Grabs information from a form field (or any variable passed using GET or POST). Also sanitises input, stripping Javascript etc."
msgstr ""

#: ../../guides/helpers.rst:12
msgid "``set_input($name, $value)`` Forces a value to a particular variable for subsequent retrieval by ``get_input()``"
msgstr ""

#: ../../guides/helpers.rst:15
msgid "Entity methods"
msgstr ""

#: ../../guides/helpers.rst:17
msgid "``$entity->getURL()`` Returns the URL of any entity in the system"
msgstr ""

#: ../../guides/helpers.rst:18
msgid "``$entity->getGUID()`` Returns the GUID of any entity in the system"
msgstr ""

#: ../../guides/helpers.rst:19
msgid "``$entity->canEdit()`` Returns whether or not the current user can edit the entity"
msgstr ""

#: ../../guides/helpers.rst:20
msgid "``$entity->getOwnerEntity()`` Returns the ElggUser owner of a particular entity"
msgstr ""

#: ../../guides/helpers.rst:23
msgid "Entity and context retrieval"
msgstr ""

#: ../../guides/helpers.rst:25
msgid "``elgg_get_logged_in_user_entity()`` Returns the ElggUser for the current user"
msgstr ""

#: ../../guides/helpers.rst:26
msgid "``elgg_get_logged_in_user_guid()`` Returns the GUID of the current user"
msgstr ""

#: ../../guides/helpers.rst:27
msgid "``elgg_is_logged_in()`` Is the viewer logged in"
msgstr ""

#: ../../guides/helpers.rst:28
msgid "``elgg_is_admin_logged_in()`` Is the view an admin and logged in"
msgstr ""

#: ../../guides/helpers.rst:29
msgid "``elgg_gatekeeper()`` Shorthand for checking if a user is logged in. Forwards user to front page if not"
msgstr ""

#: ../../guides/helpers.rst:30
msgid "``elgg_admin_gatekeeper()`` Shorthand for checking the user is logged in and is an admin. Forwards user to front page if not"
msgstr ""

#: ../../guides/helpers.rst:31
msgid "``get_user($user_guid)`` Given a GUID, returns a full ElggUser entity"
msgstr ""

#: ../../guides/helpers.rst:32
msgid "``elgg_get_page_owner_guid()`` Returns the GUID of the current page owner, if there is one"
msgstr ""

#: ../../guides/helpers.rst:33
msgid "``elgg_get_page_owner_entity()`` Like elgg_get_page_owner_guid() but returns the full entity"
msgstr ""

#: ../../guides/helpers.rst:34
msgid "``elgg_get_context()`` Returns the current page's context - eg \"blog\" for the blog plugin, \"thewire\" for the wire, etc. Returns \"main\" as default"
msgstr ""

#: ../../guides/helpers.rst:35
msgid "``elgg_set_context($context)`` Forces the context to be a particular value"
msgstr ""

#: ../../guides/helpers.rst:36
msgid "``elgg_push_context($context)`` Adds a context to the stack"
msgstr ""

#: ../../guides/helpers.rst:37
msgid "``elgg_pop_context()`` Removes the top context from the stack"
msgstr ""

#: ../../guides/helpers.rst:38
msgid "``elgg_in_context($context)`` Checks if you're in a context (this checks the complete stack, eg. 'widget' in 'groups')"
msgstr ""

#: ../../guides/helpers.rst:41
#: ../../guides/hooks-list.rst:1113
#: ../../guides/plugins.rst:2
msgid "Plugins"
msgstr ""

#: ../../guides/helpers.rst:43
msgid "``elgg_is_active_plugin($plugin_id)`` Check if a plugin is installed and enabled"
msgstr ""

#: ../../guides/helpers.rst:46
msgid "Interface and annotations"
msgstr ""

#: ../../guides/helpers.rst:48
msgid "``elgg_view_image_block($icon, $info)`` Return the result in a formatted list"
msgstr ""

#: ../../guides/helpers.rst:49
msgid "``elgg_view_comments($entity)`` Returns any comments associated with the given entity"
msgstr ""

#: ../../guides/helpers.rst:50
msgid "``elgg_get_friendly_time($unix_timestamp)`` Returns a date formatted in a friendlier way - \"18 minutes ago\", \"2 days ago\", etc."
msgstr ""

#: ../../guides/helpers.rst:53
msgid "Messages"
msgstr ""

#: ../../guides/helpers.rst:55
msgid "``system_message($message)`` Registers a success message"
msgstr ""

#: ../../guides/helpers.rst:56
msgid "``register_error($message)`` Registers an error message"
msgstr ""

#: ../../guides/helpers.rst:57
msgid "``elgg_view_message($type, $message)`` Outputs a message"
msgstr ""

#: ../../guides/hooks-list.rst:2
msgid "List of plugin hooks in core"
msgstr ""

#: ../../guides/hooks-list.rst:4
msgid "For more information on how hooks work visit :doc:`/design/events`."
msgstr ""

#: ../../guides/hooks-list.rst:8
msgid "Contents  :local:"
msgstr ""

#: ../../guides/hooks-list.rst:11
msgid "System hooks"
msgstr ""

#: ../../guides/hooks-list.rst:14
msgid "**page_owner, system**"
msgstr ""

#: ../../guides/hooks-list.rst:14
msgid "Filter the page_owner for the current page. No options are passed."
msgstr ""

#: ../../guides/hooks-list.rst:16
msgid "**siteid, system**"
msgstr ""

#: ../../guides/hooks-list.rst:19
msgid "**gc, system**"
msgstr ""

#: ../../guides/hooks-list.rst:19
msgid "Allows plugins to run garbage collection for ``$params['period']``."
msgstr ""

#: ../../guides/hooks-list.rst:22
#: ../../guides/hooks-list.rst:42
msgid "**diagnostics:report, system**"
msgstr ""

#: ../../guides/hooks-list.rst:22
msgid "Filter the output for the diagnostics report download."
msgstr ""

#: ../../guides/hooks-list.rst:25
msgid "**cron, <period>**"
msgstr ""

#: ../../guides/hooks-list.rst:25
msgid "Triggered by cron for each period."
msgstr ""

#: ../../guides/hooks-list.rst:28
msgid "**cron:intervals, system**"
msgstr ""

#: ../../guides/hooks-list.rst:28
msgid "Allow the configuration of custom cron intervals"
msgstr ""

#: ../../guides/hooks-list.rst:31
msgid "**validate, input**"
msgstr ""

#: ../../guides/hooks-list.rst:31
msgid "Filter GET and POST input. This is used by ``get_input()`` to sanitize user input."
msgstr ""

#: ../../guides/hooks-list.rst:39
msgid "**prepare, html**"
msgstr ""

#: ../../guides/hooks-list.rst:34
msgid "Triggered by ``elgg_format_html()`` and used to prepare untrusted HTML."
msgstr ""

#: ../../guides/hooks-list.rst:36
msgid "The ``$return`` value is an array:"
msgstr ""

#: ../../guides/hooks-list.rst:38
msgid "``html`` - HTML string being prepared"
msgstr ""

#: ../../guides/hooks-list.rst:39
msgid "``options`` - Preparation options"
msgstr ""

#: ../../guides/hooks-list.rst:42
msgid "Filters the output for a diagnostic report."
msgstr ""

#: ../../guides/hooks-list.rst:54
msgid "**debug, log**"
msgstr ""

#: ../../guides/hooks-list.rst:45
msgid "Triggered by the Logger. Return false to stop the default logging method. ``$params`` includes:"
msgstr ""

#: ../../guides/hooks-list.rst:51
msgid "level - The debug level. One of:"
msgstr ""

#: ../../guides/hooks-list.rst:48
msgid "``Elgg_Logger::OFF``"
msgstr ""

#: ../../guides/hooks-list.rst:49
msgid "``Elgg_Logger::ERROR``"
msgstr ""

#: ../../guides/hooks-list.rst:50
msgid "``Elgg_Logger::WARNING``"
msgstr ""

#: ../../guides/hooks-list.rst:51
msgid "``Elgg_Logger::NOTICE``"
msgstr ""

#: ../../guides/hooks-list.rst:52
msgid "``Elgg_Logger::INFO``"
msgstr ""

#: ../../guides/hooks-list.rst:53
msgid "msg - The message"
msgstr ""

#: ../../guides/hooks-list.rst:54
msgid "display - Should this message be displayed?"
msgstr ""

#: ../../guides/hooks-list.rst:57
msgid "**format, friendly:title**"
msgstr ""

#: ../../guides/hooks-list.rst:57
msgid "Formats the \"friendly\" title for strings. This is used for generating URLs."
msgstr ""

#: ../../guides/hooks-list.rst:60
msgid "**format, friendly:time**"
msgstr ""

#: ../../guides/hooks-list.rst:60
msgid "Formats the \"friendly\" time for the timestamp ``$params['time']``."
msgstr ""

#: ../../guides/hooks-list.rst:64
msgid "**format, strip_tags**"
msgstr ""

#: ../../guides/hooks-list.rst:63
msgid "Filters a string to remove tags. The original string is passed as ``$params['original_string']`` and an optional set of allowed tags is passed as ``$params['allowed_tags']``."
msgstr ""

#: ../../guides/hooks-list.rst:69
msgid "**output:before, page**"
msgstr ""

#: ../../guides/hooks-list.rst:67
msgid "In ``elgg_view_page()``, this filters ``$vars`` before it's passed to the page shell view (``page/<page_shell>``). To stop sending the X-Frame-Options header, unregister the handler ``Elgg\\Page\\SetXFrameOptionsHeaderHandler::class`` from this hook."
msgstr ""

#: ../../guides/hooks-list.rst:72
msgid "**output, page**"
msgstr ""

#: ../../guides/hooks-list.rst:72
msgid "In ``elgg_view_page()``, this filters the output return value."
msgstr ""

#: ../../guides/hooks-list.rst:81
msgid "**parameters, menu:<menu_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:75
msgid "Triggered by ``elgg_view_menu()``. Used to change menu variables (like sort order) before rendering."
msgstr ""

#: ../../guides/hooks-list.rst:77
#: ../../guides/hooks-list.rst:106
#: ../../guides/hooks-list.rst:199
#: ../../guides/hooks-list.rst:209
#: ../../guides/hooks-list.rst:236
#: ../../guides/hooks-list.rst:277
#: ../../guides/hooks-list.rst:284
#: ../../guides/hooks-list.rst:404
#: ../../guides/hooks-list.rst:418
#: ../../guides/hooks-list.rst:437
msgid "The ``$params`` array will contain:"
msgstr ""

#: ../../guides/hooks-list.rst:79
msgid "``name`` - name of the menu"
msgstr ""

#: ../../guides/hooks-list.rst:80
msgid "``sort_by`` - preferring sorting parameter"
msgstr ""

#: ../../guides/hooks-list.rst:81
msgid "other parameters passed to ``elgg_view_menu()``"
msgstr ""

#: ../../guides/hooks-list.rst:91
msgid "**register, menu:<menu_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:84
msgid "Filters the initial list of menu items pulled from configuration, before the menu has been split into sections. Triggered by ``elgg_view_menu()`` and ``elgg()->menus->getMenu()``."
msgstr ""

#: ../../guides/hooks-list.rst:87
msgid "The ``$params`` array will contain parameters returned by ``parameters, menu:<menu_name>`` hook."
msgstr ""

#: ../../guides/hooks-list.rst:89
msgid "The return value is an instance of ``\\Elgg\\Menu\\MenuItems`` containing ``\\ElggMenuItem`` objects."
msgstr ""

#: ../../guides/hooks-list.rst:91
msgid "Hook handlers can add/remove items to the collection using the collection API, as well as array access operations."
msgstr ""

#: ../../guides/hooks-list.rst:99
msgid "**register, menu:<menu_name>:<type>:<subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:94
msgid "More granular version of the menu hook triggered before the **register, menu:<menu_name>** hook."
msgstr ""

#: ../../guides/hooks-list.rst:96
#: ../../guides/hooks-list.rst:116
msgid "Only applied if menu params contain - params['entity'] with an ``\\ElggEntity`` (``<type>`` is ``\\ElggEntity::type`` and ``<subtype>`` is ``\\ElggEntity::subtype``) or - params['annotation'] with an ``\\ElggAnnotation`` (``<type>`` is ``\\ElggAnnotation::getType()`` and ``<subtype>`` is ``\\ElggAnnotation::getSubtype()``) or - params['relationship'] with an ``\\ElggRelationship`` (``<type>`` is ``\\ElggRelationship::getType()`` and ``<subtype>`` is ``\\ElggRelationship::getSubtype()``)"
msgstr ""

#: ../../guides/hooks-list.rst:111
msgid "**prepare, menu:<menu_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:102
msgid "Filters the array of menu sections before they're displayed. Each section is a string key mapping to an area of menu items. This is a good hook to sort, add, remove, and modify menu items. Triggered by ``elgg_view_menu()`` and ``elgg()->menus->prepareMenu()``."
msgstr ""

#: ../../guides/hooks-list.rst:108
msgid "``selected_item`` - ``ElggMenuItem`` selected in the menu, if any"
msgstr ""

#: ../../guides/hooks-list.rst:110
msgid "The return value is an instance of ``\\Elgg\\Menu\\PreparedMenu``. The prepared menu is a collection of ``\\Elgg\\Menu\\MenuSection``, which in turn are collections of ``\\ElggMenuItem`` objects."
msgstr ""

#: ../../guides/hooks-list.rst:119
msgid "**prepare, menu:<menu_name>:<type>:<subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:114
msgid "More granular version of the menu hook triggered before the **prepare, menu:<menu_name>** hook."
msgstr ""

#: ../../guides/hooks-list.rst:139
msgid "**register, menu:filter:<filter_id>**"
msgstr ""

#: ../../guides/hooks-list.rst:122
msgid "Allows plugins to modify layout filter tabs on layouts that specify ``<filter_id>`` parameter. Parameters and return values are same as in ``register, menu:<menu_name>`` hook."
msgstr ""

#: ../../guides/hooks-list.rst:125
msgid "If ``filter_id`` is ``filter`` (the default) then the ``all``, ``mine`` and ``friends`` tabs will be generated base on some provided information or be tried for routes similar to the current route."
msgstr ""

#: ../../guides/hooks-list.rst:128
msgid "params['all_link'] will be used for the ``all`` tab"
msgstr ""

#: ../../guides/hooks-list.rst:129
msgid "params['mine_link'] will be used for the ``mine`` tab"
msgstr ""

#: ../../guides/hooks-list.rst:130
msgid "params['friends_link'] will be used for the ``friend`` tab"
msgstr ""

#: ../../guides/hooks-list.rst:132
msgid "If the above are not provided than a route will be tried based on ``params['entity_type']`` and ``params['entity_subtype']``. If not provided ``entity_type`` and ``entity_subtype`` will be based on route detection of the current route. For example if the current route is ``collection:object:blog:all`` ``entity_type`` will be ``object`` and ``entity_subtype`` will be ``blog``. - The ``all`` tab will be based on the route ``collection:<entity_type>:<entity_subtype>:all`` - The ``mine`` tab will be based on the route ``collection:<entity_type>:<entity_subtype>:owner`` - The ``friend`` tab will be based on the route ``collection:<entity_type>:<entity_subtype>:friends``"
msgstr ""

#: ../../guides/hooks-list.rst:139
msgid "If the routes aren't registered the tabs will not appear."
msgstr ""

#: ../../guides/hooks-list.rst:143
msgid "**creating, river**"
msgstr ""

#: ../../guides/hooks-list.rst:142
msgid "The options for ``elgg_create_river_item`` are filtered through this hook. You may alter values or return ``false`` to cancel the item creation."
msgstr ""

#: ../../guides/hooks-list.rst:146
msgid "**simplecache:generate, <view>**"
msgstr ""

#: ../../guides/hooks-list.rst:146
msgid "Filters the view output for a ``/cache`` URL when simplecache is enabled."
msgstr ""

#: ../../guides/hooks-list.rst:150
msgid "**cache:generate, <view>**"
msgstr ""

#: ../../guides/hooks-list.rst:149
msgid "Filters the view output for a ``/cache`` URL when simplecache is disabled. Note this will be fired for every ``/cache`` request--no Expires headers are used when simplecache is disabled."
msgstr ""

#: ../../guides/hooks-list.rst:159
msgid "**prepare, breadcrumbs**"
msgstr ""

#: ../../guides/hooks-list.rst:153
msgid "In ``elgg_get_breadcrumbs()``, this filters the registered breadcrumbs before returning them, allowing a plugin to alter breadcrumb strategy site-wide. ``$params`` array includes:"
msgstr ""

#: ../../guides/hooks-list.rst:157
msgid "``breadcrumbs`` - an array of bredcrumbs, each with ``title`` and ``link`` keys"
msgstr ""

#: ../../guides/hooks-list.rst:158
msgid "``identifier`` - route identifier of the current page"
msgstr ""

#: ../../guides/hooks-list.rst:159
msgid "``segments`` - route segments of the current page"
msgstr ""

#: ../../guides/hooks-list.rst:162
msgid "**elgg.data, site**"
msgstr ""

#: ../../guides/hooks-list.rst:162
msgid "Filters cached configuration data to pass to the client. :ref:`More info <guides/javascript#config>`"
msgstr ""

#: ../../guides/hooks-list.rst:165
msgid "**elgg.data, page**"
msgstr ""

#: ../../guides/hooks-list.rst:165
msgid "Filters uncached, page-specific configuration data to pass to the client. :ref:`More info <guides/javascript#config>`"
msgstr ""

#: ../../guides/hooks-list.rst:170
msgid "**registration_url, site**"
msgstr ""

#: ../../guides/hooks-list.rst:168
msgid "Filters site's registration URL. Can be used by plugins to attach invitation codes, referrer codes etc. to the registration URL. ``$params`` array contains an array of query elements added to the registration URL by the invoking script. The hook must return an absolute URL to the registration page."
msgstr ""

#: ../../guides/hooks-list.rst:175
msgid "**login_url, site**"
msgstr ""

#: ../../guides/hooks-list.rst:173
msgid "Filters site's login URL. ``$params`` array contains an array of query elements added to the login URL by the invoking script. The hook must return an absolute URL of the login page."
msgstr ""

#: ../../guides/hooks-list.rst:179
msgid "**commands, cli**"
msgstr ""

#: ../../guides/hooks-list.rst:178
msgid "Allows plugins to register their own commands executable via ``elgg-cli`` binary. Handlers must return an array of command class names. Commands must extend ``\\Elgg\\Cli\\Command`` to be executable."
msgstr ""

#: ../../guides/hooks-list.rst:183
msgid "**seeds, database**"
msgstr ""

#: ../../guides/hooks-list.rst:182
msgid "Allows plugins to register their own database seeds. Seeds populate the database with fake entities for testing purposes. Seeds must extend ``\\Elgg\\Database\\Seeds\\Seed`` class to be executable via ``elgg-cli database:seed``."
msgstr ""

#: ../../guides/hooks-list.rst:186
msgid "**languages, translations**"
msgstr ""

#: ../../guides/hooks-list.rst:186
msgid "Allows plugins to add/remove languages from the configurable languages in the system."
msgstr ""

#: ../../guides/hooks-list.rst:189
msgid "**generate, password**"
msgstr ""

#: ../../guides/hooks-list.rst:189
msgid "Allows plugins to generate new random cleartext passwords."
msgstr ""

#: ../../guides/hooks-list.rst:192
msgid "User hooks"
msgstr ""

#: ../../guides/hooks-list.rst:202
msgid "**usersettings:save, user**"
msgstr ""

#: ../../guides/hooks-list.rst:195
msgid "Triggered in the aggregate action to save user settings. The hook handler must return ``false`` to prevent sticky forms from being cleared (i.e. to indicate that some of the values were not saved). Do not return ``true`` from your hook handler, as you will override other hooks' output, instead return ``null`` to indicate successful operation."
msgstr ""

#: ../../guides/hooks-list.rst:201
#: ../../guides/hooks-list.rst:211
msgid "``user`` - ``\\ElggUser``, whose settings are being saved"
msgstr ""

#: ../../guides/hooks-list.rst:202
#: ../../guides/hooks-list.rst:213
msgid "``request`` - ``\\Elgg\\Request`` to the action controller"
msgstr ""

#: ../../guides/hooks-list.rst:213
msgid "**change:email, user**"
msgstr ""

#: ../../guides/hooks-list.rst:205
msgid "Triggered before the user email is changed. Allows plugins to implement additional logic required to change email, e.g. additional email validation. The hook handler must return false to prevent the email from being changed right away."
msgstr ""

#: ../../guides/hooks-list.rst:212
msgid "``email`` - Email address that passes sanity checks"
msgstr ""

#: ../../guides/hooks-list.rst:217
#: ../../guides/hooks-list.rst:301
msgid "**access:collections:write, user**"
msgstr ""

#: ../../guides/hooks-list.rst:216
msgid "Filters an array of access permissions that the user ``$params['user_id']`` is allowed to save content with. Permissions returned are of the form (id => 'Human Readable Name')."
msgstr ""

#: ../../guides/hooks-list.rst:221
msgid "**registeruser:validate:username, all**"
msgstr ""

#: ../../guides/hooks-list.rst:220
msgid "Return boolean for if the string in ``$params['username']`` is valid for a username. Hook handler can throw ``\\Elgg\\Exceptions\\Configuration\\RegistrationException`` with an error message to be shown to the user."
msgstr ""

#: ../../guides/hooks-list.rst:225
msgid "**registeruser:validate:password, all**"
msgstr ""

#: ../../guides/hooks-list.rst:224
msgid "Return boolean for if the string in ``$params['password']`` is valid for a password. Hook handler can throw ``\\Elgg\\Exceptions\\Configuration\\RegistrationException`` with an error message to be shown to the user."
msgstr ""

#: ../../guides/hooks-list.rst:229
msgid "**registeruser:validate:email, all**"
msgstr ""

#: ../../guides/hooks-list.rst:228
msgid "Return boolean for if the string in ``$params['email']`` is valid for an email address. Hook handler can throw ``\\Elgg\\Exceptions\\Configuration\\RegistrationException`` with an error message to be shown to the user."
msgstr ""

#: ../../guides/hooks-list.rst:239
msgid "**register, user**"
msgstr ""

#: ../../guides/hooks-list.rst:232
msgid "Triggered by the ``register`` action after the user registers. Return ``false`` to delete the user. Note the function ``register_user`` does *not* trigger this hook. Hook handlers can throw ``\\Elgg\\Exceptions\\Configuration\\RegistrationException`` with an error message to be displayed to the user."
msgstr ""

#: ../../guides/hooks-list.rst:238
msgid "``user`` - Newly registered user entity"
msgstr ""

#: ../../guides/hooks-list.rst:239
msgid "All parameters sent with the request to the action (incl. ``password``, ``friend_guid``, ``invitecode`` etc)"
msgstr ""

#: ../../guides/hooks-list.rst:242
msgid "**login:forward, user**"
msgstr ""

#: ../../guides/hooks-list.rst:242
msgid "Filters the URL to which the user will be forwarded after login."
msgstr ""

#: ../../guides/hooks-list.rst:245
msgid "**find_active_users, system**"
msgstr ""

#: ../../guides/hooks-list.rst:245
msgid "Return the number of active users."
msgstr ""

#: ../../guides/hooks-list.rst:248
msgid "**status, user**"
msgstr ""

#: ../../guides/hooks-list.rst:248
msgid "Triggered by The Wire when adding a post."
msgstr ""

#: ../../guides/hooks-list.rst:253
msgid "**username:character_blacklist, user**"
msgstr ""

#: ../../guides/hooks-list.rst:251
msgid "Filters the string of blacklisted characters used to validate username during registration. The return value should be a string consisting of the disallowed characters. The default string can be found from ``$params['blacklist']``."
msgstr ""

#: ../../guides/hooks-list.rst:256
msgid "Object hooks"
msgstr ""

#: ../../guides/hooks-list.rst:260
msgid "**comments, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:259
msgid "Triggered in ``elgg_view_comments()``. If returning content, this overrides the ``page/elements/comments`` view."
msgstr ""

#: ../../guides/hooks-list.rst:263
msgid "**comments:count, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:263
msgid "Return the number of comments on ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:267
msgid "**likes:count, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:266
msgid "Return the number of likes for ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:272
msgid "Access hooks"
msgstr ""

#: ../../guides/hooks-list.rst:279
msgid "**access_collection:url, access_collection**"
msgstr ""

#: ../../guides/hooks-list.rst:275
msgid "Can be used to filter the URL of the access collection."
msgstr ""

#: ../../guides/hooks-list.rst:279
#: ../../guides/hooks-list.rst:286
msgid "``access_collection`` - `ElggAccessCollection`"
msgstr ""

#: ../../guides/hooks-list.rst:286
msgid "**access_collection:name, access_collection**"
msgstr ""

#: ../../guides/hooks-list.rst:282
msgid "Can be used to filter the display name (readable access level) of the access collection."
msgstr ""

#: ../../guides/hooks-list.rst:291
msgid "**access:collections:read, user**"
msgstr ""

#: ../../guides/hooks-list.rst:289
msgid "Filters an array of access IDs that the user ``$params['user_id']`` can see."
msgstr ""

#: ../../guides/hooks-list.rst:291
#: ../../guides/hooks-list.rst:301
msgid "The handler needs to either not use parts of the API that use the access system (triggering the hook again) or to ignore the second call. Otherwise, an infinite loop will be created."
msgstr ""

#: ../../guides/hooks-list.rst:294
msgid "Filters an array of access IDs that the user ``$params['user_id']`` can write to. In get_write_access_array(), this hook filters the return value, so it can be used to alter the available options in the input/access view. For core plugins, the value \"input_params\" has the keys \"entity\" (ElggEntity|false), \"entity_type\" (string), \"entity_subtype\" (string), \"container_guid\" (int) are provided. An empty entity value generally means the form is to create a new object."
msgstr ""

#: ../../guides/hooks-list.rst:304
msgid "**access:collections:write:subtypes, user**"
msgstr ""

#: ../../guides/hooks-list.rst:304
msgid "Returns an array of access collection subtypes to be used when retrieving access collections owned by a user as part of the ``get_write_access_array()`` function."
msgstr ""

#: ../../guides/hooks-list.rst:307
msgid "**access:collections:addcollection, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:307
msgid "Triggered after an access collection ``$params['collection_id']`` is created."
msgstr ""

#: ../../guides/hooks-list.rst:311
msgid "**access:collections:deletecollection, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:310
msgid "Triggered before an access collection ``$params['collection_id']`` is deleted. Return false to prevent deletion."
msgstr ""

#: ../../guides/hooks-list.rst:315
msgid "**access:collections:add_user, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:314
msgid "Triggered before adding user ``$params['user_id']`` to collection ``$params['collection_id']``. Return false to prevent adding."
msgstr ""

#: ../../guides/hooks-list.rst:319
msgid "**access:collections:remove_user, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:318
msgid "Triggered before removing user ``$params['user_id']`` to collection ``$params['collection_id']``. Return false to prevent removal."
msgstr ""

#: ../../guides/hooks-list.rst:338
msgid "**get_sql, access**"
msgstr ""

#: ../../guides/hooks-list.rst:322
msgid "Filters SQL clauses restricting/allowing access to entities and annotations."
msgstr ""

#: ../../guides/hooks-list.rst:324
msgid "**The hook is triggered regardless if the access is ignored**. The handlers may need to check if access is ignored and return early, if appended clauses should only apply to access controlled contexts."
msgstr ""

#: ../../guides/hooks-list.rst:326
msgid "``$return`` value is a nested array of ``ands`` and ``ors``."
msgstr ""

#: ../../guides/hooks-list.rst:328
msgid "``$params`` includes:"
msgstr ""

#: ../../guides/hooks-list.rst:330
msgid "``table_alias`` - alias of the main table used in select clause"
msgstr ""

#: ../../guides/hooks-list.rst:331
msgid "``ignore_access`` - whether ignored access is enabled"
msgstr ""

#: ../../guides/hooks-list.rst:332
msgid "``use_enabled_clause`` - whether disabled entities are shown/hidden"
msgstr ""

#: ../../guides/hooks-list.rst:333
msgid "``access_column`` - column in the main table containing the access collection ID value"
msgstr ""

#: ../../guides/hooks-list.rst:334
msgid "``owner_guid_column`` - column in the main table referencing the GUID of the owner"
msgstr ""

#: ../../guides/hooks-list.rst:335
msgid "``guid_column`` - column in the main table referencing the GUID of the entity"
msgstr ""

#: ../../guides/hooks-list.rst:336
msgid "``enabled_column`` - column in the main table referencing the enabled status of the entity"
msgstr ""

#: ../../guides/hooks-list.rst:337
msgid "``query_builder`` - an instance of the ``QueryBuilder``"
msgstr ""

#: ../../guides/hooks-list.rst:341
msgid "Action hooks"
msgstr ""

#: ../../guides/hooks-list.rst:351
msgid "**action:validate, <action>**"
msgstr ""

#: ../../guides/hooks-list.rst:344
msgid "Trigger before action script/controller is executed. This hook should be used to validate/alter user input, before proceeding with the action. The hook handler can throw an instance of ``\\Elgg\\Exceptions\\Http\\ValidationException`` or return ``false`` to terminate further execution."
msgstr ""

#: ../../guides/hooks-list.rst:349
#: ../../guides/hooks-list.rst:477
#: ../../guides/hooks-list.rst:493
#: ../../guides/hooks-list.rst:507
#: ../../guides/hooks-list.rst:527
#: ../../guides/hooks-list.rst:582
#: ../../guides/hooks-list.rst:590
#: ../../guides/hooks-list.rst:752
#: ../../guides/hooks-list.rst:760
#: ../../guides/hooks-list.rst:781
msgid "``$params`` array includes:"
msgstr ""

#: ../../guides/hooks-list.rst:351
msgid "``request`` - instance of ``\\Elgg\\Request``"
msgstr ""

#: ../../guides/hooks-list.rst:354
msgid "**action_gatekeeper:permissions:check, all**"
msgstr ""

#: ../../guides/hooks-list.rst:354
msgid "Triggered after a CSRF token is validated. Return false to prevent validation."
msgstr ""

#: ../../guides/hooks-list.rst:358
msgid "**action_gatekeeper:upload_exceeded_msg, all**"
msgstr ""

#: ../../guides/hooks-list.rst:357
msgid "Triggered when a POST exceeds the max size allowed by the server. Return an error message to display."
msgstr ""

#: ../../guides/hooks-list.rst:362
msgid "**forward, <reason>**"
msgstr ""

#: ../../guides/hooks-list.rst:361
msgid "Filter the URL to forward a user to when ``forward($url, $reason)`` is called. In certain cases, the ``params`` array will contain an instance of ``\\Elgg\\Exceptions\\HttpException`` that triggered the error."
msgstr ""

#: ../../guides/hooks-list.rst:368
msgid "**response, action:<action>**"
msgstr ""

#: ../../guides/hooks-list.rst:365
msgid "Filter an instance of ``\\Elgg\\Http\\ResponseBuilder`` before it is sent to the client. This hook can be used to modify response content, status code, forward URL, or set additional response headers. Note that the ``<action>`` value is parsed from the request URL, therefore you may not be able to filter the responses of `action()` calls if they are nested within the another action script file."
msgstr ""

#: ../../guides/hooks-list.rst:387
msgid "**ajax_response, \\***"
msgstr ""

#: ../../guides/hooks-list.rst:376
msgid "When the ``elgg/Ajax`` AMD module is used, this hook gives access to the response object (``\\Elgg\\Services\\AjaxResponse``) so it can be altered/extended. The hook type depends on the method call:"
msgstr ""

#: ../../guides/hooks-list.rst:381
msgid "elgg/Ajax method"
msgstr ""

#: ../../guides/hooks-list.rst:381
msgid "plugin hook type"
msgstr ""

#: ../../guides/hooks-list.rst:383
msgid "action()"
msgstr ""

#: ../../guides/hooks-list.rst:383
msgid "action:<action_name>"
msgstr ""

#: ../../guides/hooks-list.rst:384
msgid "path()"
msgstr ""

#: ../../guides/hooks-list.rst:384
msgid "path:<url_path>"
msgstr ""

#: ../../guides/hooks-list.rst:385
msgid "view()"
msgstr ""

#: ../../guides/hooks-list.rst:385
msgid "view:<view_name>"
msgstr ""

#: ../../guides/hooks-list.rst:386
msgid "form()"
msgstr ""

#: ../../guides/hooks-list.rst:386
msgid "form:<action_name>"
msgstr ""

#: ../../guides/hooks-list.rst:392
msgid "Permission hooks"
msgstr ""

#: ../../guides/hooks-list.rst:408
msgid "**container_logic_check, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:395
msgid "Triggered by ``ElggEntity:canWriteToContainer()`` before triggering ``permissions_check`` and ``container_permissions_check`` hooks. Unlike permissions hooks, logic check can be used to prevent certain entity types from being contained by other entity types, e.g. discussion replies should only be contained by discussions. This hook can also be used to apply status logic, e.g. do disallow new replies for closed discussions."
msgstr ""

#: ../../guides/hooks-list.rst:400
msgid "The handler should return ``false`` to prevent an entity from containing another entity. The default value passed to the hook is ``null``, so the handler can check if another hook has modified the value by checking if return value is set. Should this hook return ``false``, ``container_permissions_check`` and ``permissions_check`` hooks will not be triggered."
msgstr ""

#: ../../guides/hooks-list.rst:406
#: ../../guides/hooks-list.rst:420
msgid "``container`` - An entity that will be used as a container"
msgstr ""

#: ../../guides/hooks-list.rst:407
#: ../../guides/hooks-list.rst:421
msgid "``user`` - User who will own the entity to be written to container"
msgstr ""

#: ../../guides/hooks-list.rst:408
#: ../../guides/hooks-list.rst:422
msgid "``subtype`` - Subtype of the entity to be written to container (entity type is assumed from hook type)"
msgstr ""

#: ../../guides/hooks-list.rst:422
msgid "**container_permissions_check, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:411
msgid "Return boolean for if the user ``$params['user']`` can use the entity ``$params['container']`` as a container for an entity of ``<entity_type>`` and subtype ``$params['subtype']``."
msgstr ""

#: ../../guides/hooks-list.rst:414
msgid "In the rare case where an entity is created with neither the ``container_guid`` nor the ``owner_guid`` matching the logged in user, this hook is called *twice*, and in the first call ``$params['container']`` will be the *owner*, not the entity's real container."
msgstr ""

#: ../../guides/hooks-list.rst:425
msgid "**permissions_check, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:425
msgid "Return boolean for if the user ``$params['user']`` can edit the entity ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:428
msgid "**permissions_check:delete, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:428
msgid "Return boolean for if the user ``$params['user']`` can delete the entity ``$params['entity']``. Defaults to ``$entity->canEdit()``."
msgstr ""

#: ../../guides/hooks-list.rst:432
msgid "**permissions_check:delete, river**"
msgstr ""

#: ../../guides/hooks-list.rst:431
msgid "Return boolean for if the user ``$params['user']`` can delete the river item ``$params['item']``. Defaults to ``true`` for admins and ``false`` for other users."
msgstr ""

#: ../../guides/hooks-list.rst:440
msgid "**permissions_check:download, file**"
msgstr ""

#: ../../guides/hooks-list.rst:435
msgid "Return boolean for if the user ``$params['user']`` can download the file in ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:439
msgid "``entity`` - Instance of ``ElggFile``"
msgstr ""

#: ../../guides/hooks-list.rst:440
msgid "``user`` - User who will download the file"
msgstr ""

#: ../../guides/hooks-list.rst:444
msgid "**permissions_check, widget_layout**"
msgstr ""

#: ../../guides/hooks-list.rst:443
msgid "Return boolean for if ``$params['user']`` can edit the widgets in the context passed as ``$params['context']`` and with a page owner of ``$params['page_owner']``."
msgstr ""

#: ../../guides/hooks-list.rst:447
msgid "**permissions_check:comment, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:447
msgid "Return boolean for if the user ``$params['user']`` can comment on the entity ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:453
msgid "**permissions_check:annotate:<annotation_name>, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:450
msgid "Return boolean for if the user ``$params['user']`` can create an annotation ``<annotation_name>`` on the entity ``$params['entity']``. If logged in, the default is true."
msgstr ""

#: ../../guides/hooks-list.rst:453
msgid "This is called before the more general ``permissions_check:annotate`` hook, and its return value is that hook's initial value."
msgstr ""

#: ../../guides/hooks-list.rst:457
msgid "**permissions_check:annotate, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:456
msgid "Return boolean for if the user ``$params['user']`` can create an annotation ``$params['annotation_name']`` on the entity ``$params['entity']``. if logged in, the default is true."
msgstr ""

#: ../../guides/hooks-list.rst:461
msgid "**permissions_check:annotation**"
msgstr ""

#: ../../guides/hooks-list.rst:460
msgid "Return boolean for if the user in ``$params['user']`` can edit the annotation ``$params['annotation']`` on the entity ``$params['entity']``. The user can be null."
msgstr ""

#: ../../guides/hooks-list.rst:465
msgid "**fail, auth**"
msgstr ""

#: ../../guides/hooks-list.rst:464
msgid "Return the failure message if authentication failed. An array of previous PAM failure methods is passed as ``$params``."
msgstr ""

#: ../../guides/hooks-list.rst:468
msgid "**api_key, use**"
msgstr ""

#: ../../guides/hooks-list.rst:468
msgid "Triggered by ``elgg_ws_pam_auth_api_key()``. Returning false prevents the key from being authenticated."
msgstr ""

#: ../../guides/hooks-list.rst:481
msgid "**gatekeeper, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:471
msgid "Filters the result of ``elgg_entity_gatekeeper()`` to prevent or allow access to an entity that user would otherwise have or not have access to. A handler can return ``false`` or an instance of ``\\Elgg\\Exceptions\\HttpException`` to prevent access to an entity. A handler can return ``true`` to override the result of the gatekeeper. **Important** that the entity received by this hook is fetched with ignored access and including disabled entities, so you have to be careful to not bypass the access system."
msgstr ""

#: ../../guides/hooks-list.rst:479
msgid "``entity`` - Entity that is being accessed"
msgstr ""

#: ../../guides/hooks-list.rst:480
msgid "``user`` - User accessing the entity (``null`` implies logged in user)"
msgstr ""

#: ../../guides/hooks-list.rst:484
#: ../../guides/notifications.rst:2
msgid "Notifications"
msgstr ""

#: ../../guides/hooks-list.rst:486
msgid "These hooks are listed chronologically in the lifetime of the notification event. Note that not all hooks apply to instant notifications."
msgstr ""

#: ../../guides/hooks-list.rst:496
msgid "**enqueue, notification**"
msgstr ""

#: ../../guides/hooks-list.rst:490
msgid "Can be used to prevent a notification event from sending **subscription** notifications. Hook handler must return ``false`` to prevent a subscription notification event from being enqueued."
msgstr ""

#: ../../guides/hooks-list.rst:495
msgid "``object`` - object of the notification event"
msgstr ""

#: ../../guides/hooks-list.rst:496
msgid "``action`` - action that triggered the notification event. E.g. corresponds to ``publish`` when ``elgg_trigger_event('publish', 'object', $object)`` is called"
msgstr ""

#: ../../guides/hooks-list.rst:513
msgid "**get, subscriptions**"
msgstr ""

#: ../../guides/hooks-list.rst:499
msgid "Filters subscribers of the notification event. Applies to **subscriptions** and **instant** notifications. In case of a subscription event, by default, the subscribers list consists of the users subscribed to the container entity of the event object. In case of an instant notification event, the subscribers list consists of the users passed as recipients to ``notify_user()``"
msgstr ""

#: ../../guides/hooks-list.rst:504
msgid "**IMPORTANT** Always validate the notification event, object and/or action types before adding any new recipients to ensure that you do not accidentally dispatch notifications to unintended recipients. Consider a situation, where a mentions plugin sends out an instant notification to a mentioned user - any hook acting on a subject or an object without validating an event or action type (e.g. including an owner of the original wire thread) might end up sending notifications to wrong users."
msgstr ""

#: ../../guides/hooks-list.rst:509
#: ../../guides/hooks-list.rst:529
#: ../../guides/hooks-list.rst:540
#: ../../guides/hooks-list.rst:557
#: ../../guides/hooks-list.rst:592
msgid "``event`` - ``\\Elgg\\Notifications\\NotificationEvent`` instance that describes the notification event"
msgstr ""

#: ../../guides/hooks-list.rst:510
#: ../../guides/hooks-list.rst:547
#: ../../guides/hooks-list.rst:564
msgid "``origin`` - ``subscriptions_service`` or ``instant_notifications``"
msgstr ""

#: ../../guides/hooks-list.rst:511
msgid "``methods_override`` - delivery method preference for instant notifications"
msgstr ""

#: ../../guides/hooks-list.rst:513
msgid "Handlers must return an array in the form:"
msgstr ""

#: ../../guides/hooks-list.rst:530
msgid "**send:before, notifications**"
msgstr ""

#: ../../guides/hooks-list.rst:524
msgid "Triggered before the notification event queue is processed. Can be used to terminate the notification event. Applies to **subscriptions** and **instant** notifications."
msgstr ""

#: ../../guides/hooks-list.rst:530
#: ../../guides/hooks-list.rst:593
msgid "``subscriptions`` - a list of subscriptions. See ``'get', 'subscriptions'`` hook for details"
msgstr ""

#: ../../guides/hooks-list.rst:547
msgid "**prepare, notification**"
msgstr ""

#: ../../guides/hooks-list.rst:533
msgid "A high level hook that can be used to alter an instance of ``\\Elgg\\Notifications\\Notification`` before it is sent to the user. Applies to **subscriptions** and **instant** notifications. This hook is triggered before a more granular ``'prepare', 'notification:<action>:<entity_type>:<entity_subtype>'`` and after ``'send:before', 'notifications``. Hook handler should return an altered notification object."
msgstr ""

#: ../../guides/hooks-list.rst:538
msgid "``$params`` may vary based on the notification type and may include:"
msgstr ""

#: ../../guides/hooks-list.rst:541
#: ../../guides/hooks-list.rst:558
msgid "``object`` - object of the notification ``event``. Can be ``null`` for instant notifications"
msgstr ""

#: ../../guides/hooks-list.rst:542
#: ../../guides/hooks-list.rst:559
msgid "``action`` - action that triggered the notification ``event``. May default to ``notify_user`` for instant notifications"
msgstr ""

#: ../../guides/hooks-list.rst:543
#: ../../guides/hooks-list.rst:560
msgid "``method`` - delivery method (e.g. ``email``, ``site``)"
msgstr ""

#: ../../guides/hooks-list.rst:544
#: ../../guides/hooks-list.rst:561
msgid "``sender`` - sender"
msgstr ""

#: ../../guides/hooks-list.rst:545
#: ../../guides/hooks-list.rst:562
msgid "``recipient`` - recipient"
msgstr ""

#: ../../guides/hooks-list.rst:546
#: ../../guides/hooks-list.rst:563
msgid "``language`` - language of the notification (recipient's language)"
msgstr ""

#: ../../guides/hooks-list.rst:564
msgid "**prepare, notification:<action>:<entity_type>:<entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:550
msgid "A granular hook that can be used to filter a notification ``\\Elgg\\Notifications\\Notification`` before it is sent to the user. Applies to **subscriptions** and **instant** notifications. In case of instant notifications that have not received an object, the hook will be called as ``'prepare', 'notification:<action>'``. In case of instant notifications that have not received an action name, it will default to ``notify_user``."
msgstr ""

#: ../../guides/hooks-list.rst:555
msgid "``$params`` include:"
msgstr ""

#: ../../guides/hooks-list.rst:575
msgid "**format, notification:<method>**"
msgstr ""

#: ../../guides/hooks-list.rst:567
msgid "This hook can be used to format a notification before it is passed to the ``'send', 'notification:<method>'`` hook. Applies to **subscriptions** and **instant** notifications. The hook handler should return an instance of ``\\Elgg\\Notifications\\Notification``. The hook does not receive any ``$params``. Some of the use cases include:"
msgstr ""

#: ../../guides/hooks-list.rst:573
msgid "Strip tags from notification title and body for plaintext email notifications"
msgstr ""

#: ../../guides/hooks-list.rst:574
msgid "Inline HTML styles for HTML email notifications"
msgstr ""

#: ../../guides/hooks-list.rst:575
msgid "Wrap notification in a template, add signature etc."
msgstr ""

#: ../../guides/hooks-list.rst:584
msgid "**send, notification:<method>**"
msgstr ""

#: ../../guides/hooks-list.rst:578
msgid "Delivers a notification. Applies to **subscriptions** and **instant** notifications. The handler must return ``true`` or ``false`` indicating the success of the delivery."
msgstr ""

#: ../../guides/hooks-list.rst:584
msgid "``notification`` - a notification object ``\\Elgg\\Notifications\\Notification``"
msgstr ""

#: ../../guides/hooks-list.rst:595
msgid "**send:after, notifications**"
msgstr ""

#: ../../guides/hooks-list.rst:587
msgid "Triggered after all notifications in the queue for the notifications event have been processed. Applies to **subscriptions** and **instant** notifications."
msgstr ""

#: ../../guides/hooks-list.rst:594
msgid "``deliveries`` - a matrix of delivery statuses by user for each delivery method"
msgstr ""

#: ../../guides/hooks-list.rst:598
msgid "Emails"
msgstr ""

#: ../../guides/hooks-list.rst:606
msgid "**prepare, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:601
msgid "Triggered by ``elgg_send_email()``. Applies to all outgoing system and notification emails. This hook allows you to alter an instance of ``\\Elgg\\Email`` before it is passed to the email transport. This hook can be used to alter the sender, recipient, subject, body, and/or headers of the email."
msgstr ""

#: ../../guides/hooks-list.rst:606
msgid "``$params`` are empty. The ``$return`` value is an instance of ``\\Elgg\\Email``."
msgstr ""

#: ../../guides/hooks-list.rst:616
msgid "**validate, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:609
msgid "Triggered by ``elgg_send_email()``. Applies to all outgoing system and notification emails. This hook allows you to suppress or whitelist outgoing emails, e.g. when the site is in a development mode. The handler must return ``false`` to supress the email delivery."
msgstr ""

#: ../../guides/hooks-list.rst:614
#: ../../guides/hooks-list.rst:624
#: ../../guides/hooks-list.rst:633
msgid "``$params`` contains:"
msgstr ""

#: ../../guides/hooks-list.rst:616
#: ../../guides/hooks-list.rst:626
#: ../../guides/hooks-list.rst:635
msgid "``email`` - An instance of ``\\Elgg\\Email``"
msgstr ""

#: ../../guides/hooks-list.rst:626
msgid "**transport, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:619
msgid "Triggered by ``elgg_send_email()``. Applies to all outgoing system and notification emails. This hook allows you to implement a custom email transport, e.g. delivering emails via a third-party proxy service such as SendGrid or Mailgun. The handler must return ``true`` to indicate that the email was transported."
msgstr ""

#: ../../guides/hooks-list.rst:635
msgid "**zend:message, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:629
msgid "Triggered by the default email transport handler (Elgg uses ``laminas/laminas-mail``). Applies to all outgoing system and notification emails that were not transported using the **transport, system:email** hook. This hook allows you to alter an instance of ``\\Laminas\\Mail\\Message`` before it is passed to the Laminas email transport."
msgstr ""

#: ../../guides/hooks-list.rst:638
#: ../../guides/routing.rst:2
msgid "Routing"
msgstr ""

#: ../../guides/hooks-list.rst:643
msgid "**route:config, <route_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:641
msgid "Allows altering the route configuration before it is registered. This hook can be used to alter the path, default values, requirements, as well as to set/remove middleware. Please note that the handler for this hook should be registered outside of the ``init`` event handler, as core routes are registered during ``plugins_boot`` event."
msgstr ""

#: ../../guides/hooks-list.rst:647
msgid "**route:rewrite, <identifier>**"
msgstr ""

#: ../../guides/hooks-list.rst:646
msgid "Allows altering the site-relative URL path for an incoming request. See :doc:`routing` for details. Please note that the handler for this hook should be registered outside of the ``init`` event handler, as route rewrites take place after ``plugins_boot`` event has completed."
msgstr ""

#: ../../guides/hooks-list.rst:654
msgid "**response, path:<path>**"
msgstr ""

#: ../../guides/hooks-list.rst:650
msgid "Filter an instance of ``\\Elgg\\Http\\ResponseBuilder`` before it is sent to the client. This hook type will only be used if the path did not start with \"action/\" or \"ajax/\". This hook can be used to modify response content, status code, forward URL, or set additional response headers. Note that the ``<path>`` value is parsed from the request URL, therefore plugins using the ``route`` hook should use the original ``<path>`` to filter the response, or switch to using the ``route:rewrite`` hook."
msgstr ""

#: ../../guides/hooks-list.rst:659
msgid "**ajax_response, path:<path>**"
msgstr ""

#: ../../guides/hooks-list.rst:657
msgid "Filters ajax responses before they're sent back to the ``elgg/Ajax`` module. This hook type will only be used if the path did not start with \"action/\" or \"ajax/\"."
msgstr ""

#: ../../guides/hooks-list.rst:664
#: ../../guides/plugins/plugin-skeleton.rst:141
#: ../../guides/views.rst:2
msgid "Views"
msgstr ""

#: ../../guides/hooks-list.rst:667
msgid "**view_vars, <view_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:667
msgid "Filters the ``$vars`` array passed to the view"
msgstr ""

#: ../../guides/hooks-list.rst:670
msgid "**view, <view_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:670
msgid "Filters the returned content of the view"
msgstr ""

#: ../../guides/hooks-list.rst:678
msgid "**layout, page**"
msgstr ""

#: ../../guides/hooks-list.rst:673
msgid "In ``elgg_view_layout()``, filters the layout name. ``$params`` array includes:"
msgstr ""

#: ../../guides/hooks-list.rst:676
msgid "``identifier`` - ID of the page being rendered"
msgstr ""

#: ../../guides/hooks-list.rst:677
msgid "``segments`` - URL segments of the page being rendered"
msgstr ""

#: ../../guides/hooks-list.rst:678
msgid "other ``$vars`` received by ``elgg_view_layout()``"
msgstr ""

#: ../../guides/hooks-list.rst:681
msgid "**shell, page**"
msgstr ""

#: ../../guides/hooks-list.rst:681
msgid "In ``elgg_view_page()``, filters the page shell name"
msgstr ""

#: ../../guides/hooks-list.rst:689
msgid "**head, page**"
msgstr ""

#: ../../guides/hooks-list.rst:684
msgid "In ``elgg_view_page()``, filters ``$vars['head']`` Return value contains an array with ``title``, ``metas`` and ``links`` keys, where ``metas`` is an array of elements to be formatted as ``<meta>`` head tags, and ``links`` is an array of elements to be formatted as ``<link>`` head tags. Each meta and link element contains a set of key/value pairs that are formatted into html tag attributes, e.g."
msgstr ""

#: ../../guides/hooks-list.rst:719
msgid "**ajax_response, view:<view>**"
msgstr ""

#: ../../guides/hooks-list.rst:719
msgid "Filters ``ajax/view/`` responses before they're sent back to the ``elgg/Ajax`` module."
msgstr ""

#: ../../guides/hooks-list.rst:722
msgid "**ajax_response, form:<action>**"
msgstr ""

#: ../../guides/hooks-list.rst:722
msgid "Filters ``ajax/form/`` responses before they're sent back to the ``elgg/Ajax`` module."
msgstr ""

#: ../../guides/hooks-list.rst:727
msgid "**response, view:<view_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:725
msgid "Filter an instance of ``\\Elgg\\Http\\ResponseBuilder`` before it is sent to the client. Applies to request to ``/ajax/view/<view_name>``. This hook can be used to modify response content, status code, forward URL, or set additional response headers."
msgstr ""

#: ../../guides/hooks-list.rst:732
msgid "**response, form:<form_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:730
msgid "Filter an instance of ``\\Elgg\\Http\\ResponseBuilder`` before it is sent to the client. Applies to request to ``/ajax/form/<form_name>``. This hook can be used to modify response content, status code, forward URL, or set additional response headers."
msgstr ""

#: ../../guides/hooks-list.rst:738
msgid "**table_columns:call, <name>**"
msgstr ""

#: ../../guides/hooks-list.rst:735
msgid "When the method ``elgg()->table_columns->$name()`` is called, this hook is called to allow plugins to override or provide an implementation. Handlers receive the method arguments via ``$params['arguments']`` and should return an instance of ``Elgg\\Views\\TableColumn`` if they wish to specify the column directly."
msgstr ""

#: ../../guides/hooks-list.rst:743
msgid "**vars:compiler, css**"
msgstr ""

#: ../../guides/hooks-list.rst:741
msgid "Allows plugins to alter CSS variables passed to CssCrush during compilation. See `CSS variables <_guides/theming#css-vars>`."
msgstr ""

#: ../../guides/hooks-list.rst:746
msgid "Files"
msgstr ""

#: ../../guides/hooks-list.rst:754
msgid "**download:url, file**"
msgstr ""

#: ../../guides/hooks-list.rst:750
msgid "Allows plugins to filter the download URL of the file."
msgstr ""

#: ../../guides/hooks-list.rst:750
msgid "By default, the download URL is generated by the file service."
msgstr ""

#: ../../guides/hooks-list.rst:754
#: ../../guides/hooks-list.rst:762
msgid "``entity`` - instance of ``ElggFile``"
msgstr ""

#: ../../guides/hooks-list.rst:762
msgid "**inline:url, file**"
msgstr ""

#: ../../guides/hooks-list.rst:758
msgid "Allows plugins to filter the inline URL of the image file."
msgstr ""

#: ../../guides/hooks-list.rst:758
msgid "By default, the inline URL is generated by the file service."
msgstr ""

#: ../../guides/hooks-list.rst:766
msgid "**mime_type, file**"
msgstr ""

#: ../../guides/hooks-list.rst:765
msgid "Return the mimetype for the filename ``$params['filename']`` with original filename ``$params['original_filename']`` and with the default detected mimetype of ``$params['default']``."
msgstr ""

#: ../../guides/hooks-list.rst:772
msgid "**simple_type, file**"
msgstr ""

#: ../../guides/hooks-list.rst:769
msgid "The hook provides ``$params['mime_type']`` (e.g. ``application/pdf`` or ``image/jpeg``) and determines an overall category like ``document`` or ``image``. The bundled file plugin and other-third party plugins usually store ``simpletype`` metadata on file entities and make use of it when serving icons and constructing ``ege*`` filters and menus."
msgstr ""

#: ../../guides/hooks-list.rst:785
msgid "**upload, file**"
msgstr ""

#: ../../guides/hooks-list.rst:775
msgid "Allows plugins to implement custom logic for moving an uploaded file into an instance of ``ElggFile``. The handler must return ``true`` to indicate that the uploaded file was moved. The handler must return ``false`` to indicate that the uploaded file could not be moved. Other returns will indicate that ``ElggFile::acceptUploadedFile`` should proceed with the default upload logic."
msgstr ""

#: ../../guides/hooks-list.rst:783
msgid "``file`` - instance of ``ElggFile`` to write to"
msgstr ""

#: ../../guides/hooks-list.rst:784
msgid "``upload`` - instance of Symfony's ``UploadedFile``"
msgstr ""

#: ../../guides/hooks-list.rst:790
#: ../../guides/search.rst:2
msgid "Search"
msgstr ""

#: ../../guides/hooks-list.rst:794
msgid "**search:results, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:793
msgid "Triggered by ``elgg_search()``. Receives normalized options suitable for ``elgg_get_entities()`` call and must return an array of entities matching search options. This hook is designed for use by plugins integrating third-party indexing services, such as Solr and Elasticsearch."
msgstr ""

#: ../../guides/hooks-list.rst:798
msgid "**search:params, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:797
msgid "Triggered by ``elgg_search()``. Filters search parameters (query, sorting, search fields etc) before search clauses are prepared for a given search type. Elgg core only provides support for ``entities`` search type."
msgstr ""

#: ../../guides/hooks-list.rst:803
msgid "**search:fields, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:801
msgid "Triggered by ``elgg_search()``. Filters search fields before search clauses are prepared. ``$return`` value contains an array of names for each entity property type, which should be matched against the search query. ``$params`` array contains an array of search params passed to and filtered by ``elgg_search()``."
msgstr ""

#: ../../guides/hooks-list.rst:815
msgid "**search:fields, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:815
#: ../../guides/hooks-list.rst:818
msgid "See **search:fields, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:818
msgid "**search:fields, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:821
msgid "**search:options, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:821
msgid "Triggered by ``elgg_search()``. Prepares search clauses (options) to be passed to ``elgg_get_entities()``."
msgstr ""

#: ../../guides/hooks-list.rst:824
msgid "**search:options, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:824
#: ../../guides/hooks-list.rst:827
msgid "See **search:options, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:827
msgid "**search:options, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:832
msgid "**search:config, search_types**"
msgstr ""

#: ../../guides/hooks-list.rst:830
msgid "Implemented in the **search** plugin. Filters an array of custom search types. This allows plugins to add custom search types (e.g. tag or location search). Adding a custom search type will extend the search plugin user interface with appropriate links and lists."
msgstr ""

#: ../../guides/hooks-list.rst:837
msgid "**search:config, type_subtype_pairs**"
msgstr ""

#: ../../guides/hooks-list.rst:835
msgid "Implemented in the **search** plugin. Filters entity type/subtype pairs before entity search is performed. Allows plugins to remove certain entity types/subtypes from search results, group multiple subtypes together, or to reorder search sections."
msgstr ""

#: ../../guides/hooks-list.rst:842
msgid "**search:format, entity**"
msgstr ""

#: ../../guides/hooks-list.rst:840
msgid "Implemented in the **search** plugin. Allows plugins to populate entity's volatile data before it's passed to search view. This is used for highlighting search hit, extracting relevant substrings in long text fields etc."
msgstr ""

#: ../../guides/hooks-list.rst:847
msgid "Other"
msgstr ""

#: ../../guides/hooks-list.rst:851
msgid "**config, comments_per_page**"
msgstr ""

#: ../../guides/hooks-list.rst:850
msgid "Filters the number of comments displayed per page. Default is 25. ``$params['entity']`` will hold the containing entity or null if not provided. Use ``elgg_comments_per_page()`` to get the value."
msgstr ""

#: ../../guides/hooks-list.rst:855
msgid "**config, comments_latest_first**"
msgstr ""

#: ../../guides/hooks-list.rst:854
msgid "Filters the order of comments. Default is ``true`` for latest first. ``$params['entity']`` will hold the containing entity or null if not provided."
msgstr ""

#: ../../guides/hooks-list.rst:862
msgid "**default, access**"
msgstr ""

#: ../../guides/hooks-list.rst:858
msgid "In get_default_access(), this hook filters the return value, so it can be used to alter the default value in the input/access view. For core plugins, the value \"input_params\" has the keys \"entity\" (ElggEntity|false), \"entity_type\" (string), \"entity_subtype\" (string), \"container_guid\" (int) are provided. An empty entity value generally means the form is to create a new object."
msgstr ""

#: ../../guides/hooks-list.rst:866
msgid "**classes, icon**"
msgstr ""

#: ../../guides/hooks-list.rst:865
msgid "Can be used to filter CSS classes applied to icon glyphs. By default, Elgg uses FontAwesome. Plugins can use this hook to switch to a different font family and remap icon classes."
msgstr ""

#: ../../guides/hooks-list.rst:870
msgid "**entity:icon:sizes, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:869
msgid "Triggered by ``elgg_get_icon_sizes()`` and sets entity type/subtype specific icon sizes. ``entity_subtype`` will be passed with the ``$params`` array to the callback."
msgstr ""

#: ../../guides/hooks-list.rst:887
msgid "**entity:<icon_type>:sizes, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:873
msgid "Allows filtering sizes for custom icon types, see ``entity:icon:sizes, <entity_type>``."
msgstr ""

#: ../../guides/hooks-list.rst:875
msgid "The hook must return an associative array where keys are the names of the icon sizes (e.g. \"large\"), and the values are arrays with the following keys:"
msgstr ""

#: ../../guides/hooks-list.rst:878
msgid "``w`` - Width of the image in pixels"
msgstr ""

#: ../../guides/hooks-list.rst:879
msgid "``h`` - Height of the image in pixels"
msgstr ""

#: ../../guides/hooks-list.rst:880
msgid "``square`` - Should the aspect ratio be a square (true/false)"
msgstr ""

#: ../../guides/hooks-list.rst:881
msgid "``upscale`` - Should the image be upscaled in case it is smaller than the given width and height (true/false)"
msgstr ""

#: ../../guides/hooks-list.rst:882
msgid "``crop`` - Is cropping allowed on this image size (true/false, default: true)"
msgstr ""

#: ../../guides/hooks-list.rst:884
msgid "If the configuration array for an image size is empty, the image will be saved as an exact copy of the source without resizing or cropping."
msgstr ""

#: ../../guides/hooks-list.rst:887
#: ../../guides/i18n.rst:51
#: ../../guides/notifications.rst:24
#: ../../guides/notifications.rst:222
#: ../../guides/notifications.rst:246
#: ../../guides/notifications.rst:294
msgid "Example:"
msgstr ""

#: ../../guides/hooks-list.rst:919
msgid "**entity:icon:url, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:907
msgid "Triggered when entity icon URL is requested, see :ref:`entity icons <guides/database#entity-icons>`. Callback should return URL for the icon of size ``$params['size']`` for the entity ``$params['entity']``. Following parameters are available through the ``$params`` array:"
msgstr ""

#: ../../guides/hooks-list.rst:911
msgid "entity"
msgstr ""

#: ../../guides/hooks-list.rst:912
msgid "Entity for which icon url is requested."
msgstr ""

#: ../../guides/hooks-list.rst:913
msgid "viewtype"
msgstr ""

#: ../../guides/hooks-list.rst:914
msgid "The type of :ref:`view <guides/views#listing-entities>` e.g. ``'default'`` or ``'json'``."
msgstr ""

#: ../../guides/hooks-list.rst:916
msgid "size"
msgstr ""

#: ../../guides/hooks-list.rst:916
msgid "Size requested, see :ref:`entity icons <guides/database#entity-icons>` for possible values."
msgstr ""

#: ../../guides/hooks-list.rst:918
msgid "Example on how one could default to a Gravatar icon for users that have not yet uploaded an avatar:"
msgstr ""

#: ../../guides/hooks-list.rst:959
msgid "**entity:<icon_type>:url, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:959
msgid "Allows filtering URLs for custom icon types, see ``entity:icon:url, <entity_type>``"
msgstr ""

#: ../../guides/hooks-list.rst:964
msgid "**entity:icon:file, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:962
msgid "Triggered by ``ElggEntity::getIcon()`` and allows plugins to provide an alternative ``ElggIcon`` object that points to a custom location of the icon on filestore. The handler must return an instance of ``ElggIcon`` or an exception will be thrown."
msgstr ""

#: ../../guides/hooks-list.rst:967
msgid "**entity:<icon_type>:file, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:967
msgid "Allows filtering icon file object for custom icon types, see ``entity:icon:file, <entity_type>``"
msgstr ""

#: ../../guides/hooks-list.rst:979
msgid "**entity:<icon_type>:prepare, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:970
msgid "Triggered by ``ElggEntity::saveIcon*()`` methods and can be used to prepare an image from uploaded/linked file. This hook can be used to e.g. rotate the image before it is resized/cropped, or it can be used to extract an image frame if the uploaded file is a video. The handler must return an instance of ``ElggFile`` with a `simpletype` that resolves to `image`. The ``$return`` value passed to the hook is an instance of ``ElggFile`` that points to a temporary copy of the uploaded/linked file."
msgstr ""

#: ../../guides/hooks-list.rst:976
#: ../../guides/hooks-list.rst:1093
#: ../../guides/hooks-list.rst:1135
msgid "The ``$params`` array contains:"
msgstr ""

#: ../../guides/hooks-list.rst:978
#: ../../guides/hooks-list.rst:986
#: ../../guides/hooks-list.rst:996
#: ../../guides/hooks-list.rst:1004
msgid "``entity`` - entity that owns the icons"
msgstr ""

#: ../../guides/hooks-list.rst:979
msgid "``file`` - original input file before it has been modified by other hooks"
msgstr ""

#: ../../guides/hooks-list.rst:988
msgid "**entity:<icon_type>:save, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:982
msgid "Triggered by ``ElggEntity::saveIcon*()`` methods and can be used to apply custom image manipulation logic to resizing/cropping icons. The handler must return ``true`` to prevent the core APIs from resizing/cropping icons. The ``$params`` array contains:"
msgstr ""

#: ../../guides/hooks-list.rst:987
msgid "``file`` - ``ElggFile`` object that points to the image file to be used as source for icons"
msgstr ""

#: ../../guides/hooks-list.rst:988
#: ../../guides/hooks-list.rst:997
msgid "``x1``, ``y1``, ``x2``, ``y2`` - cropping coordinates"
msgstr ""

#: ../../guides/hooks-list.rst:997
msgid "**entity:<icon_type>:saved, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:991
msgid "Triggered by ``ElggEntity::saveIcon*()`` methods once icons have been created. This hook can be used by plugins to create river items, update cropping coordinates for custom icon types etc. The handler can access the created icons using ``ElggEntity::getIcon()``. The ``$params`` array contains:"
msgstr ""

#: ../../guides/hooks-list.rst:1004
msgid "**entity:<icon_type>:delete, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:1000
msgid "Triggered by ``ElggEntity::deleteIcon()`` method and can be used for clean up operations. This hook is triggered before the icons are deleted. The handler can return ``false`` to prevent icons from being deleted. The ``$params`` array contains:"
msgstr ""

#: ../../guides/hooks-list.rst:1009
msgid "**entity:url, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:1007
msgid "Return the URL for the entity ``$params['entity']``. Note: Generally it is better to override the ``getUrl()`` method of ElggEntity. This hook should be used when it's not possible to subclass (like if you want to extend a bundled plugin without overriding many views)."
msgstr ""

#: ../../guides/hooks-list.rst:1013
msgid "**fields, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:1012
msgid "Return an array of fields usable for ``elgg_view_field()``. The result should be returned as an array of fields. It is required to provide ``name`` and ``#type`` for each field."
msgstr ""

#: ../../guides/hooks-list.rst:1028
msgid "**to:object, <entity_type|metadata|annotation|relationship|river_item>**"
msgstr ""

#: ../../guides/hooks-list.rst:1027
msgid "Converts the entity ``$params['entity']`` to a StdClass object. This is used mostly for exporting entity properties for portable data formats like JSON and XML."
msgstr ""

#: ../../guides/hooks-list.rst:1031
msgid "**extender:url, <annotation|metadata>**"
msgstr ""

#: ../../guides/hooks-list.rst:1031
msgid "Return the URL for the annotation or metadatum ``$params['extender']``."
msgstr ""

#: ../../guides/hooks-list.rst:1034
msgid "**file:icon:url, override**"
msgstr ""

#: ../../guides/hooks-list.rst:1034
msgid "Override a file icon URL."
msgstr ""

#: ../../guides/hooks-list.rst:1037
msgid "**is_member, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1037
msgid "Return boolean for if the user ``$params['user']`` is a member of the group ``$params['group']``."
msgstr ""

#: ../../guides/hooks-list.rst:1045
msgid "**setting, plugin**"
msgstr ""

#: ../../guides/hooks-list.rst:1040
msgid "Filter plugin settings. ``$params`` contains:"
msgstr ""

#: ../../guides/hooks-list.rst:1042
msgid "``plugin`` - An ElggPlugin instance"
msgstr ""

#: ../../guides/hooks-list.rst:1043
msgid "``plugin_id`` - The plugin ID"
msgstr ""

#: ../../guides/hooks-list.rst:1044
msgid "``name`` - The name of the setting"
msgstr ""

#: ../../guides/hooks-list.rst:1045
msgid "``value`` - The value to set"
msgstr ""

#: ../../guides/hooks-list.rst:1056
msgid "**plugin_setting, <entity type>**"
msgstr ""

#: ../../guides/hooks-list.rst:1048
msgid "Can be used to change the value of the setting being saved"
msgstr ""

#: ../../guides/hooks-list.rst:1050
msgid "Params contains: - ``entity`` - The ``ElggEntity`` where the plugin setting is being saved - ``plugin_id`` - The ID of the plugin for which the setting is being saved - ``name`` - The name of the setting being saved - ``value`` - The original value of the setting being saved"
msgstr ""

#: ../../guides/hooks-list.rst:1056
msgid "Return value should be a scalar in order to be able to save it to the database. An error will be logged if this is not the case."
msgstr ""

#: ../../guides/hooks-list.rst:1059
msgid "**relationship:url, <relationship_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:1059
msgid "Filter the URL for the relationship object ``$params['relationship']``."
msgstr ""

#: ../../guides/hooks-list.rst:1063
msgid "**widget_settings, <widget_handler>**"
msgstr ""

#: ../../guides/hooks-list.rst:1062
msgid "Triggered when saving a widget settings ``$params['params']`` for widget ``$params['widget']``. If handling saving the settings, the handler should return true to prevent the default code from running."
msgstr ""

#: ../../guides/hooks-list.rst:1067
msgid "**handlers, widgets**"
msgstr ""

#: ../../guides/hooks-list.rst:1066
msgid "Triggered when a list of available widgets is needed. Plugins can conditionally add or remove widgets from this list or modify attributes of existing widgets like ``context`` or ``multiple``."
msgstr ""

#: ../../guides/hooks-list.rst:1071
msgid "**get_list, default_widgets**"
msgstr ""

#: ../../guides/hooks-list.rst:1070
msgid "Filters a list of default widgets to add for newly registered users. The list is an array of arrays in the format:"
msgstr ""

#: ../../guides/hooks-list.rst:1095
msgid "**public_pages, walled_garden**"
msgstr ""

#: ../../guides/hooks-list.rst:1088
msgid "Filters a list of URLs (paths) that can be seen by logged out users in a walled garden mode. Handlers must return an array of regex strings that will allow access if matched. Please note that system public routes are passed as the default value to the hook, and plugins must take care to not accidentally override these values."
msgstr ""

#: ../../guides/hooks-list.rst:1095
msgid "``url`` - URL of the page being tested for public accessibility"
msgstr ""

#: ../../guides/hooks-list.rst:1100
msgid "**volatile, metadata**"
msgstr ""

#: ../../guides/hooks-list.rst:1098
msgid "Triggered when exporting an entity through the export handler. This is rare. This allows handler to handle any volatile (non-persisted) metadata on the entity. It's preferred to use the ``to:object, <type>`` hook."
msgstr ""

#: ../../guides/hooks-list.rst:1104
msgid "**maintenance:allow, url**"
msgstr ""

#: ../../guides/hooks-list.rst:1104
msgid "Return boolean if the URL ``$params['current_url']`` and the path ``$params['current_path']``"
msgstr ""

#: ../../guides/hooks-list.rst:1104
msgid "is allowed during maintenance mode."
msgstr ""

#: ../../guides/hooks-list.rst:1107
msgid "**robots.txt, site**"
msgstr ""

#: ../../guides/hooks-list.rst:1107
msgid "Filter the robots.txt values for ``$params['site']``."
msgstr ""

#: ../../guides/hooks-list.rst:1110
msgid "**config, amd**"
msgstr ""

#: ../../guides/hooks-list.rst:1110
msgid "Filter the AMD config for the requirejs library."
msgstr ""

#: ../../guides/hooks-list.rst:1116
msgid "Embed"
msgstr ""

#: ../../guides/hooks-list.rst:1118
msgid "**embed_get_items, <active_section>**"
msgstr ""

#: ../../guides/hooks-list.rst:1120
msgid "**embed_get_sections, all**"
msgstr ""

#: ../../guides/hooks-list.rst:1122
msgid "**embed_get_upload_sections, all**"
msgstr ""

#: ../../guides/hooks-list.rst:1125
msgid "Groups"
msgstr ""

#: ../../guides/hooks-list.rst:1128
msgid "**profile_buttons, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1128
msgid "Filters buttons (``ElggMenuItem`` instances) to be registered in the title menu of the group profile page"
msgstr ""

#: ../../guides/hooks-list.rst:1137
msgid "**tool_options, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1131
msgid "Filters a collection of tools available within a specific group:"
msgstr ""

#: ../../guides/hooks-list.rst:1133
msgid "The ``$return`` is ``\\Elgg\\Collections\\Collection<\\Elgg\\Groups\\Tool>``, a collection of group tools."
msgstr ""

#: ../../guides/hooks-list.rst:1137
msgid "``entity`` - ``\\ElggGroup``"
msgstr ""

#: ../../guides/hooks-list.rst:1140
msgid "HTMLawed"
msgstr ""

#: ../../guides/hooks-list.rst:1143
msgid "**allowed_styles, htmlawed**"
msgstr ""

#: ../../guides/hooks-list.rst:1143
msgid "Filter the HTMLawed allowed style array."
msgstr ""

#: ../../guides/hooks-list.rst:1146
msgid "**config, htmlawed**"
msgstr ""

#: ../../guides/hooks-list.rst:1146
msgid "Filter the HTMLawed ``$config`` array."
msgstr ""

#: ../../guides/hooks-list.rst:1149
msgid "**spec, htmlawed**"
msgstr ""

#: ../../guides/hooks-list.rst:1149
msgid "Filter the HTMLawed ``$spec`` string (default empty)."
msgstr ""

#: ../../guides/hooks-list.rst:1152
msgid "Likes"
msgstr ""

#: ../../guides/hooks-list.rst:1158
msgid "**likes:is_likable, <type>:<subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:1155
msgid "This is called to set the default permissions for whether to display/allow likes on an entity of type ``<type>`` and subtype ``<subtype>``."
msgstr ""

#: ../../guides/hooks-list.rst:1158
msgid "The callback ``'Elgg\\Values::getTrue'`` is a useful handler for this hook."
msgstr ""

#: ../../guides/hooks-list.rst:1161
msgid "Members"
msgstr ""

#: ../../guides/hooks-list.rst:1164
msgid "**members:list, <page_segment>**"
msgstr ""

#: ../../guides/hooks-list.rst:1164
msgid "To handle the page ``/members/$page_segment``, register for this hook and return the HTML of the list."
msgstr ""

#: ../../guides/hooks-list.rst:1168
msgid "**members:config, tabs**"
msgstr ""

#: ../../guides/hooks-list.rst:1167
msgid "This hook is used to assemble an array of tabs to be passed to the navigation/tabs view for the members pages."
msgstr ""

#: ../../guides/hooks-list.rst:1171
msgid "Web Services"
msgstr ""

#: ../../guides/hooks-list.rst:1175
msgid "**rest, init**"
msgstr ""

#: ../../guides/hooks-list.rst:1174
msgid "Triggered by the web services rest handler. Plugins can set up their own authentication handlers, then return ``true`` to prevent the default handlers from being registered."
msgstr ""

#: ../../guides/hooks-list.rst:1177
msgid "**rest:output, <method_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:1178
msgid "Filter the result (and subsequently the output) of the API method"
msgstr ""

#: ../../guides/i18n.rst:2
msgid "Internationalization"
msgstr ""

#: ../../guides/i18n.rst:4
msgid "Make your UI translatable into many different languages."
msgstr ""

#: ../../guides/i18n.rst:6
msgid "If you’d like to contribute translations to Elgg, see :doc:`the contributors' guide </about/contributing>`."
msgstr ""

#: ../../guides/i18n.rst:8
msgid "The default language is ``en`` for English. Elgg uses a fallback system for languages:"
msgstr ""

#: ../../guides/i18n.rst:10
msgid "The language of the user"
msgstr ""

#: ../../guides/i18n.rst:11
msgid "The site language"
msgstr ""

#: ../../guides/i18n.rst:12
msgid "English"
msgstr ""

#: ../../guides/i18n.rst:17
msgid "Translations are stored in PHP files in the ``/languages`` directory of your plugin. Each file corresponds to a language. The format is ``/languages/{language-code}.php`` where ``{language-code}`` is the ISO 639-1 short code for the language. For example:"
msgstr ""

#: ../../guides/i18n.rst:28
msgid "To override an existing translation, include it in your plugin's language file, and make sure your plugin is ordered later on the Admin > Plugins page:"
msgstr ""

#: ../../guides/i18n.rst:41
msgid "Unless you are overriding core's or another plugin's language strings, it is good practice for the language keys to start with your plugin name. For example: ``yourplugin:success``, ``yourplugin:title``, etc. This helps avoid conflicts with other language keys."
msgstr ""

#: ../../guides/i18n.rst:45
msgid "Server-side API"
msgstr ""

#: ../../guides/i18n.rst:47
msgid "``elgg_echo($key, $args, $language)``"
msgstr ""

#: ../../guides/i18n.rst:49
msgid "Output the translation of the key in the current language."
msgstr ""

#: ../../guides/i18n.rst:57
msgid "It also supports variable replacement using ``vsprintf`` syntax:"
msgstr ""

#: ../../guides/i18n.rst:67
msgid "To force which language should be used for translation, set the third parameter:"
msgstr ""

#: ../../guides/i18n.rst:73
msgid "To first test whether ``elgg_echo()`` can find a translation:"
msgstr ""

#: ../../guides/i18n.rst:86
msgid "Some APIs allow creating translations for new keys. Translators should always include an English translation as a fallback. This makes ``elgg_language_key_exists($key)`` a reliable way to predict whether ``elgg_echo($key)`` will succeed."
msgstr ""

#: ../../guides/i18n.rst:90
msgid "Javascript API"
msgstr ""

#: ../../guides/i18n.rst:92
msgid "``elgg.echo(key, args)``"
msgstr ""

#: ../../guides/i18n.rst:94
msgid "This function is like ``elgg_echo`` in PHP."
msgstr ""

#: ../../guides/i18n.rst:96
msgid "Client-side translations are loaded asynchronously. Ensure translations are available by requiring the \"elgg\" AMD module:"
msgstr ""

#: ../../guides/i18n.rst:104
msgid "Translations are also available after the ``init, system`` JavaScript event."
msgstr ""

#: ../../guides/index.rst:2
msgid "Developer Guides"
msgstr ""

#: ../../guides/index.rst:4
msgid "Customize Elgg's behavior with plugins."
msgstr ""

#: ../../guides/javascript.rst:2
#: ../../guides/menus.rst:280
msgid "JavaScript"
msgstr ""

#: ../../guides/javascript.rst:9
msgid "AMD"
msgstr ""

#: ../../guides/javascript.rst:11
msgid "Developers should use the `AMD (Asynchronous Module Definition) <http://requirejs.org/docs/whyamd.html>`_ standard for writing JavaScript code in Elgg."
msgstr ""

#: ../../guides/javascript.rst:14
msgid "Here we'll describe making and executing AMD modules. The RequireJS documentation for `defining modules <http://requirejs.org/docs/api.html#define>`_ may also be of use."
msgstr ""

#: ../../guides/javascript.rst:18
msgid "Executing a module in the current page"
msgstr ""

#: ../../guides/javascript.rst:20
msgid "Telling Elgg to load an existing module in the current page is easy:"
msgstr ""

#: ../../guides/javascript.rst:27
msgid "On the client-side, this will asynchronously load the module, load any dependencies, and execute the module's definition function, if it has one."
msgstr ""

#: ../../guides/javascript.rst:31
msgid "Defining the Module"
msgstr ""

#: ../../guides/javascript.rst:33
msgid "Here we define a basic module that alters the page, by passing a \"definition function\" to ``define()``:"
msgstr ""

#: ../../guides/javascript.rst:43
msgid "The module's name is determined by the view name, which here is ``myplugin/say_hello.js``. We strip the ``.js`` extension, leaving ``myplugin/say_hello``."
msgstr ""

#: ../../guides/javascript.rst:48
msgid "The definition function **must** have one argument named ``require``."
msgstr ""

#: ../../guides/javascript.rst:51
msgid "Making modules dependent on other modules"
msgstr ""

#: ../../guides/javascript.rst:53
msgid "Below we refactor a bit so that the module depends on a new ``myplugin/hello`` module to provide the greeting:"
msgstr ""

#: ../../guides/javascript.rst:75
msgid "Passing settings to modules"
msgstr ""

#: ../../guides/javascript.rst:78
msgid "The ``elgg.data`` plugin hooks"
msgstr ""

#: ../../guides/javascript.rst:80
msgid "The ``elgg`` module provides an object ``elgg.data`` which is populated from two server side hooks:"
msgstr ""

#: ../../guides/javascript.rst:82
msgid "**elgg.data, site**: This filters an associative array of site-specific data passed to the client and cached."
msgstr ""

#: ../../guides/javascript.rst:83
msgid "**elgg.data, page**: This filters an associative array of uncached, page-specific data passed to the client."
msgstr ""

#: ../../guides/javascript.rst:85
msgid "Let's pass some data to a module:"
msgstr ""

#: ../../guides/javascript.rst:128
msgid "In ``elgg.data``, page data overrides site data. Also note ``json_encode()`` is used to copy data client-side, so the data must be JSON-encodable."
msgstr ""

#: ../../guides/javascript.rst:132
msgid "Making a config module"
msgstr ""

#: ../../guides/javascript.rst:134
msgid "You can use a PHP-based module to pass values from the server. To make the module ``myplugin/settings``, create the view file ``views/default/myplugin/settings.js.php`` (note the double extension ``.js.php``)."
msgstr ""

#: ../../guides/javascript.rst:150
msgid "You must also manually register the view as an external resource:"
msgstr ""

#: ../../guides/javascript.rst:160
msgid "The PHP view is cached, so you should treat the output as static (the same for all users) and avoid session-specific logic."
msgstr ""

#: ../../guides/javascript.rst:165
msgid "Setting the URL of a module"
msgstr ""

#: ../../guides/javascript.rst:167
msgid "You may have an AMD script outside your views you wish to make available as a module."
msgstr ""

#: ../../guides/javascript.rst:169
msgid "The best way to accomplish this is by configuring the path to the file using the ``views`` section of the ``elgg-plugin.php`` file in the root of your plugin:"
msgstr ""

#: ../../guides/javascript.rst:183
msgid "If you've copied the script directly into your plugin instead of managing it with Composer, you can use something like this instead:"
msgstr ""

#: ../../guides/javascript.rst:197
msgid "That's it! Elgg will now load this file whenever the \"underscore\" module is requested."
msgstr ""

#: ../../guides/javascript.rst:201
msgid "Using traditional JS libraries as modules"
msgstr ""

#: ../../guides/javascript.rst:203
msgid "It's possible to support JavaScript libraries that do not declare themselves as AMD modules (i.e. they declare global variables instead) if you shim them by setting ``exports`` and ``deps`` in ``elgg_define_js``:"
msgstr ""

#: ../../guides/javascript.rst:215
msgid "When this is requested client-side:"
msgstr ""

#: ../../guides/javascript.rst:217
msgid "The jQuery module is loaded, as it's marked as a dependency."
msgstr ""

#: ../../guides/javascript.rst:218
msgid "``https://elgg.example.org/cache/125235034/views/default/jquery.form.js`` is loaded and executed."
msgstr ""

#: ../../guides/javascript.rst:219
msgid "The value of ``window.jQuery.fn.ajaxForm`` is returned by the module."
msgstr ""

#: ../../guides/javascript.rst:221
msgid "Calls to ``elgg_define_js()`` must be in an ``init, system`` event handler."
msgstr ""

#: ../../guides/javascript.rst:224
msgid "Some things to note"
msgstr ""

#: ../../guides/javascript.rst:226
msgid "Do not use ``elgg.provide()`` anymore nor other means to attach code to ``elgg`` or other global objects. Use modules."
msgstr ""

#: ../../guides/javascript.rst:228
msgid "Return the value of the module instead of adding to a global variable."
msgstr ""

#: ../../guides/javascript.rst:229
msgid "Static (.js,.css,etc.) files are automatically minified and cached by Elgg's simplecache system."
msgstr ""

#: ../../guides/javascript.rst:230
msgid "The configuration is also cached in simplecache, and should not rely on user-specific values like ``get_current_language()``."
msgstr ""

#: ../../guides/javascript.rst:234
msgid "Modules provided with Elgg"
msgstr ""

#: ../../guides/javascript.rst:237
msgid "Module ``elgg``"
msgstr ""

#: ../../guides/javascript.rst:239
msgid "``elgg.echo()``"
msgstr ""

#: ../../guides/javascript.rst:241
msgid "Translate interface text"
msgstr ""

#: ../../guides/javascript.rst:248
msgid "``elgg.system_message()``"
msgstr ""

#: ../../guides/javascript.rst:250
msgid "Display a status message to the user."
msgstr ""

#: ../../guides/javascript.rst:257
msgid "``elgg.register_error()``"
msgstr ""

#: ../../guides/javascript.rst:259
msgid "Display an error message to the user."
msgstr ""

#: ../../guides/javascript.rst:266
msgid "``elgg.normalize_url()``"
msgstr ""

#: ../../guides/javascript.rst:268
msgid "Normalize a URL relative to the elgg root:"
msgstr ""

#: ../../guides/javascript.rst:275
msgid "``elgg.forward()``"
msgstr ""

#: ../../guides/javascript.rst:277
msgid "Redirect to a new page."
msgstr ""

#: ../../guides/javascript.rst:283
msgid "This function automatically normalizes the URL."
msgstr ""

#: ../../guides/javascript.rst:286
msgid "``elgg.parse_url()``"
msgstr ""

#: ../../guides/javascript.rst:288
msgid "Parse a URL into its component parts:"
msgstr ""

#: ../../guides/javascript.rst:301
msgid "``elgg.get_page_owner_guid()``"
msgstr ""

#: ../../guides/javascript.rst:303
msgid "Get the GUID of the current page's owner."
msgstr ""

#: ../../guides/javascript.rst:306
msgid "``elgg.register_hook_handler()``"
msgstr ""

#: ../../guides/javascript.rst:308
msgid "Register a hook handler with the event system."
msgstr ""

#: ../../guides/javascript.rst:310
msgid "``elgg.trigger_hook()``"
msgstr ""

#: ../../guides/javascript.rst:312
msgid "Emit a hook event in the event system."
msgstr ""

#: ../../guides/javascript.rst:319
msgid "``elgg.security.refreshToken()``"
msgstr ""

#: ../../guides/javascript.rst:321
msgid "Force a refresh of all XSRF tokens on the page."
msgstr ""

#: ../../guides/javascript.rst:323
msgid "This is automatically called every 5 minutes by default."
msgstr ""

#: ../../guides/javascript.rst:325
msgid "The user will be warned if their session has expired."
msgstr ""

#: ../../guides/javascript.rst:328
msgid "``elgg.security.addToken()``"
msgstr ""

#: ../../guides/javascript.rst:330
msgid "Add a security token to an object, URL, or query string:"
msgstr ""

#: ../../guides/javascript.rst:348
msgid "``elgg.get_logged_in_user_entity()``"
msgstr ""

#: ../../guides/javascript.rst:350
msgid "Returns the logged in user as an JS ElggUser object."
msgstr ""

#: ../../guides/javascript.rst:353
msgid "``elgg.get_logged_in_user_guid()``"
msgstr ""

#: ../../guides/javascript.rst:355
msgid "Returns the logged in user's guid."
msgstr ""

#: ../../guides/javascript.rst:358
msgid "``elgg.is_logged_in()``"
msgstr ""

#: ../../guides/javascript.rst:360
msgid "True if the user is logged in."
msgstr ""

#: ../../guides/javascript.rst:363
msgid "``elgg.is_admin_logged_in()``"
msgstr ""

#: ../../guides/javascript.rst:365
msgid "True if the user is logged in and is an admin."
msgstr ""

#: ../../guides/javascript.rst:368
msgid "``elgg.config.get_language()``"
msgstr ""

#: ../../guides/javascript.rst:370
msgid "Get the current page's language."
msgstr ""

#: ../../guides/javascript.rst:373
msgid "There are a number of configuration values set in the elgg object:"
msgstr ""

#: ../../guides/javascript.rst:389
msgid "Module ``elgg/Ajax``"
msgstr ""

#: ../../guides/javascript.rst:391
msgid "See the :doc:`ajax` page for details."
msgstr ""

#: ../../guides/javascript.rst:394
msgid "Module ``elgg/spinner``"
msgstr ""

#: ../../guides/javascript.rst:396
msgid "The ``elgg/spinner`` module can be used to create an loading indicator fixed to the top of the window. This can be used to give users feedback that the system is performing a longer running task. Using ajax features from ``elgg/Ajax`` will do this by default. You can also use it in your own code."
msgstr ""

#: ../../guides/javascript.rst:409
msgid "Module ``elgg/popup``"
msgstr ""

#: ../../guides/javascript.rst:411
msgid "The ``elgg/popup`` module can be used to display an overlay positioned relatively to its anchor (trigger)."
msgstr ""

#: ../../guides/javascript.rst:413
msgid "The ``elgg/popup`` module is loaded by default, and binding a popup module to an anchor is as simple as adding ``rel=\"popup\"`` attribute and defining target module with a ``href`` (or ``data-href``) attribute. Popup module positioning can be defined with ``data-position`` attribute of the trigger element."
msgstr ""

#: ../../guides/javascript.rst:446
msgid "The ``elgg/popup`` module allows you to build out more complex UI/UX elements. You can open and close popup modules programmatically:"
msgstr ""

#: ../../guides/javascript.rst:468
msgid "You can use ``getOptions, ui.popup`` plugin hook to manipulate the position of the popup before it has been opened. You can use jQuery ``open`` and ``close`` events to manipulate popup module after it has been opened or closed."
msgstr ""

#: ../../guides/javascript.rst:495
msgid "Open popup modules will always contain the following data that can be accessed via ``$.data()``:"
msgstr ""

#: ../../guides/javascript.rst:497
msgid "``trigger`` - jQuery element used to trigger the popup module to open"
msgstr ""

#: ../../guides/javascript.rst:498
msgid "``position`` - An object defining popup module position that was passed to ``$.position()``"
msgstr ""

#: ../../guides/javascript.rst:500
msgid "By default, ``target`` element will be appended to ``$('body')`` thus altering DOM hierarchy. If you need to preserve the DOM position of the popup module, you can add ``.elgg-popup-inline`` class to your trigger."
msgstr ""

#: ../../guides/javascript.rst:503
msgid "Module ``elgg/widgets``"
msgstr ""

#: ../../guides/javascript.rst:505
msgid "Plugins that load a widget layout via Ajax should initialize via this module:"
msgstr ""

#: ../../guides/javascript.rst:514
msgid "Module ``elgg/lightbox``"
msgstr ""

#: ../../guides/javascript.rst:516
msgid "Elgg is distributed with the Colorbox jQuery library. Please go to http://www.jacklmoore.com/colorbox for more information on the options of this lightbox."
msgstr ""

#: ../../guides/javascript.rst:518
msgid "Use the following classes to bind your anchor elements to a lightbox:"
msgstr ""

#: ../../guides/javascript.rst:520
msgid "``elgg-lightbox`` - loads an HTML resource"
msgstr ""

#: ../../guides/javascript.rst:521
msgid "``elgg-lightbox-photo`` - loads an image resource (should be used to avoid displaying raw image bytes instead of an ``img`` tag)"
msgstr ""

#: ../../guides/javascript.rst:522
msgid "``elgg-lightbox-inline`` - displays an inline HTML element in a lightbox"
msgstr ""

#: ../../guides/javascript.rst:523
msgid "``elgg-lightbox-iframe`` - loads a resource in an ``iframe``"
msgstr ""

#: ../../guides/javascript.rst:525
msgid "You may apply colorbox options to an individual ``elgg-lightbox`` element by setting the attribute ``data-colorbox-opts`` to a JSON settings object."
msgstr ""

#: ../../guides/javascript.rst:538
msgid "Use ``\"getOptions\", \"ui.lightbox\"`` plugin hook to filter options passed to ``$.colorbox()`` whenever a lightbox is opened."
msgstr ""

#: ../../guides/javascript.rst:540
msgid "``elgg/lightbox`` AMD module should be used to open and close the lightbox programmatically:"
msgstr ""

#: ../../guides/javascript.rst:558
msgid "To support gallery sets (via ``rel`` attribute), you need to bind colorbox directly to a specific selector (note that this will ignore ``data-colorbox-opts`` on all elements in a set):"
msgstr ""

#: ../../guides/javascript.rst:570
msgid "You can also resize the lightbox programmatically if needed:"
msgstr ""

#: ../../guides/javascript.rst:580
msgid "If you wish your content to be loaded by the ``elgg/Ajax`` AMD module, which automaticly loads the JS dependencies, you can pass the option ``ajaxLoadWithDependencies``"
msgstr ""

#: ../../guides/javascript.rst:592
msgid "Module ``elgg/ckeditor``"
msgstr ""

#: ../../guides/javascript.rst:594
msgid "This module can be used to add WYSIWYG editor to a textarea (requires ``ckeditor`` plugin to be enabled). Note that WYSIWYG will be automatically attached to all instances of ``.elgg-input-longtext``."
msgstr ""

#: ../../guides/javascript.rst:619
msgid "Inline tabs component"
msgstr ""

#: ../../guides/javascript.rst:621
msgid "Inline tabs component fires an ``open`` event whenever a tabs is open and, in case of ajax tabs, finished loading:"
msgstr ""

#: ../../guides/javascript.rst:642
msgid "Traditional scripts"
msgstr ""

#: ../../guides/javascript.rst:644
msgid "Although we highly recommend using AMD modules, and there is no Elgg API for loading the scripts, you can register scripts in a hook handler to add elements to the head links;"
msgstr ""

#: ../../guides/javascript.rst:652
msgid "Hooks"
msgstr ""

#: ../../guides/javascript.rst:654
msgid "The JS engine has a hooks system similar to the PHP engine's plugin hooks: hooks are triggered and plugins can register functions to react or alter information. There is no concept of Elgg events in the JS engine; everything in the JS engine is implemented as a hook."
msgstr ""

#: ../../guides/javascript.rst:657
msgid "Registering hook handlers"
msgstr ""

#: ../../guides/javascript.rst:659
msgid "Handler functions are registered using ``elgg.register_hook_handler()``. Multiple handlers can be registered for the same hook."
msgstr ""

#: ../../guides/javascript.rst:662
msgid "The handler function"
msgstr ""

#: ../../guides/javascript.rst:664
msgid "The handler will receive 4 arguments:"
msgstr ""

#: ../../guides/javascript.rst:666
msgid "**hook** - The hook name"
msgstr ""

#: ../../guides/javascript.rst:667
msgid "**type** - The hook type"
msgstr ""

#: ../../guides/javascript.rst:668
msgid "**params** - An object or set of parameters specific to the hook"
msgstr ""

#: ../../guides/javascript.rst:669
msgid "**value** - The current value"
msgstr ""

#: ../../guides/javascript.rst:671
msgid "The ``value`` will be passed through each hook. Depending on the hook, callbacks can simply react or alter data."
msgstr ""

#: ../../guides/javascript.rst:674
msgid "Triggering custom hooks"
msgstr ""

#: ../../guides/javascript.rst:676
msgid "Plugins can trigger their own hooks:"
msgstr ""

#: ../../guides/javascript.rst:685
msgid "Available hooks"
msgstr ""

#: ../../guides/javascript.rst:688
msgid "**init, system**"
msgstr ""

#: ../../guides/javascript.rst:688
msgid "Plugins should register their init functions for this hook. It is fired after Elgg's JS is loaded and all plugin boot modules have been initialized."
msgstr ""

#: ../../guides/javascript.rst:691
msgid "**getOptions, ui.popup**"
msgstr ""

#: ../../guides/javascript.rst:691
msgid "This hook is fired for pop up displays (``\"rel\"=\"popup\"``) and allows for customized placement options."
msgstr ""

#: ../../guides/javascript.rst:694
msgid "**getOptions, ui.lightbox**"
msgstr ""

#: ../../guides/javascript.rst:694
msgid "This hook can be used to filter options passed to ``$.colorbox()``"
msgstr ""

#: ../../guides/javascript.rst:697
msgid "**config, ckeditor**"
msgstr ""

#: ../../guides/javascript.rst:697
msgid "This filters the CKEditor config object. Register for this hook in a plugin boot module. The defaults can be seen in the module ``elgg/ckeditor/config``."
msgstr ""

#: ../../guides/javascript.rst:700
msgid "**prepare, ckeditor**"
msgstr ""

#: ../../guides/javascript.rst:700
msgid "This hook can be used to decorate ``CKEDITOR`` global. You can use this hook to register new CKEditor plugins and add event bindings."
msgstr ""

#: ../../guides/javascript.rst:704
msgid "**ajax_request_data, \\***"
msgstr ""

#: ../../guides/javascript.rst:703
msgid "This filters request data sent by the ``elgg/Ajax`` module. See :doc:`ajax` for details. The hook must check if the data is a plain object or an instanceof ``FormData`` to piggyback the values using correct API."
msgstr ""

#: ../../guides/javascript.rst:707
msgid "**ajax_response_data, \\***"
msgstr ""

#: ../../guides/javascript.rst:707
msgid "This filters the response data returned to users of the ``elgg/Ajax`` module. See :doc:`ajax` for details."
msgstr ""

#: ../../guides/javascript.rst:710
msgid "**insert, editor**"
msgstr ""

#: ../../guides/javascript.rst:710
msgid "This hook is triggered by the embed plugin and can be used to filter content before it is inserted into the textarea. This hook can also be used by WYSIWYG editors to insert content using their own API (in this case the handler should return ``false``). See ckeditor plugin for an example."
msgstr ""

#: ../../guides/javascript.rst:713
msgid "Third-party assets"
msgstr ""

#: ../../guides/javascript.rst:715
msgid "We recommend managing third-party scripts and styles with Composer. Elgg's composer.json is configured to install dependencies from the **NPM** or **Yarn** package repositories using Composer command-line tool. Core configuration installs the assets from `Asset Packagist <https://asset-packagist.org>`_ (a repository managed by the Yii community)."
msgstr ""

#: ../../guides/javascript.rst:720
msgid "Alternatively, you can install ``fxp/composer-asset-plugin`` globally to achieve the same results, but the installation and update takes much longer."
msgstr ""

#: ../../guides/javascript.rst:723
msgid "For example, to include jQuery, you could run the following Composer commands:"
msgstr ""

#: ../../guides/javascript.rst:730
msgid "If you are using a starter-project, or pulling in Elgg as a composer dependency via a custom composer project, update your ``composer.json`` with the following configuration:"
msgstr ""

#: ../../guides/javascript.rst:749
msgid "You can find additional information at `Asset Packagist <https://asset-packagist.org>`_ website."
msgstr ""

#: ../../guides/menus.rst:2
#: ../../guides/services.rst:12
msgid "Menus"
msgstr ""

#: ../../guides/menus.rst:4
msgid "Elgg contains helper code to build menus throughout the site."
msgstr ""

#: ../../guides/menus.rst:6
msgid "Every single menu requires a name, as does every single menu item. These are required in order to allow easy overriding and manipulation, as well as to provide hooks for theming."
msgstr ""

#: ../../guides/menus.rst:15
msgid "Basic usage"
msgstr ""

#: ../../guides/menus.rst:17
msgid "Basic functionalities can be achieved through these two functions:"
msgstr ""

#: ../../guides/menus.rst:19
msgid "``elgg_register_menu_item()`` to add an item to a menu"
msgstr ""

#: ../../guides/menus.rst:20
msgid "``elgg_unregister_menu_item()`` to remove an item from a menu"
msgstr ""

#: ../../guides/menus.rst:22
msgid "You normally want to call them from your plugin's init function."
msgstr ""

#: ../../guides/menus.rst:25
#: ../../guides/menus.rst:76
msgid "Examples"
msgstr ""

#: ../../guides/menus.rst:42
msgid "Admin menu"
msgstr ""

#: ../../guides/menus.rst:44
msgid "You can also register ``page`` menu items to the admin backend menu. When registering for the admin menu you can set the context of the menu items to ``admin`` so the menu items only show in the ``admin`` context. There are 3 default sections to add your menu items to."
msgstr ""

#: ../../guides/menus.rst:47
msgid "``administer`` for daily tasks, usermanagement and other actionable tasks"
msgstr ""

#: ../../guides/menus.rst:48
msgid "``configure`` for settings, configuration and utilities that configure stuff"
msgstr ""

#: ../../guides/menus.rst:49
msgid "``information`` for statistics, overview of information or status"
msgstr ""

#: ../../guides/menus.rst:53
msgid "Advanced usage"
msgstr ""

#: ../../guides/menus.rst:55
msgid "You can get more control over menus by using :doc:`plugin hooks </design/events>` and the public methods provided by the ``ElggMenuItem`` class."
msgstr ""

#: ../../guides/menus.rst:61
msgid "There are three hooks that can be used to modify a menu:"
msgstr ""

#: ../../guides/menus.rst:59
msgid "``'parameters', 'menu:<menu name>'`` to add or modify parameters use for the menu building (eg. sorting)"
msgstr ""

#: ../../guides/menus.rst:60
msgid "``'register', 'menu:<menu name>'`` to add or modify items (especially in dynamic menus)"
msgstr ""

#: ../../guides/menus.rst:61
msgid "``'prepare', 'menu:<menu name>'`` to modify the structure of the menu before it is displayed"
msgstr ""

#: ../../guides/menus.rst:63
msgid "When you register a plugin hook handler, replace the ``<menu name>`` part with the internal name of the menu."
msgstr ""

#: ../../guides/menus.rst:66
msgid "The third parameter passed into a menu handler contains all the menu items that have been registered so far by Elgg core and other enabled plugins. In the handler we can loop through the menu items and use the class methods to interact with the properties of the menu item."
msgstr ""

#: ../../guides/menus.rst:71
msgid "In some cases a more granular version of the ``register`` and ``prepare`` menu hooks exist with ``menu:<menu name>:<type>:<subtype>``, this applies when the menu gets provided an ``\\ElggEntity`` in ``$params['entity']`` or an ``\\ElggAnnotation`` in ``$params['annotation']`` or an ``\\ElggRelationship`` in ``$params['relationship']``."
msgstr ""

#: ../../guides/menus.rst:78
msgid "**Example 1:** Change the URL for menu item called \"albums\" in the ``owner_block`` menu:"
msgstr ""

#: ../../guides/menus.rst:117
msgid "**Example 2:** Modify the ``entity`` menu for the ``ElggBlog`` objects"
msgstr ""

#: ../../guides/menus.rst:116
msgid "Remove the thumb icon"
msgstr ""

#: ../../guides/menus.rst:117
msgid "Change the \"Edit\" text into a custom icon"
msgstr ""

#: ../../guides/menus.rst:155
msgid "Creating a new menu"
msgstr ""

#: ../../guides/menus.rst:157
msgid "Elgg provides multiple different menus by default. Sometimes you may however need some menu items that don't fit in any of the existing menus. If this is the case, you can create your very own menu with the ``elgg_view_menu()`` function. You must call the function from the view, where you want to menu to be displayed."
msgstr ""

#: ../../guides/menus.rst:163
msgid "**Example:** Display a menu called \"my_menu\" that displays it's menu items in alphapetical order:"
msgstr ""

#: ../../guides/menus.rst:171
msgid "You can now add new items to the menu like this:"
msgstr ""

#: ../../guides/menus.rst:182
msgid "Furthermore it is now possible to modify the menu using the hooks ``'register', 'menu:my_menu'`` and ``'prepare', 'menu:my_menu'``."
msgstr ""

#: ../../guides/menus.rst:186
msgid "Child Dropdown Menus"
msgstr ""

#: ../../guides/menus.rst:188
msgid "Child menus can be configured using ``child_menu`` factory option on the parent item."
msgstr ""

#: ../../guides/menus.rst:190
msgid "``child_menu`` options array accepts ``display`` parameter, which can be used to set the child menu to open as ``dropdown`` or be displayed via ``toggle``. All other key value pairs will be passed as attributes to the ``ul`` element."
msgstr ""

#: ../../guides/menus.rst:231
msgid "Theming"
msgstr ""

#: ../../guides/menus.rst:233
msgid "The menu name, section names, and item names are all embedded into the HTML as CSS classes (normalized to contain only hyphens, rather that underscores or colons). This increases the size of the markup slightly but provides themers with a high degree of control and flexibility when styling the site."
msgstr ""

#: ../../guides/menus.rst:238
msgid "**Example:** The following would be the output of the ``foo`` menu with sections ``alt`` and ``default`` containing items ``baz`` and ``bar`` respectively."
msgstr ""

#: ../../guides/menus.rst:251
msgid "Toggling Menu Items"
msgstr ""

#: ../../guides/menus.rst:253
msgid "There are situations where you wish to toggle menu items that are actions that are the opposite of each other and ajaxify them. E.g. like/unlike, friend/unfriend, ban/unban, etc. Elgg has built-in support for this kind of actions. When you register a menu item you can provide a name of the menu item (in the same menu) that should be toggled. An ajax call will be made using the href of the menu item."
msgstr ""

#: ../../guides/menus.rst:276
msgid "The menu items are optimistically toggled. This means the menu items are toggled before the actions finish. If the actions fail, the menu items will be toggled back."
msgstr ""

#: ../../guides/menus.rst:282
msgid "It is common that menu items rely on JavaScript. You can bind client-side events to menu items by placing your JavaScript into AMD module and defining the requirement during the registration."
msgstr ""

#: ../../guides/notifications.rst:6
msgid "There are two ways to send notifications in Elgg:"
msgstr ""

#: ../../guides/notifications.rst:5
#: ../../guides/notifications.rst:13
msgid "Instant notifications"
msgstr ""

#: ../../guides/notifications.rst:6
msgid "Event-based notifications send using a notifications queue"
msgstr ""

#: ../../guides/notifications.rst:15
msgid "The generic method to send a notification to a user is via the function `notify_user()`__. It is normally used when we want to notify only a single user. Notification like this might for example inform that someone has liked or commented the user's post."
msgstr ""

#: ../../guides/notifications.rst:19
msgid "The function usually gets called in an :doc:`action <actions>` file."
msgstr ""

#: ../../guides/notifications.rst:26
msgid "In this example a user (``$user``) is triggering an action to rate a post created by another user (``$owner``). After saving the rating (``ElggAnnotation $rating``) to database, we could use the following code to send a notification about the new rating to the owner."
msgstr ""

#: ../../guides/notifications.rst:57
msgid "The language used by the recipient isn't necessarily the same as the language of the person who triggers the notification. Therefore you must always remember to pass the recipient's language as the third parameter to ``elgg_echo()``."
msgstr ""

#: ../../guides/notifications.rst:63
msgid "The ``'summary'`` parameter is meant for notification plugins that only want to display a short message instead of both the subject and the body. Therefore the summary should be terse but still contain all necessary information."
msgstr ""

#: ../../guides/notifications.rst:68
msgid "Enqueued notifications"
msgstr ""

#: ../../guides/notifications.rst:70
msgid "On large sites there may be many users who have subscribed to receive notifications about a particular event. Sending notifications immediately when a user triggers such an event might remarkably slow down page loading speed. This is why sending of such notifications shoud be left for Elgg's notification queue."
msgstr ""

#: ../../guides/notifications.rst:75
msgid "New notification events can be registered with the `elgg_register_notification_event()`__ function or in the :doc:`elgg-plugin </guides/plugins>` configuration. Notifications about registered events will be sent automatically to all subscribed users."
msgstr ""

#: ../../guides/notifications.rst:79
msgid "This is the workflow of the notifications system:"
msgstr ""

#: ../../guides/notifications.rst:82
msgid "Someone does an action that triggers an event within Elgg"
msgstr ""

#: ../../guides/notifications.rst:82
msgid "The action can be ``create``, ``update`` or ``delete``"
msgstr ""

#: ../../guides/notifications.rst:83
msgid "The target of the action can be any instance of the ``ElggEntity`` class (e.g. a Blog post)"
msgstr ""

#: ../../guides/notifications.rst:84
msgid "The notifications system saves this event into a notifications queue in the database"
msgstr ""

#: ../../guides/notifications.rst:85
msgid "When the pluging hook handler for the one-minute interval gets triggered, the event is taken from the queue and it gets processed"
msgstr ""

#: ../../guides/notifications.rst:87
msgid "Subscriptions are fetched for the user who triggered the event"
msgstr ""

#: ../../guides/notifications.rst:87
msgid "By default this includes all the users who have enabled any notification method for the user at ``www.site.com/notifications/personal/<username>``"
msgstr ""

#: ../../guides/notifications.rst:89
msgid "Plugins are allowed to alter the subscriptions using the ``[get, subscriptions]`` hook"
msgstr ""

#: ../../guides/notifications.rst:90
msgid "Plugins are allowed to terminate notifications queue processing with the ``[send:before, notifications]`` hook"
msgstr ""

#: ../../guides/notifications.rst:91
msgid "Plugins are allowed to alter the notification parameters with the ``[prepare, notification]`` hook"
msgstr ""

#: ../../guides/notifications.rst:92
msgid "Plugins are allowed to alter the notification subject/message/summary with the ``[prepare, notification:<action>:<type>:<subtype>]`` hook"
msgstr ""

#: ../../guides/notifications.rst:93
msgid "Plugins are allowed to format notification subject/message/summary for individual delivery methods with ``[format, notification:<method>]`` hook"
msgstr ""

#: ../../guides/notifications.rst:94
msgid "Notifications are sent to each subscriber using the methods they have chosen"
msgstr ""

#: ../../guides/notifications.rst:95
msgid "Plugins can take over or prevent sending of each individual notification with the ``[send, notification:<method>]`` hook"
msgstr ""

#: ../../guides/notifications.rst:96
msgid "The ``[send:after, notifications]`` hook is triggered for the event after all notifications have been sent"
msgstr ""

#: ../../guides/notifications.rst:101
#: ../../guides/notifications.rst:123
msgid "Example"
msgstr ""

#: ../../guides/notifications.rst:103
msgid "Tell Elgg to send notifications when a new object of subtype \"photo\" is created:"
msgstr ""

#: ../../guides/notifications.rst:116
msgid "In order to send the event-based notifications you must have the one-minute :doc:`CRON </admin/cron>` interval configured."
msgstr ""

#: ../../guides/notifications.rst:119
msgid "Contents of the notification message can be defined with the ``'prepare', 'notification:[action]:[type]:[subtype]'`` hook."
msgstr ""

#: ../../guides/notifications.rst:125
msgid "Tell Elgg to use the function ``photos_prepare_notification()`` to format the contents of the notification when a new objects of subtype 'photo' is created:"
msgstr ""

#: ../../guides/notifications.rst:176
msgid "Make sure the notification will be in the correct language by passing the reciepient's language into the ``elgg_echo()`` function."
msgstr ""

#: ../../guides/notifications.rst:180
msgid "Notification salutation and sign-off"
msgstr ""

#: ../../guides/notifications.rst:182
msgid "Elgg will by default prepend a salutation to all outgoing notification body text. Also a sign-off will be appended. This means you will not need to add text like ``Hi Admin,`` or ``Kind regards, your friendly site administrator`` to your notifications body. If for some reason you do not need this magic to happen, you can prevent it by setting the notification parameter ``add_salutation`` to ``false``. You can do this as part of the parameters in ``notify_user()`` or in the ``prepare, notifications`` hook. You can change the salutation and sign-off texts in the translations."
msgstr ""

#: ../../guides/notifications.rst:188
msgid "You can also customize the salutation by overruling the view ``notifications/elements/salutation`` the sign-off can be customized by overruling the view ``notifications/elements/sign-off``."
msgstr ""

#: ../../guides/notifications.rst:192
msgid "Notification methods"
msgstr ""

#: ../../guides/notifications.rst:194
msgid "By default Elgg has three notification methods: email, delayed_email and the bundled site_notifications plugin."
msgstr ""

#: ../../guides/notifications.rst:199
msgid "Will send an email notification to to the recipient."
msgstr ""

#: ../../guides/notifications.rst:202
msgid "Delayed email"
msgstr ""

#: ../../guides/notifications.rst:204
msgid "Will save the notifications and deliver them in one bundled email at the interval the recipient has configured (daily or weekly)."
msgstr ""

#: ../../guides/notifications.rst:206
msgid "The availability of this delivery method can be configured by the site administrator in the Site settings section."
msgstr ""

#: ../../guides/notifications.rst:208
msgid "The layout of the bundled email can be customized by overruling the view ``email/delayed_email/plain_text`` for the plain text part of the email and ``email/delayed_email/html`` for the HTML part of the email."
msgstr ""

#: ../../guides/notifications.rst:212
msgid "Site notification"
msgstr ""

#: ../../guides/notifications.rst:214
msgid "Will show the notification on the site."
msgstr ""

#: ../../guides/notifications.rst:217
msgid "Registering a new notification method"
msgstr ""

#: ../../guides/notifications.rst:219
msgid "You can register a new notification method with the ``elgg_register_notification_method()`` function."
msgstr ""

#: ../../guides/notifications.rst:224
msgid "Register a handler that will send the notifications via SMS."
msgstr ""

#: ../../guides/notifications.rst:235
msgid "After registering the new method, it will appear on the notification settings page at ``www.example.com/notifications/personal/[username]``."
msgstr ""

#: ../../guides/notifications.rst:239
msgid "Sending the notifications using your own method"
msgstr ""

#: ../../guides/notifications.rst:241
msgid "Besides registering the notification method, you also need to register a handler that takes care of actually sending the SMS notifications. This happens with the ``'send', 'notification:[method]'`` hook."
msgstr ""

#: ../../guides/notifications.rst:283
msgid "Subscriptions"
msgstr ""

#: ../../guides/notifications.rst:285
msgid "In most cases Elgg core takes care of handling the subscriptions, so notification plugins don't usually have to alter them."
msgstr ""

#: ../../guides/notifications.rst:289
msgid "Subscriptions can however be:"
msgstr ""

#: ../../guides/notifications.rst:288
msgid "Added using the ``\\ElggEntity::addSubscription()`` function"
msgstr ""

#: ../../guides/notifications.rst:289
msgid "Removed using the ``\\ElggEntity::removeSubscription()`` function"
msgstr ""

#: ../../guides/notifications.rst:291
msgid "It's possible to modify the recipients of a notification dynamically with the ``'get', 'subscriptions'`` hook."
msgstr ""

#: ../../guides/notifications.rst:328
msgid "Muted notifications"
msgstr ""

#: ../../guides/notifications.rst:330
msgid "Notifications can be muted in order to no longer receive notifications, for example no longer receive notifications about new comments on a discussion."
msgstr ""

#: ../../guides/notifications.rst:332
msgid "In order to mute notifications call ``\\ElggEntity::muteNotifications($user_guid)`` the ``$user_guid`` is defaulted to the current logged in user. This will cause all subscriptions on the entity to be removed and a special flag will be set to know that notifications are muted."
msgstr ""

#: ../../guides/notifications.rst:335
msgid "The muting rules are applied after the subscribers of a notification event are requested and are applied for the following entities of the notification event: - the event actor ``\\Elgg\\Notifications\\NotificationEvent::getActor()`` - the event object entity ``\\Elgg\\Notifications\\NotificationEvent::getObject()`` - the event object container entity ``\\Elgg\\Notifications\\NotificationEvent::getObject()::getContainerEntity()`` - the event object owner entity ``\\Elgg\\Notifications\\NotificationEvent::getObject()::getOwnerEntity()``"
msgstr ""

#: ../../guides/notifications.rst:341
msgid "To unmute the notifications call ``\\ElggEntity::unmuteNotifications($user_guid)`` the ``$user_guid`` is defaulted to the current logged in user."
msgstr ""

#: ../../guides/notifications.rst:343
msgid "To check if a user has the notifications muted call ``\\ElggEntity::hasMutedNotifications($user_guid)`` the ``$user_guid`` is defaulted to the current logged in user."
msgstr ""

#: ../../guides/notifications.rst:346
msgid "Helper page"
msgstr ""

#: ../../guides/notifications.rst:348
msgid "A helper page has been added which can be linked (for example in an email footer) to manage muting based on a notification."
msgstr ""

#: ../../guides/notifications.rst:350
msgid "The page is required to be signed and use the route ``notifications:mute`` which needs: - ``entity_guid`` the entity the notification is about - ``recipient_guid`` the recipient of the notification"
msgstr ""

#: ../../guides/notifications.rst:355
msgid "Temporarily disable notifications"
msgstr ""

#: ../../guides/notifications.rst:357
msgid "Users can temporarily disable all notifications by going to the Notification settings and set a start and end date for the period they don't wish to receive any notifications."
msgstr ""

#: ../../guides/notifications.rst:360
msgid "Notification settings"
msgstr ""

#: ../../guides/notifications.rst:362
msgid "You can store and retreive notification settings of users with ``\\ElggUser::setNotificationSetting()`` and ``\\ElggUser::getNotificationSettings()``."
msgstr ""

#: ../../guides/notifications.rst:381
msgid "When a user has no setting yet for a non default purpose the system will fallback to the 'default' notification setting."
msgstr ""

#: ../../guides/notifications.rst:384
msgid "Notification management"
msgstr ""

#: ../../guides/notifications.rst:386
msgid "A generic menu hook handler is provided to manage notification subscription and muting. If you wish to make it easy for users to subscribe to your entities register a menu hook on ``register`` ``menu:<menu name>:<entity type>:<entity subtype>`` with the callback ``Elgg\\Notifications\\RegisterSubscriptionMenuItemsHandler`` make sure an ``\\ElggEntity`` in ``$params['entity']`` is provided. This will work for most ``elgg_view_menu()`` calls."
msgstr ""

#: ../../guides/page-owner.rst:2
msgid "Page ownership"
msgstr ""

#: ../../guides/page-owner.rst:4
msgid "One recurring task of any plugin will be to determine the page ownership in order to decide which actions are allowed or not. Elgg has a number of functions related to page ownership and also offers plugin developers flexibility by letting the plugin handle page ownership requests as well. Determining the owner of a page can be determined with ``elgg_get_page_owner_guid()``, which will return the GUID of the owner. Alternatively, ``elgg_get_page_owner_entity()`` will retrieve the whole page owner entity. If the page already knows who the page owner is, but the system doesn't, the page can set the page owner by passing the GUID to ``elgg_set_page_owner_guid($guid)``."
msgstr ""

#: ../../guides/page-owner.rst:12
msgid "The page owner entity can be any ``ElggEntity``. If you wish to only apply some setting in case of a user or a group make sure you check that you have the correct entity."
msgstr ""

#: ../../guides/page-owner.rst:16
msgid "Custom page owner handlers"
msgstr ""

#: ../../guides/page-owner.rst:18
msgid "Plugin developers can create page owner handlers, which could be necessary in certain cases, for example when integrating third party functionality. The handler will be a function which will need to get registered with ``elgg_register_plugin_hook_handler('page_owner', 'system', 'your_page_owner_function_name');``. The handler will only need to return a value (an integer GUID) when it knows for certain who the page owner is."
msgstr ""

#: ../../guides/page-owner.rst:23
msgid "By default, the system autodetects the page_owner from the following elements:"
msgstr ""

#: ../../guides/page-owner.rst:25
msgid "Based on the route definition:"
msgstr ""

#: ../../guides/page-owner.rst:27
msgid "If the name starts with ``view`` or ``edit`` the parameters ``username`` and ``guid`` are checked"
msgstr ""

#: ../../guides/page-owner.rst:28
msgid "If the name starts with ``add`` or ``collection`` the parameters ``username``, ``guid`` and ``container_guid`` are checked"
msgstr ""

#: ../../guides/page-owner.rst:29
msgid "If in the route definition the value ``detect_page_owner`` is set to ``true`` the parameters ``username``, ``guid`` and ``container_guid`` are checked"
msgstr ""

#: ../../guides/page-owner.rst:32
msgid "The legacy URL detection is tried if the route detected didn't result in a page owner:"
msgstr ""

#: ../../guides/page-owner.rst:34
msgid "The ``username`` URL parameter"
msgstr ""

#: ../../guides/page-owner.rst:35
msgid "The ``owner_guid`` URL parameter"
msgstr ""

#: ../../guides/page-owner.rst:36
msgid "The URL path"
msgstr ""

#: ../../guides/page-owner.rst:38
msgid "It then passes off to any page owner handlers defined using the :ref:`plugin hook <design/events#plugin-hooks>`. If no page owner can be determined, the page owner is set to 0, which is the same as the logged out user."
msgstr ""

#: ../../guides/permissions-check.rst:2
msgid "Permissions Check"
msgstr ""

#: ../../guides/permissions-check.rst:6
msgid "As stated in the page, this method works **only** for granting **write** access to entities. You **cannot** use this method to retrieve or view entities for which the user does not have read access."
msgstr ""

#: ../../guides/permissions-check.rst:8
msgid "Elgg provides a mechanism of overriding write permissions check through the :ref:`permissions_check plugin hook <guides/hooks-list#permission-hooks>` . This is useful for allowing plugin write to all accessible entities regardless of access settings. Entities that are hidden, however, will still be unavailable to the plugin."
msgstr ""

#: ../../guides/permissions-check.rst:11
msgid "Hooking permissions_check"
msgstr ""

#: ../../guides/permissions-check.rst:13
msgid "In your plugin, you must register the plugin hook for ``permissions_check``."
msgstr ""

#: ../../guides/permissions-check.rst:20
msgid "The override function"
msgstr ""

#: ../../guides/permissions-check.rst:22
msgid "Now create the function that will be called by the permissions check hook. In this function we determine if the entity (in parameters) has write access. Since it is important to keep Elgg secure, write access should be given only after checking a variety of situations including page context, logged in user, etc. Note that this function can return 3 values: true if the entity has write access, false if the entity does not, and null if this plugin doesn't care and the security system should consult other plugins."
msgstr ""

#: ../../guides/permissions-check.rst:40
msgid "Full Example"
msgstr ""

#: ../../guides/permissions-check.rst:42
msgid "This is a full example using the context to determine if the entity has write access."
msgstr ""

#: ../../guides/plugins.rst:4
msgid "Plugins must provide a ``composer.json`` file in the plugin root in order to be recognized by Elgg."
msgstr ""

#: ../../guides/plugins.rst:11
msgid "elgg-plugin.php"
msgstr ""

#: ../../guides/plugins.rst:13
msgid "``elgg-plugin.php`` is a static plugin configuration file. It is read by Elgg to configure various services, and must return an array if present. It should not be included by plugins and is not guaranteed to run at any particular time. Besides magic constants like ``__DIR__``, its return value should not change. The currently supported sections are:"
msgstr ""

#: ../../guides/plugins.rst:17
msgid "``plugin`` - defines plugin information and dependencies"
msgstr ""

#: ../../guides/plugins.rst:18
msgid "``bootstrap`` - defines a class used to bootstrap the plugin"
msgstr ""

#: ../../guides/plugins.rst:19
msgid "``entities`` - defines entity types and classes, and optionally registers them for search"
msgstr ""

#: ../../guides/plugins.rst:20
msgid "``actions`` - eliminates the need for calling ``elgg_register_action()``"
msgstr ""

#: ../../guides/plugins.rst:21
msgid "``routes`` - eliminates the need for calling ``elgg_register_route()``"
msgstr ""

#: ../../guides/plugins.rst:22
msgid "``settings`` - eliminates the need for setting default values on each call to ``elgg_get_plugin_setting()``"
msgstr ""

#: ../../guides/plugins.rst:23
msgid "``user_settings`` - eliminates the need for setting default values on each call to ``elgg_get_plugin_user_setting()``"
msgstr ""

#: ../../guides/plugins.rst:24
msgid "``views`` - allows plugins to alias vendor assets to a path within the Elgg's view system"
msgstr ""

#: ../../guides/plugins.rst:25
msgid "``widgets`` - eliminates the need for calling ``elgg_register_widget_type()``"
msgstr ""

#: ../../guides/plugins.rst:26
msgid "``events`` - eliminates the need for calling ``elgg_register_event_handler()``"
msgstr ""

#: ../../guides/plugins.rst:27
msgid "``hooks`` - eliminates the need for calling ``elgg_register_plugin_hook_handler()``"
msgstr ""

#: ../../guides/plugins.rst:28
msgid "``cli_commands`` - an array of ``Elgg/Cli/Command`` classes to extend the feature of ``elgg-cli``"
msgstr ""

#: ../../guides/plugins.rst:29
msgid "``view_extensions`` - eliminates the need for calling ``elgg_extend_view()`` or ``elgg_unextend_view()``"
msgstr ""

#: ../../guides/plugins.rst:30
msgid "``theme`` - an array of theme variables"
msgstr ""

#: ../../guides/plugins.rst:31
msgid "``group_tools`` - an array of available group tool options"
msgstr ""

#: ../../guides/plugins.rst:32
msgid "``view_options`` - an array of views with extra options"
msgstr ""

#: ../../guides/plugins.rst:33
msgid "``notifications`` - an array of notification events"
msgstr ""

#: ../../guides/plugins.rst:232
msgid "Bootstrap class"
msgstr ""

#: ../../guides/plugins.rst:234
msgid "As of Elgg 3.0 the recommended way to bootstrap you plugin is to use a bootstrap class. This class must implement the ``\\Elgg\\PluginBootstrapInterface`` interface. You can register you bootstrap class in the ``elgg-plugin.php``."
msgstr ""

#: ../../guides/plugins.rst:237
msgid "The bootstrap interface defines several function to be implemented which are called during different events in the system booting process."
msgstr ""

#: ../../guides/plugins.rst:241
msgid "For more information about the different functions defined in the ``\\Elgg\\PluginBootstrapInterface`` please read  :doc:`plugins/bootstrap`"
msgstr ""

#: ../../guides/plugins.rst:244
msgid "elgg-services.php"
msgstr ""

#: ../../guides/plugins.rst:246
msgid "Plugins can attach their services to Elgg's public DI container by providing PHP-DI definitions in ``elgg-services.php`` in the root of the plugin directory."
msgstr ""

#: ../../guides/plugins.rst:249
msgid "This file must return an array of PHP-DI definitions. Services will by available via ``elgg()``."
msgstr ""

#: ../../guides/plugins.rst:257
msgid "Plugins can then use PHP-DI API to autowire and call the service:"
msgstr ""

#: ../../guides/plugins.rst:263
msgid "See `PHP-DI documentation <http://php-di.org>`_ for a comprehensive list of definition and invokation possibilities."
msgstr ""

#: ../../guides/plugins.rst:266
msgid "composer.json"
msgstr ""

#: ../../guides/plugins.rst:268
msgid "Since Elgg supports being installed as a `Composer`_ dependency, having your plugins also support Composer makes for easier installation by site administrators. In order to make your plugin compatible with Composer you need to at least have a ``composer.json`` file in the root of your plugin."
msgstr ""

#: ../../guides/plugins.rst:272
msgid "Here is an example of a ``composer.json`` file:"
msgstr ""

#: ../../guides/plugins.rst:277
msgid "Read more about the ``composer.json`` format on the `Composer`_ website."
msgstr ""

#: ../../guides/plugins.rst:279
msgid "Important parts in the ``composer.json`` file are:"
msgstr ""

#: ../../guides/plugins.rst:281
msgid "``name``: the name of your plugin, keep this inline with the name of your plugin folder to ensure correct installation"
msgstr ""

#: ../../guides/plugins.rst:282
msgid "``type``: this will tell Composer where to install your plugin, ALWAYS keep this as ``elgg-plugin``"
msgstr ""

#: ../../guides/plugins.rst:283
msgid "``require``: the ``composer/installers`` requirement is to make sure Composer knows where to install your plugin"
msgstr ""

#: ../../guides/plugins.rst:285
msgid "As a suggestion, include a ``conflict`` rule with any Elgg version below your mininal required version, this will help prevent the accidental installation of your plugin on an incompatible Elgg version."
msgstr ""

#: ../../guides/plugins.rst:288
msgid "After adding a ``composer.json`` file to your plugin project, you need to register your project on `Packagist`_ in order for other people to be able to install your plugin."
msgstr ""

#: ../../guides/plugins.rst:292
msgid "Tests"
msgstr ""

#: ../../guides/plugins.rst:294
msgid "It's encouraged to create PHPUnit test for your plugin. All tests should be located in ``tests/phpunit/unit`` for unit tests and ``tests/phpunit/integration`` for integration tests."
msgstr ""

#: ../../guides/plugins.rst:297
msgid "An easy example of adding test is the ``ViewStackTest``, this will test that the views in your plugin are registered correctly and have no syntax errors. To add this test create a file ``ViewStackTest.php`` in the folder ``tests/phpunit/unit/<YourNameSpace>/<YourPluginName>/`` with the content:"
msgstr ""

#: ../../guides/plugins.rst:314
msgid "If you wish to see a better example, look in any of the Elgg core plugins."
msgstr ""

#: ../../guides/plugins.rst:318
msgid ":doc:`/contribute/tests`"
msgstr ""

#: ../../guides/plugins.rst:321
#: ../../guides/views.rst:647
#: ../../guides/web-services.rst:368
msgid "Related"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:2
msgid "Plugin bootstrap"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:4
msgid "In order to bootstrap your plugin as of Elgg 3.0 you can use a bootstrap class. This class must implement the ``\\Elgg\\PluginBootstrapInterface`` interface, but it's recommended you extend the ``\\Elgg\\PluginBootstrap`` abstract class as some preparations have already been done."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:8
msgid "If you only need a limited subset of the bootstrap functions your class can also extend the ``\\Elgg\\DefaultPluginBootstrap`` class, this class already has all the functions of ``\\Elgg\\PluginBootstrapInterface`` implemented. So you can overload only the functions you need."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:16
msgid "Registering the bootstrap class"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:18
msgid "You must register your bootstrap class in the ``elgg-plugin.php`` file."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:28
msgid "Available functions"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:31
msgid "->load()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:33
msgid "Executed during ``plugins_load``, ``system`` event"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:35
msgid "Allows the plugin to require additional files, as well as configure services prior to booting the plugin."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:38
msgid "->boot()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:40
msgid "Executed during ``plugins_boot:before``, ``system`` event"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:42
msgid "Allows the plugin to register handlers for ``plugins_boot``, ``system`` and ``init``, ``system`` events, as well as implement boot time logic."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:46
msgid "->init()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:48
msgid "Executed during ``init``, ``system`` event"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:50
msgid "Allows the plugin to implement business logic and register all other handlers."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:53
msgid "->ready()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:55
msgid "Executed during ``ready``, ``system`` event"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:57
msgid "Allows the plugin to implement logic after all plugins are initialized."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:60
msgid "->shutdown()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:62
msgid "Executed during ``shutdown``, ``system`` event"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:64
msgid "Allows the plugin to implement logic during shutdown."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:67
msgid "->activate()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:69
msgid "Executed when plugin is activated, after ``activate``, ``plugin`` event."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:72
msgid "->deactivate()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:74
msgid "Executed when plugin is deactivated, after ``deactivate``, ``plugin`` event."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:77
msgid "->upgrade()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:79
msgid "Registered as handler for ``upgrade``, ``system`` event"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:81
msgid "Allows the plugin to implement logic during system upgrade."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:84
msgid "Available helper functions"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:86
msgid "This assumes your bootstrap class extends the ``\\Elgg\\PluginBootstrap`` abstract class or the ``\\Elgg\\DefaultPluginBootstrap`` class."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:89
msgid "->elgg()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:91
msgid "Returns Elgg's public DI container. This can be helpfull if you wish to register plugin hooks or event listeners."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:102
msgid "->plugin()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:104
msgid "Returns plugin entity this bootstrap is related to. This makes it easier to get plugin settings."
msgstr ""

#: ../../guides/plugins/dependencies.rst:2
msgid "Plugin Dependencies"
msgstr ""

#: ../../guides/plugins/dependencies.rst:4
msgid "In Elgg the plugin dependencies system is there to prevent plugins from being used on incompatible systems."
msgstr ""

#: ../../guides/plugins/dependencies.rst:13
msgid "The dependencies system is controlled through a plugin's ``elgg-plugin.php`` file or ``composer.json``. Plugin authors can specify that a plugin:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:15
msgid "Requires certain Elgg plugins, PHP version or PHP extensions."
msgstr ""

#: ../../guides/plugins/dependencies.rst:16
msgid "Conflicts with certain Elgg versions or plugins."
msgstr ""

#: ../../guides/plugins/dependencies.rst:19
msgid "PHP version or extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:21
#: ../../guides/plugins/dependencies.rst:59
msgid "Add a section in your ``composer.json`` as described in de `Composer JSON reference <https://getcomposer.org/doc/04-schema.md#package-links>`_"
msgstr ""

#: ../../guides/plugins/dependencies.rst:33
msgid "Require an Elgg plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:35
msgid "Add a section to the ``elgg-plugin.php``, also see :doc:`/guides/plugins`"
msgstr ""

#: ../../guides/plugins/dependencies.rst:57
msgid "Conflicts"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:2
msgid "Plugin skeleton"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:4
msgid "The following is the standard for plugin structure in Elgg as of Elgg 2.0."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:7
msgid "Example Structure"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:9
msgid "The following is an example of a plugin with standard structure. For further explanation of this structure, see the details in the following sections. Your plugin may not need all the files listed"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:11
msgid "The following files for plugin ``example`` would go in ``/mod/example/``"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:67
msgid "Required Files"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:69
msgid "Plugins **must** provide a ``composer.json`` file in the plugin root in order to be recognized by Elgg."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:71
msgid "Therefore the following is the minimally compliant structure:"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:81
msgid "Plugins *should* place scripts for actions an ``actions/`` directory, and furthermore *should* use the name of the action to determine the location within that directory."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:83
msgid "For example, the action ``my/example/action`` would go in ``my_plugin/actions/my/example/action.php``. This makes it very obvious which script is associated with which action."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:85
msgid "Similarly, the body of the form that submits to this action should be located in ``forms/my/example/action.php``. Not only does this make the connection b/w action handler, form code, and action name obvious, but it allows you to use the ``elgg_view_form()`` function easily."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:88
msgid "Text Files"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:90
msgid "Plugins *may* provide various \\*.txt as additional documentation for the plugin. These files **must** be in Markdown syntax and will generate links on the plugin management sections."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:93
msgid "README.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:93
msgid "*should* provide additional information about the plugin of an unspecified nature"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:96
msgid "COPYRIGHT.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:96
msgid "If included, **must** provide an explanation of the plugin's copyright."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:99
msgid "LICENSE.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:99
msgid "If included, **must** provide the text of the license that the plugin is released under."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:102
msgid "INSTALL.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:102
msgid "If included, **must** provide additional instructions for installing the plugin if the process is sufficiently complicated (e.g. if it requires installing third party libraries on the host machine, or requires acquiring an API key from a third party)."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:105
msgid "CHANGES.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:105
msgid "If included, **must** provide a list of changes for their plugin, grouped by version number, with the most recent version at the top."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:107
msgid "Plugins *may* include additional \\*.txt files besides these, but no interface is given for reading them."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:110
msgid "Pages"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:112
msgid "To render full pages, plugins should use **resource views** (which have names beginning with ``resources/``). This allows other plugins to easily replace functionality via the view system."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:117
msgid "The reason we encourage this structure is"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:119
msgid "To form a logical relationship between urls and scripts, so that people examining the code can have an idea of what it does just by examining the structure."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:120
msgid "To clean up the root plugin directory, which historically has quickly gotten cluttered with the page handling scripts."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:123
msgid "Classes"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:125
msgid "Elgg provides `PSR-0 <http://www.php-fig.org/psr/psr-0/>`_ autoloading out of every active plugin's ``classes/`` directory."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:127
msgid "You're encouraged to follow the `PHP-FIG <http://www.php-fig.org/>`_ standards when writing your classes."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:131
msgid "Files with a \".class.php\" extension will **not** be recognized by Elgg."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:133
msgid "When organizing you classes Elgg does not require a specific structure. Use what works best for your plugin but keep in mind that it should be easy to read, funtionality should be easy to find and having seperated functions into different classes will improve maintainability and testability."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:136
msgid "Vendors"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:138
msgid "Included third-party libraries of any kind *should* be included in the ``vendors/`` folder in the plugin root. Though this folder has no special significance to the Elgg engine, this has historically been the location where Elgg core stores its third-party libraries, so we encourage the same format for the sake of consistency and familiarity."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:143
msgid "In order to override core views, a plugin's views can be placed in ``views/``, or an ``elgg-plugin.php`` config file can be used for more detailed file/path mapping. See :doc:`/guides/views`."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:145
msgid "Javascript and CSS will live in the views system. See :doc:`/guides/javascript`."
msgstr ""

#: ../../guides/river.rst:2
msgid "River"
msgstr ""

#: ../../guides/river.rst:4
msgid "Elgg natively supports the \"river\", an activity stream containing descriptions of activities performed by site members. This page gives an overview of adding events to the river in an Elgg plugin."
msgstr ""

#: ../../guides/river.rst:9
msgid "Pushing river items"
msgstr ""

#: ../../guides/river.rst:11
msgid "Items are pushed to the activity river through a function call, which you must include in your plugins for the items to appear."
msgstr ""

#: ../../guides/river.rst:14
msgid "Here we add a river item telling that a user has created a new blog post:"
msgstr ""

#: ../../guides/river.rst:27
msgid "All available parameters:"
msgstr ""

#: ../../guides/river.rst:29
msgid "``view`` => STR The view that will handle the river item (must exist)"
msgstr ""

#: ../../guides/river.rst:30
msgid "``action_type`` => STR An arbitrary string to define the action (e.g. 'create', 'update', 'vote', 'review', etc)"
msgstr ""

#: ../../guides/river.rst:31
msgid "``subject_guid`` => INT The GUID of the entity doing the action (default: the logged in user guid)"
msgstr ""

#: ../../guides/river.rst:32
msgid "``object_guid`` => INT The GUID of the entity being acted upon"
msgstr ""

#: ../../guides/river.rst:33
msgid "``target_guid`` => INT The GUID of the the object entity's container (optional)"
msgstr ""

#: ../../guides/river.rst:34
msgid "``access_id`` => INT The access ID of the river item (default: same as the object)"
msgstr ""

#: ../../guides/river.rst:35
msgid "``posted`` => INT The UNIX epoch timestamp of the river item (default: now)"
msgstr ""

#: ../../guides/river.rst:36
msgid "``annotation_id`` => INT The annotation ID associated with this river entry (optional)"
msgstr ""

#: ../../guides/river.rst:38
msgid "When an item is deleted or changed, the river item will be updated automatically."
msgstr ""

#: ../../guides/river.rst:41
msgid "River views"
msgstr ""

#: ../../guides/river.rst:43
msgid "As of Elgg 3.0 the ``view`` parameter is no longer required. A fallback logic has been created to check a series of views for you:"
msgstr ""

#: ../../guides/river.rst:45
msgid "``/river/{$type}/{$subtype}/{$action_type}``: eg. ``river/object/blog/create`` only the ``create`` action will come to this view"
msgstr ""

#: ../../guides/river.rst:46
msgid "``river/{$type}/{$subtype}/default``: eg. ``river/object/blog/default`` all river activity for ``object`` ``blog`` will come here"
msgstr ""

#: ../../guides/river.rst:47
msgid "``river/{$type}/{$action_type}``: eg. ``river/object/create`` all ``create`` actions for ``object`` will come here"
msgstr ""

#: ../../guides/river.rst:48
msgid "``river/{$type}/default``: eg. ``river/object/default`` all actions for all ``object`` will come here"
msgstr ""

#: ../../guides/river.rst:49
msgid "``river/elements/layout``: ultimate fall back view, this should always be called in any of the river views to make a consistent layout"
msgstr ""

#: ../../guides/river.rst:51
msgid "Both ``type`` and ``subtype`` are based on the ``type`` and ``subtype`` of the ``object_guid`` for which the river item was created."
msgstr ""

#: ../../guides/river.rst:56
msgid "If no ``summary`` parameter is provided to the ``river/elements/layout`` the view will try to create it for you. The basic result will be a text with the text `Somebody did something on Object`, where `Somebody` is based on ``subject_guid`` and `Object` is based on ``object_guid``. For both `Somebody` and `Object` links will be created. These links are passed to a series of language keys so you can create a meaningfull summary."
msgstr ""

#: ../../guides/river.rst:60
msgid "The language keys are:"
msgstr ""

#: ../../guides/river.rst:62
msgid "``river:{$type}:{$subtype}:{$action_type}``: eg. ``river:object:blog:create``"
msgstr ""

#: ../../guides/river.rst:63
msgid "``river:{$type}:{$subtype}:default``: eg. ``river:object:blog:default``"
msgstr ""

#: ../../guides/river.rst:64
msgid "``river:{$type}:{$action_type}``: eg. ``river:object:create``"
msgstr ""

#: ../../guides/river.rst:65
msgid "``river:{$type}:default``: eg. ``river:object:default``"
msgstr ""

#: ../../guides/river.rst:68
msgid "Custom river view"
msgstr ""

#: ../../guides/river.rst:70
msgid "If you wish to add some more information to the river view, like an attachment (image, YouTube embed, etc), you must specify the :doc:`view <views>` when creating the river item. This view **MUST** exist."
msgstr ""

#: ../../guides/river.rst:73
msgid "We recommend ``/river/{type}/{subtype}/{action}``, where:"
msgstr ""

#: ../../guides/river.rst:75
msgid "``{type}`` is the entity type of the content we're interested in (``object`` for objects, ``user`` for users, etc)"
msgstr ""

#: ../../guides/river.rst:76
msgid "``{subtype}`` is the entity subtype of the content we're interested in (``blog`` for blogs, ``photo_album`` for albums, etc)"
msgstr ""

#: ../../guides/river.rst:77
msgid "``{action}`` is the action that took place (``create``, ``update``, etc)"
msgstr ""

#: ../../guides/river.rst:79
msgid "River item information will be passed in an object called ``$vars['item']``, which contains the following important parameters:"
msgstr ""

#: ../../guides/river.rst:81
msgid "``$vars['item']->subject_guid`` The GUID of the user performing the action"
msgstr ""

#: ../../guides/river.rst:82
msgid "``$vars['item']->object_guid`` The GUID of the entity being acted upon"
msgstr ""

#: ../../guides/river.rst:84
msgid "Timestamps etc will be generated for you."
msgstr ""

#: ../../guides/river.rst:86
msgid "For example, the blog plugin uses the following code for its river view:"
msgstr ""

#: ../../guides/routing.rst:4
msgid "Elgg has two mechanisms to respond to HTTP requests that don't already go through the :doc:`/design/actions` and :doc:`/guides/views/simplecache` systems."
msgstr ""

#: ../../guides/routing.rst:8
msgid "URL Identifier and Segments"
msgstr ""

#: ../../guides/routing.rst:10
msgid "After removing the site URL, Elgg splits the URL path by ``/`` into an array. The first element, the **identifier**, is shifted off, and the remaining elements are called the **segments**. For example, if the site URL is ``http://example.com/elgg/``, the URL ``http://example.com/elgg/blog/owner/jane?foo=123`` produces:"
msgstr ""

#: ../../guides/routing.rst:15
msgid "Identifier: ``'blog'``. Segments: ``['owner', 'jane']``. (the query string parameters are available via ``get_input()``)"
msgstr ""

#: ../../guides/routing.rst:18
msgid "The site URL (home page) is a special case that produces an empty string identifier and an empty segments array."
msgstr ""

#: ../../guides/routing.rst:21
msgid "URL identifier/segments should be considered potentially dangerous user input. Elgg uses ``htmlspecialchars`` to escapes HTML entities in them."
msgstr ""

#: ../../guides/routing.rst:24
msgid "Page Handling"
msgstr ""

#: ../../guides/routing.rst:26
msgid "Elgg offers a facility to manage your plugin pages via custom routes, enabling URLs like ``http://yoursite/my_plugin/section``. You can register a new route using ``elgg_register_route()``, or via ``routes`` config in ``elgg-plugin.php``. Routes map to resource views, where you can render page contents."
msgstr ""

#: ../../guides/routing.rst:48
msgid "In the example above, we have registered a new route that is accessible via ``http://yoursite/my_plugin/section/<guid>/<subsection>``. Whenever that route is accessed with a required ``guid`` segment and an optional ``subsection`` segment, the router will render the specified ``my_plugin/section`` resource view and pass the parameters extracted from the URL to your resource view with ``$vars``."
msgstr ""

#: ../../guides/routing.rst:55
msgid "Routes names"
msgstr ""

#: ../../guides/routing.rst:57
msgid "Route names can then be used to generate a URL:"
msgstr ""

#: ../../guides/routing.rst:67
msgid "The route names are unique across all plugins and core, so another plugin can override the route by registering different parameters to the same route name."
msgstr ""

#: ../../guides/routing.rst:70
msgid "Route names follow a certain convention and in certain cases will be used to automatically resolve URLs, e.g. to display an entity."
msgstr ""

#: ../../guides/routing.rst:72
msgid "The following conventions are used in core and recommended for plugins:"
msgstr ""

#: ../../guides/routing.rst:76
msgid "**view:<entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/routing.rst:75
msgid "Maps to the entity profile page, e.g. ``view:user:user`` or ``view:object:blog`` The path must contain a ``guid``, or ``username`` for users"
msgstr ""

#: ../../guides/routing.rst:81
msgid "**edit:<entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/routing.rst:79
msgid "Maps to the form to edit the entity, e.g. ``edit:user:user`` or ``edit:object:blog`` The path must contain a ``guid``, or ``username`` for users If you need to add subresources, use suffixes, e.g. ``edit:object:blog:images``, keeping at least one subresource as a default without suffix."
msgstr ""

#: ../../guides/routing.rst:85
msgid "**add:<entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/routing.rst:84
msgid "Maps to the form to add a new entity of a given type, e.g. ``add:object:blog`` The path, as a rule, contains ``container_guid`` parameter"
msgstr ""

#: ../../guides/routing.rst:93
msgid "**collection:<entity_type>:<entity_subtype>:<collection_type>**"
msgstr ""

#: ../../guides/routing.rst:88
msgid "Maps to listing pages. Common route names used in core are, as follows:"
msgstr ""

#: ../../guides/routing.rst:90
msgid "``collection:object:blog:all``: list all blogs"
msgstr ""

#: ../../guides/routing.rst:91
msgid "``collection:object:blog:owner``: list blogs owned by a user with a given username"
msgstr ""

#: ../../guides/routing.rst:92
msgid "``collection:object:blog:friends``: list blogs owned by friends of the logged in user (or user with a given username)"
msgstr ""

#: ../../guides/routing.rst:93
msgid "``collection:object:blog:group``: list blogs in a group"
msgstr ""

#: ../../guides/routing.rst:98
msgid "**default:<entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/routing.rst:96
msgid "Maps to the default page for a resource, e.g. the path ``/blog``. Elgg happens to use the \"all\" collection for these routes."
msgstr ""

#: ../../guides/routing.rst:98
msgid "``default:object:blog``: handle the generic path ``/blog``."
msgstr ""

#: ../../guides/routing.rst:100
msgid "``<entity_subtype>`` can be omitted from route names to register global routes applicable to all entities of a given type. URL generator will first try to generate a URL using the subtype, and will then fallback to a route name without a subtype. For example, user profiles are routed to the same resource view regardless of user subtype."
msgstr ""

#: ../../guides/routing.rst:124
msgid "Route configuration"
msgstr ""

#: ../../guides/routing.rst:126
msgid "Segments can be defined using wildcards, e.g. ``profile/{username}``, which will match all URLs that contain ``profile/`` followed by and arbitrary username."
msgstr ""

#: ../../guides/routing.rst:129
msgid "To make a segment optional you can add a ``?`` (question mark) to the wildcard name, e.g. ``profile/{username}/{section?}``. In this case the URL will be matched even if the ``section`` segment is not provided."
msgstr ""

#: ../../guides/routing.rst:132
msgid "You can further constrain segments using regex requirements:"
msgstr ""

#: ../../guides/routing.rst:153
msgid "By default, Elgg will set the following requirements for named URL segments:"
msgstr ""

#: ../../guides/routing.rst:166
msgid "Plugin dependent routes"
msgstr ""

#: ../../guides/routing.rst:168
msgid "If a route requires a specific plugin to be active this can be configured in the route configuration."
msgstr ""

#: ../../guides/routing.rst:186
msgid "Route middleware"
msgstr ""

#: ../../guides/routing.rst:188
msgid "Route middleware can be used to prevent access to a certain route, or to perform some business logic before the route is rendered. Middleware can be used, e.g. to implement a paywall, or to log analytics, or to set open graph metatags."
msgstr ""

#: ../../guides/routing.rst:192
msgid "Elgg core implements several middleware handlers. The following middleware can be found in the namespace ``\\Elgg\\Router\\Middleware``:"
msgstr ""

#: ../../guides/routing.rst:195
msgid "Gatekeeper"
msgstr ""

#: ../../guides/routing.rst:197
msgid "This gatekeeper will prevent access by non-authenticated users."
msgstr ""

#: ../../guides/routing.rst:200
msgid "AdminGatekeeper"
msgstr ""

#: ../../guides/routing.rst:202
msgid "This gatekeeper will prevent access by non-admin users."
msgstr ""

#: ../../guides/routing.rst:205
msgid "LoggedOutGatekeeper"
msgstr ""

#: ../../guides/routing.rst:207
msgid "This gatekeeper will prevent access by authenticated users."
msgstr ""

#: ../../guides/routing.rst:210
msgid "AjaxGatekeeper"
msgstr ""

#: ../../guides/routing.rst:212
msgid "This gatekeeper will prevent access with non-xhr requests."
msgstr ""

#: ../../guides/routing.rst:215
msgid "PageOwnerCanEditGatekeeper"
msgstr ""

#: ../../guides/routing.rst:217
msgid "This gatekeeper will prevent access if there is a pageowner detected and the pageowner can't be editted."
msgstr ""

#: ../../guides/routing.rst:220
msgid "GroupPageOwnerCanEditGatekeeper"
msgstr ""

#: ../../guides/routing.rst:222
msgid "This gatekeeper extends the ``PageOwnerCanEditGatekeeper`` but also requires the pageowner to be a ``ElggGroup`` entity."
msgstr ""

#: ../../guides/routing.rst:225
msgid "UserPageOwnerCanEditGatekeeper"
msgstr ""

#: ../../guides/routing.rst:227
msgid "This gatekeeper extends the ``PageOwnerCanEditGatekeeper`` but also requires the pageowner to be an ``ElggUser`` entity."
msgstr ""

#: ../../guides/routing.rst:230
msgid "CsrfFirewall"
msgstr ""

#: ../../guides/routing.rst:232
msgid "This middleware will prevent access without the correct CSRF tokens. This middleware will automatically be applied to actions."
msgstr ""

#: ../../guides/routing.rst:235
msgid "ActionMiddleware"
msgstr ""

#: ../../guides/routing.rst:237
msgid "This middleware will provide action related logic. This middleware will automatically be applied to actions."
msgstr ""

#: ../../guides/routing.rst:240
msgid "SignedRequestGatekeeper"
msgstr ""

#: ../../guides/routing.rst:242
msgid "This gatekeeper will prevent access if the url has been tampered with. A secure URL can be generated using the ``elgg_http_get_signed_url`` function."
msgstr ""

#: ../../guides/routing.rst:246
msgid "UpgradeGatekeeper"
msgstr ""

#: ../../guides/routing.rst:248
msgid "This gatekeeper will prevent access if the upgrade URL is secured and the URL is invalid."
msgstr ""

#: ../../guides/routing.rst:251
msgid "WalledGarden"
msgstr ""

#: ../../guides/routing.rst:253
msgid "This middleware will prevent access to a route if the site is configured for authenticated users only and there is no authenticated user logged in. This middleware is automatically enabled for all routes. You can disable the walled garden gatekeeper with a :ref:`route config <guides/walled-garden#expose>` option."
msgstr ""

#: ../../guides/routing.rst:257
msgid "Custom Middleware"
msgstr ""

#: ../../guides/routing.rst:259
msgid "Middleware handlers can be set to any callable that receives an instance of ``\\Elgg\\Request``: The handler should throw an instance of ``\\Elgg\\Exceptions\\HttpException`` to prevent route access. The handler can return an instance of ``\\Elgg\\Http\\ResponseBuilder`` to prevent further implementation of the routing sequence (a redirect response can be returned to re-route the request)."
msgstr ""

#: ../../guides/routing.rst:288
msgid "Route controllers"
msgstr ""

#: ../../guides/routing.rst:290
msgid "In certain cases, using resource views is not appropriate. In these cases you can use a controller - any callable that receives an instance of ``\\Elgg\\Request``:"
msgstr ""

#: ../../guides/routing.rst:314
msgid "The ``route:rewrite`` Plugin Hook"
msgstr ""

#: ../../guides/routing.rst:316
msgid "For URL rewriting, the ``route:rewrite`` hook (with similar arguments as ``route``) is triggered very early, and allows modifying the request URL path (relative to the Elgg site)."
msgstr ""

#: ../../guides/routing.rst:319
msgid "Here we rewrite requests for ``news/*`` to ``blog/*``:"
msgstr ""

#: ../../guides/routing.rst:335
msgid "The hook must be registered directly in your plugin Bootstrap ``boot`` function. The ``init`` function is too late."
msgstr ""

#: ../../guides/routing.rst:338
msgid "Routing overview"
msgstr ""

#: ../../guides/routing.rst:340
msgid "For regular pages, Elgg's program flow is something like this:"
msgstr ""

#: ../../guides/routing.rst:342
msgid "A user requests ``http://example.com/news/owner/jane``."
msgstr ""

#: ../../guides/routing.rst:343
msgid "Plugins are initialized."
msgstr ""

#: ../../guides/routing.rst:344
msgid "Elgg parses the URL to identifier ``news`` and segments ``['owner', 'jane']``."
msgstr ""

#: ../../guides/routing.rst:345
msgid "Elgg triggers the plugin hook ``route:rewrite, news`` (see above)."
msgstr ""

#: ../../guides/routing.rst:346
msgid "Elgg finds a registered route that matches the final route path, and renders a resource view associated with it. It calls ``elgg_view_resource('blog/owner', $vars)`` where ``$vars`` contains the username."
msgstr ""

#: ../../guides/routing.rst:348
msgid "The ``resources/blog/owner`` view gets the username via ``$vars['username']``, and uses many other views and formatting functions like ``elgg_view_layout()`` and ``elgg_view_page()`` to create the entire HTML page."
msgstr ""

#: ../../guides/routing.rst:350
msgid "PHP invokes Elgg's shutdown sequence."
msgstr ""

#: ../../guides/routing.rst:351
msgid "The user receives a fully rendered page."
msgstr ""

#: ../../guides/routing.rst:353
msgid "Elgg's coding standards suggest a particular URL layout, but there is no syntax enforced."
msgstr ""

#: ../../guides/search.rst:10
msgid "Entity search"
msgstr ""

#: ../../guides/search.rst:12
msgid "Elgg core provides flexible ``elgg_search()``, which prepares custom search clauses and utilizes ``elgg_get_entities()`` to fetch the results."
msgstr ""

#: ../../guides/search.rst:14
msgid "In addition to all parameters accepted by ``elgg_get_entities()``, ``elgg_search()`` accepts the following:"
msgstr ""

#: ../../guides/search.rst:16
msgid "``query``         Search query"
msgstr ""

#: ../../guides/search.rst:17
msgid "``fields``        An array of names by property type to search in (see example below)"
msgstr ""

#: ../../guides/search.rst:18
msgid "``sort``          An array containing sorting options, including `property`, `property_type` and `direction`"
msgstr ""

#: ../../guides/search.rst:19
msgid "``type``          Entity type to search"
msgstr ""

#: ../../guides/search.rst:20
msgid "``subtype``       Optional entity subtype to search"
msgstr ""

#: ../../guides/search.rst:21
msgid "``search_type``   Custom search type (required if no ``type`` is provided)"
msgstr ""

#: ../../guides/search.rst:23
msgid "``partial_match`` Allow partial matches"
msgstr ""

#: ../../guides/search.rst:23
msgid "By default partial matches are allowed, meaning that ``elgg`` will be matched when searching for ``el`` Exact matches may be helpful when you want to match tag values, e.g. when you want to find all objects that are ``red`` and not ``darkred``"
msgstr ""

#: ../../guides/search.rst:27
msgid "``tokenize``      Break down search query into tokens"
msgstr ""

#: ../../guides/search.rst:26
msgid "By default search queries are tokenized, meaning that we will match ``elgg has been released`` when searching for ``elgg released``"
msgstr ""

#: ../../guides/search.rst:50
msgid "Search fields"
msgstr ""

#: ../../guides/search.rst:52
msgid "You can customize search fields for each entity type/subtype, using ``search:fields`` hook:"
msgstr ""

#: ../../guides/search.rst:73
msgid "Searchable types"
msgstr ""

#: ../../guides/search.rst:75
msgid "To register an entity type for search, use ``elgg_register_entity_type()``, or do so when defining an entity type in ``elgg-plugin.php``. To combine search results or filter how search results are presented in the search plugin, use ``'search:config', 'type_subtype_pairs'`` hook."
msgstr ""

#: ../../guides/search.rst:130
msgid "Custom search types"
msgstr ""

#: ../../guides/search.rst:132
msgid "Elgg core only supports entity search. You can implement custom searches, e.g. using search query as a location and listing entities by proximity to that location."
msgstr ""

#: ../../guides/search.rst:179
msgid "Autocomplete and livesearch endpoint"
msgstr ""

#: ../../guides/search.rst:181
msgid "Core provides a JSON endpoint for searching users and groups. These endpoints are used by ``input/autocomplete`` and ``input/userpicker`` views."
msgstr ""

#: ../../guides/search.rst:189
msgid "You can add custom search types, by adding a corresponding resource view:"
msgstr ""

#: ../../guides/services.rst:2
msgid "Services"
msgstr ""

#: ../../guides/services.rst:4
msgid "Elgg uses the ``Elgg\\Application`` class to load and bootstrap Elgg. In future releases this class will offer a set of service objects for plugins to use."
msgstr ""

#: ../../guides/services.rst:9
msgid "If you have a useful idea, you can :doc:`add a new service </contribute/services>`!"
msgstr ""

#: ../../guides/services.rst:14
msgid "``elgg()->menus`` provides low-level methods for constructing menus. In general, menus should be passed to ``elgg_view_menu`` for rendering instead of manual rendering."
msgstr ""

#: ../../guides/settings.rst:2
msgid "Plugin settings"
msgstr ""

#: ../../guides/settings.rst:8
msgid "You need to perform some extra steps if your plugin needs settings to be saved and controlled via the administration panel:"
msgstr ""

#: ../../guides/settings.rst:10
msgid "Create a file in your plugin’s default view folder called ``plugins/your_plugin/settings.php``, where ``your_plugin`` is the name of your plugin’s directory in the ``mod`` hierarchy"
msgstr ""

#: ../../guides/settings.rst:12
msgid "Fill this file with the form elements you want to display together with :doc:`internationalised <i18n>` text labels"
msgstr ""

#: ../../guides/settings.rst:13
msgid "Set the name attribute in your form components to ``params[`varname`]`` where ``varname`` is the name of the variable. These will be saved as private settings attached to a plugin entity. So, if your variable is called ``params[myparameter]`` your plugin (which is also passed to this view as ``$vars['entity']``) will be called ``$vars['entity']->myparameter``"
msgstr ""

#: ../../guides/settings.rst:17
msgid "An example ``settings.php`` would look like:"
msgstr ""

#: ../../guides/settings.rst:31
msgid "You don’t need to add a save button or the form, this will be handled by the framework."
msgstr ""

#: ../../guides/settings.rst:35
msgid "You cannot use form components that send no value when \"off.\" These include radio inputs and check boxes."
msgstr ""

#: ../../guides/settings.rst:37
msgid "If your plugin settings require a cache flush you can add a (hidden) input on the form with the name 'flush_cache' and value '1'"
msgstr ""

#: ../../guides/settings.rst:48
msgid "User settings"
msgstr ""

#: ../../guides/settings.rst:50
msgid "Your plugin might need to store per user settings too, and you would like to have your plugin's options to appear in the user's settings page. This is also easy to do and follows the same pattern as setting up the global plugin configuration explained earlier. The only difference is that instead of using a ``settings`` file you will use ``usersettings``. So, the path to the user edit view for your plugin would be ``plugins/<your_plugin>/usersettings.php``."
msgstr ""

#: ../../guides/settings.rst:57
msgid "The title of the usersettings form will default to the plugin name. If you want to change this, add a translation for ``<plugin_id>:usersettings:title``."
msgstr ""

#: ../../guides/settings.rst:60
msgid "Group settings"
msgstr ""

#: ../../guides/settings.rst:62
msgid "If your plugin needs settings per group you can extend the view ``groups/edit/settings`` to show your settings. The settings are shown during group creation and edit. In order for the settings to be saved correctly they need a name in the format ``settings[<plugin id>][<setting name>]``."
msgstr ""

#: ../../guides/settings.rst:66
msgid "Retrieving settings in your code"
msgstr ""

#: ../../guides/settings.rst:68
msgid "To retrieve settings from your code use:"
msgstr ""

#: ../../guides/settings.rst:74
#: ../../guides/settings.rst:107
msgid "or for user settings:"
msgstr ""

#: ../../guides/settings.rst:84
msgid "where:"
msgstr ""

#: ../../guides/settings.rst:86
msgid "``$name`` Is the value you want to retrieve"
msgstr ""

#: ../../guides/settings.rst:87
msgid "``$user_guid`` Is the user you want to retrieve these for (defaults to the currently logged in user)"
msgstr ""

#: ../../guides/settings.rst:88
msgid "``$plugin_name`` Is the name of the plugin (detected if run from within a plugin)"
msgstr ""

#: ../../guides/settings.rst:90
#: ../../guides/settings.rst:114
msgid "or for group settings:"
msgstr ""

#: ../../guides/settings.rst:98
msgid "Setting values while in code"
msgstr ""

#: ../../guides/settings.rst:100
msgid "Values may also be set from within your plugin code, to do this use one of the following functions:"
msgstr ""

#: ../../guides/settings.rst:123
msgid "The ``$plugin_id`` needs to be provided when setting plugin (user)settings."
msgstr ""

#: ../../guides/settings.rst:127
msgid "Since plugin settings are saved as private settings only `scalar <https://www.php.net/manual/en/function.is-scalar.php>`_ values are allowed, so no objects or arrays."
msgstr ""

#: ../../guides/settings.rst:131
msgid "Default plugin (group|user) settings"
msgstr ""

#: ../../guides/settings.rst:133
msgid "If a plugin or a user not have a setting stored in the database, you sometimes have the need for a certain default value. You can pass this when using the getter functions."
msgstr ""

#: ../../guides/settings.rst:144
msgid "Alternatively you can also provide default plugin and user settings in the ``elgg-plugin.php`` file."
msgstr ""

#: ../../guides/settings.rst:161
msgid "Group settings don't have a default value available in the ``elgg-plugin.php`` file."
msgstr ""

#: ../../guides/themes.rst:2
msgid "Themes"
msgstr ""

#: ../../guides/themes.rst:4
msgid "Customize the look and feel of Elgg."
msgstr ""

#: ../../guides/themes.rst:6
msgid "A theme is a type of :doc:`plugin </admin/plugins>` that overrides display aspects of Elgg."
msgstr ""

#: ../../guides/themes.rst:10
msgid "This guide assumes you are familiar with:"
msgstr ""

#: ../../guides/themes.rst:17
msgid "Theming Principles and Best Practices"
msgstr ""

#: ../../guides/themes.rst:22
msgid "**No third-party CSS frameworks**"
msgstr ""

#: ../../guides/themes.rst:20
msgid "Elgg does not use a CSS framework, because such frameworks lock users into a specific HTML markup, which in the end makes it much harder for plugins to collaborate on the appearance. What's `is-primary` in one theme, might be something else in the other. Having no framework allows plugins to alter appearance using pure css, without having to overwrite views and append framework-specific selectors to HTML markup elements."
msgstr ""

#: ../../guides/themes.rst:48
msgid "**8-point grid system**"
msgstr ""

#: ../../guides/themes.rst:46
msgid "Elgg uses an `8-point grid system <https://builttoadapt.io/intro-to-the-8-point-grid-system-d2573cde8632>`, so sizing of elements, their padding, margins etc is done in increments and fractions of `8px`. Because our default font-size is ``16px``, we use fractions of `rem`, so ``0.5rem = 8px``. 8-point grid system makes it a lot easier for developers to collaborate on styling elements: we no longer have to think if the padding should be ``5px`` or ``6px``."
msgstr ""

#: ../../guides/themes.rst:69
msgid "**Mobile first**"
msgstr ""

#: ../../guides/themes.rst:68
msgid "We write mobile-first CSS. We use two breakpoints: ``50rem`` and ``80rem`` (800px and 1280px at 16px/rem)."
msgstr ""

#: ../../guides/themes.rst:100
msgid "**Flexbox driven**"
msgstr ""

#: ../../guides/themes.rst:99
msgid "Flexbox provides simplicity in stacking elements into grids. Flexbox is used for everything from menus to layout elements. We avoid ``float`` and ``clearfix`` as they are hard to collaborate on and create lots of room for failure and distortion."
msgstr ""

#: ../../guides/themes.rst:132
msgid "**Symmetrical**"
msgstr ""

#: ../../guides/themes.rst:132
msgid "We maintain symmetry."
msgstr ""

#: ../../guides/themes.rst:152
msgid "**Simple color transitions**"
msgstr ""

#: ../../guides/themes.rst:150
msgid "We maintain 4 sets of colors for text, background and border: ``soft``, ``mild``, ``strong`` and ``highlight``. When transitioning to hover or active state, we go one level up, e.g. from ``soft`` to ``mild``, or use ``highlight``. When transition to inactive or disabled state, we go one level down."
msgstr ""

#: ../../guides/themes.rst:155
msgid "**Increase the click area**"
msgstr ""

#: ../../guides/themes.rst:155
msgid "When working with nested anchors, we increase the click area of the anchor, rather than the parent"
msgstr ""

#: ../../guides/themes.rst:174
msgid "**No z-index 999999**"
msgstr ""

#: ../../guides/themes.rst:174
msgid "z-indexes are incremented with a step of 1."
msgstr ""

#: ../../guides/themes.rst:177
msgid "**Wrap HTML siblings**"
msgstr ""

#: ../../guides/themes.rst:177
msgid "We make sure that there are no orphaned strings within a parent and that siblings are wrapped in a way that they can be targeted by CSS."
msgstr ""

#: ../../guides/themes.rst:214
msgid "Create your plugin"
msgstr ""

#: ../../guides/themes.rst:216
msgid "Create your plugin as described in the :doc:`developer guide </guides/index>`."
msgstr ""

#: ../../guides/themes.rst:218
msgid "Create a new directory under mod/"
msgstr ""

#: ../../guides/themes.rst:219
msgid "Create a new elgg-plugin.php"
msgstr ""

#: ../../guides/themes.rst:220
msgid "Create a composer.json file describing your theme."
msgstr ""

#: ../../guides/themes.rst:223
msgid "Customize the CSS"
msgstr ""

#: ../../guides/themes.rst:225
msgid "The css is split into several files based on what aspects of the site you're theming. This allows you to tackle them one at a time, giving you a chance to make real progress without getting overwhelmed."
msgstr ""

#: ../../guides/themes.rst:230
msgid "Here is a list of the existing CSS views:"
msgstr ""

#: ../../guides/themes.rst:232
msgid "elements/buttons.css: Provides a way to style all the different kinds of buttons your site will use. There are 5 kinds of buttons that plugins will expect to be available: action, cancel, delete, submit, and special."
msgstr ""

#: ../../guides/themes.rst:233
msgid "elements/chrome.css: This file has some miscellaneous look-and-feel classes."
msgstr ""

#: ../../guides/themes.rst:234
msgid "elements/components.css: This file contains many “css objects” that are used all over the site: media block, list, gallery, table, owner block, system messages, river, tags, photo, and comments."
msgstr ""

#: ../../guides/themes.rst:235
msgid "elements/forms.css: This file determines what your forms and input elements will look like."
msgstr ""

#: ../../guides/themes.rst:236
msgid "elements/icons.css: Contains styles for the icons and avatars used on your site."
msgstr ""

#: ../../guides/themes.rst:237
msgid "elements/layout.css: Determines what your page layout will look like: sidebars, page wrapper, main body, header, footer, etc."
msgstr ""

#: ../../guides/themes.rst:238
msgid "elements/modules.css: Lots of content in Elgg is displayed in boxes with a title and a content body. We called these modules. There are a few kinds: info, aside, featured, dropdown, popup, widget. Widget styles are included in this file too, since they are a subset of modules."
msgstr ""

#: ../../guides/themes.rst:239
msgid "elements/navigation.css: This file determines what all your menus will look like."
msgstr ""

#: ../../guides/themes.rst:240
msgid "elements/typography.css: This file determines what the content and headings of your site will look like."
msgstr ""

#: ../../guides/themes.rst:241
msgid "rtl.css: Custom rules for users viewing your site in a right-to-left language."
msgstr ""

#: ../../guides/themes.rst:242
msgid "admin.css: A completely separate theme for the admin area (usually not overridden)."
msgstr ""

#: ../../guides/themes.rst:243
msgid "elgg.css: Compiles all the core elements/\\* files into one file (DO NOT OVERRIDE)."
msgstr ""

#: ../../guides/themes.rst:244
msgid "elements/core.css: Contains base styles for the more complicated “css objects”. If you find yourself wanting to override this, you probably need to report a bug to Elgg core instead (DO NOT OVERRIDE)."
msgstr ""

#: ../../guides/themes.rst:245
msgid "elements/reset.css: Contains a reset stylesheet that forces elements to have the same default"
msgstr ""

#: ../../guides/themes.rst:248
msgid "CSS variables"
msgstr ""

#: ../../guides/themes.rst:250
msgid "Elgg uses CssCrush for preprocessing CSS files. This gives us the flexibility of using global CSS variables. Plugins should, wherever possible, use global CSS variables, and extend the core theme with their plugin variables, so they can be simply altered by other plugins."
msgstr ""

#: ../../guides/themes.rst:254
msgid "To add or alter variables, use the ``vars:compiler, css`` hook. Note that you may need to flush the cache to see your changes in action."
msgstr ""

#: ../../guides/themes.rst:257
msgid "For a list of default core variables, see ``engine/theme.php``."
msgstr ""

#: ../../guides/themes.rst:262
msgid "View extension"
msgstr ""

#: ../../guides/themes.rst:264
msgid "There are two ways you can modify views:"
msgstr ""

#: ../../guides/themes.rst:266
msgid "The first way is to add extra stuff to an existing view via the ``views_extensions`` section within your elgg-plugin.php definition."
msgstr ""

#: ../../guides/themes.rst:269
msgid "For example, the following configuration will add mytheme/css to Elgg's core css file:"
msgstr ""

#: ../../guides/themes.rst:283
msgid "View overloading"
msgstr ""

#: ../../guides/themes.rst:285
msgid "Plugins can have a view hierarchy, any file that exists here will replace any files in the existing core view hierarchy... so for example, if my plugin has a file:"
msgstr ""

#: ../../guides/themes.rst:289
msgid "``/mod/myplugin/views/default/elements/typography.css``"
msgstr ""

#: ../../guides/themes.rst:291
msgid "it will replace:"
msgstr ""

#: ../../guides/themes.rst:293
msgid "``/views/default/elements/typography.css``"
msgstr ""

#: ../../guides/themes.rst:295
msgid "But only when the plugin is active."
msgstr ""

#: ../../guides/themes.rst:297
msgid "This gives you total control over the way Elgg looks and behaves. It gives you the option to either slightly modify or totally replace existing views."
msgstr ""

#: ../../guides/themes.rst:302
#: ../../guides/views.rst:595
msgid "Icons"
msgstr ""

#: ../../guides/themes.rst:304
msgid "As of Elgg 2.0 the default Elgg icons come from the FontAwesome_ library. You can use any of these icons by calling:"
msgstr ""

#: ../../guides/themes.rst:307
msgid "``elgg_view_icon('icon-name');``"
msgstr ""

#: ../../guides/themes.rst:309
msgid "``icon-name`` can be any of the `FontAwesome icons`_ without the ``fa-``-prefix."
msgstr ""

#: ../../guides/themes.rst:311
msgid "By default you will get the solid styled variant of the icons. Postfixing the icon name with ``-solid``, ``-regular`` or ``-light`` allows you to target a specific style. Be advised; the light styled variant is only available as a FontAwesome Pro licensed icon."
msgstr ""

#: ../../guides/themes.rst:318
msgid "Tools"
msgstr ""

#: ../../guides/themes.rst:320
msgid "We've provided you with some development tools to help you with theming: Turn on the “Developers” plugin and go to the “Theme Preview” page to start tracking your theme's progress."
msgstr ""

#: ../../guides/themes.rst:325
msgid "Customizing the front page"
msgstr ""

#: ../../guides/themes.rst:326
msgid "The main Elgg index page is served via a resource view."
msgstr ""

#: ../../guides/themes.rst:328
msgid "Therefore, you can override it by providing your own resource file in ``your_plugin/views/default/resources/index.php``."
msgstr ""

#: ../../guides/upgrading-data.rst:2
msgid "Writing a plugin upgrade"
msgstr ""

#: ../../guides/upgrading-data.rst:4
msgid "Every now and then there comes a time when a plugin needs to change the contents or the structure of the data it has stored either in the database or the dataroot."
msgstr ""

#: ../../guides/upgrading-data.rst:7
msgid "The motivation for this may be that the data structure needs to be converted to more efficient or flexible structure. Or perhaps due to a bug the data items have been saved in an invalid way, and they needs to be converted to the correct format."
msgstr ""

#: ../../guides/upgrading-data.rst:11
msgid "Migrations and convertions like this may take a long time if there is a lot of data to be processed. This is why Elgg provides the ``Elgg\\Upgrade\\Batch`` interface that can be used for implementing long-running upgrades."
msgstr ""

#: ../../guides/upgrading-data.rst:16
msgid "Declaring a plugin upgrade"
msgstr ""

#: ../../guides/upgrading-data.rst:18
msgid "Plugin can communicate the need for an upgrade under the ``upgrades`` key in ``elgg-plugin.php`` file. Each value of the array must be the fully qualified name of an upgrade class that implements the ``Elgg\\Upgrade\\Batch`` interface."
msgstr ""

#: ../../guides/upgrading-data.rst:22
msgid "Example from ``mod/blog/elgg-plugin.php`` file:"
msgstr ""

#: ../../guides/upgrading-data.rst:35
msgid "The class names in the example refer to the classes:"
msgstr ""

#: ../../guides/upgrading-data.rst:34
msgid "``mod/blog/classes/Blog/Upgrades/AccessLevelFix``"
msgstr ""

#: ../../guides/upgrading-data.rst:35
msgid "``mod/blog/classes/Blog/Upgrades/DraftStatusUpgrade``"
msgstr ""

#: ../../guides/upgrading-data.rst:37
msgid "Elgg core upgrade classes can be declared in ``engine/lib/upgrades/async-upgrades.php``."
msgstr ""

#: ../../guides/upgrading-data.rst:40
msgid "The upgrade class"
msgstr ""

#: ../../guides/upgrading-data.rst:42
msgid "A class implementing the ``Elgg\\Upgrade\\Batch`` interface has a lot of freedom on how it wants to handle the actual processing of the data. It must however declare some constant variables and also take care of marking whether each processed item was upgraded successfully or not."
msgstr ""

#: ../../guides/upgrading-data.rst:47
msgid "The basic structure of the class is the following:"
msgstr ""

#: ../../guides/upgrading-data.rst:112
msgid "Do not assume when your class will be instantiated or when/how often its public methods will be called."
msgstr ""

#: ../../guides/upgrading-data.rst:115
msgid "Class methods"
msgstr ""

#: ../../guides/upgrading-data.rst:118
msgid "getVersion()"
msgstr ""

#: ../../guides/upgrading-data.rst:120
msgid "This must return an integer representing the date the upgrade was added. It consists of eight digits and is in format ``yyyymmddnn`` where:"
msgstr ""

#: ../../guides/upgrading-data.rst:123
msgid "``yyyy`` is the year"
msgstr ""

#: ../../guides/upgrading-data.rst:124
msgid "``mm`` is the month (with leading zero)"
msgstr ""

#: ../../guides/upgrading-data.rst:125
msgid "``dd`` is the day (with leading zero)"
msgstr ""

#: ../../guides/upgrading-data.rst:126
msgid "``nn`` is an incrementing number (starting from ``00``) that is used in case two separate upgrades have been added during the same day"
msgstr ""

#: ../../guides/upgrading-data.rst:130
msgid "shouldBeSkipped()"
msgstr ""

#: ../../guides/upgrading-data.rst:132
msgid "This should return ``false`` unless the upgrade won't be needed."
msgstr ""

#: ../../guides/upgrading-data.rst:134
msgid "If ``true`` is returned the upgrade cannot be run later."
msgstr ""

#: ../../guides/upgrading-data.rst:137
msgid "needsIncrementOffset()"
msgstr ""

#: ../../guides/upgrading-data.rst:139
msgid "If ``true``, your ``run()`` method will receive as ``$offset`` the number of items aready processed. This is useful if you are only modifying data, and need to use the ``$offset`` in a function like ``elgg_get_entities()`` to know how many you've already handled."
msgstr ""

#: ../../guides/upgrading-data.rst:144
msgid "If ``false``, your ``run()`` method will receive as ``$offset`` the total number of failures. ``false`` should be used if your process deletes or moves data out of the way of the process. E.g. if you delete 50 objects on each ``run()``, you don't really need the ``$offset``."
msgstr ""

#: ../../guides/upgrading-data.rst:150
msgid "countItems()"
msgstr ""

#: ../../guides/upgrading-data.rst:152
msgid "Get the total number of items to process during the upgrade. If unknown, ``Batch::UNKNOWN_COUNT`` can be returned, but ``run()`` must manually mark the upgrade complete."
msgstr ""

#: ../../guides/upgrading-data.rst:156
msgid "run()"
msgstr ""

#: ../../guides/upgrading-data.rst:158
msgid "This must perform a portion of the actual upgrade. And depending on how long it takes, it may be called multiple times during a single request."
msgstr ""

#: ../../guides/upgrading-data.rst:161
msgid "It receives two arguments:"
msgstr ""

#: ../../guides/upgrading-data.rst:163
msgid "``$result``: An instance of ``Elgg\\Upgrade\\Result`` object"
msgstr ""

#: ../../guides/upgrading-data.rst:164
msgid "``$offset``: The offset where the next upgrade portion should start (or total number of failures)"
msgstr ""

#: ../../guides/upgrading-data.rst:166
msgid "For each item the method processes, it must call either:"
msgstr ""

#: ../../guides/upgrading-data.rst:168
msgid "``$result->addSuccesses()``: If the item was upgraded successfully"
msgstr ""

#: ../../guides/upgrading-data.rst:169
msgid "``$result->addFailures()``: If it failed to upgrade the item"
msgstr ""

#: ../../guides/upgrading-data.rst:171
msgid "Both methods default to one item, but you can optionally pass in the number of items."
msgstr ""

#: ../../guides/upgrading-data.rst:173
msgid "Additionally it can set as many error messages as it sees necessary in case something goes wrong:"
msgstr ""

#: ../../guides/upgrading-data.rst:175
msgid "``$result->addError(\"Error message goes here\")``"
msgstr ""

#: ../../guides/upgrading-data.rst:177
msgid "If ``countItems()`` returned ``Batch::UNKNOWN_COUNT``, then at some point ``run()`` must call ``$result->markComplete()`` to finish the upgrade."
msgstr ""

#: ../../guides/upgrading-data.rst:180
msgid "In most cases your ``run()`` method will want to pass the ``$offset`` parameter to one of the ``elgg_get_entities()`` functions:"
msgstr ""

#: ../../guides/upgrading-data.rst:213
msgid "Administration interface"
msgstr ""

#: ../../guides/upgrading-data.rst:215
msgid "Each upgrade implementing the ``Elgg\\Upgrade\\Batch`` interface gets listed in the admin panel after triggering the site upgrade from the Administration dashboard."
msgstr ""

#: ../../guides/upgrading-data.rst:219
msgid "While running the upgrades Elgg provides:"
msgstr ""

#: ../../guides/upgrading-data.rst:221
msgid "Estimated duration of the upgrade"
msgstr ""

#: ../../guides/upgrading-data.rst:222
msgid "Count of processed items"
msgstr ""

#: ../../guides/upgrading-data.rst:223
msgid "Number of errors"
msgstr ""

#: ../../guides/upgrading-data.rst:224
msgid "Possible error messages"
msgstr ""

#: ../../guides/views.rst:9
msgid "Introduction"
msgstr ""

#: ../../guides/views.rst:11
msgid "Views are responsible for creating output. They handle everything from:"
msgstr ""

#: ../../guides/views.rst:13
msgid "the layout of pages"
msgstr ""

#: ../../guides/views.rst:14
msgid "chunks of presentation output (like a footer or a toolbar)"
msgstr ""

#: ../../guides/views.rst:15
msgid "individual links and form inputs."
msgstr ""

#: ../../guides/views.rst:16
msgid "the images, js, and css needed by your web page"
msgstr ""

#: ../../guides/views.rst:19
msgid "Using views"
msgstr ""

#: ../../guides/views.rst:21
msgid "At their most basic level, the default views are just PHP files with snippets of html:"
msgstr ""

#: ../../guides/views.rst:27
msgid "Assuming this view is located at ``/views/default/hello.php``, we could output it like so:"
msgstr ""

#: ../../guides/views.rst:33
msgid "For your convenience, Elgg comes with quite a lot of views by default. In order to keep things manageable, they are organized into subdirectories. Elgg handles this situation quite nicely. For example, our simple view might live in ``/views/default/hello/world.php``, in which case it would be called like so:"
msgstr ""

#: ../../guides/views.rst:42
msgid "The name of the view simply reflects the location of the view in the views directory."
msgstr ""

#: ../../guides/views.rst:45
msgid "Views as templates"
msgstr ""

#: ../../guides/views.rst:47
msgid "You can pass arbitrary data to a view via the ``$vars`` array. Our ``hello/world`` view might be modified to accept a variable like so:"
msgstr ""

#: ../../guides/views.rst:54
msgid "In this case, we can pass an arbitrary name parameter to the view like so:"
msgstr ""

#: ../../guides/views.rst:60
msgid "which would produce the following output:"
msgstr ""

#: ../../guides/views.rst:68
msgid "Views don't do any kind of automatic output sanitization by default. You are responsible for doing the correct sanitization yourself to prevent XSS attacks and the like."
msgstr ""

#: ../../guides/views.rst:73
msgid "Views as cacheable assets"
msgstr ""

#: ../../guides/views.rst:75
msgid "As mentioned before, views can contain JS, CSS, or even images."
msgstr ""

#: ../../guides/views.rst:77
msgid "Asset views must meet certain requirements:"
msgstr ""

#: ../../guides/views.rst:79
msgid "They *must not* take any ``$vars`` parameters"
msgstr ""

#: ../../guides/views.rst:80
msgid "They *must not* change their output based on global state like"
msgstr ""

#: ../../guides/views.rst:82
msgid "who is logged in"
msgstr ""

#: ../../guides/views.rst:83
msgid "the time of day"
msgstr ""

#: ../../guides/views.rst:85
msgid "They *must* contain a valid file extension"
msgstr ""

#: ../../guides/views.rst:87
msgid "Bad: ``my/cool/template``"
msgstr ""

#: ../../guides/views.rst:88
msgid "Good: ``my/cool/template.html``"
msgstr ""

#: ../../guides/views.rst:90
msgid "For example, suppose you wanted to load some CSS on a page. You could define a view ``mystyles.css``, which would look like so:"
msgstr ""

#: ../../guides/views.rst:102
msgid "Leave off the trailing \".php\" from the filename and Elgg will automatically recognize the view as cacheable."
msgstr ""

#: ../../guides/views.rst:105
msgid "To get a URL to this file, you would use ``elgg_get_simplecache_url``:"
msgstr ""

#: ../../guides/views.rst:112
msgid "Elgg automatically adds the magic numbers you see there for cache-busting and sets long-term expires headers on the returned file."
msgstr ""

#: ../../guides/views.rst:117
msgid "Elgg may decide to change the location or structure of the returned URL in a future release for whatever reason, and the cache-busting numbers change every time you flush Elgg's caches, so the exact URL is not stable by design."
msgstr ""

#: ../../guides/views.rst:121
msgid "With that in mind, here's a couple anti-patterns to avoid:"
msgstr ""

#: ../../guides/views.rst:123
msgid "Don't rely on the exact structure/location of this URL"
msgstr ""

#: ../../guides/views.rst:124
msgid "Don't try to generate the URLs yourself"
msgstr ""

#: ../../guides/views.rst:125
msgid "Don't store the returned URLs in a database"
msgstr ""

#: ../../guides/views.rst:127
msgid "On the page you want to load the css, call:"
msgstr ""

#: ../../guides/views.rst:137
msgid "Views and third-party assets"
msgstr ""

#: ../../guides/views.rst:139
msgid "The best way to serve third-party assets is through views. However, instead of manually copy/pasting the assets into the right location in ``/views/*``, you can map the assets into the views system via the ``\"views\"`` key in your plugin's ``elgg-plugin.php`` config file."
msgstr ""

#: ../../guides/views.rst:143
msgid "The views value must be a 2 dimensional array. The first level maps a viewtype to a list of view mappings. The secondary lists map view names to file paths, either absolute or relative to the Elgg root directory."
msgstr ""

#: ../../guides/views.rst:146
msgid "If you check your assets into source control, point to them like this:"
msgstr ""

#: ../../guides/views.rst:162
msgid "To point to assets installed with composer, use install-root-relative paths by leaving off the leading slash:"
msgstr ""

#: ../../guides/views.rst:176
msgid "Elgg core uses this feature extensively, though the value is returned directly from ``/engine/views.php``."
msgstr ""

#: ../../guides/views.rst:180
msgid "You don't have to use NPM, Composer Asset Plugin or any other script for managing your plugin's assets, but we highly recommend using a package manager of some kind because it makes upgrading so much easier."
msgstr ""

#: ../../guides/views.rst:185
msgid "Specifying additional views directories"
msgstr ""

#: ../../guides/views.rst:187
msgid "In ``elgg-plugin.php`` you can also specify directories to be scanned for views. Just provide a view name prefix ending with ``/`` and a directory path (like above)."
msgstr ""

#: ../../guides/views.rst:201
msgid "With the above, files found within the ``icons`` folder will be interpreted as views. E.g. the view ``file/icon/general.gif`` will be created and mapped to ``mod/file/graphics/icons/general.gif``."
msgstr ""

#: ../../guides/views.rst:206
msgid "This is a fully recursive scan. All files found will be brought into the views system."
msgstr ""

#: ../../guides/views.rst:208
msgid "Multiple paths can share the same prefix, just give an array of paths:"
msgstr ""

#: ../../guides/views.rst:225
msgid "Viewtypes"
msgstr ""

#: ../../guides/views.rst:227
msgid "You might be wondering: \"Why ``/views/default/hello/world.php`` instead of just ``/views/hello/world.php``?\"."
msgstr ""

#: ../../guides/views.rst:229
msgid "The subdirectory under ``/views`` determines the *viewtype* of the views below it. A viewtype generally corresponds to the output format of the views."
msgstr ""

#: ../../guides/views.rst:232
msgid "The default viewtype is assumed to be HTML and other static assets necessary to render a responsive web page in a desktop or mobile browser, but it could also be:"
msgstr ""

#: ../../guides/views.rst:235
msgid "RSS"
msgstr ""

#: ../../guides/views.rst:236
msgid "ATOM"
msgstr ""

#: ../../guides/views.rst:237
msgid "JSON"
msgstr ""

#: ../../guides/views.rst:238
msgid "Mobile-optimized HTML"
msgstr ""

#: ../../guides/views.rst:239
msgid "TV-optimized HTML"
msgstr ""

#: ../../guides/views.rst:240
msgid "Any number of other data formats"
msgstr ""

#: ../../guides/views.rst:242
msgid "You can force Elgg to use a particular viewtype to render the page by setting the ``view`` input variable like so: ``https://mysite.com/?view=rss``."
msgstr ""

#: ../../guides/views.rst:245
msgid "You could also write a plugin to set this automatically using the ``elgg_set_viewtype()`` function. For example, your plugin might detect that the page was accessed with an iPhone's browser string, and set the viewtype to ``iphone`` by calling:"
msgstr ""

#: ../../guides/views.rst:253
msgid "The plugin would presumably also supply a set of views optimized for those devices."
msgstr ""

#: ../../guides/views.rst:258
msgid "Altering views via plugins"
msgstr ""

#: ../../guides/views.rst:260
msgid "Without modifying Elgg's core, Elgg provides several ways to customize almost all output:"
msgstr ""

#: ../../guides/views.rst:262
msgid "You can `override a view <#overriding-views>`_, completely changing the file used to render it."
msgstr ""

#: ../../guides/views.rst:263
msgid "You can `extend a view <#extending-views>`_ by prepending or appending the output of another view to it."
msgstr ""

#: ../../guides/views.rst:264
msgid "You can `alter a view's inputs <#altering-view-input>`_ by plugin hook."
msgstr ""

#: ../../guides/views.rst:265
msgid "You can `alter a view's output <#altering-view-output>`_ by plugin hook."
msgstr ""

#: ../../guides/views.rst:268
msgid "Overriding views"
msgstr ""

#: ../../guides/views.rst:270
msgid "Views in plugin directories always override views in the core directory; however, when plugins override the views of other plugins, :ref:`later plugins take precedent <admin/plugins#plugin-order>`."
msgstr ""

#: ../../guides/views.rst:274
msgid "For example, if we wanted to customize the ``hello/world`` view to use an ``h2`` instead of an ``h1``, we could create a file at ``/mod/example/views/default/hello/world.php`` like this:"
msgstr ""

#: ../../guides/views.rst:283
msgid "When considering long-term maintenance, overriding views in the core and bundled plugins has a cost: Upgrades may bring changes in views, and if you have overridden them, you will not get those changes."
msgstr ""

#: ../../guides/views.rst:286
msgid "You may instead want to alter :ref:`the input <guides/views#altering-view-input>` or :ref:`the output <guides/views#altering-view-output>` of the view via plugin hooks."
msgstr ""

#: ../../guides/views.rst:291
msgid "Elgg caches view locations. This means that you should disable the system cache while developing with views. When you install the changes to a production environment you must flush the caches."
msgstr ""

#: ../../guides/views.rst:295
msgid "Extending views"
msgstr ""

#: ../../guides/views.rst:297
msgid "There may be other situations in which you don't want to override the whole view, you just want to prepend or append some more content to it. In Elgg this is called *extending a view*."
msgstr ""

#: ../../guides/views.rst:300
msgid "For example, instead of overriding the ``hello/world`` view, we could extend it like so:"
msgstr ""

#: ../../guides/views.rst:306
msgid "If the contents of ``/views/default/hello/greeting.php`` is:"
msgstr ""

#: ../../guides/views.rst:312
msgid "Then every time we call ``elgg_view('hello/world');``, we'll get:"
msgstr ""

#: ../../guides/views.rst:319
msgid "You can prepend views by passing a value to the 3rd parameter that is less than 500:"
msgstr ""

#: ../../guides/views.rst:329
msgid "All view extensions should be registered in your plugin's ``elgg-plugin.php``."
msgstr ""

#: ../../guides/views.rst:334
msgid "Altering view input"
msgstr ""

#: ../../guides/views.rst:336
msgid "It may be useful to alter a view's ``$vars`` array before the view is rendered."
msgstr ""

#: ../../guides/views.rst:338
msgid "Before each view rendering the ``$vars`` array is filtered by the :ref:`plugin hook <guides/hooks-list#views>` ``[\"view_vars\", $view_name]``. Each registered handler function is passed these arguments:"
msgstr ""

#: ../../guides/views.rst:342
msgid "``$hook`` - the string ``\"view_vars\"``"
msgstr ""

#: ../../guides/views.rst:343
#: ../../guides/views.rst:381
msgid "``$view_name`` - the view name being rendered (the first argument passed to ``elgg_view()``)"
msgstr ""

#: ../../guides/views.rst:344
msgid "``$returnvalue`` - the modified ``$vars`` array"
msgstr ""

#: ../../guides/views.rst:345
#: ../../guides/views.rst:383
msgid "``$params`` - an array containing:"
msgstr ""

#: ../../guides/views.rst:347
msgid "``vars`` - the original ``$vars`` array, unaltered"
msgstr ""

#: ../../guides/views.rst:348
msgid "``view`` - the view name"
msgstr ""

#: ../../guides/views.rst:349
#: ../../guides/views.rst:385
msgid "``viewtype`` - The :ref:`viewtype <guides/views#viewtypes>` being rendered"
msgstr ""

#: ../../guides/views.rst:352
msgid "Altering view input example"
msgstr ""

#: ../../guides/views.rst:354
msgid "Here we'll alter the default pagination limit for the comments view:"
msgstr ""

#: ../../guides/views.rst:372
msgid "Altering view output"
msgstr ""

#: ../../guides/views.rst:374
msgid "Sometimes it is preferable to alter the output of a view instead of overriding it."
msgstr ""

#: ../../guides/views.rst:376
msgid "The output of each view is run through the :ref:`plugin hook <guides/hooks-list#views>` ``[\"view\", $view_name]`` before being returned by ``elgg_view()``. Each registered handler function is passed these arguments:"
msgstr ""

#: ../../guides/views.rst:380
msgid "``$hook`` - the string ``\"view\"``"
msgstr ""

#: ../../guides/views.rst:382
msgid "``$result`` - the modified output of the view"
msgstr ""

#: ../../guides/views.rst:387
msgid "To alter the view output, the handler just needs to alter ``$returnvalue`` and return a new string."
msgstr ""

#: ../../guides/views.rst:390
msgid "Altering view output example"
msgstr ""

#: ../../guides/views.rst:392
msgid "Here we'll eliminate breadcrumbs that don't have at least one link."
msgstr ""

#: ../../guides/views.rst:413
msgid "Replacing view output completely"
msgstr ""

#: ../../guides/views.rst:415
msgid "You can pre-set the view output by setting ``$vars['__view_output']``. The value will be returned as a string. View extensions will not be used and the ``view`` hook will not be triggered."
msgstr ""

#: ../../guides/views.rst:430
msgid "For ease of use you can also use a already existing default hook callback to prevent output ``\\Elgg\\Values::preventViewOutput``"
msgstr ""

#: ../../guides/views.rst:435
msgid "If you don't know what an entity is, :doc:`check this page out first </design/database>`."
msgstr ""

#: ../../guides/views.rst:437
msgid "The following code will automatically display the entity in ``$entity``:"
msgstr ""

#: ../../guides/views.rst:443
msgid "As you'll know from the data model introduction, all entities have a *type* (object, site, user or group), and optionally a subtype (which could be anything - 'blog', 'forumpost', 'banana')."
msgstr ""

#: ../../guides/views.rst:447
msgid "``elgg_view_entity`` will automatically look for a view called ``type/subtype``; if there's no subtype, it will look for ``type/type``. Failing that, before it gives up completely it tries ``type/default``."
msgstr ""

#: ../../guides/views.rst:451
msgid "RSS feeds in Elgg generally work by outputting the ``object/default`` view in the 'rss' viewtype."
msgstr ""

#: ../../guides/views.rst:453
msgid "For example, the view to display a blog post might be ``object/blog``. The view to display a user is ``user/default``."
msgstr ""

#: ../../guides/views.rst:457
msgid "Full and partial entity views"
msgstr ""

#: ../../guides/views.rst:459
msgid "``elgg_view_entity`` actually has a number of parameters, although only the very first one is required. The first three are:"
msgstr ""

#: ../../guides/views.rst:462
msgid "``$entity`` - The entity to display"
msgstr ""

#: ../../guides/views.rst:463
msgid "``$viewtype`` - The viewtype to display in (defaults to the one we're currently in, but it can be forced - eg to display a snippet of RSS within an HTML page)"
msgstr ""

#: ../../guides/views.rst:465
msgid "``$full_view`` - Whether to display a *full* version of the entity. (Defaults to ``true``.)"
msgstr ""

#: ../../guides/views.rst:467
msgid "This last parameter is passed to the view as ``$vars['full_view']``. It's up to you what you do with it; the usual behaviour is to only display comments and similar information if this is set to true."
msgstr ""

#: ../../guides/views.rst:474
msgid "Listing entities"
msgstr ""

#: ../../guides/views.rst:476
msgid "This is then used in the provided listing functions. To automatically display a list of blog posts (:doc:`see the full tutorial </tutorials/blog>`), you can call:"
msgstr ""

#: ../../guides/views.rst:486
msgid "This function checks to see if there are any entities; if there are, it first displays the ``navigation/pagination`` view in order to display a way to move from page to page. It then repeatedly calls ``elgg_view_entity`` on each entity before returning the result."
msgstr ""

#: ../../guides/views.rst:491
msgid "Note that ``elgg_list_entities`` allows the URL to set its ``limit`` and ``offset`` options, so set those explicitly if you need particular values (e.g. if you're not using it for pagination)."
msgstr ""

#: ../../guides/views.rst:494
msgid "Elgg knows that it can automatically supply an RSS feed on pages that use ``elgg_list_entities``. It initializes the ``[\"head\",\"page\"]`` plugin hook (which is used by the header) in order to provide RSS autodiscovery, which is why you can see the orange RSS icon on those pages in some browsers."
msgstr ""

#: ../../guides/views.rst:499
msgid "Entity listings will default try to load entity owners and container owners. If you want to prevent this you can turn this off."
msgstr ""

#: ../../guides/views.rst:511
msgid "See also :doc:`this background information on Elgg's database </design/database>`."
msgstr ""

#: ../../guides/views.rst:513
msgid "If you want to show a message when the list does not contain items to list, you can pass a ``no_results`` message or ``true`` for the default message. If you want even more controle over the ``no_results`` message you can also pass a Closure (an anonymous function)."
msgstr ""

#: ../../guides/views.rst:527
msgid "Rendering a list with an alternate view"
msgstr ""

#: ../../guides/views.rst:529
msgid "You can define an alternative view to render list items using ``'item_view'`` parameter."
msgstr ""

#: ../../guides/views.rst:531
msgid "In some cases, default entity views may be unsuitable for your needs. Using ``item_view`` allows you to customize the look, while preserving pagination, list's HTML markup etc."
msgstr ""

#: ../../guides/views.rst:534
msgid "Consider these two examples:"
msgstr ""

#: ../../guides/views.rst:556
msgid "In the first example, we are displaying a list of groups a user is a member of using the default group view. In the second example, we want to display a list of groups the user was invited to."
msgstr ""

#: ../../guides/views.rst:559
msgid "Since invitations are not entities, they do not have their own views and can not be listed using ``elgg_list_*``. We are providing an alternative item view, that will use the group entity to display an invitation that contains a group name and buttons to access or reject the invitation."
msgstr ""

#: ../../guides/views.rst:564
msgid "Rendering a list as a table"
msgstr ""

#: ../../guides/views.rst:566
msgid "Since 2.3 you can render lists as tables. Set ``$options['list_type'] = 'table'`` and provide an array of TableColumn objects as ``$options['columns']``. The service ``elgg()->table_columns`` provides several methods to create column objects based around existing views (like ``page/components/column/*``), properties, or methods."
msgstr ""

#: ../../guides/views.rst:571
msgid "In this example, we list the latest ``my_plugin`` objects in a table of 3 columns: entity icon, the display name, and a friendly format of the time."
msgstr ""

#: ../../guides/views.rst:590
msgid "See the ``Elgg\\Views\\TableColumn\\ColumnFactory`` class for more details on how columns are specified and rendered. You can add or override methods of ``elgg()->table_columns`` in a variety of ways, based on views, properties/methods on the items, or given functions."
msgstr ""

#: ../../guides/views.rst:597
msgid "Elgg has support for two kind of icons: generic icons to help with styling (eg. show delete icon) and Entity icons (eg. user avatar)."
msgstr ""

#: ../../guides/views.rst:600
msgid "Generic icons"
msgstr ""

#: ../../guides/views.rst:602
msgid "As of Elgg 2.0 the generic icons are based on the FontAwesome_ library. You can get any of the supported icons by calling ``elgg_view_icon($icon_name, $vars);`` where:"
msgstr ""

#: ../../guides/views.rst:605
msgid "``$icon_name`` is the FontAwesome name (without ``fa-``) for example ``user``"
msgstr ""

#: ../../guides/views.rst:606
msgid "``$vars`` is optional, for example you can set an additional class"
msgstr ""

#: ../../guides/views.rst:608
msgid "``elgg_view_icon()`` calls the view ``output/icon`` with the given icon name and outputs all the correct classes to render the FontAwesome icon. If you wish to replace an icon with another icon you can write a ``view_vars``, ``output/icon`` hook to replace the icon name with your replacement."
msgstr ""

#: ../../guides/views.rst:611
msgid "For backwards compatibility some older Elgg icon names are translated to a corresponding FontAwesome icon."
msgstr ""

#: ../../guides/views.rst:614
msgid "Entity icons"
msgstr ""

#: ../../guides/views.rst:616
msgid "To view an icon belowing to an Entity call ``elgg_view_entity_icon($entity, $size, $vars);`` where:"
msgstr ""

#: ../../guides/views.rst:618
msgid "``$entity`` is the ``ElggEntity`` you wish to show the icon for"
msgstr ""

#: ../../guides/views.rst:619
msgid "``$size`` is the requestes size. Default Elgg supports ``large``, ``medium``, ``small``, ``tiny`` and ``topbar`` (``master`` is also available, but don't use it)"
msgstr ""

#: ../../guides/views.rst:621
msgid "``$vars`` in order to pass additional information to the icon view"
msgstr ""

#: ../../guides/views.rst:623
msgid "``elgg_view_entity_icon()`` calls a view in the order:"
msgstr ""

#: ../../guides/views.rst:625
msgid "``icon/<type>/<subtype>``"
msgstr ""

#: ../../guides/views.rst:626
msgid "``icon/<type>/default``"
msgstr ""

#: ../../guides/views.rst:627
msgid "``icon/default``"
msgstr ""

#: ../../guides/views.rst:629
msgid "So if you wish to customize the layout of the icon you can overrule the corresponding view."
msgstr ""

#: ../../guides/views.rst:631
msgid "An example of displaying a user avatar is"
msgstr ""

#: ../../guides/views/foot-vs-footer.rst:2
msgid "Page/elements/foot vs footer"
msgstr ""

#: ../../guides/views/foot-vs-footer.rst:4
msgid "``page/elements/footer`` is the content that goes inside this part of the page:"
msgstr ""

#: ../../guides/views/foot-vs-footer.rst:14
msgid "It's content is visible to end users and usually where you would put a sitemap or other secondary global navigation, copyright info, powered by elgg, etc."
msgstr ""

#: ../../guides/views/foot-vs-footer.rst:16
msgid "``page/elements/foot`` is inserted just before the ending ``</body>`` tag and is mostly meant as a place to insert scripts that don't already work with ``elgg_require_js('amd/module');``. In other words, you should never override this view and probably don't need to extend it either. Just use the ``elgg_*_js`` functions instead"
msgstr ""

#: ../../guides/views/page-structure.rst:2
msgid "Page structure best practice"
msgstr ""

#: ../../guides/views/page-structure.rst:4
msgid "Elgg pages have an overall pageshell, a main layout and several page elements. It's recommended to always use the ``default`` layout as all page elements can be controlled using that layout."
msgstr ""

#: ../../guides/views/page-structure.rst:7
msgid "If you're not using the ``default`` layout you can call"
msgstr ""

#: ../../guides/views/page-structure.rst:16
msgid "The different page elements are passed as an ``array`` in the second parameter. The array keys correspond to elements in the layout. The array values contain the html that should be displayed in those areas:"
msgstr ""

#: ../../guides/views/page-structure.rst:32
msgid "You can then, ultimately, pass this into the ``elgg_view_page`` function:"
msgstr ""

#: ../../guides/views/page-structure.rst:38
msgid "If you're using the ``default`` layout you can also pass the array with page elements directly to ``elgg_view_page``:"
msgstr ""

#: ../../guides/views/page-structure.rst:47
msgid "You can control many of the page elements:"
msgstr ""

#: ../../guides/views/page-structure.rst:60
msgid "Have a look at the ``page/layouts/default`` view to find out more information about the supported page elements"
msgstr ""

#: ../../guides/views/simplecache.rst:2
msgid "Simplecache"
msgstr ""

#: ../../guides/views/simplecache.rst:6
msgid ":doc:`/admin/performance`"
msgstr ""

#: ../../guides/views/simplecache.rst:7
msgid ":doc:`/guides/views`"
msgstr ""

#: ../../guides/views/simplecache.rst:9
msgid "The Simplecache is a mechanism designed to alleviate the need for certain views to be regenerated dynamically. Instead, they are generated once, saved as a static file, and served in a way that entirely bypasses the Elgg engine."
msgstr ""

#: ../../guides/views/simplecache.rst:12
msgid "If Simplecache is turned off (which can be done from the administration panel), these views will be served as normal, with the exception of site CSS."
msgstr ""

#: ../../guides/views/simplecache.rst:15
msgid "The criteria for whether a view is suitable for the Simplecache is as follows:"
msgstr ""

#: ../../guides/views/simplecache.rst:17
msgid "The view must not change depending on who or when it is being looked at"
msgstr ""

#: ../../guides/views/simplecache.rst:18
msgid "The view must not depend on variables fed to it (except for global variables like site URL that never change)"
msgstr ""

#: ../../guides/views/simplecache.rst:21
msgid "Regenerating the Simplecache"
msgstr ""

#: ../../guides/views/simplecache.rst:23
msgid "You can regenerate the Simplecache at any time by:"
msgstr ""

#: ../../guides/views/simplecache.rst:25
msgid "Loading ``/upgrade.php``, even if you have nothing to upgrade"
msgstr ""

#: ../../guides/views/simplecache.rst:26
msgid "In the admin panel click on 'Flush the caches'"
msgstr ""

#: ../../guides/views/simplecache.rst:27
msgid "Enabling or disabling a plugin"
msgstr ""

#: ../../guides/views/simplecache.rst:28
msgid "Reordering your plugins"
msgstr ""

#: ../../guides/views/simplecache.rst:31
msgid "Using the Simplecache in your plugins"
msgstr ""

#: ../../guides/views/simplecache.rst:33
msgid "**Registering views with the Simplecache**"
msgstr ""

#: ../../guides/views/simplecache.rst:35
msgid "You can register a view with the Simplecache with the following function at init-time:"
msgstr ""

#: ../../guides/views/simplecache.rst:41
msgid "**Accessing the cached view**"
msgstr ""

#: ../../guides/views/simplecache.rst:43
msgid "If you registered a JavaScript or CSS file with Simplecache and put in the view folder as ``your_view.js`` or ``your_view.css`` you can very easily get the url to this cached view by calling ``elgg_get_simplecache_url($view)``. For example:"
msgstr ""

#: ../../guides/walled-garden.rst:2
msgid "Walled Garden"
msgstr ""

#: ../../guides/walled-garden.rst:4
msgid "Elgg supports a \"Walled Garden\" mode. In this mode, almost all pages are restricted to logged in users. This is useful for sites that don't allow public registration."
msgstr ""

#: ../../guides/walled-garden.rst:7
msgid "Activating Walled Garden mode"
msgstr ""

#: ../../guides/walled-garden.rst:9
msgid "To activate Walled Garden mode in Elgg, go to the Administration section. On the right sidebar menu, under the \"Configure\" section, expand \"Settings,\" then click on \"Advanced.\""
msgstr ""

#: ../../guides/walled-garden.rst:11
msgid "From the Advanced Settings page, find the option labelled \"Restrict pages to logged-in users.\" Enable this option, then click \"Save\" to switch your site into Walled Garden mode."
msgstr ""

#: ../../guides/walled-garden.rst:16
msgid "Exposing pages through Walled Gardens"
msgstr ""

#: ../../guides/walled-garden.rst:18
msgid "Many plugins extend Elgg by adding pages. Walled Garden mode will prevent these pages from being viewed by logged out users. Elgg uses :ref:`plugin hook <design/events#plugin-hooks>` to manage which pages are visible through the Walled Garden."
msgstr ""

#: ../../guides/walled-garden.rst:21
msgid "Plugin authors must register pages as public if they should be viewable through Walled Gardens:"
msgstr ""

#: ../../guides/walled-garden.rst:23
msgid "by setting ``'walled' => false`` in route configuration"
msgstr ""

#: ../../guides/walled-garden.rst:24
msgid "by responding to the ``public_pages``, ``walled_garden`` plugin hook. The returned value is an array of regexp expressions for public pages."
msgstr ""

#: ../../guides/walled-garden.rst:26
msgid "The following code shows how to expose http://example.org/my_plugin/public_page through a Walled Garden. This assumes the plugin has registered a :doc:`route </guides/routing>` for ``my_plugin/public_page``."
msgstr ""

#: ../../guides/web-services.rst:2
msgid "Web services"
msgstr ""

#: ../../guides/web-services.rst:4
msgid "Build an HTTP API for your site."
msgstr ""

#: ../../guides/web-services.rst:6
msgid "Elgg provides a powerful framework for building web services. This allows developers to expose functionality to other web sites and desktop applications along with doing integrations with third-party web applications. While we call the API RESTful, it is actually a REST/RPC hybrid similar to the APIs provided by sites like Flickr and Twitter."
msgstr ""

#: ../../guides/web-services.rst:12
msgid "To create an API for your Elgg site, you need to do 4 things:"
msgstr ""

#: ../../guides/web-services.rst:14
msgid "enable the web services plugin"
msgstr ""

#: ../../guides/web-services.rst:15
msgid "expose methods"
msgstr ""

#: ../../guides/web-services.rst:16
msgid "setup API authentication"
msgstr ""

#: ../../guides/web-services.rst:17
msgid "setup user authentication"
msgstr ""

#: ../../guides/web-services.rst:19
msgid "Additionally, you may want to control what types of authentication are available on your site. This will also be covered."
msgstr ""

#: ../../guides/web-services.rst:29
msgid "It is crucial that the web services are consumed via secure protocols. Do not enable web services if your site is not served via HTTPs. This is especially important if you allow API key only authentication."
msgstr ""

#: ../../guides/web-services.rst:33
msgid "If you are using third-party tools that expose API methods, make sure to carry out a thorough security audit. You may want to make sure that API authentication is required for ALL methods, even if they require user authentication. Methods that do not require API authentication can be easily abused to spam your site."
msgstr ""

#: ../../guides/web-services.rst:38
msgid "Ensure that the validity of API keys is limited and provide mechanisms for your API clients to renew their keys."
msgstr ""

#: ../../guides/web-services.rst:42
msgid "Exposing methods"
msgstr ""

#: ../../guides/web-services.rst:44
msgid "The function to use to expose a method is ``elgg_ws_expose_function()``. As an example, let's assume you want to expose a function that echos text back to the calling application. The function could look like this"
msgstr ""

#: ../../guides/web-services.rst:54
msgid "Since we are providing this function to allow developers to test their API clients, we will require neither API authentication nor user authentication. This call registers the function with the web services API framework:"
msgstr ""

#: ../../guides/web-services.rst:75
msgid "If you add this code to a plugin and then go to http://yoursite.com/services/api/rest/json/?method=system.api.list, you should now see your test.echo method listed as an API call. Further, to test the exposed method from a web browser, you could hit the url: http://yoursite.com/services/api/rest/json/?method=test.echo&string=testing and you should see JSON data like this:"
msgstr ""

#: ../../guides/web-services.rst:89
msgid "Plugins can filter the output of individual API methods by registering a handler for ``'rest:output',$method`` plugin hook."
msgstr ""

#: ../../guides/web-services.rst:93
msgid "Response formats"
msgstr ""

#: ../../guides/web-services.rst:95
msgid "JSON is the default format, however XML and serialized PHP can be fetched by enabling the ``data_views`` plugin and substituting ``xml`` or ``php`` in place of ``json`` in the above URLs."
msgstr ""

#: ../../guides/web-services.rst:98
msgid "You can also add additional response formats by defining new viewtypes."
msgstr ""

#: ../../guides/web-services.rst:101
msgid "Parameters"
msgstr ""

#: ../../guides/web-services.rst:103
msgid "Parameters expected by each method should be listed as an associative array, where the key represents the parameter name, and the value contains an array with ``type``, ``default`` and ``required`` fields."
msgstr ""

#: ../../guides/web-services.rst:106
msgid "Values submitted with the API request for each parameter should match the declared type. API will throw on exception if validation fails."
msgstr ""

#: ../../guides/web-services.rst:108
msgid "Recognized parameter types are:"
msgstr ""

#: ../../guides/web-services.rst:110
msgid "``integer`` (or ``int``)"
msgstr ""

#: ../../guides/web-services.rst:111
msgid "``boolean`` (or ``bool``) ``'false'``, ``0`` and ``'0'`` will evaluate to ``false`` the rest will evaluate to ``true``"
msgstr ""

#: ../../guides/web-services.rst:112
msgid "``string``"
msgstr ""

#: ../../guides/web-services.rst:113
msgid "``float``"
msgstr ""

#: ../../guides/web-services.rst:114
msgid "``array``"
msgstr ""

#: ../../guides/web-services.rst:116
msgid "Unrecognized types will throw an API exception."
msgstr ""

#: ../../guides/web-services.rst:118
msgid "You can use additional fields to describe your parameter, e.g. ``description``."
msgstr ""

#: ../../guides/web-services.rst:146
msgid "If a missing parameter has no default value, the argument will be ``null``. Before Elgg v2.1, a bug caused later arguments to be shifted left in this case."
msgstr ""

#: ../../guides/web-services.rst:150
msgid "Receive parameters as associative array"
msgstr ""

#: ../../guides/web-services.rst:152
msgid "If you have a large number of method parameters, you can force the execution script to invoke the callback function with a single argument that contains an associative array of parameter => input pairs (instead of each parameter being a separate argument). To do that, set ``$assoc`` to ``true`` in ``elgg_ws_expose_function()``."
msgstr ""

#: ../../guides/web-services.rst:185
msgid "If a missing parameter has no default value, ``null`` will be used."
msgstr ""

#: ../../guides/web-services.rst:188
msgid "API authentication"
msgstr ""

#: ../../guides/web-services.rst:190
msgid "You may want to control access to some of the functions that you expose. Perhaps you are exposing functions in order to integrate Elgg with another open source platform on the same server. In that case, you only want to allow that other application access to these methods. Another possibility is that you want to limit what external developers have access to your API. Or maybe you want to limit how many calls a developer can make against your API in a single day."
msgstr ""

#: ../../guides/web-services.rst:198
msgid "In all of these cases, you can use Elgg's API authentication functions to control access. Elgg provides two built-in methods to perform API authentication: key based and HMAC signature based. You can also add your own authentication methods. The key based approach is very similar to what Google, Flickr, or Twitter. Developers can request a key (a random string) and pass that key with all calls that require API authentication. The keys are stored in the database and if an API call is made without a key or a bad key, the call is denied and an error message is returned."
msgstr ""

#: ../../guides/web-services.rst:209
msgid "Key-based authentication"
msgstr ""

#: ../../guides/web-services.rst:211
msgid "As an example, let's write a function that returns the number of users that have viewed the site in the last x minutes."
msgstr ""

#: ../../guides/web-services.rst:222
msgid "Now, let's expose it and make the number of minutes an optional parameter:"
msgstr ""

#: ../../guides/web-services.rst:242
msgid "This function is now available and if you check ``system.api.list``, you will see that it requires API authentication. If you hit the method with a web browser, it will return an error message about failing the API authentication. To test this method, you need an API key. As of Elgg 3.2 API keys can be generated by the webservices plugin. It will return a public and private key and you will use the public key for this kind of API authentication. Grab a key and then do a GET request with your browser on this API method passing in the key string as the parameter ``api_key``. It might look something like this: http://yoursite.com/services/api/rest/xml/?method=users.active&api_key=1140321cb56c71710c38feefdf72bc462938f59f."
msgstr ""

#: ../../guides/web-services.rst:254
msgid "Signature-based authentication"
msgstr ""

#: ../../guides/web-services.rst:256
msgid "The :doc:`web-services/hmac` is similar to what is used with OAuth or Amazon's S3 service. This involves both the public and private key. If you want to be very sure that the API calls are coming from the developer you think they are coming from and you want to make sure the data is not being tampered with during transmission, you would use this authentication method. Be aware that it is much more involved and could turn off developers when there are other sites out there with key-based authentication."
msgstr ""

#: ../../guides/web-services.rst:266
msgid "User authentication"
msgstr ""

#: ../../guides/web-services.rst:268
msgid "So far you have been allowing developers to pull data out of your Elgg site. Now we'll move on to pushing data into Elgg. In this case, it is going to be done by a user. Maybe you have created a desktop application that allows your Users to post to the wire without going to the site. You need to expose a method for posting to the wire and you need to make sure that a user cannot post using someone else's account. Elgg provides a token-based approach for user authentication. It allows a user to submit their username and password in exchange for a token using the method ``auth.gettoken``. This token can then be used for some amount of time to authenticate all calls to the API before it expires by passing it as the parameter ``auth_token``. If you do not want to have your users trusting their passwords to 3rd-party applications, you can also extend the current capability to use an approach like OAuth."
msgstr ""

#: ../../guides/web-services.rst:282
msgid "Let's write our wire posting function:"
msgstr ""

#: ../../guides/web-services.rst:296
msgid "Exposing this function is the same as the previous except we require user authentication and we're going to make this use POST rather than GET HTTP requests."
msgstr ""

#: ../../guides/web-services.rst:316
msgid "Please note that you will not be able to test this using a web browser as you did with the other methods. You need to write some client code to do this."
msgstr ""

#: ../../guides/web-services.rst:321
msgid "Building out your API"
msgstr ""

#: ../../guides/web-services.rst:323
msgid "As soon as you feel comfortable with Elgg's web services API framework, you will want to step back and design your API. What sort of data are you trying to expose? Who or what will be API users? How do you want them to get access to authentication keys? How are you going to document your API? Be sure to take a look at the APIs created by popular Web 2.0 sites for inspiration. If you are looking for 3rd party developers to build applications using your API, you will probably want to provide one or more language-specific clients."
msgstr ""

#: ../../guides/web-services.rst:333
msgid "Determining the authentication available"
msgstr ""

#: ../../guides/web-services.rst:335
msgid "Elgg's web services API uses a type of `pluggable authentication module (PAM)`_ architecture to manage how users and developers are authenticated. This provides you the flexibility to add and remove authentication modules. Do you want to not use the default user authentication PAM but would prefer using OAuth? You can do this."
msgstr ""

#: ../../guides/web-services.rst:341
msgid "The first step is registering a callback function for the *rest, init* plugin hook:"
msgstr ""

#: ../../guides/web-services.rst:348
msgid "Then in the callback function, you register the PAMs that you want to use:"
msgstr ""

#: ../../guides/web-services/hmac.rst:2
msgid "HMAC Authentication"
msgstr ""

#: ../../guides/web-services/hmac.rst:4
msgid "Elgg's RESTful API framework provides functions to support a `HMAC`_ signature scheme for API authentication. The client must send the HMAC signature together with a set of special HTTP headers when making a call that requires API authentication. This ensures that the API call is being made from the stated client and that the data has not been tampered with."
msgstr ""

#: ../../guides/web-services/hmac.rst:10
msgid "The HMAC must be constructed over the following data:"
msgstr ""

#: ../../guides/web-services/hmac.rst:12
msgid "The public API key identifying you to the Elgg api server as provided by the APIAdmin plugin"
msgstr ""

#: ../../guides/web-services/hmac.rst:13
msgid "The private API Key provided by Elgg (that is companion to the public key)"
msgstr ""

#: ../../guides/web-services/hmac.rst:14
msgid "The current unix time in seconds"
msgstr ""

#: ../../guides/web-services/hmac.rst:15
msgid "A nonce to guarantee two requests the same second have different signatures"
msgstr ""

#: ../../guides/web-services/hmac.rst:16
msgid "URL encoded string representation of any GET variable parameters, eg ``method=test.test&foo=bar``"
msgstr ""

#: ../../guides/web-services/hmac.rst:17
msgid "If you are sending post data, the hash of this data"
msgstr ""

#: ../../guides/web-services/hmac.rst:19
msgid "Some extra information must be added to the HTTP header in order for this data to be correctly processed:"
msgstr ""

#: ../../guides/web-services/hmac.rst:21
msgid "**X-Elgg-apikey** - The public API key"
msgstr ""

#: ../../guides/web-services/hmac.rst:22
msgid "**X-Elgg-time** - Unix time used in the HMAC calculation"
msgstr ""

#: ../../guides/web-services/hmac.rst:23
msgid "**X-Elgg-nonce** - a random string"
msgstr ""

#: ../../guides/web-services/hmac.rst:24
msgid "**X-Elgg-hmac** - The HMAC as base64 encoded"
msgstr ""

#: ../../guides/web-services/hmac.rst:25
msgid "**X-Elgg-hmac-algo** - The algorithm used in the HMAC calculation"
msgstr ""

#: ../../guides/web-services/hmac.rst:27
msgid "If you are sending POST data you must also send:"
msgstr ""

#: ../../guides/web-services/hmac.rst:29
msgid "**X-Elgg-posthash** - The hash of the POST data"
msgstr ""

#: ../../guides/web-services/hmac.rst:30
msgid "**X-Elgg-posthash-algo** - The algorithm used to produce the POST data hash"
msgstr ""

#: ../../guides/web-services/hmac.rst:31
msgid "**Content-type** - The content type of the data you are sending (if in doubt use ``application/octet-stream``)"
msgstr ""

#: ../../guides/web-services/hmac.rst:32
msgid "**Content-Length** - The length in bytes of your POST data"
msgstr ""

#: ../../guides/web-services/hmac.rst:34
msgid "Elgg provides a sample API client that implements this HMAC signature: ``\\Elgg\\WebServices\\ElggApiClient``. It serves as a good reference on how to implement it."
msgstr ""

#: ../../guides/web-services/hmac.rst:38
msgid "Supported hashing algorithms"
msgstr ""

#: ../../guides/web-services/hmac.rst:40
msgid "``sha256``: recommended"
msgstr ""

#: ../../guides/web-services/hmac.rst:41
msgid "``sha1``: fast however less secure"
msgstr ""

#: ../../guides/web-services/hmac.rst:42
msgid "``md5``: weak and will be removed in the future"
msgstr ""

#: ../../guides/web-services/hmac.rst:45
msgid "Post hash calculation"
msgstr ""

#: ../../guides/web-services/hmac.rst:47
msgid "The post hash needs to be calculated over all the post data using one of the supported hashing algorithms. The result of the hashing needs to be reported in the ``X-Elgg-posthash`` header and the used hashing algorithm must be reported in the ``X-Elgg-posthash-algo`` header."
msgstr ""

#: ../../guides/web-services/hmac.rst:52
msgid "HMAC hash calculation"
msgstr ""

#: ../../guides/web-services/hmac.rst:54
msgid "The overall HMAC needs to be calculated over the following data (in order) using the API secret as the HMAC secret and with one of the supported hashing algorithms:"
msgstr ""

#: ../../guides/web-services/hmac.rst:57
msgid "a UNIX timestamp, report this timestamp in the ``X-Elgg-time`` header"
msgstr ""

#: ../../guides/web-services/hmac.rst:58
msgid "a random string, report this string in the ``X-Elgg-nonce`` header"
msgstr ""

#: ../../guides/web-services/hmac.rst:59
msgid "the public API key, report this API key in the ``X-Elgg-apikey`` header"
msgstr ""

#: ../../guides/web-services/hmac.rst:60
msgid "the url query string (for example ``method=test.test&foo=bar``)"
msgstr ""

#: ../../guides/web-services/hmac.rst:61
msgid "when the request is a POST add the ``posthash`` as reported in the ``X-Elgg-posthash`` header"
msgstr ""

#: ../../guides/web-services/hmac.rst:63
msgid "The resulting string needs to be base64 encoded and then url encoded and be repoted in the ``X-Elgg-hmac`` header. The used hashing algorithm needs to be reported in the ``X-Elgg-hmac-algo``."
msgstr ""

#: ../../guides/web-services/hmac.rst:67
msgid "Hashing cache"
msgstr ""

#: ../../guides/web-services/hmac.rst:69
msgid "For security reasons each HMAC hash needs to be unique, all submitted hashes are stored for 25 hours to prevent reuse."
msgstr ""

#: ../../guides/web-services/result.rst:2
msgid "API results"
msgstr ""

#: ../../guides/web-services/result.rst:9
msgid "Success result structure"
msgstr ""

#: ../../guides/web-services/result.rst:11
msgid "A successful API result looks like this:"
msgstr ""

#: ../../guides/web-services/result.rst:20
msgid "Depending on the API call ``result`` can contain any type of content (string, number, array, object, etc.)."
msgstr ""

#: ../../guides/web-services/result.rst:22
msgid "An example of a numberic result (for example a user count):"
msgstr ""

#: ../../guides/web-services/result.rst:31
msgid "An example of an object result (for example a user):"
msgstr ""

#: ../../guides/web-services/result.rst:45
msgid "Error result structure"
msgstr ""

#: ../../guides/web-services/result.rst:47
msgid "When an API call fails the result will look like this:"
msgstr ""

#: ../../guides/web-services/result.rst:58
msgid "Default status codes"
msgstr ""

#: ../../guides/web-services/result.rst:60
msgid "The ``status`` field always contains a number representing the result. Any value other than ``0`` is considered an error."
msgstr ""

#: ../../guides/web-services/result.rst:62
msgid "``0``: This is a success result"
msgstr ""

#: ../../guides/web-services/result.rst:63
msgid "``-1``: This is a generic error result"
msgstr ""

#: ../../guides/web-services/result.rst:64
msgid "``-20``: The user authentication token is missing, is invalid or has expired"
msgstr ""

#: ../../guides/web-services/result.rst:65
msgid "``-30``: The api key has been disabled"
msgstr ""

#: ../../guides/web-services/result.rst:66
msgid "``-31``: The api key is inactive"
msgstr ""

#: ../../guides/web-services/result.rst:67
msgid "``-32``: The api key is invalid"
msgstr ""

#: ../../guides/web-services/result.rst:69
msgid "Developers can implement their own status codes to represent different error states, so the request doesn't have to rely on the error message to know what went wrong."
msgstr ""

#: ../../guides/web-services/result.rst:74
msgid "``result`` and ``message`` can contain messages in different languages. This is depending on the user language when using user authenticated API calls or the site langauge for other API calls. Keep in mind that the language can change, eighter by the user or by a site administrator for the site language."
msgstr ""

#: ../../guides/widgets.rst:2
msgid "Widgets"
msgstr ""

#: ../../guides/widgets.rst:4
msgid "Widgets are content areas that users can drag around their page to customize the layout. They can typically be customized by their owner to show more/less content and determine who sees the widget. By default Elgg provides plugins for customizing the profile page and dashboard via widgets."
msgstr ""

#: ../../guides/widgets.rst:11
msgid "Structure"
msgstr ""

#: ../../guides/widgets.rst:13
msgid "To create a widget, create two views:"
msgstr ""

#: ../../guides/widgets.rst:15
msgid "``widgets/widget/edit``"
msgstr ""

#: ../../guides/widgets.rst:16
msgid "``widgets/widget/content``"
msgstr ""

#: ../../guides/widgets.rst:18
msgid "``content.php`` is responsible for all the content that will output within the widget. The ``edit.php`` file contains any extra edit functions you wish to present to the user. You do not need to add access level as this comes as part of the widget framework."
msgstr ""

#: ../../guides/widgets.rst:22
msgid "Using HTML checkboxes to set widget flags is problematic because if unchecked, the checkbox input is omitted from form submission. The effect is that you can only set and not clear flags. The \"input/checkboxes\" view will not work properly in a widget's edit panel."
msgstr ""

#: ../../guides/widgets.rst:28
msgid "Register the widget"
msgstr ""

#: ../../guides/widgets.rst:30
msgid "Once you have created your edit and view pages, you need to initialize the plugin widget."
msgstr ""

#: ../../guides/widgets.rst:32
msgid "The easiest way to do this is to add the ``widgets`` section to your ``elgg-plugin.php`` config file."
msgstr ""

#: ../../guides/widgets.rst:44
msgid "Alternatively you can also use an function to add a widget. This is done within the plugins ``init()`` function."
msgstr ""

#: ../../guides/widgets.rst:58
msgid "The only required attribute is the ``id``."
msgstr ""

#: ../../guides/widgets.rst:61
msgid "Multiple widgets"
msgstr ""

#: ../../guides/widgets.rst:63
msgid "It is possible to add multiple widgets for a plugin. You just initialize as many widget directories as you need."
msgstr ""

#: ../../guides/widgets.rst:91
msgid "Make sure you have the corresponding directories within your plugin views structure:"
msgstr ""

#: ../../guides/widgets.rst:111
msgid "Magic widget name and description"
msgstr ""

#: ../../guides/widgets.rst:112
msgid "When registering a widget you can omit providing a name and a description. If a translation in the following format is provided, they will be used. For the name: ``widgets:<widget_id>:name`` and for the description ``widgets:<widget_id>:description``. If you make sure these translation are available in a translation file, you have very little work registering the widget."
msgstr ""

#: ../../guides/widgets.rst:119
msgid "How to restrict where widgets can be used"
msgstr ""

#: ../../guides/widgets.rst:120
msgid "The widget can specify the context that it can be used in (just profile, just dashboard, etc.)."
msgstr ""

#: ../../guides/widgets.rst:130
msgid "Allow multiple widgets on the same page"
msgstr ""

#: ../../guides/widgets.rst:131
msgid "By default you can only add one widget of the same type on the page. If you want more of the same widget on the page, you can specify this when registering the widget:"
msgstr ""

#: ../../guides/widgets.rst:142
msgid "Register widgets in a hook"
msgstr ""

#: ../../guides/widgets.rst:143
msgid "If, for example, you wish to conditionally register widgets you can also use a hook to register widgets."
msgstr ""

#: ../../guides/widgets.rst:166
msgid "Modify widget properties of existing widget registration"
msgstr ""

#: ../../guides/widgets.rst:167
msgid "If, for example, you wish to change the allowed contexts of an already registered widget you can do so by re-registering the widget with ``elgg_register_widget_type`` as it will override an already existing widget definition. If you want even more control you can also use the ``handlers, widgets`` hook to change the widget definition."
msgstr ""

#: ../../guides/widgets.rst:188
msgid "Default widgets"
msgstr ""

#: ../../guides/widgets.rst:190
msgid "If your plugin uses the widget canvas, you can register default widget support with Elgg core, which will handle everything else."
msgstr ""

#: ../../guides/widgets.rst:192
msgid "To announce default widget support in your plugin, register for the ``get_list, default_widgets`` plugin hook:"
msgstr ""

#: ../../guides/widgets.rst:215
msgid "In the plugin hook handler, push an array into the return value defining your default widget support and when to create default widgets. Arrays require the following keys to be defined:"
msgstr ""

#: ../../guides/widgets.rst:217
msgid "name - The name of the widgets page. This is displayed on the tab in the admin interface."
msgstr ""

#: ../../guides/widgets.rst:218
msgid "widget\\_context - The context the widgets page is called from. (If not explicitly set, this is your plugin's id.)"
msgstr ""

#: ../../guides/widgets.rst:219
msgid "widget\\_columns - How many columns the widgets page will use."
msgstr ""

#: ../../guides/widgets.rst:220
msgid "event\\_name - The Elgg event name to create new widgets for. This is usually ``create``."
msgstr ""

#: ../../guides/widgets.rst:221
msgid "event\\_type - The Elgg event type to create new widgets for."
msgstr ""

#: ../../guides/widgets.rst:222
msgid "entity\\_type - The entity type to create new widgets for."
msgstr ""

#: ../../guides/widgets.rst:223
msgid "entity\\_subtype - The entity subtype to create new widgets for. The can be ELGG\\_ENTITIES\\_ANY\\_VALUE to create for all entity types."
msgstr ""

#: ../../guides/widgets.rst:225
msgid "To have widgets be created you need to register the following plugin hook:"
msgstr ""

#: ../../guides/widgets.rst:231
msgid "When an object triggers an event that matches the event, entity\\_type, and entity\\_subtype parameters passed, Elgg core will look for default widgets that match the widget\\_context and will copy them to that object's owner\\_guid and container\\_guid. All widget settings will also be copied."
msgstr ""

