Elgg-Lorea-Hydra/docs/locale/pot/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 1.12\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2016-03-06 18:02+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/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:0
#: ../../guides/database.rst:0
#: ../../guides/events-list.rst:0
#: ../../guides/guidelines.rst:0
#: ../../guides/hooks-list.rst:0
#: ../../guides/javascript.rst:0
#: ../../guides/menus.rst:0
#: ../../guides/notifications.rst:0
#: ../../guides/plugins/dependencies.rst:0
#: ../../guides/themes.rst:0
#: ../../guides/upgrading.rst:0
#: ../../guides/views.rst:0
#: ../../guides/web-services.rst:0
#: ../../guides/widgets.rst:0
msgid "Contents"
msgstr ""

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

#: ../../guides/actions.rst:21
msgid "Actions must be registered before use. Use ``elgg_register_action`` for this:"
msgstr ""

#: ../../guides/actions.rst:27
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:29
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."
msgstr ""

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

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

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

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

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

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

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

#: ../../guides/actions.rst:60
msgid "To redirect the page once you've completed your actions, use the ``forward`` function:"
msgstr ""

#: ../../guides/actions.rst:66
msgid "For example, to forward to the user's profile:"
msgstr ""

#: ../../guides/actions.rst:73
msgid "URLs can be relative to the Elgg root:"
msgstr ""

#: ../../guides/actions.rst:80
msgid "Redirect to the referring page by using the ``REFERRER`` constant:"
msgstr ""

#: ../../guides/actions.rst:87
msgid "Give feedback to the user about the status of the action by using ``system_message`` for positive feedback or ``register_error`` for warnings and errors:"
msgstr ""

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

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

#: ../../guides/actions.rst:108
msgid "Where ``$action`` is the action being called. If the hook returns ``false`` then the action will not be executed."
msgstr ""

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

#: ../../guides/actions.rst:113
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 ``true`` if valid or ``false`` if not (which prevents the associated action from executing)."
msgstr ""

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

#: ../../guides/actions.rst:137
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:140
msgid "To output a form, use the elgg_view_form function like so:"
msgstr ""

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

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

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

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

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

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

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

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

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

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

#: ../../guides/actions.rst:203
msgid "In your action file, use the ``$_FILES`` global to access the uploaded file:"
msgstr ""

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

#: ../../guides/actions.rst:212
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 1.8 includes helper functions so you can make any form sticky."
msgstr ""

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

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

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

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

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

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

#: ../../guides/actions.rst:232
#: ../../guides/i18n.rst:9
#: ../../guides/plugins/dependencies.rst:11
msgid "Overview"
msgstr ""

#: ../../guides/actions.rst:234
msgid "The basic flow of using sticky forms is: Call ``elgg_make_sticky_form($name)`` at the top of actions for forms you want to be sticky. Use ``elgg_is_sticky_form($name)`` and ``elgg_get_sticky_values($name)`` to get sticky values when rendering a form view. 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:240
msgid "Example: User registration"
msgstr ""

#: ../../guides/actions.rst:242
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:244
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:259
msgid "The registration action sets creates the sticky form and clears it once the action is completed:"
msgstr ""

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

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

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

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

#: ../../guides/actions.rst:302
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:314
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:316
msgid "Defines the input names and default values for form inputs."
msgstr ""

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

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

#: ../../guides/actions.rst:320
msgid "TODO: Include directly from lib/bookmarks.php"
msgstr ""

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

#: ../../guides/actions.rst:373
#: ../../guides/ajax.rst:2
msgid "Ajax"
msgstr ""

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

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

#: ../../guides/actions.rst:379
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:381
msgid "A few views and functions automatically generate security tokens:"
msgstr ""

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

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

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

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

#: ../../guides/actions.rst:408
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:413
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:438
msgid "Note: If you use a non-string as HMAC data, you must use types consistently. Consider the following:"
msgstr ""

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

#: ../../guides/ajax.rst:7
msgid "From JavaScript we can execute actions via XHR POST operations. Here's an example action and script for some basic math:"
msgstr ""

#: ../../guides/ajax.rst:45
msgid "Basically what happens here:"
msgstr ""

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

#: ../../guides/ajax.rst:48
msgid "The data is posted via XHR to http://localhost/elgg/action/example/add."
msgstr ""

#: ../../guides/ajax.rst:49
msgid "The action makes sure this is an XHR request, and returns a JSON string."
msgstr ""

#: ../../guides/ajax.rst:50
msgid "Once the action completes, Elgg builds a JSON response wrapper containing the echoed output."
msgstr ""

#: ../../guides/ajax.rst:51
msgid "Client-side Elgg extracts and displays the system message \"We did it!\" from the wrapper."
msgstr ""

#: ../../guides/ajax.rst:52
msgid "The ``success`` function receives the full wrapper object and validates the ``output`` key."
msgstr ""

#: ../../guides/ajax.rst:53
msgid "The browser alerts \"3\" then \"2\"."
msgstr ""

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

#: ../../guides/ajax.rst:58
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:60
msgid "You may want to use the :doc:`elgg/spinner</guides/javascript>` module."
msgstr ""

#: ../../guides/ajax.rst:61
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:63
msgid "If the action echoes a non-JSON string, ``wrapper.output`` will contain that string."
msgstr ""

#: ../../guides/ajax.rst:64
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:65
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:67
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:69
msgid "To make sure Ajax actions can only be executed via XHR, check ``elgg_is_xhr()`` first."
msgstr ""

#: ../../guides/ajax.rst:72
msgid "The action JSON response wrapper"
msgstr ""

#: ../../guides/ajax.rst:86
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:90
msgid "Fetching Views"
msgstr ""

#: ../../guides/ajax.rst:92
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:128
msgid "The Ajax view system works significantly differently than the action system."
msgstr ""

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

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

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

#: ../../guides/ajax.rst:133
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:135
msgid "There's no \"wrapper\" object placed around the view output."
msgstr ""

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

#: ../../guides/ajax.rst:137
msgid "If the view name begins with ``js/`` or ``css/``, a corresponding Content-Type header is added."
msgstr ""

#: ../../guides/ajax.rst:141
msgid "Unlike views rendered server-side, Ajax views must treat ``$vars`` as completely untrusted user data."
msgstr ""

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

#: ../../guides/ajax.rst:146
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:149
msgid "Here's an example of fetching a view that returns a JSON-encoded array of times:"
msgstr ""

#: ../../guides/ajax.rst:160
msgid "Fetching Forms"
msgstr ""

#: ../../guides/ajax.rst:162
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:184
msgid "Unlike views rendered server-side, Ajax views must treat ``$vars`` as completely untrusted user data. Review the use of ``$vars`` in an existing form before registering it for Ajax fetching."
msgstr ""

#: ../../guides/ajax.rst:188
msgid "Ajax helper functions"
msgstr ""

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

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

#: ../../guides/ajax.rst:203
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:46
msgid "Gatekeepers"
msgstr ""

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

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

#: ../../guides/authentication.rst:60
msgid "In Elgg 1.8 and below this function was called ``gatekeeper()``"
msgstr ""

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

#: ../../guides/authentication.rst:72
msgid "In Elgg 1.8 and below this function was called ``admin_gatekeeper()``"
msgstr ""

#: ../../guides/authentication.rst:75
msgid "Prevent CSRF attacks with ``action_gatekeeper()``."
msgstr ""

#: ../../guides/authentication.rst:83
msgid "This function should be used in :doc:`actions` prior to Elgg 1.8."
msgstr ""

#: ../../guides/authentication.rst:87
msgid "As of Elgg version 1.8 this function is called for all registered actions. There is no longer a need to call this function in your own actions. If you wish to protect other pages with action tokens then you can call this function."
msgstr ""

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

#: ../../guides/authentication.rst:96
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:98
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:100
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:117
msgid "Importance"
msgstr ""

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

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

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

#: ../../guides/authentication.rst:131
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:4
msgid "Within the Elgg framework, context can be used to 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:6
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:9
msgid "If you don't set it, Elgg tries to guess the context. If the page was called through the page handler, the context is set to the name of the handler which was set in ``elgg_register_page_handler()``. If the page wasn't called through the page handler, it uses the name of your plugin directory. If it cannot determine that, it returns main as the default context."
msgstr ""

#: ../../guides/context.rst:11
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/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 "**``site_guid``** The owning site's GUID. This is set automatically when an instance of ``ElggObject`` gets created)"
msgstr ""

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

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

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

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

#: ../../guides/database.rst:31
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:45
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:49
msgid "**ACCESS_PRIVATE** Only the owner can see it"
msgstr ""

#: ../../guides/database.rst:50
msgid "**ACCESS_FRIENDS** Only the owner and his/her friends can see it"
msgstr ""

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

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

#: ../../guides/database.rst:54
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:58
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:65
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:68
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:73
msgid "Loading an object"
msgstr ""

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

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

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

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

#: ../../guides/database.rst:102
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:106
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:109
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:117
msgid "But what about getting objects with a particular piece of metadata?"
msgstr ""

#: ../../guides/database.rst:120
msgid "By metadata"
msgstr ""

#: ../../guides/database.rst:122
msgid "The function ``elgg_get_entities_from_metadata`` allows fetching entities with metadata in a variety of ways."
msgstr ""

#: ../../guides/database.rst:126
msgid "By annotation"
msgstr ""

#: ../../guides/database.rst:128
msgid "The function ``elgg_get_entities_from_annotations`` allows fetching entities with metadata in a variety of ways."
msgstr ""

#: ../../guides/database.rst:133
msgid "As of Elgg 1.10 the default behaviour of `elgg_get_entities_from_annotations` was brought inline with the rest of the `elgg_get_entities*` functions."
msgstr ""

#: ../../guides/database.rst:135
msgid "Pre Elgg 1.10 the sorting of the entities was based on the latest addition of an annotation (in $options your could add `$options['order_by'] = 'maxtime ASC'` or `$options['order_by'] = 'maxtime DESC'`. As of Elgg 1.10 this was changed to the creation time of the entity, just like the rest of the `elgg_get_entities*` functions. To get the old behaviour back add the following to your `$options`:"
msgstr ""

#: ../../guides/database.rst:150
#: ../../guides/views.rst:239
msgid "Displaying entities"
msgstr ""

#: ../../guides/database.rst:152
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:155
msgid "To display an entity, create a view EntityType/subtype where EntityType is one of the following:"
msgstr ""

#: ../../guides/database.rst:158
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:163
msgid "A default view for all entities has already been created, this is called EntityType/default."
msgstr ""

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

#: ../../guides/database.rst:171
msgid "Every entity can be assigned an icon which is retrieved using the ``ElggEntity::getIconURL($params)`` method. This method accepts a ``$params`` argument that can be either a string specifying on of the configured icon sizes, or an array of parameters, that specify the size and provide additional context for the hook to determine the icon to serve."
msgstr ""

#: ../../guides/database.rst:176
msgid "Use ``elgg_get_config('icon_sizes')`` to get all possible values. The following sizes exist by default: ``'large'``, ``'medium'``, ``'small'``, ``'tiny'``, and ``'topbar'``. The method triggers the ``entity:icon:url`` :ref:`hook <guides/hooks-list#other>`."
msgstr ""

#: ../../guides/database.rst:180
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."
msgstr ""

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

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

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

#: ../../guides/database.rst:187
msgid "Where"
msgstr ""

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

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

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

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

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

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

#: ../../guides/database.rst:196
msgid "By convention entities that have an uploaded avatar or icon will have the ``icontime`` property assigned. This means that you can use ``$entity->icontime`` to check if an icon exists for the given entity."
msgstr ""

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

#: ../../guides/database.rst:203
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:213
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:218
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:224
msgid "Extending ElggEntity"
msgstr ""

#: ../../guides/database.rst:226
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:256
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:259
msgid "This template was extracted from the definition of ElggFile."
msgstr ""

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

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

#: ../../guides/database.rst:267
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:271
msgid "For example, a profile page in the case of users."
msgstr ""

#: ../../guides/database.rst:273
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:280
msgid "The default handler is to use the default export interface."
msgstr ""

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

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

#: ../../guides/database.rst:287
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:288
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:289
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:291
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:294
msgid "Pre-1.8 Notes"
msgstr ""

#: ../../guides/database.rst:296
msgid "update\\_subtype(): This function is new in 1.8. In prior versions, you would need to edit the database by hand if you updated the class name associated with a given subtype."
msgstr ""

#: ../../guides/database.rst:300
msgid "elgg\\_register\\_entity\\_url\\_handler(): This function is new in 1.8. It deprecates register\\_entity\\_url\\_handler(), which you should use if developing for a pre-1.8 version of Elgg."
msgstr ""

#: ../../guides/database.rst:304
msgid "elgg\\_get\\_entities\\_from\\_metadata(): This function is new in 1.8. It deprecates get\\_entities\\_from\\_metadata(), which you should use if developing for a pre-1.8 version of Elgg."
msgstr ""

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

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

#: ../../guides/database.rst:315
msgid "Example: Run SQL script on plugin activation"
msgstr ""

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

#: ../../guides/database.rst:319
msgid "my_plugin/activate.php:"
msgstr ""

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

#: ../../guides/database.rst:345
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:351
msgid "Systemlog"
msgstr ""

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

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

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

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

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

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

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

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

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

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

#: ../../guides/database.rst:392
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 "Don't modify any non-config files that come with Elgg."
msgstr ""

#: ../../guides/dont-modify-core.rst:8
msgid "Instead, create a :doc:`custom plugin<plugins>` and alter behavior through the rich Elgg plugin API."
msgstr ""

#: ../../guides/dont-modify-core.rst:10
msgid "Here are the main reasons not to modify the core of Elgg, or of any other third party software that offers better extensibility routes through plugins."
msgstr ""

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

#: ../../guides/dont-modify-core.rst:15
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:18
msgid "It makes upgrading tricky and potentially disastrous"
msgstr ""

#: ../../guides/dont-modify-core.rst:20
msgid "You will certainly want or need to upgrade Elgg to take advantage of security patches, new features, new plugin APIs, new stability and performance improvements. 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 or even completely break your site."
msgstr ""

#: ../../guides/dont-modify-core.rst:22
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:25
msgid "It may break plugins"
msgstr ""

#: ../../guides/dont-modify-core.rst:27
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:30
msgid "Summary"
msgstr ""

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

#: ../../guides/dont-modify-core.rst:33
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:34
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:35
msgid "Apply these principle to software in general."
msgstr ""

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

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

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

#: ../../guides/events-list.rst:12
msgid "**boot, system**"
msgstr ""

#: ../../guides/events-list.rst:12
msgid "First event triggered. Triggered before plugins have been loaded."
msgstr ""

#: ../../guides/events-list.rst:15
msgid "**plugins_boot, system**"
msgstr ""

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

#: ../../guides/events-list.rst:18
msgid "**init, system**"
msgstr ""

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

#: ../../guides/events-list.rst:22
msgid "**ready, system**"
msgstr ""

#: ../../guides/events-list.rst:21
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:25
msgid "**pagesetup, system**"
msgstr ""

#: ../../guides/events-list.rst:25
msgid "Called just before the first content is produced. Is triggered by ``elgg_view()``."
msgstr ""

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

#: ../../guides/events-list.rst:28
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:31
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:37
msgid "**regenerate_site_secret:before, system**"
msgstr ""

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

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

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

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

#: ../../guides/events-list.rst:43
msgid "Called for all triggered events. Used internally by ``system_log_default_logger()`` to populate the ``system_log`` table."
msgstr ""

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

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

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

#: ../../guides/events-list.rst:53
msgid "A single upgrade script finished executing. Handlers are passed a ``stdClass`` object with the properties"
msgstr ""

#: ../../guides/events-list.rst:52
msgid "from - The version of Elgg upgrading from."
msgstr ""

#: ../../guides/events-list.rst:53
msgid "to - The version just upgraded to."
msgstr ""

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

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

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

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

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

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

#: ../../guides/events-list.rst:65
msgid "**cache:flush, system**"
msgstr ""

#: ../../guides/events-list.rst:65
msgid "Reset 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:68
msgid "User events"
msgstr ""

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:83
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:88
msgid "**profileupdate, user**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:112
msgid "This event was broken in Elgg 1.9 - 1.12.3, returning false would *not* delete the relationship.  This is working as of 1.12.4"
msgstr ""

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

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:132
msgid "Triggered before an update for the user, group, object, and site entities. Return false to prevent update."
msgstr ""

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

#: ../../guides/events-list.rst:135
msgid "Triggered after an update for the user, group, object, and site entities."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:203
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/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:8
msgid "Be sure to follow the :doc:`plugins/plugin-skeleton` for your plugin's layout."
msgstr ""

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

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

#: ../../guides/guidelines.rst:21
#: ../../guides/guidelines.rst:50
#: ../../guides/guidelines.rst:61
msgid "Example: Bookmarks plugin"
msgstr ""

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

#: ../../guides/guidelines.rst:24
#: ../../guides/guidelines.rst:69
msgid "Purpose"
msgstr ""

#: ../../guides/guidelines.rst:24
#: ../../guides/guidelines.rst:69
msgid "URL"
msgstr ""

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

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

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

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

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

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

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

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

#: ../../guides/guidelines.rst:34
#: ../../guides/guidelines.rst:71
msgid "Add"
msgstr ""

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

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

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

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

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

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

#: ../../guides/guidelines.rst:41
#: ../../guides/upgrading.rst:460
msgid "Call ``set_input()`` for entity guids in the page handler and use ``get_input()`` in the page handler scripts."
msgstr ""

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

#: ../../guides/guidelines.rst:43
msgid "The group URL should use the ``pages/<handler>/owner.php`` script."
msgstr ""

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

#: ../../guides/guidelines.rst:45
msgid "If upgrading a 1.7 plugin, update the URLs throughout the plugin. (Don’t forget to remove ``/pg/``!)"
msgstr ""

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

#: ../../guides/guidelines.rst:51
msgid "Store page handler scripts in ``mod/<plugin>/pages/<page_handler>/<page_name>``"
msgstr ""

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

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

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

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

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

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

#: ../../guides/guidelines.rst:62
msgid "Make sure there are views for ``$vars[‘full’] == true`` and ``$vars[‘full’] == false``"
msgstr ""

#: ../../guides/guidelines.rst:63
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:64
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:65
msgid "Update action structure - Example: Bookmarks plugin."
msgstr ""

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

#: ../../guides/guidelines.rst:75
#: ../../guides/upgrading.rst:493
msgid "Use the following action URLs:"
msgstr ""

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

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

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

#: ../../guides/guidelines.rst:77
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:78
msgid "If updating a 1.7 plugin, replace calls to functions deprecated in 1.7 because these will produce visible errors on every load in 1.8"
msgstr ""

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

#: ../../guides/guidelines.rst:87
msgid "As of Elgg 1.7 all actions require action tokens."
msgstr ""

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

#: ../../guides/guidelines.rst:92
msgid "Never call an action directly by saying:"
msgstr ""

#: ../../guides/guidelines.rst:98
msgid "This circumvents the security systems in Elgg."
msgstr ""

#: ../../guides/guidelines.rst:100
msgid "There is no need to include the ``engine/start.php`` file in your actions. Actions should never be called directly, so the engine will be started automatically when called correctly."
msgstr ""

#: ../../guides/guidelines.rst:102
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:105
msgid "Directly calling a file"
msgstr ""

#: ../../guides/guidelines.rst:107
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:110
msgid "Recommended"
msgstr ""

#: ../../guides/guidelines.rst:112
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:114
msgid "Update the widget views (see the blog or file widgets)"
msgstr ""

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

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

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

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

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

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

#: ../../guides/guidelines.rst:121
#: ../../guides/upgrading.rst:536
msgid "Clean up CSS/HTML"
msgstr ""

#: ../../guides/guidelines.rst:122
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:123
msgid "Use hyphens rather than underscores in classes/ids"
msgstr ""

#: ../../guides/guidelines.rst:124
msgid "Update the ``manifest.xml`` file to the 1.8 format. Use http://el.gg/manifest17to18 to automate this"
msgstr ""

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

#: ../../guides/guidelines.rst:127
msgid "Update functions deprecated in 1.8."
msgstr ""

#: ../../guides/guidelines.rst:127
msgid "Many registration functions simply added an ``elgg_`` prefix for consistency"
msgstr ""

#: ../../guides/guidelines.rst:128
msgid "See ``/engine/lib/deprecated-1.8.php`` for the full list. You can also set the debug level to warning to get visual reminders of deprecated functions"
msgstr ""

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

#: ../../guides/helpers.rst:7
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:8
msgid "``set_input($name, $value)`` Forces a value to a particular variable for subsequent retrieval by ``get_input()``"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/helpers.rst:26
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:27
msgid "``get_user($user_guid)`` Given a GUID, returns a full ElggUser entity"
msgstr ""

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

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

#: ../../guides/helpers.rst:30
msgid "``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:31
msgid "``set_context($context)`` Forces the context to be a particular value"
msgstr ""

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

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

#: ../../guides/helpers.rst:34
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:37
#: ../../guides/hooks-list.rst:470
#: ../../guides/plugins.rst:2
msgid "Plugins"
msgstr ""

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

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

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

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

#: ../../guides/helpers.rst:46
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:47
msgid "You can pass ``'use_hover' => false`` to the user icon view if you don't want the avatar drop down menu to appear e.g."
msgstr ""

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

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

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

#: ../../guides/hooks-list.rst:12
msgid "Triggered when sending email. ``$params`` contains:"
msgstr ""

#: ../../guides/hooks-list.rst:14
msgid "to"
msgstr ""

#: ../../guides/hooks-list.rst:15
msgid "from"
msgstr ""

#: ../../guides/hooks-list.rst:16
msgid "subject"
msgstr ""

#: ../../guides/hooks-list.rst:17
msgid "body"
msgstr ""

#: ../../guides/hooks-list.rst:18
msgid "headers"
msgstr ""

#: ../../guides/hooks-list.rst:19
msgid "params"
msgstr ""

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:36
#: ../../guides/hooks-list.rst:534
msgid "**search_types, get_types**"
msgstr ""

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

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

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

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

#: ../../guides/hooks-list.rst:45
msgid "**geocode, location**"
msgstr ""

#: ../../guides/hooks-list.rst:45
msgid "Deprecated as of 1.9."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:81
msgid "**output:before, layout**"
msgstr ""

#: ../../guides/hooks-list.rst:81
msgid "In ``elgg_view_layout()``, filters ``$params`` before it's passed to the layout view."
msgstr ""

#: ../../guides/hooks-list.rst:84
msgid "**output:after, layout**"
msgstr ""

#: ../../guides/hooks-list.rst:84
msgid "In ``elgg_view_layout()``, filters the return value of the layout view."
msgstr ""

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

#: ../../guides/hooks-list.rst:87
msgid "Triggered in the ajax forward hook that is called for ajax requests. Allows plugins to alter the output returned, including the forward URL, system messages, and errors."
msgstr ""

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

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

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

#: ../../guides/hooks-list.rst:94
msgid "Triggered by ``elgg_view_menu()``. Used to add dynamic menu items."
msgstr ""

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

#: ../../guides/hooks-list.rst:97
msgid "Trigger by ``elgg_view_menu()``. Used to sort, add, remove, and modify menu items."
msgstr ""

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

#: ../../guides/hooks-list.rst:100
msgid "Triggered before a river item is created. Return false to prevent river item from being created."
msgstr ""

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

#: ../../guides/hooks-list.rst:103
msgid "Triggered when generating the cached content of a view."
msgstr ""

#: ../../guides/hooks-list.rst:107
msgid "**get, subscriptions**"
msgstr ""

#: ../../guides/hooks-list.rst:106
msgid "Filter notification subscriptions for users for the Elgg_Notifications_Event ``$params['event']``. Return an array like:"
msgstr ""

#: ../../guides/hooks-list.rst:118
msgid "**prepare, breadcrumbs**"
msgstr ""

#: ../../guides/hooks-list.rst:117
msgid "In elgg_get_breadcrumbs(), this filters the registered breadcrumbs before returning them, allowing a plugin to alter breadcrumb strategy site-wide."
msgstr ""

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

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

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

#: ../../guides/hooks-list.rst:126
msgid "Triggered in the aggregate action to save user settings. Return false prevent sticky forms from being cleared."
msgstr ""

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

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

#: ../../guides/hooks-list.rst:134
msgid "Return boolean for if the string in ``$params['username']`` is valid for a username."
msgstr ""

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

#: ../../guides/hooks-list.rst:137
msgid "Return boolean for if the string in ``$params['password']`` is valid for a password."
msgstr ""

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

#: ../../guides/hooks-list.rst:140
msgid "Return boolean for if the string in ``$params['email']`` is valid for an email address."
msgstr ""

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

#: ../../guides/hooks-list.rst:143
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."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:177
msgid "Triggered before executing action scripts. Return false to abort action."
msgstr ""

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

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

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

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

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

#: ../../guides/hooks-list.rst:187
msgid "Filter the URL to forward a user to when ``forward($url, $reason)`` is called."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:222
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:225
msgid "This is functions differently than the ``permissions_check:metadata`` hook by passing the annotation name instead of the metadata object."
msgstr ""

#: ../../guides/hooks-list.rst:229
msgid "**permissions_check:annotation**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:269
msgid "Filters the SQL clauses used in ``_elgg_get_access_where_sql()``."
msgstr ""

#: ../../guides/hooks-list.rst:274
#: ../../guides/plugins/plugin-skeleton.rst:152
#: ../../guides/views.rst:2
msgid "Views"
msgstr ""

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

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

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

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

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

#: ../../guides/hooks-list.rst:283
msgid "In ``elgg_view_layout()``, filters the layout name"
msgstr ""

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

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

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

#: ../../guides/hooks-list.rst:289
msgid "In ``elgg_view_page()``, filters ``$vars['head']``"
msgstr ""

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

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

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

#: ../../guides/hooks-list.rst:299
msgid "In ``elgg_get_file_simple_type()``, filters the return value. The hook uses ``$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:308
msgid "Other"
msgstr ""

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

#: ../../guides/hooks-list.rst:311
msgid "Filters the number of comments displayed per page. Default is 25."
msgstr ""

#: ../../guides/hooks-list.rst:318
msgid "**default, access**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:386
msgid "**entity:annotate, <entity_type>**"
msgstr ""

#: ../../guides/hooks-list.rst:385
msgid "Triggered in ``elgg_view_entity_annotations()``, which is called by ``elgg_view_entity()``. Can be used to add annotations to all full entity views."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:409
#: ../../guides/hooks-list.rst:420
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:421
msgid "**profile:fields, profile**"
msgstr ""

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

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

#: ../../guides/hooks-list.rst:434
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:448
msgid "**rest, init**"
msgstr ""

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

#: ../../guides/hooks-list.rst:451
msgid "Filter the URLs that are can be seen by logged out users if Walled Garden is enabled. ``$value`` is an array of regex strings that will allow access if matched."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:497
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:501
msgid "Twitter API"
msgstr ""

#: ../../guides/hooks-list.rst:505
msgid "**authorize, twitter_api**"
msgstr ""

#: ../../guides/hooks-list.rst:504
msgid "Triggered when a user is authorizes Twitter for a login. ``$params['token']`` contains the Twitter authorization token."
msgstr ""

#: ../../guides/hooks-list.rst:508
msgid "Reported Content"
msgstr ""

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:520
msgid "Search"
msgstr ""

#: ../../guides/hooks-list.rst:524
msgid "**search, <type>:<subtype>**"
msgstr ""

#: ../../guides/hooks-list.rst:523
msgid "Filter more granular search results than searching by type alone. Must return an array with ``count`` as the total count of results and  ``entities`` an array of ElggUser entities."
msgstr ""

#: ../../guides/hooks-list.rst:526
msgid "**search, tags**"
msgstr ""

#: ../../guides/hooks-list.rst:530
msgid "**search, <type>**"
msgstr ""

#: ../../guides/hooks-list.rst:529
msgid "Filter the search for entities for type ``$type``. Must return an array with ``count`` as the total count of results and  ``entities`` an array of ElggUser entities."
msgstr ""

#: ../../guides/hooks-list.rst:533
msgid "Filter an array of search types. This allows plugins to add custom types that don't correspond directly to entities."
msgstr ""

#: ../../guides/hooks-list.rst:537
msgid "**search_types, get_queries**"
msgstr ""

#: ../../guides/hooks-list.rst:537
msgid "Before a search this filters the types queried. This can be used to reorder the display of search results."
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:11
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:22
msgid "The default language is “en” for English."
msgstr ""

#: ../../guides/i18n.rst:24
msgid "To change the wording of any phrase, provide a new mapping in your plugin’s ``{language}.php`` file for the associated key:"
msgstr ""

#: ../../guides/i18n.rst:36
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:40
msgid "Server-side API"
msgstr ""

#: ../../guides/i18n.rst:42
msgid "``elgg_echo($key, $args, $language)``"
msgstr ""

#: ../../guides/i18n.rst:44
msgid "Output the translation of the key in the current language."
msgstr ""

#: ../../guides/i18n.rst:46
#: ../../guides/notifications.rst:24
#: ../../guides/notifications.rst:167
#: ../../guides/notifications.rst:191
#: ../../guides/notifications.rst:246
msgid "Example:"
msgstr ""

#: ../../guides/i18n.rst:52
msgid "It also supports variable replacement using sprintf syntax:"
msgstr ""

#: ../../guides/i18n.rst:62
msgid "To force which language should be used for translation, set the third parameter:"
msgstr ""

#: ../../guides/i18n.rst:71
msgid "Javascript API"
msgstr ""

#: ../../guides/i18n.rst:73
msgid "``elgg.echo(key, args, language)``"
msgstr ""

#: ../../guides/i18n.rst:75
msgid "This function is the exact counterpart to ``elgg_echo`` in PHP."
msgstr ""

#: ../../guides/i18n.rst:77
msgid "Client-side translations are loaded asynchronously. Ensure translations are available by requiring the \"elgg\" AMD module:"
msgstr ""

#: ../../guides/i18n.rst:87
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
msgid "JavaScript"
msgstr ""

#: ../../guides/javascript.rst:4
msgid "As of Elgg 1.9, we encourage all developers to adopt the `AMD (Asynchronous Module Definition) <http://requirejs.org/docs/whyamd.html>`_ standard for writing JavaScript code in Elgg. The 1.8 version is still functional and is :ref:`described below<1.8-js>`."
msgstr ""

#: ../../guides/javascript.rst:13
msgid "AMD"
msgstr ""

#: ../../guides/javascript.rst:15
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:19
msgid "Executing a module in the current page"
msgstr ""

#: ../../guides/javascript.rst:21
msgid "Telling Elgg to load an existing module in the current page is easy:"
msgstr ""

#: ../../guides/javascript.rst:28
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:32
msgid "Defining the Module"
msgstr ""

#: ../../guides/javascript.rst:34
msgid "Here we define a basic module that alters the page, by passing a \"definition function\" to ``define()``:"
msgstr ""

#: ../../guides/javascript.rst:47
msgid "The module's name is determined by the view name, which here is ``js/myplugin/say_hello.js``. We strip the leading ``js/`` and the ``.js`` extension, leaving ``myplugin/say_hello``."
msgstr ""

#: ../../guides/javascript.rst:52
msgid "The definition function **must** have one argument named ``require``."
msgstr ""

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

#: ../../guides/javascript.rst:57
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:82
msgid "Passing plugin/Elgg settings to modules"
msgstr ""

#: ../../guides/javascript.rst:84
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/js/myplugin/settings.js.php`` (note the double extension ``.js.php``)."
msgstr ""

#: ../../guides/javascript.rst:101
msgid "You must also manually register the view as an external resource:"
msgstr ""

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

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

#: ../../guides/javascript.rst:120
msgid "In your PHP ``init, system`` event handler, you can use ``elgg_define_js()`` to do this:"
msgstr ""

#: ../../guides/javascript.rst:131
msgid "The ``src`` option in ``elgg_define_js()`` is passed through ``elgg_normalize_url``, so you can use paths relative to the site URL."
msgstr ""

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

#: ../../guides/javascript.rst:137
msgid "JavaScript libraries that define global resources can also be defined as AMD modules if you shim them by setting ``exports`` and optionally ``deps``:"
msgstr ""

#: ../../guides/javascript.rst:150
msgid "When this is requested client-side:"
msgstr ""

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

#: ../../guides/javascript.rst:153
msgid "``http://example.org/elgg/mod/myplugin/vendors/jquery/jquery.form.js`` is loaded and executed."
msgstr ""

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

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

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

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

#: ../../guides/javascript.rst:164
msgid "JS and CSS views (names starting with ``js/`` or ``css/``) as well as static (.js/.css) files are automatically minified and cached by Elgg's simplecache system."
msgstr ""

#: ../../guides/javascript.rst:169
msgid "Migrating JS from Elgg 1.8 to AMD / 1.9"
msgstr ""

#: ../../guides/javascript.rst:171
msgid "**Current 1.8 JavaScript modules will continue to work with Elgg**."
msgstr ""

#: ../../guides/javascript.rst:173
msgid "We do not anticipate any backwards compatibility issues with this new direction and will fix any issues that do come up. The old system will still be functional in Elgg 1.9, but developers are encouraged to begin looking to AMD as the future of JS in Elgg."
msgstr ""

#: ../../guides/javascript.rst:180
msgid "Traditional JavaScript (1.8)"
msgstr ""

#: ../../guides/javascript.rst:183
msgid "Register third-party libraries with ``elgg_register_js``:"
msgstr ""

#: ../../guides/javascript.rst:189
msgid "This will override any URLs previously registered under this name."
msgstr ""

#: ../../guides/javascript.rst:191
msgid "Load a library on the current page with ``elgg_load_js``:"
msgstr ""

#: ../../guides/javascript.rst:197
msgid "This will include and execute the linked code."
msgstr ""

#: ../../guides/javascript.rst:204
msgid "Using inline scripts is strongly discouraged because:"
msgstr ""

#: ../../guides/javascript.rst:202
msgid "They are not testable (maintainability)"
msgstr ""

#: ../../guides/javascript.rst:203
msgid "They are not cacheable (performance)"
msgstr ""

#: ../../guides/javascript.rst:204
msgid "Doing so forces some scripts to be loaded in ``<head>`` (performance)"
msgstr ""

#: ../../guides/javascript.rst:206
msgid "Inline scripts in core or bundled plugins are considered legacy bugs."
msgstr ""

#: ../../guides/javascript.rst:209
msgid "Core functions available in JS"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/javascript.rst:283
msgid "Register a hook handler with the event system."
msgstr ""

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

#: ../../guides/javascript.rst:300
msgid "Emit a hook event in the event system."
msgstr ""

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

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

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

#: ../../guides/javascript.rst:314
msgid "This requires a valid security token in 1.8, but not in 1.9."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/javascript.rst:401
msgid "The JS engine has a hooks system similar to the PHP engine's plugin hooks: hooks are triggered and plugins can register callbacks 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:404
msgid "Registering a callback to a hook"
msgstr ""

#: ../../guides/javascript.rst:406
msgid "Callbacks are registered using ``elgg.register_hook_handler()``. Multiple callbacks can be registered for the same hook."
msgstr ""

#: ../../guides/javascript.rst:408
msgid "The following example registers the ``elgg.ui.initDatePicker`` callback for the *init*, *system* event. Note that a difference in the JS engine is that instead of passing a string you pass the function itself to ``elgg.register_hook_handler()`` as the callback."
msgstr ""

#: ../../guides/javascript.rst:418
msgid "The callback"
msgstr ""

#: ../../guides/javascript.rst:420
msgid "The callback accepts 4 arguments:"
msgstr ""

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

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

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

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

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

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

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

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

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

#: ../../guides/javascript.rst:442
msgid "This hook is fired when the JS system is ready. Plugins should register their init functions for this hook."
msgstr ""

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

#: ../../guides/javascript.rst:445
msgid "This hook is fired when the system has fully booted."
msgstr ""

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

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

#: ../../guides/menus.rst:2
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:28
#: ../../guides/menus.rst:65
msgid "Examples"
msgstr ""

#: ../../guides/menus.rst:45
msgid "Advanced usage"
msgstr ""

#: ../../guides/menus.rst:47
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:52
msgid "There are two hooks that can be used to modify a menu:"
msgstr ""

#: ../../guides/menus.rst:51
msgid "``'register', 'menu:<menu name>'`` to add or modify items (especially in dynamic menus)"
msgstr ""

#: ../../guides/menus.rst:52
msgid "``'prepare', 'menu:<menu name>'`` to modify the structure of the menu before it is displayed"
msgstr ""

#: ../../guides/menus.rst:54
msgid "When you register a plugin hook handler, replace the ``<menu name>`` part with the internal name of the menu."
msgstr ""

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

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

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

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

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

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

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

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

#: ../../guides/menus.rst:184
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:189
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/notifications.rst:2
#: ../../guides/upgrading.rst:157
msgid "Notifications"
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:82
#: ../../guides/notifications.rst:104
msgid "Example"
msgstr ""

#: ../../guides/notifications.rst:84
msgid "Tell Elgg to send notifications when a new object of subtype \"photo\" is created:"
msgstr ""

#: ../../guides/notifications.rst:97
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:100
msgid "Contents of the notification message can be defined with the ``'prepare', 'notification:[action]:[type]:[subtype]'`` hook."
msgstr ""

#: ../../guides/notifications.rst:106
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:154
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:158
msgid "Registering a new notification method"
msgstr ""

#: ../../guides/notifications.rst:160
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:169
msgid "Register a handler that will send the notifications via SMS."
msgstr ""

#: ../../guides/notifications.rst:180
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:184
msgid "Sending the notifications using your own method"
msgstr ""

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

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

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

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

#: ../../guides/notifications.rst:242
msgid "It's possible to modify the recipients of a notification dynamically with the ``'get', 'subscriptions'`` hook."
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 it be can set by passing the GUID to ``elgg_set_page_owner_guid($guid)``."
msgstr ""

#: ../../guides/page-owner.rst:8
msgid "Custom page owner handlers"
msgstr ""

#: ../../guides/page-owner.rst:10
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:12
msgid "By default, the system determines the page_owner from the following elements:"
msgstr ""

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

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

#: ../../guides/page-owner.rst:17
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/pagehandler.rst:2
msgid "Page handler"
msgstr ""

#: ../../guides/pagehandler.rst:4
msgid "Elgg offers a facility to manage your plugin pages via a page handler, enabling custom urls like ``http://yoursite/your_plugin/section``. To add a page handler to a plugin, a handler function needs to be registered in the plugin's ``start.php`` file with ``elgg_register_page_handler()``:"
msgstr ""

#: ../../guides/pagehandler.rst:10
msgid "The plugin's page handler is passed two parameters:"
msgstr ""

#: ../../guides/pagehandler.rst:12
msgid "an array containing the sections of the URL exploded by '/'. With this information the handler will be able to apply any logic necessary, for example loading the appropriate view and returning its contents."
msgstr ""

#: ../../guides/pagehandler.rst:13
msgid "the handler, this is the handler that is currently used (in our example ``your_plugin``). If you don't register multiple page handlers to the same function you'll never need this."
msgstr ""

#: ../../guides/pagehandler.rst:16
msgid "Code flow"
msgstr ""

#: ../../guides/pagehandler.rst:18
msgid "Pages in plugins should be served only through page handlers, stored in ``pages/`` of your plugin's directory and do not need to ``include`` or ``require`` Elgg's ``engine/start.php`` file. The purpose of these files are to knit together output from different views to form the page that the user sees. The program flow is something like this:"
msgstr ""

#: ../../guides/pagehandler.rst:20
msgid "A user requests ``/plugin_name/section/entity``"
msgstr ""

#: ../../guides/pagehandler.rst:21
msgid "Elgg checks if ``plugin_name`` is registered to a page handler and calls that function, passing ``array('section', 'entity')`` as the first argument"
msgstr ""

#: ../../guides/pagehandler.rst:22
msgid "The page handler function determines which page to display, optionally sets some values, and then includes the correct page under ``plugin_name/pages/plugin_name/``"
msgstr ""

#: ../../guides/pagehandler.rst:23
msgid "The included file combines many separate views, calls formatting functions like ``elgg_view_layout()`` and ``elgg_view_page()``, and then echos the final output"
msgstr ""

#: ../../guides/pagehandler.rst:24
msgid "The user sees a fully rendered page"
msgstr ""

#: ../../guides/pagehandler.rst:26
msgid "There is no syntax enforced on the URLs, but Elgg's coding standards suggests a certain format."
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 start.php and manifest.xml file in the plugin root in order to be recognized by Elgg."
msgstr ""

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

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

#: ../../guides/plugins.rst:14
msgid "activate.php, deactivate.php"
msgstr ""

#: ../../guides/plugins.rst:16
msgid "The activate.php and deactivate.php files contain procedural code that will run upon plugin activation and deactivation. Use these files to perform one-time events such as registering a persistent admin notice, registering subtypes, or performing garbage collection when deactivated."
msgstr ""

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

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

#: ../../guides/plugins.rst:26
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:29
msgid "Syntax"
msgstr ""

#: ../../guides/plugins.rst:31
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:38
msgid "The manifest syntax is as follows:"
msgstr ""

#: ../../guides/plugins.rst:44
msgid "Many elements can contain children attributes:"
msgstr ""

#: ../../guides/plugins.rst:54
msgid "Required Elements"
msgstr ""

#: ../../guides/plugins.rst:56
msgid "All plugins are required to define the following elements in their manifest files:"
msgstr ""

#: ../../guides/plugins.rst:58
msgid "id - This has the name as the directory that the plugin uses."
msgstr ""

#: ../../guides/plugins.rst:59
msgid "name - The display name of the plugin."
msgstr ""

#: ../../guides/plugins.rst:60
msgid "author - The name of the author who wrote the plugin."
msgstr ""

#: ../../guides/plugins.rst:61
msgid "version - The version of the plugin."
msgstr ""

#: ../../guides/plugins.rst:62
msgid "description - A description of the what the plugin provides, its features, and other relevant information"
msgstr ""

#: ../../guides/plugins.rst:63
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:66
msgid "Available Elements"
msgstr ""

#: ../../guides/plugins.rst:68
msgid "In addition to the require elements above, the follow elements are available to use:"
msgstr ""

#: ../../guides/plugins.rst:70
msgid "blurb - A short description of the plugin."
msgstr ""

#: ../../guides/plugins.rst:71
msgid "category - The category of the plugin. It is recommended to follow the [[Plugin_Guidelines|plugin guidelines]] and use one of the defined categories. There can be multiple entries."
msgstr ""

#: ../../guides/plugins.rst:72
msgid "conflicts - Specifies that the plugin conflicts with a certain system configuration."
msgstr ""

#: ../../guides/plugins.rst:73
msgid "copyright - The plugin's copyright information."
msgstr ""

#: ../../guides/plugins.rst:74
msgid "license - The plugin's license information."
msgstr ""

#: ../../guides/plugins.rst:75
msgid "provides - Specifies that this plugin provides the same functionality as another Elgg plugin or a PHP extension."
msgstr ""

#: ../../guides/plugins.rst:76
msgid "screenshot - Screenshots of the plugin. There can be multiple entries. See the advanced example for syntax."
msgstr ""

#: ../../guides/plugins.rst:77
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:78
msgid "website - A link to the website for the plugin."
msgstr ""

#: ../../guides/plugins.rst:82
msgid ":doc:`plugins/dependencies`"
msgstr ""

#: ../../guides/plugins.rst:85
#: ../../guides/widgets.rst:115
msgid "Simple Example"
msgstr ""

#: ../../guides/plugins.rst:87
msgid "This manifest file is the bare minimum a plugin must have."
msgstr ""

#: ../../guides/plugins.rst:105
msgid "Advanced example"
msgstr ""

#: ../../guides/plugins.rst:107
msgid "This example uses all of the available elements:"
msgstr ""

#: ../../guides/plugins.rst:149
#: ../../guides/views.rst:344
#: ../../guides/web-services.rst:329
msgid "Related"
msgstr ""

#: ../../guides/plugins/dependencies.rst:2
msgid "Plugin Dependencies"
msgstr ""

#: ../../guides/plugins/dependencies.rst:4
msgid "In Elgg 1.8 a plugin dependencies system was introduced 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_version and 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 either by the Elgg API ``version`` (2011010401) or the ``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_version:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:58
msgid "Using elgg_release:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:68
msgid "Suggests"
msgstr ""

#: ../../guides/plugins/dependencies.rst:70
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:72
msgid "Suggest another plugin:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:82
msgid "Suggest a certain PHP setting:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:94
msgid "Conflicts"
msgstr ""

#: ../../guides/plugins/dependencies.rst:96
msgid "``conflicts`` dependencies mean the plugin cannot be used under a specific system configuration."
msgstr ""

#: ../../guides/plugins/dependencies.rst:98
msgid "Conflict with any version of the profile plugin:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:107
msgid "Conflict with a specific version of Elgg:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:118
msgid "Provides"
msgstr ""

#: ../../guides/plugins/dependencies.rst:120
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:122
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:134
msgid "All plugins provide themselves as their plugin id (directory name) at the version defined in the their manifest."
msgstr ""

#: ../../guides/plugins/dependencies.rst:137
msgid "Types"
msgstr ""

#: ../../guides/plugins/dependencies.rst:139
msgid "Every dependency verb has a mandatory ``<type>`` element that must be one of the following six values:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:141
msgid "**elgg_version** - The API version of Elgg (2011010401)"
msgstr ""

#: ../../guides/plugins/dependencies.rst:142
msgid "**elgg_release** - The release version of Elgg (1.8)"
msgstr ""

#: ../../guides/plugins/dependencies.rst:143
msgid "**plugin** - An Elgg plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:144
msgid "**priority** - A plugin load priority"
msgstr ""

#: ../../guides/plugins/dependencies.rst:145
msgid "**php_extension** - A PHP extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:146
msgid "**php_ini** - A PHP setting"
msgstr ""

#: ../../guides/plugins/dependencies.rst:147
msgid "**php_version** - A PHP version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:151
msgid "``provides`` only supports ``plugin`` and ``php_extension`` types."
msgstr ""

#: ../../guides/plugins/dependencies.rst:153
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:164
msgid "elgg_version and elgg_release"
msgstr ""

#: ../../guides/plugins/dependencies.rst:166
msgid "These concern the API and release versions of Elgg and requires the following option element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:168
msgid "**version** - The API or release version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:170
#: ../../guides/plugins/dependencies.rst:229
msgid "The following option element is supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:172
#: ../../guides/plugins/dependencies.rst:184
#: ../../guides/plugins/dependencies.rst:231
msgid "**comparison** - The comparison operator to use. Defaults to >= if not passed"
msgstr ""

#: ../../guides/plugins/dependencies.rst:175
msgid "plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:177
msgid "Specifies an Elgg plugin by its ID (directory name). This requires the following option element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:179
msgid "**name** - The ID of the plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:181
#: ../../guides/plugins/dependencies.rst:201
msgid "The following option elements are supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:183
msgid "**version** - The version of the plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:187
msgid "priority"
msgstr ""

#: ../../guides/plugins/dependencies.rst:189
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:191
msgid "**plugin** - The plugin ID to base the load order on"
msgstr ""

#: ../../guides/plugins/dependencies.rst:192
msgid "**priority** - The load order: 'before' or 'after'"
msgstr ""

#: ../../guides/plugins/dependencies.rst:195
msgid "php_extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:197
msgid "This checks PHP extensions. The follow option element is required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:199
msgid "**name** - The name of the PHP extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:203
msgid "**version** - The version of the extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:204
#: ../../guides/plugins/dependencies.rst:220
msgid "**comparison** - The comparison operator to use. Defaults to =="
msgstr ""

#: ../../guides/plugins/dependencies.rst:208
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:211
msgid "php_ini"
msgstr ""

#: ../../guides/plugins/dependencies.rst:213
msgid "This checks PHP settings. The following option elements are required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:215
msgid "**name** - The name of the setting to check"
msgstr ""

#: ../../guides/plugins/dependencies.rst:216
msgid "**value** - The value of the setting to compare against"
msgstr ""

#: ../../guides/plugins/dependencies.rst:218
msgid "The following options are supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:223
msgid "php_version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:225
msgid "This checks the PHP version. The following option elements are required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:227
msgid "**version** - The PHP version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:234
msgid "Comparison Operators"
msgstr ""

#: ../../guides/plugins/dependencies.rst:236
msgid "Dependencies that check versions support passing a custom operator via the ``<comparison>`` element."
msgstr ""

#: ../../guides/plugins/dependencies.rst:238
msgid "The follow are valid comparison operators:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:240
msgid "< or lt"
msgstr ""

#: ../../guides/plugins/dependencies.rst:241
msgid "<= or le"
msgstr ""

#: ../../guides/plugins/dependencies.rst:242
msgid "=, ==, or eq"
msgstr ""

#: ../../guides/plugins/dependencies.rst:243
msgid "!=, <>, or ne"
msgstr ""

#: ../../guides/plugins/dependencies.rst:244
msgid "> or gt"
msgstr ""

#: ../../guides/plugins/dependencies.rst:245
msgid ">= or ge"
msgstr ""

#: ../../guides/plugins/dependencies.rst:247
msgid "If ``<comparison>`` is not passed, the follow are used as defaults, depending upon the dependency type:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:249
msgid "requires->elgg_version and elgg_release: >="
msgstr ""

#: ../../guides/plugins/dependencies.rst:250
msgid "requires->plugin: >="
msgstr ""

#: ../../guides/plugins/dependencies.rst:251
msgid "requires->php_extension: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:252
msgid "requires->php_ini: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:253
msgid "all conflicts: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:257
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:260
msgid "Quick Examples"
msgstr ""

#: ../../guides/plugins/dependencies.rst:263
msgid "Requires Elgg 1.8.2 or higher"
msgstr ""

#: ../../guides/plugins/dependencies.rst:273
msgid "Requires the Groups plugin is active"
msgstr ""

#: ../../guides/plugins/dependencies.rst:283
msgid "Requires to be after the Profile plugin if Profile is active"
msgstr ""

#: ../../guides/plugins/dependencies.rst:294
msgid "Conflicts with The Wire plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:304
msgid "Requires at least 256 MB memory in PHP"
msgstr ""

#: ../../guides/plugins/dependencies.rst:317
msgid "Requires at least PHP version 5.3"
msgstr ""

#: ../../guides/plugins/dependencies.rst:327
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 1.8. Plugins written for Elgg 1.7 and down are strongly encouraged to use this structure as well, though some of the benefits are not as apparent as when used in 1.8."
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 ``start.php`` and ``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:84
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:86
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:88
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 new (as of Elgg 1.8) ``elgg_view_form()`` function easily."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:91
msgid "Text Files"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:93
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:96
msgid "README.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:96
msgid "*should* provide additional information about the plugin of an unspecified nature"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:99
msgid "COPYRIGHT.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:99
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:102
msgid "LICENSE.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:102
msgid "If included, **must** provide the text of the license that the plugin is released under."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:105
msgid "INSTALL.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:105
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:108
msgid "CHANGES.txt"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:108
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:110
msgid "Plugins *may* include additional \\*.txt files besides these, but no interface is given for reading them."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:113
msgid "Pages"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:115
msgid "Plugins *should* put page-generating scripts in a ``pages/`` directory inside their plugin root. Furthermore, plugins *should* put page-generating scripts under a directory named for their handler. For example, the script for page ``yoursite.com/my_handler/view/1234`` *should* be located at ``mod/my_plugin/pages/my_handler/view.php``."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:117
msgid "In the past, these scripts were included directly in the plugin root. Plugins *should not* do this anymore, and if any core plugins are found to do this, that is a bug if not present solely for the sake of backwards compatibility."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:121
msgid "The reason we encourage this structure is"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:123
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:124
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:128
msgid "Classes"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:130
msgid "All classes that your plugin defines *should* be included in a ``classes/`` directory. This directory has special meaning to Elgg. Classes placed in this directory are autoloaded on demand, and do not need to be included explicitly."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:134
msgid "Each file **must** have exactly one class defined inside it. The file name **must** match the name of the one class that the file defines (except for the \".php\" suffix)."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:139
msgid "Files with a \".class.php\" extension will **not** be recognized by Elgg."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:142
msgid "Vendors"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:144
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:147
msgid "Lib"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:149
msgid "Procedural code defined by your plugin *should* be placed in the `lib/` directory. Though this folder has no special significance to the Elgg engine, this has historically been the location where Elgg core stores its procedural code, so we encourage the same format for the sake of consistency and familiarity."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:154
msgid "In order to override core views, a plugin's views **must** be placed in a ``views/``. This directory has special meaning to Elgg as views defined here automatically override Elgg core's version of those views. For more info, see :doc:`/guides/views`."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:157
msgid "Javascript"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:159
msgid "Javascript that will be included on every page *should* be put in the ``plugin/js`` view and your plugin *should* extend ``js/elgg`` with this view. Javascript that does not need to be included on every page *should* be put in a static javascript file under the ``js/`` directory. For more information on Javascript in Elgg, see :doc:`/guides/javascript`."
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:162
msgid "activate.php and deactivate.php"
msgstr ""

#: ../../guides/plugins/plugin-skeleton.rst:164
msgid "The ``activate.php`` and ``deactivate.php`` files contain procedural code that will run respectively upon plugin activation or deactivation. Use these files to perform one-time events such as registering a persistent admin notice, registering subtypes, or performing garbage collection when deactivated."
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"
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 "In order for events to appear in the river you need to provide a corresponding :doc:`view <views>` with the name specified in the function above."
msgstr ""

#: ../../guides/river.rst:46
msgid "We recommend ``/river/{type}/{subtype}/{action}``, where:"
msgstr ""

#: ../../guides/river.rst:48
msgid "{type} is the entity type of the content we're interested in (``object`` for objects, ``user`` for users, etc)"
msgstr ""

#: ../../guides/river.rst:49
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:50
msgid "{action} is the action that took place (''create'', ''update'', etc)"
msgstr ""

#: ../../guides/river.rst:52
msgid "River item information will be passed in an object called ``$vars['item']``, which contains the following important parameters:"
msgstr ""

#: ../../guides/river.rst:54
msgid "``$vars['item']->subject_guid`` The GUID of the user performing the action"
msgstr ""

#: ../../guides/river.rst:55
msgid "``$vars['item']->object_guid`` The GUID of the entity being acted upon"
msgstr ""

#: ../../guides/river.rst:57
msgid "Timestamps etc will be generated for you."
msgstr ""

#: ../../guides/river.rst:59
msgid "For example, the blog plugin uses the following code for its river view:"
msgstr ""

#: ../../guides/routing.rst:2
msgid "Routing"
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:23
msgid "Page Handler"
msgstr ""

#: ../../guides/routing.rst:25
msgid "To handle all URLs that begin with a particular identifier, you can register a function to act as a :doc:`/guides/pagehandler`. When the handler is called, the segments array is passed in as the first argument."
msgstr ""

#: ../../guides/routing.rst:29
msgid "The following code registers a page handler for \"blog\" URLs and shows how one might route the request to a resource view."
msgstr ""

#: ../../guides/routing.rst:56
msgid "The ``route`` Plugin Hook"
msgstr ""

#: ../../guides/routing.rst:58
msgid "The ``route`` plugin hook is triggered earlier, before page handlers are called. The URL identifier is given as the type of the hook. This hook can be used to modify the identifier or segments, to take over page rendering completely, or just to add some logic before the request is handled elsewhere."
msgstr ""

#: ../../guides/routing.rst:63
msgid "Generally devs should use a page handler unless they need to affect a single page or a wider variety of URLs."
msgstr ""

#: ../../guides/routing.rst:65
msgid "The following code intercepts requests to the page handler for ``customblog`` and internally redirects them to the ``blog`` page handler."
msgstr ""

#: ../../guides/routing.rst:78
msgid "The following code results in ``/blog/all`` requests being completely handled by the plugin hook handler. For these requests the ``blog`` page handler is never called."
msgstr ""

#: ../../guides/routing.rst:103
msgid "Routing overview"
msgstr ""

#: ../../guides/routing.rst:105
msgid "For regular pages, Elgg's program flow is something like this:"
msgstr ""

#: ../../guides/routing.rst:107
msgid "A user requests ``http://example.com/blog/owner/jane``."
msgstr ""

#: ../../guides/routing.rst:108
msgid "Plugins are initialized."
msgstr ""

#: ../../guides/routing.rst:109
msgid "Elgg parses the URL to identifier ``blog`` and segments ``['owner', 'jane']``."
msgstr ""

#: ../../guides/routing.rst:110
msgid "Elgg triggers the plugin hook ``route, blog`` (see above)."
msgstr ""

#: ../../guides/routing.rst:111
msgid "Elgg finds a registered page handler (see above) for ``blog``, and calls the function, passing in the segments."
msgstr ""

#: ../../guides/routing.rst:113
msgid "The page handler function determines it needs to render a single user's blog. It stores the username via ``set_input()`` and calls the view ``resources/blog/owner``."
msgstr ""

#: ../../guides/routing.rst:115
msgid "The ``resources/blog/owner`` view gets the username via ``get_input()``, 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:117
msgid "The page handler echos the view HTML and returns ``true`` to indicate it handled the request."
msgstr ""

#: ../../guides/routing.rst:118
msgid "PHP invokes Elgg's shutdown sequence."
msgstr ""

#: ../../guides/routing.rst:119
msgid "The user receives a fully rendered page."
msgstr ""

#: ../../guides/routing.rst:121
msgid "Elgg's coding standards suggest a particular URL layout, but there is no syntax enforced."
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 ``param[`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 ``param[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:34
msgid "User settings"
msgstr ""

#: ../../guides/settings.rst:36
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:40
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:43
msgid "Retrieving settings in your code"
msgstr ""

#: ../../guides/settings.rst:45
msgid "To retrieve settings from your code use:"
msgstr ""

#: ../../guides/settings.rst:51
msgid "or for user settings"
msgstr ""

#: ../../guides/settings.rst:57
msgid "where:"
msgstr ""

#: ../../guides/settings.rst:59
msgid "``$name`` Is the value you want to retrieve"
msgstr ""

#: ../../guides/settings.rst:60
msgid "``$user_guid`` Is the user you want to retrieve these for (defaults to the currently logged in user)"
msgstr ""

#: ../../guides/settings.rst:61
msgid "``$plugin_name`` Is the name of the plugin (detected if run from within a plugin)"
msgstr ""

#: ../../guides/settings.rst:64
msgid "Setting values while in code"
msgstr ""

#: ../../guides/settings.rst:66
msgid "Values may also be set from within your plugin code, to do this use one of the following functions:"
msgstr ""

#: ../../guides/settings.rst:72
msgid "or"
msgstr ""

#: ../../guides/settings.rst:80
msgid "The ``$plugin_id`` needs to be provided when setting plugin (user)settings."
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 "Create your plugin"
msgstr ""

#: ../../guides/themes.rst:19
msgid "Create your plugin as described in the :doc:`developer guide </guides/index>`."
msgstr ""

#: ../../guides/themes.rst:21
msgid "Create a new directory under mod/"
msgstr ""

#: ../../guides/themes.rst:22
msgid "Create a new start.php"
msgstr ""

#: ../../guides/themes.rst:23
msgid "Create a manifest.xml file describing your theme."
msgstr ""

#: ../../guides/themes.rst:26
msgid "Customize the CSS"
msgstr ""

#: ../../guides/themes.rst:28
msgid "As of Elgg 1.8, 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:33
msgid "Here is a list of the existing CSS views:"
msgstr ""

#: ../../guides/themes.rst:35
msgid "css/elements/buttons: 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:36
msgid "css/elements/chrome: This file has some miscellaneous look-and-feel classes."
msgstr ""

#: ../../guides/themes.rst:37
msgid "css/elements/components: 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:38
msgid "css/elements/forms: This file determines what your forms and input elements will look like."
msgstr ""

#: ../../guides/themes.rst:39
msgid "css/elements/icons: Contains styles for the sprite icons and avatars used on your site."
msgstr ""

#: ../../guides/themes.rst:40
msgid "css/elements/layout: Determines what your page layout will look like: sidebars, page wrapper, main body, header, footer, etc."
msgstr ""

#: ../../guides/themes.rst:41
msgid "css/elements/modules: 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:42
msgid "css/elements/navigation: This file determines what all your menus will look like."
msgstr ""

#: ../../guides/themes.rst:43
msgid "css/elements/typography: This file determines what the content and headings of your site will look like."
msgstr ""

#: ../../guides/themes.rst:44
msgid "css/rtl: Custom rules for users viewing your site in a right-to-left language."
msgstr ""

#: ../../guides/themes.rst:45
msgid "css/admin: A completely separate theme for the admin area (usually not overridden)."
msgstr ""

#: ../../guides/themes.rst:46
msgid "css/elgg: Compiles all the core css/elements/\\* files into one file (DO NOT OVERRIDE)."
msgstr ""

#: ../../guides/themes.rst:47
msgid "css/elements/core: 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:48
msgid "css/elements/reset: Contains a reset stylesheet that forces elements to have the same default"
msgstr ""

#: ../../guides/themes.rst:52
msgid "View extension"
msgstr ""

#: ../../guides/themes.rst:54
msgid "There are two ways you can modify views:"
msgstr ""

#: ../../guides/themes.rst:56
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:59
msgid "For example, the following start.php will add mytheme/css to Elgg's core css file:"
msgstr ""

#: ../../guides/themes.rst:74
msgid "View overloading"
msgstr ""

#: ../../guides/themes.rst:76
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:80
msgid "``/mod/myplugin/views/default/css/elements/typography.php``"
msgstr ""

#: ../../guides/themes.rst:82
msgid "it will replace:"
msgstr ""

#: ../../guides/themes.rst:84
msgid "``/views/default/css/elements/typography.php``"
msgstr ""

#: ../../guides/themes.rst:86
msgid "But only when the plugin is active."
msgstr ""

#: ../../guides/themes.rst:88
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:93
msgid "Tools"
msgstr ""

#: ../../guides/themes.rst:95
msgid "Starting in Elgg 1.8, 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:100
msgid "Customizing the front page"
msgstr ""

#: ../../guides/themes.rst:101
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:105
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:108
msgid "Here's a quick overview:"
msgstr ""

#: ../../guides/themes.rst:110
msgid "Create your new plugin"
msgstr ""

#: ../../guides/themes.rst:112
msgid "In the start.php you will need something like the following:"
msgstr ""

#: ../../guides/themes.rst:134
msgid "Then, create an index page (/pluginname/pages/index.php) and use that to put the content you would like on the front page of your Elgg site."
msgstr ""

#: ../../guides/upgrading.rst:2
msgid "Upgrading Plugins"
msgstr ""

#: ../../guides/upgrading.rst:4
msgid "Prepare your plugin for the next version of Elgg."
msgstr ""

#: ../../guides/upgrading.rst:6
msgid "See the administator guides for :doc:`how to upgrade a live site </admin/upgrading>`."
msgstr ""

#: ../../guides/upgrading.rst:13
msgid "From 1.10 to 1.11"
msgstr ""

#: ../../guides/upgrading.rst:16
msgid "Comment highlighting"
msgstr ""

#: ../../guides/upgrading.rst:18
msgid "If your theme is using the file ``views/default/css/elements/components.php``, you must add the following style definitions in it to enable highlighting for comments and discussion replies:"
msgstr ""

#: ../../guides/upgrading.rst:36
msgid "From 1.9 to 1.10"
msgstr ""

#: ../../guides/upgrading.rst:39
msgid "File uploads"
msgstr ""

#: ../../guides/upgrading.rst:41
msgid "If your plugin is using a snippet copied from the ``file/upload`` action to fix detected mime types for Microsoft zipped formats, it can now be safely removed."
msgstr ""

#: ../../guides/upgrading.rst:43
msgid "If your upload action performs other manipulations on detected mime and simple types, it is recommended to make use of available plugin hooks:"
msgstr ""

#: ../../guides/upgrading.rst:45
msgid "``'mime_type','file'`` for filtering detected mime types"
msgstr ""

#: ../../guides/upgrading.rst:46
msgid "``'simple_type','file'`` for filtering parsed simple types"
msgstr ""

#: ../../guides/upgrading.rst:49
msgid "From 1.8 to 1.9"
msgstr ""

#: ../../guides/upgrading.rst:51
msgid "In the examples we are upgrading an imaginary \"Photos\" plugin."
msgstr ""

#: ../../guides/upgrading.rst:53
msgid "Only the key changes are included. For example some of the deprecated functions are not mentioned here separately."
msgstr ""

#: ../../guides/upgrading.rst:55
msgid "Each section will include information whether the change is backwards compatible with Elgg 1.8."
msgstr ""

#: ../../guides/upgrading.rst:58
msgid "The manifest file"
msgstr ""

#: ../../guides/upgrading.rst:60
msgid "No changes are needed if your plugin is compatible with 1.8."
msgstr ""

#: ../../guides/upgrading.rst:62
msgid "It's however recommended to add the ``<id>`` tag. It's value should be the name of the directory where the plugin is located inside the ``mod/`` directory."
msgstr ""

#: ../../guides/upgrading.rst:64
msgid "If you make changes that break BC, you must update the plugin version and the required Elgg release."
msgstr ""

#: ../../guides/upgrading.rst:66
msgid "Example of (shortened) old version:"
msgstr ""

#: ../../guides/upgrading.rst:82
msgid "Example of (shortened) new version:"
msgstr ""

#: ../../guides/upgrading.rst:100
msgid "$CONFIG and $vars['config']"
msgstr ""

#: ../../guides/upgrading.rst:102
msgid "Both the global ``$CONFIG`` variable and the ``$vars['config']`` parameter have been deprecated. They should be replaced with the ``elgg_get_config()`` function."
msgstr ""

#: ../../guides/upgrading.rst:104
msgid "Example of old code:"
msgstr ""

#: ../../guides/upgrading.rst:115
msgid "Example of new code:"
msgstr ""

#: ../../guides/upgrading.rst:123
#: ../../guides/upgrading.rst:312
msgid "Compatible with 1.8"
msgstr ""

#: ../../guides/upgrading.rst:127
msgid "See how the community_plugins plugin was updated: https://github.com/Elgg/community_plugins/commit/f233999bbd1478a200ee783679c2e2897c9a0483"
msgstr ""

#: ../../guides/upgrading.rst:130
msgid "Language files"
msgstr ""

#: ../../guides/upgrading.rst:132
msgid "In Elgg 1.8 the language files needed to use the ``add_translation()`` function. In 1.9 it is enough to just return the array that was previously passed to the function as a parameter. Elgg core will use the file name (e.g. en.php) to tell which language the file contains."
msgstr ""

#: ../../guides/upgrading.rst:135
msgid "Example of the old way in ``languages/en.php``:"
msgstr ""

#: ../../guides/upgrading.rst:144
msgid "Example of new way:"
msgstr ""

#: ../../guides/upgrading.rst:154
#: ../../guides/upgrading.rst:244
#: ../../guides/upgrading.rst:340
#: ../../guides/upgrading.rst:402
msgid "Not compatible with 1.8"
msgstr ""

#: ../../guides/upgrading.rst:159
msgid "One of the biggest changes in Elgg 1.9 is the notifications system. The new system allows more flexible and scalable way of sending notifications."
msgstr ""

#: ../../guides/upgrading.rst:161
#: ../../guides/upgrading.rst:262
#: ../../guides/upgrading.rst:347
msgid "Example of the old way:"
msgstr ""

#: ../../guides/upgrading.rst:200
#: ../../guides/upgrading.rst:282
#: ../../guides/upgrading.rst:368
msgid "Example of the new way:"
msgstr ""

#: ../../guides/upgrading.rst:248
msgid "See how the community_plugins plugin was updated to use the new system: https://github.com/Elgg/community_plugins/commit/bfa356cfe8fb99ebbca4109a1b8a1383b70ff123"
msgstr ""

#: ../../guides/upgrading.rst:250
msgid "Notifications can also be sent with the ``notify_user()`` function."
msgstr ""

#: ../../guides/upgrading.rst:252
msgid "It has however been updated to support three new optional parameters passed inside an array as the fifth parameter."
msgstr ""

#: ../../guides/upgrading.rst:254
msgid "The parameters give notification plugins more control over the notifications, so they should be included whenever possible. For example the bundled site_notifications plugin won't work properly if the parameters are missing."
msgstr ""

#: ../../guides/upgrading.rst:256
msgid "Parameters:"
msgstr ""

#: ../../guides/upgrading.rst:258
msgid "**object** The object that we are notifying about (e.g. ElggEntity or ElggAnnotation). This is needed so that notification plugins can provide a link to the object."
msgstr ""

#: ../../guides/upgrading.rst:259
msgid "**action** String that describes the action that triggered the notification (e.g. \"create\", \"update\", etc)."
msgstr ""

#: ../../guides/upgrading.rst:260
msgid "**summary** String that contains a summary of the notification. (It should be more informative than the notification subject but less informative than the notification body.)"
msgstr ""

#: ../../guides/upgrading.rst:315
msgid "Adding items to the Activity listing"
msgstr ""

#: ../../guides/upgrading.rst:330
msgid "You can also add the optional ``target_guid`` parameter which tells the target of the create action."
msgstr ""

#: ../../guides/upgrading.rst:332
msgid "If the photo would had been added for example into a photo album, we could add it by passing in also:"
msgstr ""

#: ../../guides/upgrading.rst:343
msgid "Entity URL handlers"
msgstr ""

#: ../../guides/upgrading.rst:345
msgid "The ``elgg_register_entity_url_handler()`` function has been deprecated. In 1.9 you should use the ``'entity:url', 'object'`` plugin hook instead."
msgstr ""

#: ../../guides/upgrading.rst:405
#: ../../guides/web-services.rst:2
msgid "Web services"
msgstr ""

#: ../../guides/upgrading.rst:407
msgid "In Elgg 1.8 the web services API was included in core and methods were exposed using ``expose_function()``. To enable the same functionality for Elgg 1.9, enable the \"Web services 1.9\" plugin and replace all calls to ``expose_function()`` with  ``elgg_ws_expose_function()``."
msgstr ""

#: ../../guides/upgrading.rst:413
msgid "From 1.7 to 1.8"
msgstr ""

#: ../../guides/upgrading.rst:414
msgid "Elgg 1.8 is the biggest leap forward in the development of Elgg since version 1.0. As such, there is more work to update core and plugins than with previous upgrades. There were a small number of API changes and following our standard practice, the methods we deprecated have been updated to work with the new API. The biggest changes are in the standardization of plugins and in the views system."
msgstr ""

#: ../../guides/upgrading.rst:422
msgid "Updating core"
msgstr ""

#: ../../guides/upgrading.rst:423
msgid "Delete the following core directories (same level as _graphics and engine):"
msgstr ""

#: ../../guides/upgrading.rst:425
msgid "_css"
msgstr ""

#: ../../guides/upgrading.rst:426
msgid "account"
msgstr ""

#: ../../guides/upgrading.rst:427
msgid "admin"
msgstr ""

#: ../../guides/upgrading.rst:428
msgid "dashboard"
msgstr ""

#: ../../guides/upgrading.rst:429
msgid "entities"
msgstr ""

#: ../../guides/upgrading.rst:430
msgid "friends"
msgstr ""

#: ../../guides/upgrading.rst:431
msgid "search"
msgstr ""

#: ../../guides/upgrading.rst:432
msgid "settings"
msgstr ""

#: ../../guides/upgrading.rst:433
msgid "simplecache"
msgstr ""

#: ../../guides/upgrading.rst:434
msgid "views"
msgstr ""

#: ../../guides/upgrading.rst:438
msgid "If you do not delete these directories before an upgrade, you will have problems!"
msgstr ""

#: ../../guides/upgrading.rst:442
msgid "Updating plugins"
msgstr ""

#: ../../guides/upgrading.rst:446
msgid "All: /page_handler/all"
msgstr ""

#: ../../guides/upgrading.rst:447
msgid "User’s content: /page_handler/owner/:username"
msgstr ""

#: ../../guides/upgrading.rst:448
msgid "User’s friends' content: /page_handler/friends/:username"
msgstr ""

#: ../../guides/upgrading.rst:449
msgid "Single entity: /page_handler/view/:guid/:title"
msgstr ""

#: ../../guides/upgrading.rst:450
msgid "Added: /page_handler/add/:container_guid"
msgstr ""

#: ../../guides/upgrading.rst:451
msgid "Editing: /page_handler/edit/:guid"
msgstr ""

#: ../../guides/upgrading.rst:452
msgid "Group list: /page_handler/group/:guid/all"
msgstr ""

#: ../../guides/upgrading.rst:456
msgid "Include page handler scripts from the page handler"
msgstr ""

#: ../../guides/upgrading.rst:457
msgid "Almost every page handler should have a page handler script. (Example: ``bookmarks/all => mod/bookmarks/pages/bookmarks/all.php``)"
msgstr ""

#: ../../guides/upgrading.rst:461
msgid "Call ``gatekeeper()`` and ``admin_gatekeeper()`` in the page handler function if required."
msgstr ""

#: ../../guides/upgrading.rst:462
msgid "The group URL should use the ``pages/:handler/owner.php`` script."
msgstr ""

#: ../../guides/upgrading.rst:464
msgid "Update the URLs throughout the plugin. (Don't forget to remove ``/pg/``!)"
msgstr ""

#: ../../guides/upgrading.rst:469
msgid "Store page handler scripts in ``mod/:plugin/pages/:page_handler/:page_name.php``"
msgstr ""

#: ../../guides/upgrading.rst:470
msgid "Use the content page layout in page handler scripts:"
msgstr ""

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

#: ../../guides/upgrading.rst:478
msgid "No need to set page owner if the URLs are in the standardized format."
msgstr ""

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

#: ../../guides/upgrading.rst:483
msgid "The ``object/:subtype`` view"
msgstr ""

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

#: ../../guides/upgrading.rst:485
msgid "Check for the object in ``$vars['entity']``. Use ``elgg_instance_of()`` to make sure it's the type of entity you want."
msgstr ""

#: ../../guides/upgrading.rst:486
msgid "Return ``true`` to short circuit the view if the entity is missing or wrong."
msgstr ""

#: ../../guides/upgrading.rst:487
msgid "Use ``elgg_view(‘object/elements/summary’, array(‘entity’ => $entity));`` and ``elgg_view_menu(‘entity’, array(‘entity’ => $entity));`` to help format. You should use very little markup in these views."
msgstr ""

#: ../../guides/upgrading.rst:491
msgid "Update action structure"
msgstr ""

#: ../../guides/upgrading.rst:495
msgid "Add: ``action/:plugin/save``"
msgstr ""

#: ../../guides/upgrading.rst:496
msgid "Edit: ``action/:plugin/save``"
msgstr ""

#: ../../guides/upgrading.rst:497
msgid "Delete: ``action/:plugin/delete``"
msgstr ""

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

#: ../../guides/upgrading.rst:503
msgid "Update deprecated functions"
msgstr ""

#: ../../guides/upgrading.rst:504
msgid "Functions deprecated in 1.7 will produce visible errors in 1.8."
msgstr ""

#: ../../guides/upgrading.rst:506
msgid "See ``/engine/lib/deprecated-1.7.php`` for the full list."
msgstr ""

#: ../../guides/upgrading.rst:508
msgid "You can also update functions deprecated in 1.8."
msgstr ""

#: ../../guides/upgrading.rst:510
msgid "Many registration functions simply added an ``elgg_`` prefix for consistency, and should be easy to update."
msgstr ""

#: ../../guides/upgrading.rst:511
msgid "See ``/engine/lib/deprecated-1.8.php`` for the full list."
msgstr ""

#: ../../guides/upgrading.rst:512
msgid "You can set the debug level to “warning” to get visual reminders of deprecated functions."
msgstr ""

#: ../../guides/upgrading.rst:516
msgid "Update the widget views"
msgstr ""

#: ../../guides/upgrading.rst:517
msgid "See the blog or file widgets for examples."
msgstr ""

#: ../../guides/upgrading.rst:521
msgid "Update the group profile module"
msgstr ""

#: ../../guides/upgrading.rst:522
msgid "Use the blog or file plugins for examples. This will help with making your plugin themeable by the new CSS framework."
msgstr ""

#: ../../guides/upgrading.rst:526
msgid "Update forms"
msgstr ""

#: ../../guides/upgrading.rst:527
msgid "Move form bodies to the ``forms/:action`` view to use Evan's new ``elgg_view_form``."
msgstr ""

#: ../../guides/upgrading.rst:528
msgid "Use input views in form bodies rather than html. This helps with theming and future-proofing."
msgstr ""

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

#: ../../guides/upgrading.rst:530
msgid "Make your forms sticky (see the file plugin's upload action and form prepare function)."
msgstr ""

#: ../../guides/upgrading.rst:532
msgid "The forms API is discussed in more detail in :doc:`/guides/actions`."
msgstr ""

#: ../../guides/upgrading.rst:537
msgid "We have added many CSS patterns to the base CSS file (modules, image block, spacing primitives). We encourage you to use these patterns and classes wherever possible. Doing so should:"
msgstr ""

#: ../../guides/upgrading.rst:539
msgid "Reduce maintenance costs, since you can delete most custom CSS."
msgstr ""

#: ../../guides/upgrading.rst:540
msgid "Make your plugin more compatible with community themes."
msgstr ""

#: ../../guides/upgrading.rst:542
msgid "Look for patterns that can be moved into core if you need significant CSS."
msgstr ""

#: ../../guides/upgrading.rst:544
msgid "We use hyphens rather than underscores in classes/ids and encourage you do the same for consistency."
msgstr ""

#: ../../guides/upgrading.rst:546
msgid "If you do need your own CSS, you should use your own namespace, rather than ``elgg-``."
msgstr ""

#: ../../guides/upgrading.rst:550
msgid "Update manifest.xml"
msgstr ""

#: ../../guides/upgrading.rst:551
msgid "Use http://el.gg/manifest17to18 to automate this."
msgstr ""

#: ../../guides/upgrading.rst:552
msgid "Don't use the \"bundled\" category with your plugins. That is only for plugins distributed with Elgg."
msgstr ""

#: ../../guides/upgrading.rst:556
msgid "Update settings and user settings views"
msgstr ""

#: ../../guides/upgrading.rst:557
msgid "The view for settings is now ``plugins/:plugin/settings`` (previously ``settings/:plugin/edit``)."
msgstr ""

#: ../../guides/upgrading.rst:558
msgid "The view for user settings is now ``plugins/:plugin/usersettings`` (previously ``usersettings/:plugin/edit``)."
msgstr ""

#: ../../guides/views.rst:9
msgid "Introduction"
msgstr ""

#: ../../guides/views.rst:11
msgid "Elgg follows a MVC pattern and Views are the V in MVC. Views are responsible for creating the output. Generally, this will be HTML sent to a web browser, but it could also be RSS, JSON or any number of other data formats."
msgstr ""

#: ../../guides/views.rst:13
msgid "The Views system handles everything from the layout of pages and chunks of presentation output (like a footer or a toolbar) down to individual links and form inputs. It also allows for advanced features like automatic RSS generation, a swift-to-develop mobile interface, and the alternative interfaces suggested below."
msgstr ""

#: ../../guides/views.rst:16
msgid "Using views"
msgstr ""

#: ../../guides/views.rst:18
msgid "At their most basic level, the default views are just PHP files with snippets of html. For example:"
msgstr ""

#: ../../guides/views.rst:24
msgid "Assuming this view is located at ``/views/default/hello.php``, we could output it like so:"
msgstr ""

#: ../../guides/views.rst:30
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:36
msgid "Well that's easy enough to remember! The name of the view simply reflects the location of the view in the views directory."
msgstr ""

#: ../../guides/views.rst:39
msgid "Views as templates"
msgstr ""

#: ../../guides/views.rst:41
msgid "Views would be pretty useless if they could only contain static information. Fortunately, 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:47
msgid "In this case, we can pass an arbitrary name parameter to the view like so:"
msgstr ""

#: ../../guides/views.rst:53
msgid "which would produce the following output:"
msgstr ""

#: ../../guides/views.rst:62
msgid "Viewtypes"
msgstr ""

#: ../../guides/views.rst:64
msgid "You might be wondering, \"what's with the 'default' in the directory structure? Why don't we just put the ``hello/world`` view at ``/views/hello/world.php``?\"."
msgstr ""

#: ../../guides/views.rst:66
msgid "Great question."
msgstr ""

#: ../../guides/views.rst:68
msgid "This subdirectory (the one under ``/views``) determines the *viewtype* of the views below it. It's possible that you might want your Elgg site to have several sets of interface pages. For example:"
msgstr ""

#: ../../guides/views.rst:70
msgid "Standard HTML for desktop browsing (This is the default view)"
msgstr ""

#: ../../guides/views.rst:71
msgid "HTML optimized for Mobile devices (iPhone, Android, Blackberry, etc.)"
msgstr ""

#: ../../guides/views.rst:72
msgid "HTML optimized Tablet devices (iPad, etc.)"
msgstr ""

#: ../../guides/views.rst:73
msgid "RSS"
msgstr ""

#: ../../guides/views.rst:74
msgid "Atom"
msgstr ""

#: ../../guides/views.rst:75
msgid "JSON"
msgstr ""

#: ../../guides/views.rst:76
msgid "etc..."
msgstr ""

#: ../../guides/views.rst:78
msgid "In Elgg, one set of these interface pages is called a *viewtype*. You can force Elgg to use a particular viewtype to render the page simply by setting the ``$view`` input variable. For example, to get an RSS version of the home page, you would access ``http://localhost/elgg/?view=rss``."
msgstr ""

#: ../../guides/views.rst:80
msgid "You could also write a plugin to set this automatically using the ``set_input()`` function. For example, your plugin might detect that the page was accessed with an iPhone's browser string, and set the viewtype to *handheld* by calling:"
msgstr ""

#: ../../guides/views.rst:86
msgid "The plugin would presumably also supply a set of views optimized for handheld devices."
msgstr ""

#: ../../guides/views.rst:91
msgid "Altering views via plugins"
msgstr ""

#: ../../guides/views.rst:93
msgid "Without modifying Elgg's core, Elgg provides several ways to customize almost all output:"
msgstr ""

#: ../../guides/views.rst:95
msgid "You can `override a view <#overriding-views>`_, completely changing the file used to render it."
msgstr ""

#: ../../guides/views.rst:96
msgid "You can `extend a view <#extending-views>`_ by prepending or appending the output of another view to it."
msgstr ""

#: ../../guides/views.rst:97
msgid "You can `alter a view's inputs <#altering-view-input>`_ by plugin hook."
msgstr ""

#: ../../guides/views.rst:98
msgid "You can `alter a view's output <#altering-view-output>`_ by plugin hook."
msgstr ""

#: ../../guides/views.rst:101
msgid "Overriding views"
msgstr ""

#: ../../guides/views.rst:103
msgid "Via plugin you can completely replace the rendering strategy of a view provided by Elgg or another plugin. Each plugin may have its own ``/views`` directory, and within it define its own view implementations."
msgstr ""

#: ../../guides/views.rst:105
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:107
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:113
msgid "While it is **not recommended**, one *could* alternatively force the location of a view using the ``set_view_location`` function:"
msgstr ""

#: ../../guides/views.rst:119
msgid "Again, the best way to override views is to place them in the appropriate place in the views hierarchy."
msgstr ""

#: ../../guides/views.rst:123
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. You may instead want to :ref:`alter the input <guides/views#altering-view-input>` or the :ref:`the output <guides/views#altering-view-output>` of the view via plugin hooks."
msgstr ""

#: ../../guides/views.rst:127
msgid "Elgg caches view locations. This means that you should disable the system cache while working with views. When you install the changes to a production environment you mush flush the caches."
msgstr ""

#: ../../guides/views.rst:130
msgid "Extending views"
msgstr ""

#: ../../guides/views.rst:132
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:134
msgid "For example, instead of overriding the ``hello/world`` view, we could extend it like so:"
msgstr ""

#: ../../guides/views.rst:140
msgid "If the contents of ``/views/default/hello/greeting.php`` is:"
msgstr ""

#: ../../guides/views.rst:146
msgid "Then every time we call ``elgg_view('hello/world');``, we'll get:"
msgstr ""

#: ../../guides/views.rst:153
msgid "You can prepend views by passing a value to the 3rd parameter that is less than 500:"
msgstr ""

#: ../../guides/views.rst:163
msgid "Note that if you extend the core css view like this:"
msgstr ""

#: ../../guides/views.rst:169
msgid "You **must** do so within code that is executed by engine/start.php (normally this would mean your plugin's init code).  Because the core css view is loaded separately via a ``<link>`` tag, any extensions you add will not have the same context as the rest of your page."
msgstr ""

#: ../../guides/views.rst:174
msgid "Altering view input"
msgstr ""

#: ../../guides/views.rst:176
msgid "It may be useful to alter a view's ``$vars`` array before it's rendered."
msgstr ""

#: ../../guides/views.rst:178
msgid "Since 1.11, 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:180
msgid "``$hook`` - the string ``\"view_vars\"``"
msgstr ""

#: ../../guides/views.rst:181
#: ../../guides/views.rst:211
msgid "``$type`` - the view name being rendered (the first argument passed to ``elgg_view()``)"
msgstr ""

#: ../../guides/views.rst:182
msgid "``$returnvalue`` - the ``$vars`` array"
msgstr ""

#: ../../guides/views.rst:183
msgid "``$params`` - an array containing: the unaltered ``$vars`` under the key ``vars``; :ref:`viewtype <guides/views#viewtypes>` being rendered under the key ``viewtype``; the view name under the key ``view``."
msgstr ""

#: ../../guides/views.rst:186
msgid "Altering view input example"
msgstr ""

#: ../../guides/views.rst:188
msgid "Here we'll alter the default pagination limit for the comments view:"
msgstr ""

#: ../../guides/views.rst:204
msgid "Altering view output"
msgstr ""

#: ../../guides/views.rst:206
msgid "Sometimes it is preferable to alter the output of a view instead of overriding it."
msgstr ""

#: ../../guides/views.rst:208
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:210
msgid "``$hook`` - the string ``\"view\"``"
msgstr ""

#: ../../guides/views.rst:212
msgid "``$returnvalue`` - the rendered output of the view (or the return value of the last handler)"
msgstr ""

#: ../../guides/views.rst:213
msgid "``$params`` - an array containing the key ``viewtype`` with value being the :ref:`viewtype <guides/views#viewtypes>` being rendered"
msgstr ""

#: ../../guides/views.rst:215
msgid "To alter the view output, the handler just needs to alter ``$returnvalue`` and return a new string."
msgstr ""

#: ../../guides/views.rst:218
msgid "Altering view output example"
msgstr ""

#: ../../guides/views.rst:220
msgid "Here we'll eliminate breadcrumbs that don't have at least one link."
msgstr ""

#: ../../guides/views.rst:241
msgid "If you don't know what an entity is, :doc:`check this page out first </design/database>`."
msgstr ""

#: ../../guides/views.rst:243
msgid "The following code will automatically display the entity in ``$entity``:"
msgstr ""

#: ../../guides/views.rst:249
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'). ``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``. (RSS feeds in Elgg generally work by outputting the ``object/default`` view in the 'rss' viewtype.)"
msgstr ""

#: ../../guides/views.rst:251
msgid "So for example, the view to display a blogpost might be ``object/blog``. The view to display a user is ``user/user``."
msgstr ""

#: ../../guides/views.rst:254
msgid "Full and partial entity views"
msgstr ""

#: ../../guides/views.rst:256
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:258
msgid "``$entity`` - The entity to display"
msgstr ""

#: ../../guides/views.rst:259
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:260
msgid "``$full_view`` - Whether to display a *full* version of the entity. (Defaults to false.)"
msgstr ""

#: ../../guides/views.rst:262
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:267
msgid "Listing entities"
msgstr ""

#: ../../guides/views.rst:269
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:278
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:280
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:282
msgid "Because it does this, Elgg knows that it can automatically supply an RSS feed - it extends the ``metatags`` view (which is called by the header) in order to provide RSS autodiscovery, which is why you can see the orange RSS icon on those pages."
msgstr ""

#: ../../guides/views.rst:284
msgid "If your entity list will display the entity owners, you can improve performance a bit by preloading all owner entities:"
msgstr ""

#: ../../guides/views.rst:296
msgid "See also :doc:`check this page out first </design/database>`."
msgstr ""

#: ../../guides/views.rst:298
msgid "Since 1.11, you can define an alternative view to render list items using ```'item_view'``` parameter."
msgstr ""

#: ../../guides/views.rst:300
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:302
msgid "Consider these two examples:"
msgstr ""

#: ../../guides/views.rst:324
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. 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:327
msgid "Using a different templating system"
msgstr ""

#: ../../guides/views.rst:331
msgid "This functionality is deprecated as of Elgg 1.12. It will be removed in 2.0. It affects the behavior of templates globally, which is almost sure to cause breakages and therefore we suspect no one uses it in practice."
msgstr ""

#: ../../guides/views.rst:335
msgid "You can write your own templating system if you want to."
msgstr ""

#: ../../guides/views.rst:337
msgid "Before going through the motions of drawing views, Elgg checks the ``$CONFIG->template_handler`` variable to see if it contains the name of a callable function. If it does, the function will be passed the view name and template vars, and the return value of this function will be returned instead of the standard output:"
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 and a main content area. In Elgg 1.0+, we've marked out a space \\\"the canvas\\\" for items to write to the page. This means the user always has a very consistent experience, while giving maximum flexibility to plugin authors for laying out their functionality."
msgstr ""

#: ../../guides/views/page-structure.rst:6
msgid "Think of the canvas area as a big rectangle that you can do what you like in. We've created a couple of standard canvases for you:"
msgstr ""

#: ../../guides/views/page-structure.rst:8
msgid "one column"
msgstr ""

#: ../../guides/views/page-structure.rst:9
msgid "two column"
msgstr ""

#: ../../guides/views/page-structure.rst:10
msgid "content"
msgstr ""

#: ../../guides/views/page-structure.rst:11
msgid "widgets"
msgstr ""

#: ../../guides/views/page-structure.rst:13
msgid "are the main ones. You can access these with the function:"
msgstr ""

#: ../../guides/views/page-structure.rst:22
msgid "The content sections are passed as an ``array`` in the second parameter. The array keys correspond to sections in the layout, the choice of layout will determine which sections to pass. The array values contain the html that should be displayed in those areas. Examples of two common layouts:"
msgstr ""

#: ../../guides/views/page-structure.rst:37
msgid "You can then, ultimately, pass this into the ``elgg_view_page`` function:"
msgstr ""

#: ../../guides/views/page-structure.rst:43
msgid "You may also have noticed that we've started including a standard title area at the top of each plugin page (or at least, most plugin pages). This is created using the following wrapper function, and should usually be included at the top of the plugin content:"
msgstr ""

#: ../../guides/views/page-structure.rst:49
msgid "This will also display any submenu items that exist (unless you set the second, optional parameter to false). So how do you add submenu items?"
msgstr ""

#: ../../guides/views/page-structure.rst:51
msgid "In your plugin_init function, include the following call:"
msgstr ""

#: ../../guides/views/page-structure.rst:61
msgid "The submenu will then automatically display when your page is rendered. The 'identifier' is a machine name for the link, it should be unique per menu."
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:11
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:13
msgid "The criteria for whether a view is suitable for the Simplecache is as follows:"
msgstr ""

#: ../../guides/views/simplecache.rst:15
msgid "The view must not change depending on who or when it is being looked at"
msgstr ""

#: ../../guides/views/simplecache.rst:16
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:19
msgid "Regenerating the Simplecache"
msgstr ""

#: ../../guides/views/simplecache.rst:21
msgid "You can regenerate the Simplecache at any time by:"
msgstr ""

#: ../../guides/views/simplecache.rst:23
msgid "Loading ``/upgrade.php``, even if you have nothing to upgrade"
msgstr ""

#: ../../guides/views/simplecache.rst:24
msgid "In the admin panel click on 'Flush the caches'"
msgstr ""

#: ../../guides/views/simplecache.rst:25
msgid "Enabling or disabling a plugin"
msgstr ""

#: ../../guides/views/simplecache.rst:26
msgid "Reordering your plugins"
msgstr ""

#: ../../guides/views/simplecache.rst:29
msgid "Using the Simplecache in your plugins"
msgstr ""

#: ../../guides/views/simplecache.rst:31
msgid "**Registering views with the Simplecache**"
msgstr ""

#: ../../guides/views/simplecache.rst:33
msgid "You can register a view with the Simplecache with the following function at init-time:"
msgstr ""

#: ../../guides/views/simplecache.rst:39
msgid "**Accessing the cached view**"
msgstr ""

#: ../../guides/views/simplecache.rst:41
msgid "If you registered a JavaScript or CSS file with Simplecache and put in in the view folder ``js/your_view`` or ``css/your_view`` you can very easily the the url to this cached view by calling"
msgstr ""

#: ../../guides/views/simplecache.rst:47
msgid "Where:"
msgstr ""

#: ../../guides/views/simplecache.rst:49
msgid "``$type`` is js or css"
msgstr ""

#: ../../guides/views/simplecache.rst:50
msgid "``$view`` the view name after css/ or js/"
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 1.8, 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:14
msgid "Exposing pages through Walled Gardens"
msgstr ""

#: ../../guides/walled-garden.rst:16
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:18
msgid "Plugin authors must register pages as public if they should be viewable through Walled Gardens by responding to the ``public_pages``, ``walled_garden`` plugin hook."
msgstr ""

#: ../../guides/walled-garden.rst:20
msgid "The returned value is an array of regexp expressions for public pages."
msgstr ""

#: ../../guides/walled-garden.rst:22
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:`pagehandler` for ``my_plugin``."
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:70
msgid "If you add this code to a plugin and then go to http://yoursite.com/services/api/rest/xml/?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/xml/?method=test.echo&string=testing and you should see xml data like this:"
msgstr ""

#: ../../guides/web-services.rst:85
msgid "Response formats"
msgstr ""

#: ../../guides/web-services.rst:87
msgid "The web services API framework provides three different response formats by default: xml, json, and serialized php. You can request the different formats for substituting “json” or “php” for “xml” in the above URLs. You can also add additional response formats by defining new viewtypes."
msgstr ""

#: ../../guides/web-services.rst:93
msgid "Parameters"
msgstr ""

#: ../../guides/web-services.rst:95
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:97
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:99
msgid "Recognized parameter types are:"
msgstr ""

#: ../../guides/web-services.rst:101
msgid "``integer`` (or ``int``)"
msgstr ""

#: ../../guides/web-services.rst:102
msgid "``boolean`` (or ``bool``)"
msgstr ""

#: ../../guides/web-services.rst:103
msgid "``string``"
msgstr ""

#: ../../guides/web-services.rst:104
msgid "``float``"
msgstr ""

#: ../../guides/web-services.rst:105
msgid "``array``"
msgstr ""

#: ../../guides/web-services.rst:107
msgid "Unrecognized types will throw an API exception."
msgstr ""

#: ../../guides/web-services.rst:109
msgid "You can use additional fields to describe your parameter, e.g. ``description``."
msgstr ""

#: ../../guides/web-services.rst:135
msgid "API authentication"
msgstr ""

#: ../../guides/web-services.rst:137
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:145
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:156
msgid "Key-based authentication"
msgstr ""

#: ../../guides/web-services.rst:158
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:169
msgid "Now, let's expose it and make the number of minutes an optional parameter:"
msgstr ""

#: ../../guides/web-services.rst:184
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. Fortunately, there is a plugin called apiadmin that creates keys for you. It is available in the Elgg plugin repository. 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:197
msgid "Signature-based authentication"
msgstr ""

#: ../../guides/web-services.rst:199
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:209
msgid "OAuth"
msgstr ""

#: ../../guides/web-services.rst:211
msgid "With the addition of the OAuth plugin, Elgg also fully supports the OAuth 1.0a authorization standard. Clients can then use standard OAuth libraries to make any API calls to the site."
msgstr ""

#: ../../guides/web-services.rst:216
msgid "User authentication"
msgstr ""

#: ../../guides/web-services.rst:218
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:232
msgid "Let's write our wire posting function:"
msgstr ""

#: ../../guides/web-services.rst:246
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:261
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. There is some example client code in ``/engine/lib/api.php``. Take a look at `send\\_api\\_post\\_call()`_. You can also do a search for clients that have been written for the APIs of Flickr or Twitter or any other similar API. You will find a wide variety written in almost any language you can think of."
msgstr ""

#: ../../guides/web-services.rst:270
msgid "Building out your API"
msgstr ""

#: ../../guides/web-services.rst:272
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:284
msgid "Determining the authentication available"
msgstr ""

#: ../../guides/web-services.rst:286
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:292
msgid "The first step is registering a callback function for the *rest, init* plugin hook:"
msgstr ""

#: ../../guides/web-services.rst:299
msgid "Then in the callback function, you register the PAMs that you want to use:"
msgstr ""

#: ../../guides/web-services.rst:315
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.rst:320
msgid "Right now, the only other PAMs publicly available besides those provided by the Elgg core are the OAuth PAMs. See `Justin Richer's OAuth plugin`_ for more detail."
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/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:6
msgid "TODO: Screenshot"
msgstr ""

#: ../../guides/widgets.rst:13
msgid "Structure"
msgstr ""

#: ../../guides/widgets.rst:15
msgid "To create a widget, create two views:"
msgstr ""

#: ../../guides/widgets.rst:17
msgid "``widgets/widget/edit``"
msgstr ""

#: ../../guides/widgets.rst:18
msgid "``widgets/widget/content``"
msgstr ""

#: ../../guides/widgets.rst:20
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:24
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:30
msgid "Initialise the widget"
msgstr ""

#: ../../guides/widgets.rst:32
msgid "Once you have created your edit and view pages, you need to initialize the plugin widget. This is done within the plugins ``init()`` function."
msgstr ""

#: ../../guides/widgets.rst:41
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:55
msgid "Multiple widgets"
msgstr ""

#: ../../guides/widgets.rst:57
msgid "Make sure you have the corrosponding directories within your plugin views structure:"
msgstr ""

#: ../../guides/widgets.rst:77
msgid "Elgg 1.8: Default widgets"
msgstr ""

#: ../../guides/widgets.rst:79
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:81
msgid "To announce default widget support in your plugin, register for the ``get_list, default_widgets`` plugin hook:"
msgstr ""

#: ../../guides/widgets.rst:87
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:89
msgid "name - The name of the widgets page. This is displayed on the tab in the admin interface."
msgstr ""

#: ../../guides/widgets.rst:90
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:91
msgid "widget\\_columns - How many columns the widgets page will use."
msgstr ""

#: ../../guides/widgets.rst:92
msgid "event - The Elgg event to create new widgets for. This is usually ``create``."
msgstr ""

#: ../../guides/widgets.rst:93
msgid "entity\\_type - The entity type to create new widgets for."
msgstr ""

#: ../../guides/widgets.rst:94
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:96
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 ""

#: ../../guides/widgets.rst:117
msgid "Here is a simple Flickr widget that uses Flickr's JSON output."
msgstr ""

#: ../../guides/widgets.rst:119
msgid "Widget edit page:"
msgstr ""

#: ../../guides/widgets.rst:130
msgid "Widget view page:"
msgstr ""

#: ../../guides/widgets.rst:201
msgid "How to restrict where widgets can be used"
msgstr ""

#: ../../guides/widgets.rst:203
msgid "Any plugin that has a widget must register that widget with Elgg. The widget can specify the context that it can be used in (all, just profile, just dashboard, etc.). If you want to change where your users can use a widget, you can make a quick edit to the plugin's source."
msgstr ""

#: ../../guides/widgets.rst:206
msgid "Find where the plugin registers the widget"
msgstr ""

#: ../../guides/widgets.rst:208
msgid "The function you are looking for is ``add_widget_type()``. It is typically used in an init function in ``start.php``. You should be able to go to ``/mod/<plugin name>/``, open ``start.php`` in a text editor, and find the string ``add_widget_type``."
msgstr ""

#: ../../guides/widgets.rst:211
msgid "Changing the function's parameters"
msgstr ""

#: ../../guides/widgets.rst:213
msgid "Let's use the friends plugin as an example. We want to restrict it so that it can only be used on a user's profile. Currently, the function call looks like this:"
msgstr ""

#: ../../guides/widgets.rst:217
msgid "Keep in mind :doc:`dont-modify-core`"
msgstr ""

#: ../../guides/widgets.rst:223
msgid "To restrict it to the profile, change it to this:"
msgstr ""

#: ../../guides/widgets.rst:229
msgid "Notice that the context was not specified originally (there were only 3 parameters and we added a 4th). That means it defaulted to the \"all\" context. Besides \"all\" and \"profile\", the only other context available in default Elgg is \"dashboard\"."
msgstr ""