guides.pot

# 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: 2020-04-24 13:13+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:10
#: ../../guides/database.rst:8
#: ../../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/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:13
#: ../../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:358
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:6
msgid "Client and server code written for the legacy API should not need modification."
msgstr ""

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

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

#: ../../guides/ajax.rst:18
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:19
msgid "The method returns a ``jqXHR`` object, which can be used as a Promise."
msgstr ""

#: ../../guides/ajax.rst:20
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:21
msgid "The response object is filtered by the hook ``ajax_response``."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/ajax.rst:35
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:36
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:37
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:38
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:41
msgid "Performing actions"
msgstr ""

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

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

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

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

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

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

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

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

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

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

#: ../../guides/ajax.rst:92
msgid "Using ``forward()`` in an action simply sends the response. The URL given in not returned to the client."
msgstr ""

#: ../../guides/ajax.rst:94
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:98
msgid "Fetching data"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/ajax.rst:200
#: ../../guides/ajax.rst:238
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:204
#: ../../guides/ajax.rst:249
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:209
msgid "Fetching forms"
msgstr ""

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

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

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

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

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

#: ../../guides/ajax.rst:242
#: ../../guides/ajax.rst:547
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:254
msgid "Submitting forms"
msgstr ""

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

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

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

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

#: ../../guides/ajax.rst:278
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:280
msgid "Let's say when the view ``foo`` is fetched, we want to also send the server some data:"
msgstr ""

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

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

#: ../../guides/ajax.rst:300
msgid "The form will be objectified as ``FormData``, and the request content type will be determined accordingly. Effectively this allows plugins to submit multipart form data without using ``jquery.form`` plugin and other ``iframe`` hacks."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/ajax.rst:359
msgid "You may need only worry about the 2nd case. We can do this by looking at ``jqXHR.AjaxData.status``:"
msgstr ""

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

#: ../../guides/ajax.rst:375
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/ajax.rst:384
msgid "Legacy elgg.ajax APIs"
msgstr ""

#: ../../guides/ajax.rst:386
msgid "Elgg 1.8 introduced ``elgg.action``, ``elgg.get``, ``elgg.getJSON``, and other methods which behave less consistently both client-side and server-side."
msgstr ""

#: ../../guides/ajax.rst:389
msgid "Legacy elgg.action"
msgstr ""

#: ../../guides/ajax.rst:391
msgid "Differences:"
msgstr ""

#: ../../guides/ajax.rst:393
msgid "you must manually pull the ``output`` from the returned wrapper"
msgstr ""

#: ../../guides/ajax.rst:394
msgid "the ``success`` handler will fire even if the action is prevented"
msgstr ""

#: ../../guides/ajax.rst:395
msgid "the ``success`` handler will receive a wrapper object. You must look for ``wrapper.output``"
msgstr ""

#: ../../guides/ajax.rst:396
msgid "no ajax hooks"
msgstr ""

#: ../../guides/ajax.rst:419
msgid "elgg.action notes"
msgstr ""

#: ../../guides/ajax.rst:421
msgid "It's best to echo a non-empty string, as this is easy to validate in the ``success`` function. If the action was not allowed to run for some reason, ``wrapper.output`` will be an empty string."
msgstr ""

#: ../../guides/ajax.rst:423
msgid "You may want to use the :doc:`elgg/spinner</guides/javascript>` module."
msgstr ""

#: ../../guides/ajax.rst:424
msgid "Elgg does not use ``wrapper.status`` for anything, but a call to ``register_error()`` causes it to be set to ``-1``."
msgstr ""

#: ../../guides/ajax.rst:426
msgid "If the action echoes a non-JSON string, ``wrapper.output`` will contain that string."
msgstr ""

#: ../../guides/ajax.rst:427
msgid "``elgg.action`` is based on ``jQuery.ajax`` and returns a ``jqXHR`` object (like a Promise), if you should want to use it."
msgstr ""

#: ../../guides/ajax.rst:428
msgid "After the PHP action completes, other plugins can alter the wrapper via the plugin hook ``'output', 'ajax'``, which filters the wrapper as an array (not a JSON string)."
msgstr ""

#: ../../guides/ajax.rst:430
msgid "A ``forward()`` call forces the action to be processed and output immediately, with the ``wrapper.forward_url`` value set to the normalized location given."
msgstr ""

#: ../../guides/ajax.rst:432
msgid "To make sure Ajax actions can only be executed via XHR, use ``elgg_ajax_gatekeeper()``."
msgstr ""

#: ../../guides/ajax.rst:435
msgid "elgg.action JSON response wrapper"
msgstr ""

#: ../../guides/ajax.rst:449
msgid "It's probably best to rely only on the ``output`` key, and validate it in case the PHP action could not run for some reason, e.g. the user was logged out or a CSRF attack did not provide tokens."
msgstr ""

#: ../../guides/ajax.rst:454
msgid "If ``forward()`` is used in response to a legacy ajax request (e.g. ``elgg.ajax``), Elgg will *always* respond with this wrapper, **even if not in an action**."
msgstr ""

#: ../../guides/ajax.rst:458
msgid "Legacy view fetching"
msgstr ""

#: ../../guides/ajax.rst:460
msgid "A plugin can use a view script to handle XHR ``GET`` requests. Here's a simple example of a view that returns a link to an object given by its GUID:"
msgstr ""

#: ../../guides/ajax.rst:496
msgid "The Ajax view system works significantly differently than the action system."
msgstr ""

#: ../../guides/ajax.rst:498
msgid "There are no access controls based on session status."
msgstr ""

#: ../../guides/ajax.rst:499
msgid "Non-XHR requests are automatically rejected."
msgstr ""

#: ../../guides/ajax.rst:500
msgid "GET vars are injected into ``$vars`` in the view."
msgstr ""

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

#: ../../guides/ajax.rst:503
msgid "There's no \"wrapper\" object placed around the view output."
msgstr ""

#: ../../guides/ajax.rst:504
msgid "System messages/errors shouldn't be used, as they don't display until the user loads another page."
msgstr ""

#: ../../guides/ajax.rst:505
msgid "Depending on the view's suffix (.js, .html, .css, etc.), a corresponding Content-Type header is added."
msgstr ""

#: ../../guides/ajax.rst:509
#: ../../guides/ajax.rst:554
msgid "In ajax views and forms, note that ``$vars`` can be populated by client input. The data is filtered like"
msgstr ""

#: ../../guides/ajax.rst:510
#: ../../guides/ajax.rst:555
msgid "``get_input()``, but may not be the type you're expecting or may have unexpected keys."
msgstr ""

#: ../../guides/ajax.rst:513
msgid "Returning JSON from a view"
msgstr ""

#: ../../guides/ajax.rst:515
msgid "If the view outputs encoded JSON, you must use ``elgg.getJSON`` to fetch it (or use some other method to set jQuery's ajax option ``dataType`` to ``json``). Your ``success`` function will be passed the decoded Object."
msgstr ""

#: ../../guides/ajax.rst:518
msgid "Here's an example of fetching a view that returns a JSON-encoded array of times:"
msgstr ""

#: ../../guides/ajax.rst:529
msgid "Legacy form fetching"
msgstr ""

#: ../../guides/ajax.rst:531
msgid "If you register a form view (name starting with ``forms/``), you can fetch it pre-rendered with ``elgg_view_form()``. Simply use ``ajax/form/<action>`` (instead of ``ajax/view/<view_name>``):"
msgstr ""

#: ../../guides/ajax.rst:559
msgid "Legacy helper functions"
msgstr ""

#: ../../guides/ajax.rst:561
msgid "These functions extend jQuery's native Ajax features."
msgstr ""

#: ../../guides/ajax.rst:563
msgid "``elgg.get()`` is a wrapper for jQuery's ``$.ajax()``, but forces ``GET`` and does URL normalization."
msgstr ""

#: ../../guides/ajax.rst:574
msgid "``elgg.post()`` is a wrapper for jQuery's ``$.ajax()``, but forces ``POST`` and does URL normalization."
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:`start.php <plugins>` file, 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:92
msgid "Importance"
msgstr ""

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

#: ../../guides/authentication.rst:96
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:99
msgid "Passed credentials"
msgstr ""

#: ../../guides/authentication.rst:101
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:104
msgid "Return value"
msgstr ""

#: ../../guides/authentication.rst:106
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:430
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:349
msgid "Example: Run SQL script on plugin activation"
msgstr ""

#: ../../guides/database.rst:351
msgid "This example shows how you can populate your database on plugin activation."
msgstr ""

#: ../../guides/database.rst:360
msgid "my_plugin/sql/activate.sql:"
msgstr ""

#: ../../guides/database.rst:376
msgid "Note that Elgg execute statements through PHPs built-in functions and have limited support for comments. I.e. only single line comments are supported and must be prefixed by \"-- \" or \"# \". A comment must start at the very beginning of a line."
msgstr ""

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

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

#: ../../guides/database.rst:388
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:391
msgid "System log storage"
msgstr ""

#: ../../guides/database.rst:393
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:395
msgid "Common events include:"
msgstr ""

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

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

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

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

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

#: ../../guides/database.rst:405
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:407
msgid "To do this, you can create a function that listens to all events for all types of object:"
msgstr ""

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

#: ../../guides/database.rst:423
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 the root directory 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/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 ``system_log_default_logger()`` 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 "**logout:before, user**"
msgstr ""

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

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

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

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

#: ../../guides/events-list.rst:108
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:113
msgid "**validate:after, user**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:160
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:167
msgid "**update:after, <entity type>**"
msgstr ""

#: ../../guides/events-list.rst:165
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:170
msgid "**delete, <entity type>**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:232
msgid "**created, river**"
msgstr ""

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

#: ../../guides/events-list.rst:232
msgid "Use the plugin hook ``creating, river`` to cancel creation (or alter options)."
msgstr ""

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

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

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

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

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

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

#: ../../guides/events-list.rst:244
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:249
msgid "Notes"
msgstr ""

#: ../../guides/events-list.rst:251
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:56
msgid "Reading Files"
msgstr ""

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

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

#: ../../guides/file-system.rst:87
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:90
msgid "**``file``** An instance of ``ElggFile`` to be served"
msgstr ""

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

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

#: ../../guides/file-system.rst:94
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:99
msgid "The default behaviour of ``use_cookie`` can be controlled on the admin security settings page."
msgstr ""

#: ../../guides/file-system.rst:101
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:104
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:109
msgid "Embedding Files"
msgstr ""

#: ../../guides/file-system.rst:111
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:115
msgid "To embed an entity icon, use ``elgg_get_embed_url()``."
msgstr ""

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

#: ../../guides/file-system.rst:121
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:159
msgid "If your file input supports multiple files, you can iterate through them in your action:"
msgstr ""

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

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

#: ../../guides/file-system.rst:189
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:194
msgid "It's not possible to save the ``ElggTempFile`` to the database. You'll get an ``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:81
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:1101
#: ../../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/helpers.rst:60
msgid "E-mail address formatting"
msgstr ""

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

#: ../../guides/helpers.rst:80
msgid "There are some helper functions available"
msgstr ""

#: ../../guides/helpers.rst:82
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/helpers.rst:84
msgid "``\\Elgg\\Email\\Address::getFormattedEmailAddress($email, $name)`` Will return a formatted string provided an e-mail address and optionaly a name"
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
msgid "**unit_test, system**"
msgstr ""

#: ../../guides/hooks-list.rst:22
msgid "Add a Simple Test test. (Deprecated.)"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:55
msgid "``Elgg_Logger::INFO``"
msgstr ""

#: ../../guides/hooks-list.rst:56
msgid "msg - The message"
msgstr ""

#: ../../guides/hooks-list.rst:57
msgid "display - Should this message be displayed?"
msgstr ""

#: ../../guides/hooks-list.rst:60
msgid "**format, friendly:title**"
msgstr ""

#: ../../guides/hooks-list.rst:60
msgid "Formats the \"friendly\" title for strings. This is used for generating URLs."
msgstr ""

#: ../../guides/hooks-list.rst:63
msgid "**format, friendly:time**"
msgstr ""

#: ../../guides/hooks-list.rst:63
msgid "Formats the \"friendly\" time for the timestamp ``$params['time']``."
msgstr ""

#: ../../guides/hooks-list.rst:67
msgid "**format, strip_tags**"
msgstr ""

#: ../../guides/hooks-list.rst:66
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:72
msgid "**output:before, page**"
msgstr ""

#: ../../guides/hooks-list.rst:70
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_views_send_header_x_frame_options()`` from this hook."
msgstr ""

#: ../../guides/hooks-list.rst:75
msgid "**output, page**"
msgstr ""

#: ../../guides/hooks-list.rst:75
msgid "In ``elgg_view_page()``, this filters the output return value."
msgstr ""

#: ../../guides/hooks-list.rst:84
msgid "**parameters, menu:<menu_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:78
msgid "Triggered by ``elgg_view_menu()``. Used to change menu variables (like sort order) before rendering."
msgstr ""

#: ../../guides/hooks-list.rst:80
#: ../../guides/hooks-list.rst:101
#: ../../guides/hooks-list.rst:180
#: ../../guides/hooks-list.rst:190
#: ../../guides/hooks-list.rst:217
#: ../../guides/hooks-list.rst:258
#: ../../guides/hooks-list.rst:265
#: ../../guides/hooks-list.rst:395
#: ../../guides/hooks-list.rst:409
#: ../../guides/hooks-list.rst:428
msgid "The ``$params`` array will contain:"
msgstr ""

#: ../../guides/hooks-list.rst:82
msgid "``name`` - name of the menu"
msgstr ""

#: ../../guides/hooks-list.rst:83
msgid "``sort_by`` - preferring sorting parameter"
msgstr ""

#: ../../guides/hooks-list.rst:84
msgid "other parameters passed to ``elgg_view_menu()``"
msgstr ""

#: ../../guides/hooks-list.rst:94
msgid "**register, menu:<menu_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:87
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:90
msgid "The ``$params`` array will contain parameters returned by ``parameters, menu:<menu_name>`` hook."
msgstr ""

#: ../../guides/hooks-list.rst:92
msgid "The return value is an instance of ``\\Elgg\\Collections\\Collection`` containing ``\\ElggMenuItem`` objects."
msgstr ""

#: ../../guides/hooks-list.rst:94
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:106
msgid "**prepare, menu:<menu_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:97
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:103
msgid "``selected_item`` - ``ElggMenuItem`` selected in the menu, if any"
msgstr ""

#: ../../guides/hooks-list.rst:105
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:110
msgid "**register, menu:filter:<filter_id>**"
msgstr ""

#: ../../guides/hooks-list.rst:109
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:118
msgid "**filter_tabs, <context>**"
msgstr ""

#: ../../guides/hooks-list.rst:113
msgid "Filters the array of ``ElggMenuItem`` used to display the All/Mine/Friends tabs. The ``$params`` array includes:"
msgstr ""

#: ../../guides/hooks-list.rst:116
msgid "``selected``: the selected menu item name"
msgstr ""

#: ../../guides/hooks-list.rst:117
msgid "``user``: the logged in ``ElggUser`` or ``null``"
msgstr ""

#: ../../guides/hooks-list.rst:118
msgid "``vars``: The ``$vars`` argument passed to ``elgg_get_filter_tabs``"
msgstr ""

#: ../../guides/hooks-list.rst:122
msgid "**creating, river**"
msgstr ""

#: ../../guides/hooks-list.rst:121
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:125
msgid "**simplecache:generate, <view>**"
msgstr ""

#: ../../guides/hooks-list.rst:125
msgid "Filters the view output for a ``/cache`` URL when simplecache is enabled."
msgstr ""

#: ../../guides/hooks-list.rst:129
msgid "**cache:generate, <view>**"
msgstr ""

#: ../../guides/hooks-list.rst:128
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:138
msgid "**prepare, breadcrumbs**"
msgstr ""

#: ../../guides/hooks-list.rst:132
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:136
msgid "``breadcrumbs`` - an array of bredcrumbs, each with ``title`` and ``link`` keys"
msgstr ""

#: ../../guides/hooks-list.rst:137
msgid "``identifier`` - route identifier of the current page"
msgstr ""

#: ../../guides/hooks-list.rst:138
msgid "``segments`` - route segments of the current page"
msgstr ""

#: ../../guides/hooks-list.rst:140
msgid "**add, river**"
msgstr ""

#: ../../guides/hooks-list.rst:143
msgid "**elgg.data, site**"
msgstr ""

#: ../../guides/hooks-list.rst:143
msgid "Filters cached configuration data to pass to the client. :ref:`More info <guides/javascript#config>`"
msgstr ""

#: ../../guides/hooks-list.rst:146
msgid "**elgg.data, page**"
msgstr ""

#: ../../guides/hooks-list.rst:146
msgid "Filters uncached, page-specific configuration data to pass to the client. :ref:`More info <guides/javascript#config>`"
msgstr ""

#: ../../guides/hooks-list.rst:151
msgid "**registration_url, site**"
msgstr ""

#: ../../guides/hooks-list.rst:149
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:156
msgid "**login_url, site**"
msgstr ""

#: ../../guides/hooks-list.rst:154
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:160
msgid "**commands, cli**"
msgstr ""

#: ../../guides/hooks-list.rst:159
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:164
msgid "**seeds, database**"
msgstr ""

#: ../../guides/hooks-list.rst:163
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:167
msgid "**languages, translations**"
msgstr ""

#: ../../guides/hooks-list.rst:167
msgid "Allows plugins to add/remove languages from the configurable languages in the system."
msgstr ""

#: ../../guides/hooks-list.rst:170
msgid "**generate, password**"
msgstr ""

#: ../../guides/hooks-list.rst:170
msgid "Allows plugins to generate new random cleartext passwords."
msgstr ""

#: ../../guides/hooks-list.rst:173
msgid "User hooks"
msgstr ""

#: ../../guides/hooks-list.rst:183
msgid "**usersettings:save, user**"
msgstr ""

#: ../../guides/hooks-list.rst:176
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:182
#: ../../guides/hooks-list.rst:192
msgid "``user`` - ``\\ElggUser``, whose settings are being saved"
msgstr ""

#: ../../guides/hooks-list.rst:183
#: ../../guides/hooks-list.rst:194
msgid "``request`` - ``\\Elgg\\Request`` to the action controller"
msgstr ""

#: ../../guides/hooks-list.rst:194
msgid "**change:email, user**"
msgstr ""

#: ../../guides/hooks-list.rst:186
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:193
msgid "``email`` - Email address that passes sanity checks"
msgstr ""

#: ../../guides/hooks-list.rst:198
#: ../../guides/hooks-list.rst:282
msgid "**access:collections:write, user**"
msgstr ""

#: ../../guides/hooks-list.rst:197
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:202
msgid "**registeruser:validate:username, all**"
msgstr ""

#: ../../guides/hooks-list.rst:201
msgid "Return boolean for if the string in ``$params['username']`` is valid for a username. Hook handler can throw ``\\RegistrationException`` with an error message to be shown to the user."
msgstr ""

#: ../../guides/hooks-list.rst:206
msgid "**registeruser:validate:password, all**"
msgstr ""

#: ../../guides/hooks-list.rst:205
msgid "Return boolean for if the string in ``$params['password']`` is valid for a password. Hook handler can throw ``\\RegistrationException`` with an error message to be shown to the user."
msgstr ""

#: ../../guides/hooks-list.rst:210
msgid "**registeruser:validate:email, all**"
msgstr ""

#: ../../guides/hooks-list.rst:209
msgid "Return boolean for if the string in ``$params['email']`` is valid for an email address. Hook handler can throw ``\\RegistrationException`` with an error message to be shown to the user."
msgstr ""

#: ../../guides/hooks-list.rst:220
msgid "**register, user**"
msgstr ""

#: ../../guides/hooks-list.rst:213
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 ``\\RegistrationException`` with an error message to be displayed to the user."
msgstr ""

#: ../../guides/hooks-list.rst:219
msgid "``user`` - Newly registered user entity"
msgstr ""

#: ../../guides/hooks-list.rst:220
msgid "All parameters sent with the request to the action (incl. ``password``, ``friend_guid``, ``invitecode`` etc)"
msgstr ""

#: ../../guides/hooks-list.rst:223
msgid "**login:forward, user**"
msgstr ""

#: ../../guides/hooks-list.rst:223
msgid "Filters the URL to which the user will be forwarded after login."
msgstr ""

#: ../../guides/hooks-list.rst:226
msgid "**find_active_users, system**"
msgstr ""

#: ../../guides/hooks-list.rst:226
msgid "Return the number of active users."
msgstr ""

#: ../../guides/hooks-list.rst:229
msgid "**status, user**"
msgstr ""

#: ../../guides/hooks-list.rst:229
msgid "Triggered by The Wire when adding a post."
msgstr ""

#: ../../guides/hooks-list.rst:234
msgid "**username:character_blacklist, user**"
msgstr ""

#: ../../guides/hooks-list.rst:232
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:237
msgid "Object hooks"
msgstr ""

#: ../../guides/hooks-list.rst:241
msgid "**comments, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:240
msgid "Triggered in ``elgg_view_comments()``. If returning content, this overrides the ``page/elements/comments`` view."
msgstr ""

#: ../../guides/hooks-list.rst:244
msgid "**comments:count, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:244
msgid "Return the number of comments on ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:248
msgid "**likes:count, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:247
msgid "Return the number of likes for ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:253
msgid "Access hooks"
msgstr ""

#: ../../guides/hooks-list.rst:260
msgid "**access_collection:url, access_collection**"
msgstr ""

#: ../../guides/hooks-list.rst:256
msgid "Can be used to filter the URL of the access collection."
msgstr ""

#: ../../guides/hooks-list.rst:260
#: ../../guides/hooks-list.rst:267
msgid "``access_collection`` - `ElggAccessCollection`"
msgstr ""

#: ../../guides/hooks-list.rst:267
msgid "**access_collection:name, access_collection**"
msgstr ""

#: ../../guides/hooks-list.rst:263
msgid "Can be used to filter the display name (readable access level) of the access collection."
msgstr ""

#: ../../guides/hooks-list.rst:272
msgid "**access:collections:read, user**"
msgstr ""

#: ../../guides/hooks-list.rst:270
msgid "Filters an array of access IDs that the user ``$params['user_id']`` can see."
msgstr ""

#: ../../guides/hooks-list.rst:272
#: ../../guides/hooks-list.rst:282
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:275
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:285
msgid "**access:collections:write:subtypes, user**"
msgstr ""

#: ../../guides/hooks-list.rst:285
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:288
msgid "**access:collections:addcollection, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:288
msgid "Triggered after an access collection ``$params['collection_id']`` is created."
msgstr ""

#: ../../guides/hooks-list.rst:292
msgid "**access:collections:deletecollection, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:291
msgid "Triggered before an access collection ``$params['collection_id']`` is deleted. Return false to prevent deletion."
msgstr ""

#: ../../guides/hooks-list.rst:296
msgid "**access:collections:add_user, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:295
msgid "Triggered before adding user ``$params['user_id']`` to collection ``$params['collection_id']``. Return false to prevent adding."
msgstr ""

#: ../../guides/hooks-list.rst:300
msgid "**access:collections:remove_user, collection**"
msgstr ""

#: ../../guides/hooks-list.rst:299
msgid "Triggered before removing user ``$params['user_id']`` to collection ``$params['collection_id']``. Return false to prevent removal."
msgstr ""

#: ../../guides/hooks-list.rst:319
msgid "**get_sql, access**"
msgstr ""

#: ../../guides/hooks-list.rst:303
msgid "Filters SQL clauses restricting/allowing access to entities and annotations."
msgstr ""

#: ../../guides/hooks-list.rst:305
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:307
msgid "``$return`` value is a nested array of ``ands`` and ``ors``."
msgstr ""

#: ../../guides/hooks-list.rst:309
msgid "``$params`` includes:"
msgstr ""

#: ../../guides/hooks-list.rst:311
msgid "``table_alias`` - alias of the main table used in select clause"
msgstr ""

#: ../../guides/hooks-list.rst:312
msgid "``ignore_access`` - whether ignored access is enabled"
msgstr ""

#: ../../guides/hooks-list.rst:313
msgid "``use_enabled_clause`` - whether disabled entities are shown/hidden"
msgstr ""

#: ../../guides/hooks-list.rst:314
msgid "``access_column`` - column in the main table containing the access collection ID value"
msgstr ""

#: ../../guides/hooks-list.rst:315
msgid "``owner_guid_column`` - column in the main table referencing the GUID of the owner"
msgstr ""

#: ../../guides/hooks-list.rst:316
msgid "``guid_column`` - column in the main table referencing the GUID of the entity"
msgstr ""

#: ../../guides/hooks-list.rst:317
msgid "``enabled_column`` - column in the main table referencing the enabled status of the entity"
msgstr ""

#: ../../guides/hooks-list.rst:318
msgid "``query_builder`` - an instance of the ``QueryBuilder``"
msgstr ""

#: ../../guides/hooks-list.rst:322
msgid "Action hooks"
msgstr ""

#: ../../guides/hooks-list.rst:326
msgid "**action, <action>**"
msgstr ""

#: ../../guides/hooks-list.rst:325
msgid "Deprecated. Use ``'action:validate', <action>`` hook instead. Triggered before executing action scripts. Return false to abort action."
msgstr ""

#: ../../guides/hooks-list.rst:336
msgid "**action:validate, <action>**"
msgstr ""

#: ../../guides/hooks-list.rst:329
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\\ValidationException`` or return ``false`` to terminate further execution."
msgstr ""

#: ../../guides/hooks-list.rst:334
#: ../../guides/hooks-list.rst:472
#: ../../guides/hooks-list.rst:488
#: ../../guides/hooks-list.rst:502
#: ../../guides/hooks-list.rst:522
#: ../../guides/hooks-list.rst:577
#: ../../guides/hooks-list.rst:585
#: ../../guides/hooks-list.rst:747
#: ../../guides/hooks-list.rst:755
#: ../../guides/hooks-list.rst:776
msgid "``$params`` array includes:"
msgstr ""

#: ../../guides/hooks-list.rst:336
msgid "``request`` - instance of ``\\Elgg\\Request``"
msgstr ""

#: ../../guides/hooks-list.rst:339
msgid "**action_gatekeeper:permissions:check, all**"
msgstr ""

#: ../../guides/hooks-list.rst:339
msgid "Triggered after a CSRF token is validated. Return false to prevent validation."
msgstr ""

#: ../../guides/hooks-list.rst:343
msgid "**action_gatekeeper:upload_exceeded_msg, all**"
msgstr ""

#: ../../guides/hooks-list.rst:342
msgid "Triggered when a POST exceeds the max size allowed by the server. Return an error message to display."
msgstr ""

#: ../../guides/hooks-list.rst:347
msgid "**forward, <reason>**"
msgstr ""

#: ../../guides/hooks-list.rst:346
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 ``HttpException`` that triggered the error."
msgstr ""

#: ../../guides/hooks-list.rst:353
msgid "**response, action:<action>**"
msgstr ""

#: ../../guides/hooks-list.rst:350
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:372
msgid "**ajax_response, \\***"
msgstr ""

#: ../../guides/hooks-list.rst:361
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:366
msgid "elgg/Ajax method"
msgstr ""

#: ../../guides/hooks-list.rst:366
msgid "plugin hook type"
msgstr ""

#: ../../guides/hooks-list.rst:368
msgid "action()"
msgstr ""

#: ../../guides/hooks-list.rst:368
msgid "action:<action_name>"
msgstr ""

#: ../../guides/hooks-list.rst:369
msgid "path()"
msgstr ""

#: ../../guides/hooks-list.rst:369
msgid "path:<url_path>"
msgstr ""

#: ../../guides/hooks-list.rst:370
msgid "view()"
msgstr ""

#: ../../guides/hooks-list.rst:370
msgid "view:<view_name>"
msgstr ""

#: ../../guides/hooks-list.rst:371
msgid "form()"
msgstr ""

#: ../../guides/hooks-list.rst:371
msgid "form:<action_name>"
msgstr ""

#: ../../guides/hooks-list.rst:378
msgid "**output, ajax**"
msgstr ""

#: ../../guides/hooks-list.rst:375
msgid "This filters the JSON output wrapper returned to the legacy ajax API (``elgg.ajax``, ``elgg.action``, etc.). Plugins can alter the output, forward URL, system messages, and errors. For the ``elgg/Ajax`` AMD module, use the ``ajax_response`` hook documented above."
msgstr ""

#: ../../guides/hooks-list.rst:383
msgid "Permission hooks"
msgstr ""

#: ../../guides/hooks-list.rst:399
msgid "**container_logic_check, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:386
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:391
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:397
#: ../../guides/hooks-list.rst:411
msgid "``container`` - An entity that will be used as a container"
msgstr ""

#: ../../guides/hooks-list.rst:398
#: ../../guides/hooks-list.rst:412
msgid "``user`` - User who will own the entity to be written to container"
msgstr ""

#: ../../guides/hooks-list.rst:399
#: ../../guides/hooks-list.rst:413
msgid "``subtype`` - Subtype of the entity to be written to container (entity type is assumed from hook type)"
msgstr ""

#: ../../guides/hooks-list.rst:413
msgid "**container_permissions_check, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:402
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:405
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:416
msgid "**permissions_check, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:416
msgid "Return boolean for if the user ``$params['user']`` can edit the entity ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:419
msgid "**permissions_check:delete, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:419
msgid "Return boolean for if the user ``$params['user']`` can delete the entity ``$params['entity']``. Defaults to ``$entity->canEdit()``."
msgstr ""

#: ../../guides/hooks-list.rst:423
msgid "**permissions_check:delete, river**"
msgstr ""

#: ../../guides/hooks-list.rst:422
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:431
msgid "**permissions_check:download, file**"
msgstr ""

#: ../../guides/hooks-list.rst:426
msgid "Return boolean for if the user ``$params['user']`` can download the file in ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:430
msgid "``entity`` - Instance of ``ElggFile``"
msgstr ""

#: ../../guides/hooks-list.rst:431
msgid "``user`` - User who will download the file"
msgstr ""

#: ../../guides/hooks-list.rst:435
msgid "**permissions_check, widget_layout**"
msgstr ""

#: ../../guides/hooks-list.rst:434
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:439
msgid "**permissions_check:metadata, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:438
msgid "(Deprecated) Return boolean for if the user ``$params['user']`` can edit the metadata ``$params['metadata']`` on the entity ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:442
msgid "**permissions_check:comment, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:442
msgid "Return boolean for if the user ``$params['user']`` can comment on the entity ``$params['entity']``."
msgstr ""

#: ../../guides/hooks-list.rst:448
msgid "**permissions_check:annotate:<annotation_name>, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:445
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:448
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:452
msgid "**permissions_check:annotate, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:451
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:456
msgid "**permissions_check:annotation**"
msgstr ""

#: ../../guides/hooks-list.rst:455
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:460
msgid "**fail, auth**"
msgstr ""

#: ../../guides/hooks-list.rst:459
msgid "Return the failure message if authentication failed. An array of previous PAM failure methods is passed as ``$params``."
msgstr ""

#: ../../guides/hooks-list.rst:463
msgid "**api_key, use**"
msgstr ""

#: ../../guides/hooks-list.rst:463
msgid "Triggered by ``api_auth_key()``. Returning false prevents the key from being authenticated."
msgstr ""

#: ../../guides/hooks-list.rst:476
msgid "**gatekeeper, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:466
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 ``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:474
msgid "``entity`` - Entity that is being accessed"
msgstr ""

#: ../../guides/hooks-list.rst:475
msgid "``user`` - User accessing the entity (``null`` implies logged in user)"
msgstr ""

#: ../../guides/hooks-list.rst:479
#: ../../guides/notifications.rst:2
msgid "Notifications"
msgstr ""

#: ../../guides/hooks-list.rst:481
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:491
msgid "**enqueue, notification**"
msgstr ""

#: ../../guides/hooks-list.rst:485
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:490
msgid "``object`` - object of the notification event"
msgstr ""

#: ../../guides/hooks-list.rst:491
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:508
msgid "**get, subscriptions**"
msgstr ""

#: ../../guides/hooks-list.rst:494
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:499
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:504
#: ../../guides/hooks-list.rst:524
#: ../../guides/hooks-list.rst:535
#: ../../guides/hooks-list.rst:552
#: ../../guides/hooks-list.rst:587
msgid "``event`` - ``\\Elgg\\Notifications\\NotificationEvent`` instance that describes the notification event"
msgstr ""

#: ../../guides/hooks-list.rst:505
#: ../../guides/hooks-list.rst:542
#: ../../guides/hooks-list.rst:559
msgid "``origin`` - ``subscriptions_service`` or ``instant_notifications``"
msgstr ""

#: ../../guides/hooks-list.rst:506
msgid "``methods_override`` - delivery method preference for instant notifications"
msgstr ""

#: ../../guides/hooks-list.rst:508
msgid "Handlers must return an array in the form:"
msgstr ""

#: ../../guides/hooks-list.rst:525
msgid "**send:before, notifications**"
msgstr ""

#: ../../guides/hooks-list.rst:519
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:525
#: ../../guides/hooks-list.rst:588
msgid "``subscriptions`` - a list of subscriptions. See ``'get', 'subscriptions'`` hook for details"
msgstr ""

#: ../../guides/hooks-list.rst:542
msgid "**prepare, notification**"
msgstr ""

#: ../../guides/hooks-list.rst:528
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:533
msgid "``$params`` may vary based on the notification type and may include:"
msgstr ""

#: ../../guides/hooks-list.rst:536
#: ../../guides/hooks-list.rst:553
msgid "``object`` - object of the notification ``event``. Can be ``null`` for instant notifications"
msgstr ""

#: ../../guides/hooks-list.rst:537
#: ../../guides/hooks-list.rst:554
msgid "``action`` - action that triggered the notification ``event``. May default to ``notify_user`` for instant notifications"
msgstr ""

#: ../../guides/hooks-list.rst:538
#: ../../guides/hooks-list.rst:555
msgid "``method`` - delivery method (e.g. ``email``, ``site``)"
msgstr ""

#: ../../guides/hooks-list.rst:539
#: ../../guides/hooks-list.rst:556
msgid "``sender`` - sender"
msgstr ""

#: ../../guides/hooks-list.rst:540
#: ../../guides/hooks-list.rst:557
msgid "``recipient`` - recipient"
msgstr ""

#: ../../guides/hooks-list.rst:541
#: ../../guides/hooks-list.rst:558
msgid "``language`` - language of the notification (recipient's language)"
msgstr ""

#: ../../guides/hooks-list.rst:559
msgid "**prepare, notification:<action>:<entity_type>:<entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:545
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:550
msgid "``$params`` include:"
msgstr ""

#: ../../guides/hooks-list.rst:570
msgid "**format, notification:<method>**"
msgstr ""

#: ../../guides/hooks-list.rst:562
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:568
msgid "Strip tags from notification title and body for plaintext email notifications"
msgstr ""

#: ../../guides/hooks-list.rst:569
msgid "Inline HTML styles for HTML email notifications"
msgstr ""

#: ../../guides/hooks-list.rst:570
msgid "Wrap notification in a template, add signature etc."
msgstr ""

#: ../../guides/hooks-list.rst:579
msgid "**send, notification:<method>**"
msgstr ""

#: ../../guides/hooks-list.rst:573
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:579
msgid "``notification`` - a notification object ``\\Elgg\\Notifications\\Notification``"
msgstr ""

#: ../../guides/hooks-list.rst:590
msgid "**send:after, notifications**"
msgstr ""

#: ../../guides/hooks-list.rst:582
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:589
msgid "``deliveries`` - a matrix of delivery statuses by user for each delivery method"
msgstr ""

#: ../../guides/hooks-list.rst:593
msgid "Emails"
msgstr ""

#: ../../guides/hooks-list.rst:601
msgid "**prepare, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:596
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:601
msgid "``$params`` are empty. The ``$return`` value is an instance of ``\\Elgg\\Email``."
msgstr ""

#: ../../guides/hooks-list.rst:611
msgid "**validate, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:604
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:609
#: ../../guides/hooks-list.rst:619
#: ../../guides/hooks-list.rst:628
msgid "``$params`` contains:"
msgstr ""

#: ../../guides/hooks-list.rst:611
#: ../../guides/hooks-list.rst:621
#: ../../guides/hooks-list.rst:630
msgid "``email`` - An instance of ``\\Elgg\\Email``"
msgstr ""

#: ../../guides/hooks-list.rst:621
msgid "**transport, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:614
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:630
msgid "**zend:message, system:email**"
msgstr ""

#: ../../guides/hooks-list.rst:624
msgid "Triggered by the default email transport handler (Elgg uses ``zendframework/zend-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 ``\\Zend\\Mail\\Message`` before it is passed to the Zend email transport."
msgstr ""

#: ../../guides/hooks-list.rst:633
#: ../../guides/routing.rst:2
msgid "Routing"
msgstr ""

#: ../../guides/hooks-list.rst:638
msgid "**route:config, <route_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:636
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:642
msgid "**route:rewrite, <identifier>**"
msgstr ""

#: ../../guides/hooks-list.rst:641
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:649
msgid "**response, path:<path>**"
msgstr ""

#: ../../guides/hooks-list.rst:645
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:654
msgid "**ajax_response, path:<path>**"
msgstr ""

#: ../../guides/hooks-list.rst:652
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:659
#: ../../guides/plugins/plugin-skeleton.rst:143
#: ../../guides/views.rst:2
msgid "Views"
msgstr ""

#: ../../guides/hooks-list.rst:662
msgid "**view_vars, <view_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:662
msgid "Filters the ``$vars`` array passed to the view"
msgstr ""

#: ../../guides/hooks-list.rst:665
msgid "**view, <view_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:665
msgid "Filters the returned content of the view"
msgstr ""

#: ../../guides/hooks-list.rst:673
msgid "**layout, page**"
msgstr ""

#: ../../guides/hooks-list.rst:668
msgid "In ``elgg_view_layout()``, filters the layout name. ``$params`` array includes:"
msgstr ""

#: ../../guides/hooks-list.rst:671
msgid "``identifier`` - ID of the page being rendered"
msgstr ""

#: ../../guides/hooks-list.rst:672
msgid "``segments`` - URL segments of the page being rendered"
msgstr ""

#: ../../guides/hooks-list.rst:673
msgid "other ``$vars`` received by ``elgg_view_layout()``"
msgstr ""

#: ../../guides/hooks-list.rst:676
msgid "**shell, page**"
msgstr ""

#: ../../guides/hooks-list.rst:676
msgid "In ``elgg_view_page()``, filters the page shell name"
msgstr ""

#: ../../guides/hooks-list.rst:684
msgid "**head, page**"
msgstr ""

#: ../../guides/hooks-list.rst:679
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:714
msgid "**ajax_response, view:<view>**"
msgstr ""

#: ../../guides/hooks-list.rst:714
msgid "Filters ``ajax/view/`` responses before they're sent back to the ``elgg/Ajax`` module."
msgstr ""

#: ../../guides/hooks-list.rst:717
msgid "**ajax_response, form:<action>**"
msgstr ""

#: ../../guides/hooks-list.rst:717
msgid "Filters ``ajax/form/`` responses before they're sent back to the ``elgg/Ajax`` module."
msgstr ""

#: ../../guides/hooks-list.rst:722
msgid "**response, view:<view_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:720
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:727
msgid "**response, form:<form_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/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:733
msgid "**table_columns:call, <name>**"
msgstr ""

#: ../../guides/hooks-list.rst:730
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:738
msgid "**vars:compiler, css**"
msgstr ""

#: ../../guides/hooks-list.rst:736
msgid "Allows plugins to alter CSS variables passed to CssCrush during compilation. See `CSS variables <_guides/theming#css-vars>`."
msgstr ""

#: ../../guides/hooks-list.rst:741
msgid "Files"
msgstr ""

#: ../../guides/hooks-list.rst:749
msgid "**download:url, file**"
msgstr ""

#: ../../guides/hooks-list.rst:745
msgid "Allows plugins to filter the download URL of the file."
msgstr ""

#: ../../guides/hooks-list.rst:745
msgid "By default, the download URL is generated by the file service."
msgstr ""

#: ../../guides/hooks-list.rst:749
#: ../../guides/hooks-list.rst:757
msgid "``entity`` - instance of ``ElggFile``"
msgstr ""

#: ../../guides/hooks-list.rst:757
msgid "**inline:url, file**"
msgstr ""

#: ../../guides/hooks-list.rst:753
msgid "Allows plugins to filter the inline URL of the image file."
msgstr ""

#: ../../guides/hooks-list.rst:753
msgid "By default, the inline URL is generated by the file service."
msgstr ""

#: ../../guides/hooks-list.rst:761
msgid "**mime_type, file**"
msgstr ""

#: ../../guides/hooks-list.rst:760
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:767
msgid "**simple_type, file**"
msgstr ""

#: ../../guides/hooks-list.rst:764
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:780
msgid "**upload, file**"
msgstr ""

#: ../../guides/hooks-list.rst:770
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:778
msgid "``file`` - instance of ``ElggFile`` to write to"
msgstr ""

#: ../../guides/hooks-list.rst:779
msgid "``upload`` - instance of Symfony's ``UploadedFile``"
msgstr ""

#: ../../guides/hooks-list.rst:785
#: ../../guides/search.rst:2
msgid "Search"
msgstr ""

#: ../../guides/hooks-list.rst:789
msgid "**search:results, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:788
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:793
msgid "**search:params, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:792
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:798
msgid "**search:fields, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:796
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:810
msgid "**search:fields, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:810
#: ../../guides/hooks-list.rst:813
msgid "See **search:fields, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:813
msgid "**search:fields, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:816
msgid "**search:options, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:816
msgid "Triggered by ``elgg_search()``. Prepares search clauses (options) to be passed to ``elgg_get_entities()``."
msgstr ""

#: ../../guides/hooks-list.rst:819
msgid "**search:options, <entity_type>:<entity_subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:819
#: ../../guides/hooks-list.rst:822
msgid "See **search:options, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:822
msgid "**search:options, <search_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:827
msgid "**search:config, search_types**"
msgstr ""

#: ../../guides/hooks-list.rst:825
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:832
msgid "**search:config, type_subtype_pairs**"
msgstr ""

#: ../../guides/hooks-list.rst:830
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:837
msgid "**search:format, entity**"
msgstr ""

#: ../../guides/hooks-list.rst:835
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:842
msgid "Other"
msgstr ""

#: ../../guides/hooks-list.rst:846
msgid "**config, comments_per_page**"
msgstr ""

#: ../../guides/hooks-list.rst:845
msgid "Filters the number of comments displayed per page. Default is 25. ``$params['entity']`` will hold the containing entity or null if not provided."
msgstr ""

#: ../../guides/hooks-list.rst:850
msgid "**config, comments_latest_first**"
msgstr ""

#: ../../guides/hooks-list.rst:849
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:857
msgid "**default, access**"
msgstr ""

#: ../../guides/hooks-list.rst:853
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:861
msgid "**classes, icon**"
msgstr ""

#: ../../guides/hooks-list.rst:860
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:865
msgid "**entity:icon:sizes, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:864
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:882
msgid "**entity:<icon_type>:sizes, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:868
msgid "Allows filtering sizes for custom icon types, see ``entity:icon:sizes, <entity_type>``."
msgstr ""

#: ../../guides/hooks-list.rst:870
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:873
msgid "``w`` - Width of the image in pixels"
msgstr ""

#: ../../guides/hooks-list.rst:874
msgid "``h`` - Height of the image in pixels"
msgstr ""

#: ../../guides/hooks-list.rst:875
msgid "``square`` - Should the aspect ratio be a square (true/false)"
msgstr ""

#: ../../guides/hooks-list.rst:876
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:877
msgid "``crop`` - Is cropping allowed on this image size (true/false, default: true)"
msgstr ""

#: ../../guides/hooks-list.rst:879
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:882
#: ../../guides/i18n.rst:51
#: ../../guides/notifications.rst:24
#: ../../guides/notifications.rst:186
#: ../../guides/notifications.rst:210
#: ../../guides/notifications.rst:265
msgid "Example:"
msgstr ""

#: ../../guides/hooks-list.rst:914
msgid "**entity:icon:url, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:902
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:906
msgid "entity"
msgstr ""

#: ../../guides/hooks-list.rst:907
msgid "Entity for which icon url is requested."
msgstr ""

#: ../../guides/hooks-list.rst:908
msgid "viewtype"
msgstr ""

#: ../../guides/hooks-list.rst:909
msgid "The type of :ref:`view <guides/views#listing-entities>` e.g. ``'default'`` or ``'json'``."
msgstr ""

#: ../../guides/hooks-list.rst:911
msgid "size"
msgstr ""

#: ../../guides/hooks-list.rst:911
msgid "Size requested, see :ref:`entity icons <guides/database#entity-icons>` for possible values."
msgstr ""

#: ../../guides/hooks-list.rst:913
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:948
msgid "**entity:<icon_type>:url, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:948
msgid "Allows filtering URLs for custom icon types, see ``entity:icon:url, <entity_type>``"
msgstr ""

#: ../../guides/hooks-list.rst:953
msgid "**entity:icon:file, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:951
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:956
msgid "**entity:<icon_type>:file, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:956
msgid "Allows filtering icon file object for custom icon types, see ``entity:icon:file, <entity_type>``"
msgstr ""

#: ../../guides/hooks-list.rst:968
msgid "**entity:<icon_type>:prepare, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:959
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:965
#: ../../guides/hooks-list.rst:1081
#: ../../guides/hooks-list.rst:1123
msgid "The ``$params`` array contains:"
msgstr ""

#: ../../guides/hooks-list.rst:967
#: ../../guides/hooks-list.rst:975
#: ../../guides/hooks-list.rst:985
#: ../../guides/hooks-list.rst:993
msgid "``entity`` - entity that owns the icons"
msgstr ""

#: ../../guides/hooks-list.rst:968
msgid "``file`` - original input file before it has been modified by other hooks"
msgstr ""

#: ../../guides/hooks-list.rst:977
msgid "**entity:<icon_type>:save, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:971
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:976
msgid "``file`` - ``ElggFile`` object that points to the image file to be used as source for icons"
msgstr ""

#: ../../guides/hooks-list.rst:977
#: ../../guides/hooks-list.rst:986
msgid "``x1``, ``y1``, ``x2``, ``y2`` - cropping coordinates"
msgstr ""

#: ../../guides/hooks-list.rst:986
msgid "**entity:<icon_type>:saved, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:980
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:993
msgid "**entity:<icon_type>:delete, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:989
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:998
msgid "**entity:url, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:996
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:1002
msgid "**to:object, <entity_type|metadata|annotation|relationship|river_item>**"
msgstr ""

#: ../../guides/hooks-list.rst:1001
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:1005
msgid "**extender:url, <annotation|metadata>**"
msgstr ""

#: ../../guides/hooks-list.rst:1005
msgid "Return the URL for the annotation or metadatum ``$params['extender']``."
msgstr ""

#: ../../guides/hooks-list.rst:1008
msgid "**file:icon:url, override**"
msgstr ""

#: ../../guides/hooks-list.rst:1008
msgid "Override a file icon URL."
msgstr ""

#: ../../guides/hooks-list.rst:1011
msgid "**is_member, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1011
msgid "Return boolean for if the user ``$params['user']`` is a member of the group ``$params['group']``."
msgstr ""

#: ../../guides/hooks-list.rst:1020
msgid "**usersetting, plugin**"
msgstr ""

#: ../../guides/hooks-list.rst:1014
msgid "Filter user settings for plugins. ``$params`` contains:"
msgstr ""

#: ../../guides/hooks-list.rst:1016
msgid "``user`` - An ElggUser instance"
msgstr ""

#: ../../guides/hooks-list.rst:1017
#: ../../guides/hooks-list.rst:1025
msgid "``plugin`` - An ElggPlugin instance"
msgstr ""

#: ../../guides/hooks-list.rst:1018
#: ../../guides/hooks-list.rst:1026
msgid "``plugin_id`` - The plugin ID"
msgstr ""

#: ../../guides/hooks-list.rst:1019
#: ../../guides/hooks-list.rst:1027
msgid "``name`` - The name of the setting"
msgstr ""

#: ../../guides/hooks-list.rst:1020
#: ../../guides/hooks-list.rst:1028
msgid "``value`` - The value to set"
msgstr ""

#: ../../guides/hooks-list.rst:1028
msgid "**setting, plugin**"
msgstr ""

#: ../../guides/hooks-list.rst:1023
msgid "Filter plugin settings. ``$params`` contains:"
msgstr ""

#: ../../guides/hooks-list.rst:1031
msgid "**relationship:url, <relationship_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:1031
msgid "Filter the URL for the relationship object ``$params['relationship']``."
msgstr ""

#: ../../guides/hooks-list.rst:1035
msgid "**profile:fields, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1034
#: ../../guides/hooks-list.rst:1045
msgid "Filter an array of profile fields. The result should be returned as an array in the format ``name => input view name``. For example:"
msgstr ""

#: ../../guides/hooks-list.rst:1046
msgid "**profile:fields, profile**"
msgstr ""

#: ../../guides/hooks-list.rst:1056
msgid "**widget_settings, <widget_handler>**"
msgstr ""

#: ../../guides/hooks-list.rst:1055
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:1060
msgid "**handlers, widgets**"
msgstr ""

#: ../../guides/hooks-list.rst:1059
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:1064
msgid "**get_list, default_widgets**"
msgstr ""

#: ../../guides/hooks-list.rst:1063
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:1083
msgid "**public_pages, walled_garden**"
msgstr ""

#: ../../guides/hooks-list.rst:1076
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:1083
msgid "``url`` - URL of the page being tested for public accessibility"
msgstr ""

#: ../../guides/hooks-list.rst:1088
msgid "**volatile, metadata**"
msgstr ""

#: ../../guides/hooks-list.rst:1086
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:1092
msgid "**maintenance:allow, url**"
msgstr ""

#: ../../guides/hooks-list.rst:1092
msgid "Return boolean if the URL ``$params['current_url']`` and the path ``$params['current_path']``"
msgstr ""

#: ../../guides/hooks-list.rst:1092
msgid "is allowed during maintenance mode."
msgstr ""

#: ../../guides/hooks-list.rst:1095
msgid "**robots.txt, site**"
msgstr ""

#: ../../guides/hooks-list.rst:1095
msgid "Filter the robots.txt values for ``$params['site']``."
msgstr ""

#: ../../guides/hooks-list.rst:1098
msgid "**config, amd**"
msgstr ""

#: ../../guides/hooks-list.rst:1098
msgid "Filter the AMD config for the requirejs library."
msgstr ""

#: ../../guides/hooks-list.rst:1104
msgid "Embed"
msgstr ""

#: ../../guides/hooks-list.rst:1106
msgid "**embed_get_items, <active_section>**"
msgstr ""

#: ../../guides/hooks-list.rst:1108
msgid "**embed_get_sections, all**"
msgstr ""

#: ../../guides/hooks-list.rst:1110
msgid "**embed_get_upload_sections, all**"
msgstr ""

#: ../../guides/hooks-list.rst:1113
msgid "Groups"
msgstr ""

#: ../../guides/hooks-list.rst:1116
msgid "**profile_buttons, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1116
msgid "Filters buttons (``ElggMenuItem`` instances) to be registered in the title menu of the group profile page"
msgstr ""

#: ../../guides/hooks-list.rst:1125
msgid "**tool_options, group**"
msgstr ""

#: ../../guides/hooks-list.rst:1119
msgid "Filters a collection of tools available within a specific group:"
msgstr ""

#: ../../guides/hooks-list.rst:1121
msgid "The ``$return`` is ``\\Elgg\\Collections\\Collection<\\Elgg\\Groups\\Tool>``, a collection of group tools."
msgstr ""

#: ../../guides/hooks-list.rst:1125
msgid "``entity`` - ``\\ElggGroup``"
msgstr ""

#: ../../guides/hooks-list.rst:1128
msgid "HTMLawed"
msgstr ""

#: ../../guides/hooks-list.rst:1131
msgid "**allowed_styles, htmlawed**"
msgstr ""

#: ../../guides/hooks-list.rst:1131
msgid "Filter the HTMLawed allowed style array."
msgstr ""

#: ../../guides/hooks-list.rst:1134
msgid "**config, htmlawed**"
msgstr ""

#: ../../guides/hooks-list.rst:1134
msgid "Filter the HTMLawed ``$config`` array."
msgstr ""

#: ../../guides/hooks-list.rst:1137
msgid "**spec, htmlawed**"
msgstr ""

#: ../../guides/hooks-list.rst:1137
msgid "Filter the HTMLawed ``$spec`` string (default empty)."
msgstr ""

#: ../../guides/hooks-list.rst:1140
msgid "Likes"
msgstr ""

#: ../../guides/hooks-list.rst:1146
msgid "**likes:is_likable, <type>:<subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:1143
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:1146
msgid "The callback ``'Elgg\\Values::getTrue'`` is a useful handler for this hook."
msgstr ""

#: ../../guides/hooks-list.rst:1149
msgid "Members"
msgstr ""

#: ../../guides/hooks-list.rst:1152
msgid "**members:list, <page_segment>**"
msgstr ""

#: ../../guides/hooks-list.rst:1152
msgid "To handle the page ``/members/$page_segment``, register for this hook and return the HTML of the list."
msgstr ""

#: ../../guides/hooks-list.rst:1156
msgid "**members:config, tabs**"
msgstr ""

#: ../../guides/hooks-list.rst:1155
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:1159
msgid "Reported Content"
msgstr ""

#: ../../guides/hooks-list.rst:1162
msgid "**reportedcontent:add, system**"
msgstr ""

#: ../../guides/hooks-list.rst:1162
msgid "Triggered after adding the reported content object ``$params['report']``. Return false to delete report."
msgstr ""

#: ../../guides/hooks-list.rst:1165
msgid "**reportedcontent:archive, system**"
msgstr ""

#: ../../guides/hooks-list.rst:1165
msgid "Triggered before archiving the reported content object ``$params['report']``. Return false to prevent archiving."
msgstr ""

#: ../../guides/hooks-list.rst:1169
msgid "**reportedcontent:delete, system**"
msgstr ""

#: ../../guides/hooks-list.rst:1168
msgid "Triggered before deleting the reported content object ``$params['report']``. Return false to prevent deleting."
msgstr ""

#: ../../guides/hooks-list.rst:1172
msgid "Web Services"
msgstr ""

#: ../../guides/hooks-list.rst:1176
msgid "**rest, init**"
msgstr ""

#: ../../guides/hooks-list.rst:1175
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:1178
msgid "**rest:output, <method_name>**"
msgstr ""

#: ../../guides/hooks-list.rst:1179
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:106
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:273
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:46
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:51
msgid "The definition function **must** have one argument named ``require``."
msgstr ""

#: ../../guides/javascript.rst:54
msgid "Making modules dependent on other modules"
msgstr ""

#: ../../guides/javascript.rst:56
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:83
msgid "Passing settings to modules"
msgstr ""

#: ../../guides/javascript.rst:86
msgid "The ``elgg.data`` plugin hooks"
msgstr ""

#: ../../guides/javascript.rst:88
msgid "The ``elgg`` module provides an object ``elgg.data`` which is populated from two server side hooks:"
msgstr ""

#: ../../guides/javascript.rst:90
msgid "**elgg.data, site**: This filters an associative array of site-specific data passed to the client and cached."
msgstr ""

#: ../../guides/javascript.rst:91
msgid "**elgg.data, page**: This filters an associative array of uncached, page-specific data passed to the client."
msgstr ""

#: ../../guides/javascript.rst:93
msgid "Let's pass some data to a module:"
msgstr ""

#: ../../guides/javascript.rst:130
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:134
msgid "Making a config module"
msgstr ""

#: ../../guides/javascript.rst:136
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:152
msgid "You must also manually register the view as an external resource:"
msgstr ""

#: ../../guides/javascript.rst:162
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:167
msgid "Setting the URL of a module"
msgstr ""

#: ../../guides/javascript.rst:169
msgid "You may have an AMD script outside your views you wish to make available as a module."
msgstr ""

#: ../../guides/javascript.rst:171
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:185
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:199
msgid "That's it! Elgg will now load this file whenever the \"underscore\" module is requested."
msgstr ""

#: ../../guides/javascript.rst:203
msgid "Using traditional JS libraries as modules"
msgstr ""

#: ../../guides/javascript.rst:205
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:217
msgid "When this is requested client-side:"
msgstr ""

#: ../../guides/javascript.rst:219
msgid "The jQuery module is loaded, as it's marked as a dependency."
msgstr ""

#: ../../guides/javascript.rst:220
msgid "``https://elgg.example.org/cache/125235034/views/default/jquery.form.js`` is loaded and executed."
msgstr ""

#: ../../guides/javascript.rst:221
msgid "The value of ``window.jQuery.fn.ajaxForm`` is returned by the module."
msgstr ""

#: ../../guides/javascript.rst:223
msgid "Calls to ``elgg_define_js()`` must be in an ``init, system`` event handler."
msgstr ""

#: ../../guides/javascript.rst:226
msgid "Some things to note"
msgstr ""

#: ../../guides/javascript.rst:228
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:230
msgid "Return the value of the module instead of adding to a global variable."
msgstr ""

#: ../../guides/javascript.rst:231
msgid "Static (.js,.css,etc.) files are automatically minified and cached by Elgg's simplecache system."
msgstr ""

#: ../../guides/javascript.rst:232
msgid "The configuration is also cached in simplecache, and should not rely on user-specific values like ``get_current_language()``."
msgstr ""

#: ../../guides/javascript.rst:238
msgid "Booting your plugin"
msgstr ""

#: ../../guides/javascript.rst:240
msgid "To add functionality to each page, or make sure your hook handlers are registered early enough, you may create a boot module for your plugin, with the name ``boot/<plugin_id>``."
msgstr ""

#: ../../guides/javascript.rst:261
msgid "When your plugin is active, this module will automatically be loaded on each page. Other modules can depend on ``elgg/init`` to make sure all boot modules are loaded."
msgstr ""

#: ../../guides/javascript.rst:263
msgid "Each boot module **must** return an instance of ``elgg/Plugin``. The constructor must receive an object with a function in the ``init`` key. The ``init`` function will be called in the order of the plugin in Elgg's admin area."
msgstr ""

#: ../../guides/javascript.rst:265
msgid "Though not strictly necessary, you may want to use the ``init, system`` event to control when your initialization code runs with respect to other modules."
msgstr ""

#: ../../guides/javascript.rst:267
msgid "A boot module **cannot** depend on the modules ``elgg/init`` or ``elgg/ready``."
msgstr ""

#: ../../guides/javascript.rst:270
msgid "Modules provided with Elgg"
msgstr ""

#: ../../guides/javascript.rst:273
msgid "Modules ``jquery`` and ``jquery-ui``"
msgstr ""

#: ../../guides/javascript.rst:275
msgid "You must depend on these modules to use ``$`` or ``$.ui`` methods. In the future Elgg may stop loading these by default."
msgstr ""

#: ../../guides/javascript.rst:278
msgid "Module ``elgg``"
msgstr ""

#: ../../guides/javascript.rst:280
msgid "``elgg.echo()``"
msgstr ""

#: ../../guides/javascript.rst:282
msgid "Translate interface text"
msgstr ""

#: ../../guides/javascript.rst:289
msgid "``elgg.system_message()``"
msgstr ""

#: ../../guides/javascript.rst:291
msgid "Display a status message to the user."
msgstr ""

#: ../../guides/javascript.rst:298
msgid "``elgg.register_error()``"
msgstr ""

#: ../../guides/javascript.rst:300
msgid "Display an error message to the user."
msgstr ""

#: ../../guides/javascript.rst:307
msgid "``elgg.normalize_url()``"
msgstr ""

#: ../../guides/javascript.rst:309
msgid "Normalize a URL relative to the elgg root:"
msgstr ""

#: ../../guides/javascript.rst:316
msgid "``elgg.forward()``"
msgstr ""

#: ../../guides/javascript.rst:318
msgid "Redirect to a new page."
msgstr ""

#: ../../guides/javascript.rst:324
msgid "This function automatically normalizes the URL."
msgstr ""

#: ../../guides/javascript.rst:327
msgid "``elgg.parse_url()``"
msgstr ""

#: ../../guides/javascript.rst:329
msgid "Parse a URL into its component parts:"
msgstr ""

#: ../../guides/javascript.rst:342
msgid "``elgg.get_page_owner_guid()``"
msgstr ""

#: ../../guides/javascript.rst:344
msgid "Get the GUID of the current page's owner."
msgstr ""

#: ../../guides/javascript.rst:347
msgid "``elgg.register_hook_handler()``"
msgstr ""

#: ../../guides/javascript.rst:349
msgid "Register a hook handler with the event system. For best results, do this in a plugin boot module."
msgstr ""

#: ../../guides/javascript.rst:364
msgid "``elgg.trigger_hook()``"
msgstr ""

#: ../../guides/javascript.rst:366
msgid "Emit a hook event in the event system. For best results depend on the elgg/init module."
msgstr ""

#: ../../guides/javascript.rst:381
msgid "``elgg.security.refreshToken()``"
msgstr ""

#: ../../guides/javascript.rst:383
msgid "Force a refresh of all XSRF tokens on the page."
msgstr ""

#: ../../guides/javascript.rst:385
msgid "This is automatically called every 5 minutes by default."
msgstr ""

#: ../../guides/javascript.rst:387
msgid "The user will be warned if their session has expired."
msgstr ""

#: ../../guides/javascript.rst:390
msgid "``elgg.security.addToken()``"
msgstr ""

#: ../../guides/javascript.rst:392
msgid "Add a security token to an object, URL, or query string:"
msgstr ""

#: ../../guides/javascript.rst:410
msgid "``elgg.get_logged_in_user_entity()``"
msgstr ""

#: ../../guides/javascript.rst:412
msgid "Returns the logged in user as an JS ElggUser object."
msgstr ""

#: ../../guides/javascript.rst:415
msgid "``elgg.get_logged_in_user_guid()``"
msgstr ""

#: ../../guides/javascript.rst:417
msgid "Returns the logged in user's guid."
msgstr ""

#: ../../guides/javascript.rst:420
msgid "``elgg.is_logged_in()``"
msgstr ""

#: ../../guides/javascript.rst:422
msgid "True if the user is logged in."
msgstr ""

#: ../../guides/javascript.rst:425
msgid "``elgg.is_admin_logged_in()``"
msgstr ""

#: ../../guides/javascript.rst:427
msgid "True if the user is logged in and is an admin."
msgstr ""

#: ../../guides/javascript.rst:430
msgid "``elgg.config.get_language()``"
msgstr ""

#: ../../guides/javascript.rst:432
msgid "Get the current page's language."
msgstr ""

#: ../../guides/javascript.rst:435
msgid "There are a number of configuration values set in the elgg object:"
msgstr ""

#: ../../guides/javascript.rst:451
msgid "Module ``elgg/Ajax``"
msgstr ""

#: ../../guides/javascript.rst:453
msgid "See the :doc:`ajax` page for details."
msgstr ""

#: ../../guides/javascript.rst:456
msgid "Module ``elgg/init``"
msgstr ""

#: ../../guides/javascript.rst:458
msgid "``elgg/init`` loads and initializes all boot modules in priority order and triggers the [init, system] hook."
msgstr ""

#: ../../guides/javascript.rst:460
#: ../../guides/javascript.rst:472
msgid "Require this module to make sure all plugins are ready."
msgstr ""

#: ../../guides/javascript.rst:463
msgid "Module ``elgg/Plugin``"
msgstr ""

#: ../../guides/javascript.rst:465
msgid "Used to create a :ref:`boot module <guides/javascript#boot>`."
msgstr ""

#: ../../guides/javascript.rst:468
msgid "Module ``elgg/ready``"
msgstr ""

#: ../../guides/javascript.rst:470
msgid "``elgg/ready`` loads and initializes all plugin boot modules in priority order."
msgstr ""

#: ../../guides/javascript.rst:475
msgid "Module ``elgg/spinner``"
msgstr ""

#: ../../guides/javascript.rst:477
msgid "The ``elgg/spinner`` module can be used to create an Ajax loading indicator fixed to the top of the window."
msgstr ""

#: ../../guides/javascript.rst:493
msgid "The ``elgg/Ajax`` module uses the spinner by default."
msgstr ""

#: ../../guides/javascript.rst:496
msgid "Module ``elgg/popup``"
msgstr ""

#: ../../guides/javascript.rst:498
msgid "The ``elgg/popup`` module can be used to display an overlay positioned relatively to its anchor (trigger)."
msgstr ""

#: ../../guides/javascript.rst:500
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:533
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:558
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:587
msgid "Open popup modules will always contain the following data that can be accessed via ``$.data()``:"
msgstr ""

#: ../../guides/javascript.rst:589
msgid "``trigger`` - jQuery element used to trigger the popup module to open"
msgstr ""

#: ../../guides/javascript.rst:590
msgid "``position`` - An object defining popup module position that was passed to ``$.position()``"
msgstr ""

#: ../../guides/javascript.rst:592
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:595
msgid "Module ``elgg/widgets``"
msgstr ""

#: ../../guides/javascript.rst:597
msgid "Plugins that load a widget layout via Ajax should initialize via this module:"
msgstr ""

#: ../../guides/javascript.rst:606
msgid "Module ``elgg/lightbox``"
msgstr ""

#: ../../guides/javascript.rst:608
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:610
msgid "Use the following classes to bind your anchor elements to a lightbox:"
msgstr ""

#: ../../guides/javascript.rst:612
msgid "``elgg-lightbox`` - loads an HTML resource"
msgstr ""

#: ../../guides/javascript.rst:613
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:614
msgid "``elgg-lightbox-inline`` - displays an inline HTML element in a lightbox"
msgstr ""

#: ../../guides/javascript.rst:615
msgid "``elgg-lightbox-iframe`` - loads a resource in an ``iframe``"
msgstr ""

#: ../../guides/javascript.rst:617
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:630
msgid "Use ``\"getOptions\", \"ui.lightbox\"`` plugin hook to filter options passed to ``$.colorbox()`` whenever a lightbox is opened. Note that the hook handler should depend on ``elgg/init`` AMD module."
msgstr ""

#: ../../guides/javascript.rst:632
msgid "``elgg/lightbox`` AMD module should be used to open and close the lightbox programmatically:"
msgstr ""

#: ../../guides/javascript.rst:653
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:665
msgid "You can also resize the lightbox programmatically if needed:"
msgstr ""

#: ../../guides/javascript.rst:678
msgid "Module ``elgg/ckeditor``"
msgstr ""

#: ../../guides/javascript.rst:680
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:705
msgid "Inline tabs component"
msgstr ""

#: ../../guides/javascript.rst:707
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:728
msgid "Traditional scripts"
msgstr ""

#: ../../guides/javascript.rst:730
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:738
msgid "Hooks"
msgstr ""

#: ../../guides/javascript.rst:740
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:743
msgid "Registering hook handlers"
msgstr ""

#: ../../guides/javascript.rst:745
msgid "Handler functions are registered using ``elgg.register_hook_handler()``. Multiple handlers can be registered for the same hook."
msgstr ""

#: ../../guides/javascript.rst:747
msgid "The following example registers the ``handleFoo`` function for the ``foo, bar`` hook."
msgstr ""

#: ../../guides/javascript.rst:765
msgid "The handler function"
msgstr ""

#: ../../guides/javascript.rst:767
msgid "The handler will receive 4 arguments:"
msgstr ""

#: ../../guides/javascript.rst:769
msgid "**hook** - The hook name"
msgstr ""

#: ../../guides/javascript.rst:770
msgid "**type** - The hook type"
msgstr ""

#: ../../guides/javascript.rst:771
msgid "**params** - An object or set of parameters specific to the hook"
msgstr ""

#: ../../guides/javascript.rst:772
msgid "**value** - The current value"
msgstr ""

#: ../../guides/javascript.rst:774
msgid "The ``value`` will be passed through each hook. Depending on the hook, callbacks can simply react or alter data."
msgstr ""

#: ../../guides/javascript.rst:777
msgid "Triggering custom hooks"
msgstr ""

#: ../../guides/javascript.rst:779
msgid "Plugins can trigger their own hooks:"
msgstr ""

#: ../../guides/javascript.rst:790
msgid "Be aware of timing. If you don't depend on elgg/init, other plugins may not have had a chance to register their handlers."
msgstr ""

#: ../../guides/javascript.rst:793
msgid "Available hooks"
msgstr ""

#: ../../guides/javascript.rst:796
msgid "**init, system**"
msgstr ""

#: ../../guides/javascript.rst:796
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. Depend on the ``elgg/init`` module to be sure this has completed."
msgstr ""

#: ../../guides/javascript.rst:799
msgid "**ready, system**"
msgstr ""

#: ../../guides/javascript.rst:799
msgid "This hook is fired when the system has fully booted (after init). Depend on the ``elgg/ready`` module to be sure this has completed."
msgstr ""

#: ../../guides/javascript.rst:802
msgid "**getOptions, ui.popup**"
msgstr ""

#: ../../guides/javascript.rst:802
msgid "This hook is fired for pop up displays (``\"rel\"=\"popup\"``) and allows for customized placement options."
msgstr ""

#: ../../guides/javascript.rst:805
msgid "**getOptions, ui.lightbox**"
msgstr ""

#: ../../guides/javascript.rst:805
msgid "This hook can be used to filter options passed to ``$.colorbox()``"
msgstr ""

#: ../../guides/javascript.rst:808
msgid "**config, ckeditor**"
msgstr ""

#: ../../guides/javascript.rst:808
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:811
msgid "**prepare, ckeditor**"
msgstr ""

#: ../../guides/javascript.rst:811
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:815
msgid "**ajax_request_data, \\***"
msgstr ""

#: ../../guides/javascript.rst:814
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:818
msgid "**ajax_response_data, \\***"
msgstr ""

#: ../../guides/javascript.rst:818
msgid "This filters the response data returned to users of the ``elgg/Ajax`` module. See :doc:`ajax` for details."
msgstr ""

#: ../../guides/javascript.rst:821
msgid "**insert, editor**"
msgstr ""

#: ../../guides/javascript.rst:821
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:824
msgid "Third-party assets"
msgstr ""

#: ../../guides/javascript.rst:826
msgid "We recommend managing third-party scripts and styles with Composer. Elgg's composer.json is configured to install dependencies from the **Bower** 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:831
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:834
msgid "For example, to include jQuery, you could run the following Composer commands:"
msgstr ""

#: ../../guides/javascript.rst:841
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:860
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:72
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:74
msgid "**Example 1:** Change the URL for menu item called \"albums\" in the ``owner_block`` menu:"
msgstr ""

#: ../../guides/menus.rst:112
msgid "**Example 2:** Modify the ``entity`` menu for the ``ElggBlog`` objects"
msgstr ""

#: ../../guides/menus.rst:111
msgid "Remove the thumb icon"
msgstr ""

#: ../../guides/menus.rst:112
msgid "Change the \"Edit\" text into a custom icon"
msgstr ""

#: ../../guides/menus.rst:148
msgid "Creating a new menu"
msgstr ""

#: ../../guides/menus.rst:150
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:156
msgid "**Example:** Display a menu called \"my_menu\" that displays it's menu items in alphapetical order:"
msgstr ""

#: ../../guides/menus.rst:164
msgid "You can now add new items to the menu like this:"
msgstr ""

#: ../../guides/menus.rst:175
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:179
msgid "Child Dropdown Menus"
msgstr ""

#: ../../guides/menus.rst:181
msgid "Child menus can be configured using ``child_menu`` factory option on the parent item."
msgstr ""

#: ../../guides/menus.rst:183
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:224
msgid "Theming"
msgstr ""

#: ../../guides/menus.rst:226
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:231
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:244
msgid "Toggling Menu Items"
msgstr ""

#: ../../guides/menus.rst:246
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:269
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:275
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. 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:173
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:177
msgid "Registering a new notification method"
msgstr ""

#: ../../guides/notifications.rst:179
msgid "By default Elgg has two notification methods: email and the bundled site_notifications plugin. You can register a new notification method with the `elgg_register_notification_method()`__ function."
msgstr ""

#: ../../guides/notifications.rst:188
msgid "Register a handler that will send the notifications via SMS."
msgstr ""

#: ../../guides/notifications.rst:199
msgid "After registering the new method, it will appear to the notification settings page at ``www.example.com/notifications/personal/[username]``."
msgstr ""

#: ../../guides/notifications.rst:203
msgid "Sending the notifications using your own method"
msgstr ""

#: ../../guides/notifications.rst:205
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:249
msgid "Subscriptions"
msgstr ""

#: ../../guides/notifications.rst:251
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:256
msgid "Subscriptions can however be:"
msgstr ""

#: ../../guides/notifications.rst:255
msgid "Added using the `elgg_add_subscription()`__ function"
msgstr ""

#: ../../guides/notifications.rst:256
msgid "Removed using the `elgg_remove_subscription()`__ function"
msgstr ""

#: ../../guides/notifications.rst:261
msgid "It's possible to modify the recipients of a notification dynamically with the ``'get', 'subscriptions'`` hook."
msgstr ""

#: ../../guides/notifications.rst:300
msgid "E-mail attachments"
msgstr ""

#: ../../guides/notifications.rst:302
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/notifications.rst:305
msgid "An ``ElggFile`` which points to an existing file"
msgstr ""

#: ../../guides/notifications.rst:306
msgid "An array with the file contents"
msgstr ""

#: ../../guides/notifications.rst:307
msgid "An array with a filepath"
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:10
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:13
msgid "Custom page owner handlers"
msgstr ""

#: ../../guides/page-owner.rst:15
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:17
msgid "By default, the system uses ``default_page_owner_handler()`` to determine the page_owner from the following elements:"
msgstr ""

#: ../../guides/page-owner.rst:19
msgid "The ``username`` URL parameter"
msgstr ""

#: ../../guides/page-owner.rst:20
msgid "The ``owner_guid`` URL parameter"
msgstr ""

#: ../../guides/page-owner.rst:21
msgid "The URL path"
msgstr ""

#: ../../guides/page-owner.rst:23
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 ``manifest.xml`` 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 "``bootstrap`` - defines a class used to bootstrap the plugin"
msgstr ""

#: ../../guides/plugins.rst:18
msgid "``entities`` - defines entity types and classes, and optionally registers them for search"
msgstr ""

#: ../../guides/plugins.rst:19
msgid "``actions`` - eliminates the need for calling ``elgg_register_action()``"
msgstr ""

#: ../../guides/plugins.rst:20
msgid "``routes`` - eliminates the need for calling ``elgg_register_route()``"
msgstr ""

#: ../../guides/plugins.rst:21
msgid "``settings`` - eliminates the need for setting default values on each call to ``elgg_get_plugin_setting()``"
msgstr ""

#: ../../guides/plugins.rst:22
msgid "``user_settings`` - eliminates the need for setting default values on each call to ``elgg_get_plugin_user_setting()``"
msgstr ""

#: ../../guides/plugins.rst:23
msgid "``views`` - allows plugins to alias vendor assets to a path within the Elgg's view system"
msgstr ""

#: ../../guides/plugins.rst:24
msgid "``widgets`` - eliminates the need for calling ``elgg_register_widget_type()``"
msgstr ""

#: ../../guides/plugins.rst:25
msgid "``events`` - eliminates the need for calling ``elgg_register_event_handler()``"
msgstr ""

#: ../../guides/plugins.rst:26
msgid "``hooks`` - eliminates the need for calling ``elgg_register_plugin_hook_handler()``"
msgstr ""

#: ../../guides/plugins.rst:27
msgid "``cli_commands`` - an array of ``Elgg/Cli/Command`` classes to extend the feature of ``elgg-cli``"
msgstr ""

#: ../../guides/plugins.rst:28
msgid "``view_extensions`` - eliminates the need for calling ``elgg_extend_view()`` or ``elgg_unextend_view()``"
msgstr ""

#: ../../guides/plugins.rst:29
msgid "``theme`` - an array of theme variables"
msgstr ""

#: ../../guides/plugins.rst:175
msgid "Bootstrap class"
msgstr ""

#: ../../guides/plugins.rst:177
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:180
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:184
msgid "For more information about the different functions defined in the ``\\Elgg\\PluginBootstrapInterface`` please read  :doc:`plugins/bootstrap`"
msgstr ""

#: ../../guides/plugins.rst:187
msgid "start.php"
msgstr ""

#: ../../guides/plugins.rst:189
msgid "The ``start.php`` file bootstraps plugin by registering event listeners and plugin hooks."
msgstr ""

#: ../../guides/plugins.rst:191
msgid "It is advised that plugins return an instance of Closure from the ``start.php`` instead of placing registrations in the root of the file. This allows for consistency in Application bootstrapping, especially for testing purposes."
msgstr ""

#: ../../guides/plugins.rst:215
msgid "elgg-services.php"
msgstr ""

#: ../../guides/plugins.rst:217
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:220
msgid "This file must return an array of PHP-DI definitions. Services will by available via ``elgg()``."
msgstr ""

#: ../../guides/plugins.rst:228
msgid "Plugins can then use PHP-DI API to autowire and call the service:"
msgstr ""

#: ../../guides/plugins.rst:234
msgid "See `PHP-DI documentation <http://php-di.org>`_ for a comprehensive list of definition and invokation possibilities."
msgstr ""

#: ../../guides/plugins.rst:237
#: ../../guides/plugins.rst:260
msgid "Syntax"
msgstr ""

#: ../../guides/plugins.rst:239
msgid "Here's a trivial example configuring view locations via the ``views`` key:"
msgstr ""

#: ../../guides/plugins.rst:252
msgid "manifest.xml"
msgstr ""

#: ../../guides/plugins.rst:254
msgid "Elgg plugins are required to have a ``manifest.xml`` file in the root of a plugin."
msgstr ""

#: ../../guides/plugins.rst:256
msgid "The ``manifest.xml`` file includes information about the plugin itself, requirements to run the plugin, and optional information including where to display the plugin in the admin area and what APIs the plugin provides."
msgstr ""

#: ../../guides/plugins.rst:262
msgid "The manifest file is a standard XML file in UTF-8. Everything is a child of the ``<plugin_manifest>`` element."
msgstr ""

#: ../../guides/plugins.rst:269
msgid "The manifest syntax is as follows:"
msgstr ""

#: ../../guides/plugins.rst:275
msgid "Many elements can contain children attributes:"
msgstr ""

#: ../../guides/plugins.rst:285
msgid "Required Elements"
msgstr ""

#: ../../guides/plugins.rst:287
msgid "All plugins are required to define the following elements in their manifest files:"
msgstr ""

#: ../../guides/plugins.rst:289
msgid "id - This has the name as the directory that the plugin uses."
msgstr ""

#: ../../guides/plugins.rst:290
msgid "name - The display name of the plugin."
msgstr ""

#: ../../guides/plugins.rst:291
msgid "author - The name of the author who wrote the plugin."
msgstr ""

#: ../../guides/plugins.rst:292
msgid "version - The version of the plugin."
msgstr ""

#: ../../guides/plugins.rst:293
msgid "description - A description of the what the plugin provides, its features, and other relevant information"
msgstr ""

#: ../../guides/plugins.rst:294
msgid "requires - Each plugin must specify the release of Elgg it was developed for. See the plugin Dependencies page for more information."
msgstr ""

#: ../../guides/plugins.rst:297
msgid "Available Elements"
msgstr ""

#: ../../guides/plugins.rst:299
msgid "In addition to the require elements above, the follow elements are available to use:"
msgstr ""

#: ../../guides/plugins.rst:301
msgid "blurb - A short description of the plugin."
msgstr ""

#: ../../guides/plugins.rst:302
msgid "category - The category of the plugin. It is recommended to follow the :doc:`guidelines` and use one of the defined categories. There can be multiple entries."
msgstr ""

#: ../../guides/plugins.rst:304
msgid "conflicts - Specifies that the plugin conflicts with a certain system configuration."
msgstr ""

#: ../../guides/plugins.rst:305
msgid "copyright - The plugin's copyright information."
msgstr ""

#: ../../guides/plugins.rst:306
msgid "license - The plugin's license information."
msgstr ""

#: ../../guides/plugins.rst:307
msgid "provides - Specifies that this plugin provides the same functionality as another Elgg plugin or a PHP extension."
msgstr ""

#: ../../guides/plugins.rst:308
msgid "suggests - Parallels the requires system, but doesn't affect if the plugin can be enabled. Used to suggest other plugins that interact or build on the plugin."
msgstr ""

#: ../../guides/plugins.rst:310
msgid "website - A link to the website for the plugin."
msgstr ""

#: ../../guides/plugins.rst:314
msgid ":doc:`plugins/dependencies`"
msgstr ""

#: ../../guides/plugins.rst:317
msgid "Simple Example"
msgstr ""

#: ../../guides/plugins.rst:319
msgid "This manifest file is the bare minimum a plugin must have."
msgstr ""

#: ../../guides/plugins.rst:337
msgid "Advanced example"
msgstr ""

#: ../../guides/plugins.rst:339
msgid "This example uses all of the available elements:"
msgstr ""

#: ../../guides/plugins.rst:375
msgid "composer.json"
msgstr ""

#: ../../guides/plugins.rst:377
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:381
msgid "Here is an example of a ``composer.json`` file:"
msgstr ""

#: ../../guides/plugins.rst:386
msgid "Read more about the ``composer.json`` format on the `Composer`_ website."
msgstr ""

#: ../../guides/plugins.rst:388
msgid "Important parts in the ``composer.json`` file are:"
msgstr ""

#: ../../guides/plugins.rst:390
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:391
msgid "``type``: this will tell Composer where to install your plugin, ALWAYS keep this as ``elgg-plugin``"
msgstr ""

#: ../../guides/plugins.rst:392
msgid "``require``: the ``composer/installers`` requirement is to make sure Composer knows where to install your plugin"
msgstr ""

#: ../../guides/plugins.rst:394
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:397
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:401
msgid "Tests"
msgstr ""

#: ../../guides/plugins.rst:403
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:406
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:423
msgid "If you wish to see a better example, look in any of the Elgg core plugins."
msgstr ""

#: ../../guides/plugins.rst:427
msgid ":doc:`/contribute/tests`"
msgstr ""

#: ../../guides/plugins.rst:430
#: ../../guides/views.rst:644
#: ../../guides/web-services.rst:373
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 and before ``activate.php`` is included."
msgstr ""

#: ../../guides/plugins/bootstrap.rst:72
msgid "->deactivate()"
msgstr ""

#: ../../guides/plugins/bootstrap.rst:74
msgid "Executed when plugin is deactivated, after ``deactivate``, ``plugin`` event and before ``deactivate.php`` is included."
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 ``manifest.xml`` file. Plugin authors can specify that a plugin:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:15
msgid "Requires certain Elgg versions, Elgg plugins, PHP extensions, and PHP settings."
msgstr ""

#: ../../guides/plugins/dependencies.rst:16
msgid "Suggests certain Elgg versions, Elgg plugins, PHP extensions, and PHP settings."
msgstr ""

#: ../../guides/plugins/dependencies.rst:17
msgid "Conflicts with certain Elgg versions or Elgg plugins."
msgstr ""

#: ../../guides/plugins/dependencies.rst:18
msgid "Provides the equivalent of another Elgg plugin or PHP extension."
msgstr ""

#: ../../guides/plugins/dependencies.rst:20
msgid "The dependency system uses the four verbs above (``requires``, ``suggests``, ``conflicts``, and ``provides``) as parent elements to indicate what type of dependency is described by its children. All dependencies have a similar format with similar options:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:32
msgid "``type`` is always required"
msgstr ""

#: ../../guides/plugins/dependencies.rst:35
msgid "Verbs"
msgstr ""

#: ../../guides/plugins/dependencies.rst:37
msgid "With the exception of ``provides``, all verbs use the same six types with differing effects, and the type options are the same among the verbs. ``provides`` only supports ``plugin`` and ``php_extension``."
msgstr ""

#: ../../guides/plugins/dependencies.rst:40
msgid "Requires"
msgstr ""

#: ../../guides/plugins/dependencies.rst:42
msgid "Using a ``requires`` dependency means that the plugin cannot be enabled unless the dependency is exactly met."
msgstr ""

#: ../../guides/plugins/dependencies.rst:45
msgid "Mandatory requires: elgg_release"
msgstr ""

#: ../../guides/plugins/dependencies.rst:47
msgid "Every plugin must have at least one requires: the version of Elgg the plugin is developed for. This is specified by the Elgg API ``release`` (1.8). The default comparison ``>=``, but you can specify your own by passing the ``<comparison>`` element."
msgstr ""

#: ../../guides/plugins/dependencies.rst:49
msgid "Using elgg_release:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:59
msgid "Suggests"
msgstr ""

#: ../../guides/plugins/dependencies.rst:61
msgid "``suggests`` dependencies signify that the plugin author suggests a specific system configuration, but it is not required to use the plugin. The suggestions can also be another plugin itself which could interact, extend, or be extended by this plugin, but is not required for it to function."
msgstr ""

#: ../../guides/plugins/dependencies.rst:63
msgid "Suggest another plugin:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:73
msgid "Suggest a certain PHP setting:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:85
msgid "Conflicts"
msgstr ""

#: ../../guides/plugins/dependencies.rst:87
msgid "``conflicts`` dependencies mean the plugin cannot be used under a specific system configuration."
msgstr ""

#: ../../guides/plugins/dependencies.rst:89
msgid "Conflict with any version of the profile plugin:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:98
msgid "Conflict with a specific release of Elgg:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:109
msgid "Provides"
msgstr ""

#: ../../guides/plugins/dependencies.rst:111
msgid "``provides`` dependencies tell Elgg that this plugin is providing the functionality of another plugin or PHP extension. Unlike the other verbs, it only supports two types: ``plugin`` and ``php_extension``."
msgstr ""

#: ../../guides/plugins/dependencies.rst:113
msgid "The purpose of this is to provide interchangeable APIs implemented by different plugins. For example, the twitter_services plugin provides an API for other plugins to Tweet on behalf of the user via curl and Oauth. A plugin author could write a compatible plugin for servers without curl support that uses sockets streams and specify that it provides twitter_services. Any plugins that suggest or require twitter_services would then know they can work."
msgstr ""

#: ../../guides/plugins/dependencies.rst:125
msgid "All plugins provide themselves as their plugin id (directory name) at the version defined in the their manifest."
msgstr ""

#: ../../guides/plugins/dependencies.rst:128
msgid "Types"
msgstr ""

#: ../../guides/plugins/dependencies.rst:130
msgid "Every dependency verb has a mandatory ``<type>`` element that must be one of the following six values:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:132
msgid "**elgg_release** - The release version of Elgg (1.8)"
msgstr ""

#: ../../guides/plugins/dependencies.rst:133
msgid "**plugin** - An Elgg plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:134
msgid "**priority** - A plugin load priority"
msgstr ""

#: ../../guides/plugins/dependencies.rst:135
msgid "**php_extension** - A PHP extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:136
msgid "**php_ini** - A PHP setting"
msgstr ""

#: ../../guides/plugins/dependencies.rst:137
msgid "**php_version** - A PHP version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:141
msgid "``provides`` only supports ``plugin`` and ``php_extension`` types."
msgstr ""

#: ../../guides/plugins/dependencies.rst:143
msgid "Every type is defined with a dependency verb as the parent element. Additional option elements are at the same level as the type element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:154
msgid "elgg_release"
msgstr ""

#: ../../guides/plugins/dependencies.rst:156
msgid "These concern the API and release versions of Elgg and requires the following option element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:158
msgid "**version** - The API or release version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:160
#: ../../guides/plugins/dependencies.rst:219
msgid "The following option element is supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:162
#: ../../guides/plugins/dependencies.rst:174
#: ../../guides/plugins/dependencies.rst:221
msgid "**comparison** - The comparison operator to use. Defaults to >= if not passed"
msgstr ""

#: ../../guides/plugins/dependencies.rst:165
msgid "plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:167
msgid "Specifies an Elgg plugin by its ID (directory name). This requires the following option element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:169
msgid "**name** - The ID of the plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:171
#: ../../guides/plugins/dependencies.rst:191
msgid "The following option elements are supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:173
msgid "**version** - The version of the plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:177
msgid "priority"
msgstr ""

#: ../../guides/plugins/dependencies.rst:179
msgid "This requires the plugin to be loaded before or after another plugin, if that plugin exists. ``requires`` should be used to require that a plugin exists. The following option elements are required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:181
msgid "**plugin** - The plugin ID to base the load order on"
msgstr ""

#: ../../guides/plugins/dependencies.rst:182
msgid "**priority** - The load order: 'before' or 'after'"
msgstr ""

#: ../../guides/plugins/dependencies.rst:185
msgid "php_extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:187
msgid "This checks PHP extensions. The follow option element is required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:189
msgid "**name** - The name of the PHP extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:193
msgid "**version** - The version of the extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:194
#: ../../guides/plugins/dependencies.rst:210
msgid "**comparison** - The comparison operator to use. Defaults to =="
msgstr ""

#: ../../guides/plugins/dependencies.rst:198
msgid "The format of extension versions varies greatly among PHP extensions and is sometimes not even set. This is generally worthless to check."
msgstr ""

#: ../../guides/plugins/dependencies.rst:201
msgid "php_ini"
msgstr ""

#: ../../guides/plugins/dependencies.rst:203
msgid "This checks PHP settings. The following option elements are required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:205
msgid "**name** - The name of the setting to check"
msgstr ""

#: ../../guides/plugins/dependencies.rst:206
msgid "**value** - The value of the setting to compare against"
msgstr ""

#: ../../guides/plugins/dependencies.rst:208
msgid "The following options are supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:213
msgid "php_version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:215
msgid "This checks the PHP version. The following option elements are required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:217
msgid "**version** - The PHP version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:224
msgid "Comparison Operators"
msgstr ""

#: ../../guides/plugins/dependencies.rst:226
msgid "Dependencies that check versions support passing a custom operator via the ``<comparison>`` element."
msgstr ""

#: ../../guides/plugins/dependencies.rst:228
msgid "The follow are valid comparison operators:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:230
msgid "< or lt"
msgstr ""

#: ../../guides/plugins/dependencies.rst:231
msgid "<= or le"
msgstr ""

#: ../../guides/plugins/dependencies.rst:232
msgid "=, ==, or eq"
msgstr ""

#: ../../guides/plugins/dependencies.rst:233
msgid "!=, <>, or ne"
msgstr ""

#: ../../guides/plugins/dependencies.rst:234
msgid "> or gt"
msgstr ""

#: ../../guides/plugins/dependencies.rst:235
msgid ">= or ge"
msgstr ""

#: ../../guides/plugins/dependencies.rst:237
msgid "If ``<comparison>`` is not passed, the follow are used as defaults, depending upon the dependency type:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:239
msgid "requires->elgg_release: >="
msgstr ""

#: ../../guides/plugins/dependencies.rst:240
msgid "requires->plugin: >="
msgstr ""

#: ../../guides/plugins/dependencies.rst:241
msgid "requires->php_extension: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:242
msgid "requires->php_ini: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:243
msgid "all conflicts: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:247
msgid "You must escape < and > to ``&gt;`` and ``&lt;``. For comparisons that use these values, it is recommended you use the string equivalents instead!"
msgstr ""

#: ../../guides/plugins/dependencies.rst:250
msgid "Quick Examples"
msgstr ""

#: ../../guides/plugins/dependencies.rst:253
msgid "Requires Elgg 1.8.2 or higher"
msgstr ""

#: ../../guides/plugins/dependencies.rst:263
msgid "Requires the Groups plugin is active"
msgstr ""

#: ../../guides/plugins/dependencies.rst:273
msgid "Requires to be after the Profile plugin if Profile is active"
msgstr ""

#: ../../guides/plugins/dependencies.rst:284
msgid "Conflicts with The Wire plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:294
msgid "Requires at least 256 MB memory in PHP"
msgstr ""

#: ../../guides/plugins/dependencies.rst:307
msgid "Requires at least PHP version 5.3"
msgstr ""

#: ../../guides/plugins/dependencies.rst:317
msgid "Suggest the TidyPics plugin is loaded"
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:69
msgid "Required Files"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:71
msgid "Plugins **must** provide a ``manifest.xml`` file in the plugin root in order to be recognized by Elgg."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:73
msgid "Therefore the following is the minimally compliant structure:"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:83
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:85
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:87
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:90
msgid "Text Files"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:92
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:95
msgid "README.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:95
msgid "*should* provide additional information about the plugin of an unspecified nature"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:98
msgid "COPYRIGHT.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:98
msgid "If included, **must** provide an explanation of the plugin's copyright, besides what is included in ``manifest.xml``"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:101
msgid "LICENSE.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:101
msgid "If included, **must** provide the text of the license that the plugin is released under."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:104
msgid "INSTALL.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:104
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:107
msgid "CHANGES.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:107
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:109
msgid "Plugins *may* include additional \\*.txt files besides these, but no interface is given for reading them."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:112
msgid "Pages"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:114
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:119
msgid "The reason we encourage this structure is"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:121
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:122
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:125
msgid "Classes"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:127
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:129
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:133
msgid "Files with a \".class.php\" extension will **not** be recognized by Elgg."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:135
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:138
msgid "Vendors"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:140
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:145
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:147
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 ``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:332
msgid "The hook must be registered directly in your plugin ``start.php`` (the ``[init, system]`` event is too late)."
msgstr ""

#: ../../guides/routing.rst:336
msgid "Routing overview"
msgstr ""

#: ../../guides/routing.rst:338
msgid "For regular pages, Elgg's program flow is something like this:"
msgstr ""

#: ../../guides/routing.rst:340
msgid "A user requests ``http://example.com/news/owner/jane``."
msgstr ""

#: ../../guides/routing.rst:341
msgid "Plugins are initialized."
msgstr ""

#: ../../guides/routing.rst:342
msgid "Elgg parses the URL to identifier ``news`` and segments ``['owner', 'jane']``."
msgstr ""

#: ../../guides/routing.rst:343
msgid "Elgg triggers the plugin hook ``route:rewrite, news`` (see above)."
msgstr ""

#: ../../guides/routing.rst:344
msgid "Elgg triggers the plugin hook ``route, blog`` (was rewritten in the rewrite hook)."
msgstr ""

#: ../../guides/routing.rst:345
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:347
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:349
msgid "PHP invokes Elgg's shutdown sequence."
msgstr ""

#: ../../guides/routing.rst:350
msgid "The user receives a fully rendered page."
msgstr ""

#: ../../guides/routing.rst:352
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:133
msgid "Custom search types"
msgstr ""

#: ../../guides/search.rst:135
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:182
msgid "Autocomplete and livesearch endpoint"
msgstr ""

#: ../../guides/search.rst:184
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:192
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:4
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:6
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:7
msgid "Fill this file with the form elements you want to display together with :doc:`internationalised <i18n>` text labels"
msgstr ""

#: ../../guides/settings.rst:8
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:10
msgid "An example ``settings.php`` would look like:"
msgstr ""

#: ../../guides/settings.rst:27
msgid "You don’t need to add a save button or the form, this will be handled by the framework."
msgstr ""

#: ../../guides/settings.rst:31
msgid "You cannot use form components that send no value when \"off.\" These include radio inputs and check boxes."
msgstr ""

#: ../../guides/settings.rst:33
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:44
msgid "User settings"
msgstr ""

#: ../../guides/settings.rst:46
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:50
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:53
msgid "Retrieving settings in your code"
msgstr ""

#: ../../guides/settings.rst:55
msgid "To retrieve settings from your code use:"
msgstr ""

#: ../../guides/settings.rst:61
msgid "or for user settings"
msgstr ""

#: ../../guides/settings.rst:67
msgid "where:"
msgstr ""

#: ../../guides/settings.rst:69
msgid "``$name`` Is the value you want to retrieve"
msgstr ""

#: ../../guides/settings.rst:70
msgid "``$user_guid`` Is the user you want to retrieve these for (defaults to the currently logged in user)"
msgstr ""

#: ../../guides/settings.rst:71
msgid "``$plugin_name`` Is the name of the plugin (detected if run from within a plugin)"
msgstr ""

#: ../../guides/settings.rst:74
msgid "Setting values while in code"
msgstr ""

#: ../../guides/settings.rst:76
msgid "Values may also be set from within your plugin code, to do this use one of the following functions:"
msgstr ""

#: ../../guides/settings.rst:82
msgid "or"
msgstr ""

#: ../../guides/settings.rst:90
msgid "The ``$plugin_id`` needs to be provided when setting plugin (user)settings."
msgstr ""

#: ../../guides/settings.rst:93
msgid "Default plugin (user) settings"
msgstr ""

#: ../../guides/settings.rst:95
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:104
msgid "Alternatively you can also provide default plugin and user settings 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 start.php"
msgstr ""

#: ../../guides/themes.rst:220
msgid "Create a manifest.xml 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 extend view function from within your start.php’s initialization function."
msgstr ""

#: ../../guides/themes.rst:269
msgid "For example, the following start.php will add mytheme/css to Elgg's core css file:"
msgstr ""

#: ../../guides/themes.rst:284
msgid "View overloading"
msgstr ""

#: ../../guides/themes.rst:286
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:290
msgid "``/mod/myplugin/views/default/elements/typography.css``"
msgstr ""

#: ../../guides/themes.rst:292
msgid "it will replace:"
msgstr ""

#: ../../guides/themes.rst:294
msgid "``/views/default/elements/typography.css``"
msgstr ""

#: ../../guides/themes.rst:296
msgid "But only when the plugin is active."
msgstr ""

#: ../../guides/themes.rst:298
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:303
#: ../../guides/views.rst:592
msgid "Icons"
msgstr ""

#: ../../guides/themes.rst:305
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:308
msgid "``elgg_view_icon('icon-name');``"
msgstr ""

#: ../../guides/themes.rst:310
msgid "``icon-name`` can be any of the `FontAwesome icons`_ without the ``fa-``-prefix."
msgstr ""

#: ../../guides/themes.rst:312
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:319
msgid "Tools"
msgstr ""

#: ../../guides/themes.rst:321
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:326
msgid "Customizing the front page"
msgstr ""

#: ../../guides/themes.rst:327
msgid "The main Elgg index page runs a plugin hook called 'index,system'. If this returns true, it assumes that another front page has been drawn and doesn't display the default page."
msgstr ""

#: ../../guides/themes.rst:331
msgid "Therefore, you can override it by registering a function to the 'index,system' plugin hook and then returning true from that function."
msgstr ""

#: ../../guides/themes.rst:334
msgid "Here's a quick overview:"
msgstr ""

#: ../../guides/themes.rst:336
msgid "Create your new plugin"
msgstr ""

#: ../../guides/themes.rst:338
msgid "In the start.php you will need something like the following:"
msgstr ""

#: ../../guides/themes.rst:363
msgid "Then, create an index page (/pluginname/pages/index.php) and use that"
msgstr ""

#: ../../guides/themes.rst:361
msgid "to put the content you would like on the front page of your Elgg site."
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 Bower, 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 ``init,system`` event handler in ``start.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:378
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:380
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:382
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:369
msgid "Altering view output"
msgstr ""

#: ../../guides/views.rst:371
msgid "Sometimes it is preferable to alter the output of a view instead of overriding it."
msgstr ""

#: ../../guides/views.rst:373
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:377
msgid "``$hook`` - the string ``\"view\"``"
msgstr ""

#: ../../guides/views.rst:379
msgid "``$result`` - the modified output of the view"
msgstr ""

#: ../../guides/views.rst:384
msgid "To alter the view output, the handler just needs to alter ``$returnvalue`` and return a new string."
msgstr ""

#: ../../guides/views.rst:387
msgid "Altering view output example"
msgstr ""

#: ../../guides/views.rst:389
msgid "Here we'll eliminate breadcrumbs that don't have at least one link."
msgstr ""

#: ../../guides/views.rst:410
msgid "Replacing view output completely"
msgstr ""

#: ../../guides/views.rst:412
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:427
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:432
msgid "If you don't know what an entity is, :doc:`check this page out first </design/database>`."
msgstr ""

#: ../../guides/views.rst:434
msgid "The following code will automatically display the entity in ``$entity``:"
msgstr ""

#: ../../guides/views.rst:440
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:444
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:448
msgid "RSS feeds in Elgg generally work by outputting the ``object/default`` view in the 'rss' viewtype."
msgstr ""

#: ../../guides/views.rst:450
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:454
msgid "Full and partial entity views"
msgstr ""

#: ../../guides/views.rst:456
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:459
msgid "``$entity`` - The entity to display"
msgstr ""

#: ../../guides/views.rst:460
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:462
msgid "``$full_view`` - Whether to display a *full* version of the entity. (Defaults to ``true``.)"
msgstr ""

#: ../../guides/views.rst:464
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:471
msgid "Listing entities"
msgstr ""

#: ../../guides/views.rst:473
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:483
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:488
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:491
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:496
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:508
msgid "See also :doc:`this background information on Elgg's database </design/database>`."
msgstr ""

#: ../../guides/views.rst:510
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:524
msgid "Rendering a list with an alternate view"
msgstr ""

#: ../../guides/views.rst:526
msgid "You can define an alternative view to render list items using ``'item_view'`` parameter."
msgstr ""

#: ../../guides/views.rst:528
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:531
msgid "Consider these two examples:"
msgstr ""

#: ../../guides/views.rst:553
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:556
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:561
msgid "Rendering a list as a table"
msgstr ""

#: ../../guides/views.rst:563
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:568
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:587
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:594
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:597
msgid "Generic icons"
msgstr ""

#: ../../guides/views.rst:599
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:602
msgid "``$icon_name`` is the FontAwesome name (without ``fa-``) for example ``user``"
msgstr ""

#: ../../guides/views.rst:603
msgid "``$vars`` is optional, for example you can set an additional class"
msgstr ""

#: ../../guides/views.rst:605
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:608
msgid "For backwards compatibility some older Elgg icon names are translated to a corresponding FontAwesome icon."
msgstr ""

#: ../../guides/views.rst:611
msgid "Entity icons"
msgstr ""

#: ../../guides/views.rst:613
msgid "To view an icon belowing to an Entity call ``elgg_view_entity_icon($entity, $size, $vars);`` where:"
msgstr ""

#: ../../guides/views.rst:615
msgid "``$entity`` is the ``ElggEntity`` you wish to show the icon for"
msgstr ""

#: ../../guides/views.rst:616
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:618
msgid "``$vars`` in order to pass additional information to the icon view"
msgstr ""

#: ../../guides/views.rst:620
msgid "``elgg_view_entity_icon()`` calls a view in the order:"
msgstr ""

#: ../../guides/views.rst:622
msgid "``icon/<type>/<subtype>``"
msgstr ""

#: ../../guides/views.rst:623
msgid "``icon/<type>/default``"
msgstr ""

#: ../../guides/views.rst:624
msgid "``icon/default``"
msgstr ""

#: ../../guides/views.rst:626
msgid "So if you wish to customize the layout of the icon you can overrule the corresponding view."
msgstr ""

#: ../../guides/views.rst:628
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_register_js(array('location' => 'footer'));`` or ``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:9
msgid "Several of the older (deprecated) layouts are automatically rewritten to the ``default`` layout:"
msgstr ""

#: ../../guides/views/page-structure.rst:11
msgid "one_column"
msgstr ""

#: ../../guides/views/page-structure.rst:12
msgid "one_sidebar"
msgstr ""

#: ../../guides/views/page-structure.rst:13
msgid "two_sidebar"
msgstr ""

#: ../../guides/views/page-structure.rst:14
msgid "content"
msgstr ""

#: ../../guides/views/page-structure.rst:16
msgid "If you're not using the ``default`` layout you can call"
msgstr ""

#: ../../guides/views/page-structure.rst:25
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:41
msgid "You can then, ultimately, pass this into the ``elgg_view_page`` function:"
msgstr ""

#: ../../guides/views/page-structure.rst:47
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:56
msgid "You can control many of the page elements:"
msgstr ""

#: ../../guides/views/page-structure.rst:69
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``)"
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.rst:364
msgid "When testing, you may find it useful to register the ``pam_auth_session`` PAM so that you can easily test your methods from the browser. Be careful not to use this PAM on a production site because it could open up your users to a `CSRF attack`_."
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:8
msgid "The HMAC must be constructed over the following data:"
msgstr ""

#: ../../guides/web-services/hmac.rst:10
msgid "The public API key identifying you to the Elgg api server as provided by the APIAdmin plugin"
msgstr ""

#: ../../guides/web-services/hmac.rst:11
msgid "The private API Key provided by Elgg (that is companion to the public key)"
msgstr ""

#: ../../guides/web-services/hmac.rst:12
msgid "The current unix time in seconds"
msgstr ""

#: ../../guides/web-services/hmac.rst:13
msgid "A nonce to guarantee two requests the same second have different signatures"
msgstr ""

#: ../../guides/web-services/hmac.rst:14
msgid "URL encoded string representation of any GET variable parameters, eg ``method=test.test&foo=bar``"
msgstr ""

#: ../../guides/web-services/hmac.rst:15
msgid "If you are sending post data, the hash of this data"
msgstr ""

#: ../../guides/web-services/hmac.rst:17
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:19
msgid "**X-Elgg-apikey** - The public API key"
msgstr ""

#: ../../guides/web-services/hmac.rst:20
msgid "**X-Elgg-time** - Unix time used in the HMAC calculation"
msgstr ""

#: ../../guides/web-services/hmac.rst:21
msgid "**X-Elgg-none** - a random string"
msgstr ""

#: ../../guides/web-services/hmac.rst:22
msgid "**X-Elgg-hmac** - The HMAC as base64 encoded"
msgstr ""

#: ../../guides/web-services/hmac.rst:23
msgid "**X-Elgg-hmac-algo** - The algorithm used in the HMAC calculation - eg, sha1, md5 etc."
msgstr ""

#: ../../guides/web-services/hmac.rst:25
msgid "If you are sending POST data you must also send:"
msgstr ""

#: ../../guides/web-services/hmac.rst:27
msgid "**X-Elgg-posthash** - The hash of the POST data"
msgstr ""

#: ../../guides/web-services/hmac.rst:28
msgid "**X-Elgg-posthash-algo** - The algorithm used to produce the POST data hash - eg, md5"
msgstr ""

#: ../../guides/web-services/hmac.rst:29
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:30
msgid "**Content-Length** - The length in bytes of your POST data"
msgstr ""

#: ../../guides/web-services/hmac.rst:32
msgid "Elgg provides a sample API client that implements this HMAC signature: send_api_call(). It serves as a good reference on how to implement it."
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:164
msgid "Modify widget properties of existing widget registration"
msgstr ""

#: ../../guides/widgets.rst:165
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:184
msgid "Default widgets"
msgstr ""

#: ../../guides/widgets.rst:186
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:188
msgid "To announce default widget support in your plugin, register for the ``get_list, default_widgets`` plugin hook:"
msgstr ""

#: ../../guides/widgets.rst:194
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:196
msgid "name - The name of the widgets page. This is displayed on the tab in the admin interface."
msgstr ""

#: ../../guides/widgets.rst:197
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:198
msgid "widget\\_columns - How many columns the widgets page will use."
msgstr ""

#: ../../guides/widgets.rst:199
msgid "event - The Elgg event to create new widgets for. This is usually ``create``."
msgstr ""

#: ../../guides/widgets.rst:200
msgid "entity\\_type - The entity type to create new widgets for."
msgstr ""

#: ../../guides/widgets.rst:201
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:203
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 ""