# 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.10\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-01-26 00:05+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 Guidelines"
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
msgid "Ajax"
msgstr ""

#: ../../guides/actions.rst:375
msgid "To call an action via JavaScript without actually submitting a form, use ``elgg.action``:"
msgstr ""

#: ../../guides/actions.rst:381
msgid "This does a few things under the hood:"
msgstr ""

#: ../../guides/actions.rst:383
msgid "Automatically normalizes the request URL to http://localhost/elgg/action/example."
msgstr ""

#: ../../guides/actions.rst:384
msgid "Adds XSRF tokens to the request body for security"
msgstr ""

#: ../../guides/actions.rst:385
msgid "If the action emits any system messages or errors, they will automatically be displayed when the response comes back."
msgstr ""

#: ../../guides/actions.rst:387
msgid "Often you’ll want to do something in response to a successful action:"
msgstr ""

#: ../../guides/actions.rst:400
msgid "Security"
msgstr ""

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

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

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

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

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

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

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

#: ../../guides/authentication.rst:7
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:9
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:11
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:28
msgid "Importance"
msgstr ""

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

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

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

#: ../../guides/authentication.rst:42
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:195
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($size)`` method. This method accepts a ``$size`` argument that can be either of the configured icon sizes.  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:177
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:180
msgid "views/$viewtype/icon/$type/$subtype.php"
msgstr ""

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

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

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

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

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

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

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

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

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

#: ../../guides/database.rst:193
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:198
msgid "Adding, reading and deleting annotations"
msgstr ""

#: ../../guides/database.rst:200
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:210
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:215
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:221
msgid "Extending ElggEntity"
msgstr ""

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

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

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

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

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

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

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

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

#: ../../guides/database.rst:293
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:297
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:301
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:306
msgid "Custom database functionality"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/dont-modify-core.rst:6
msgid "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 "**log, systemlog**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/events-list.rst:187
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/gatekeeper.rst:2
msgid "Gatekeeper"
msgstr ""

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

#: ../../guides/gatekeeper.rst:9
msgid "elgg_gatekeeper()"
msgstr ""

#: ../../guides/gatekeeper.rst:11
msgid "This function will forward a user to the front page if the current viewing user is not logged in."
msgstr ""

#: ../../guides/gatekeeper.rst:13
msgid "This can be used in your plugin's pages to protect them from being viewed by non-logged in users."
msgstr ""

#: ../../guides/gatekeeper.rst:17
msgid "In versions of Elgg prior to 1.9 this function was called ``gatekeeper()``"
msgstr ""

#: ../../guides/gatekeeper.rst:20
msgid "elgg_admin_gatekeeper()"
msgstr ""

#: ../../guides/gatekeeper.rst:22
msgid "Same as :ref:`elgg-gatekeeper` , but ensures that only admin users can view the page."
msgstr ""

#: ../../guides/gatekeeper.rst:26
msgid "In versions of Elgg prior to 1.9 this function was called ``admin_gatekeeper()``"
msgstr ""

#: ../../guides/gatekeeper.rst:29
msgid "action_gatekeeper()"
msgstr ""

#: ../../guides/gatekeeper.rst:31
msgid "This function should be used in :doc:`actions` , and helps protect the action from certain forms of attack."
msgstr ""

#: ../../guides/gatekeeper.rst:35
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/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:422
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:437
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:440
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:445
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:454
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:469
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:470
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:81
#: ../../guides/plugins/plugin-skeleton.rst:82
msgid "Actions"
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:513
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_loggedin_user_entity()`` Returns the ElggUser for the current user"
msgstr ""

#: ../../guides/helpers.rst:22
msgid "``elgg_get_loggedin_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:434
#: ../../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:498
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 "**register, menu:<menu_name>**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:135
msgid "Triggered after user registers. Return false to delete the user."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:207
msgid "**permissions_check:annotate**"
msgstr ""

#: ../../guides/hooks-list.rst:204
msgid "Return boolean for if the user ``$params['user']`` can create an annotation with the name ``$params['annotation']`` on the entity ``$params['entity']``."
msgstr ""

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:223
#: ../../guides/hooks-list.rst:228
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:226
msgid "Filters an array of access IDs that the user ``$params['user_id']`` can write to."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:285
msgid "In ``get_default_access()``, filters the return value."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:352
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:362
msgid "**usersetting, plugin**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:376
#: ../../guides/hooks-list.rst:387
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:388
msgid "**profile:fields, profile**"
msgstr ""

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

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

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

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

#: ../../guides/hooks-list.rst:418
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:424
msgid "**volatile, metadata**"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/hooks-list.rst:487
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:490
msgid "**search, tags**"
msgstr ""

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

#: ../../guides/hooks-list.rst:493
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:497
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:501
msgid "**search_types, get_queries**"
msgstr ""

#: ../../guides/hooks-list.rst:501
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 "Defining and loading a module in Elgg 1.9 takes two steps:"
msgstr ""

#: ../../guides/javascript.rst:17
msgid "Define your module as asynchronous JavaScript."
msgstr ""

#: ../../guides/javascript.rst:18
msgid "Tell Elgg to asynchronously execute your module in the current page."
msgstr ""

#: ../../guides/javascript.rst:21
msgid "1. Define your module as asynchronous JavaScript"
msgstr ""

#: ../../guides/javascript.rst:23
msgid "You can define a module by creating a view or registering a URL."
msgstr ""

#: ../../guides/javascript.rst:26
msgid "Defining modules as a view"
msgstr ""

#: ../../guides/javascript.rst:28
msgid "Modules defined by creating views are immediately available for use and require no registration. To register a module named ``my/module``, create the view ``views/default/js/my/module.js``."
msgstr ""

#: ../../guides/javascript.rst:33
msgid "A basic module could look like this:"
msgstr ""

#: ../../guides/javascript.rst:47
msgid "Define your module via a URL"
msgstr ""

#: ../../guides/javascript.rst:49
msgid "You can define an existing AMD module using ``elgg_define_js()``. Traditional (browser-globals) JavaScript files can also be defined as AMD modules if you shim them by setting ``exports`` and optionally ``deps``."
msgstr ""

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

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

#: ../../guides/javascript.rst:81
msgid "Do not use ``elgg.provide()`` or ``elgg.require()`` anymore. They are fully replaced by ``define()`` and ``require()`` respectively."
msgstr ""

#: ../../guides/javascript.rst:82
msgid "Return the value of the module instead of adding to a global variable."
msgstr ""

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

#: ../../guides/javascript.rst:87
msgid "2. Tell Elgg to asynchronously execute your module in the current page"
msgstr ""

#: ../../guides/javascript.rst:88
msgid "Once an AMD module is defined, you can use ``require([\"my/module\"])`` from JavaScript to access its \"exported\" value."
msgstr ""

#: ../../guides/javascript.rst:91
msgid "Also, calling ``elgg_require_js(\"my/module\")`` from PHP tells Elgg to execute the module code on the current page."
msgstr ""

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

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

#: ../../guides/javascript.rst:99
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:106
msgid "Traditional JavaScript (1.8)"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/javascript.rst:306
msgid "Ajax helper functions"
msgstr ""

#: ../../guides/javascript.rst:308
msgid "The JS engine includes many features related to AJAX. Some are specific to Elgg, and some extend jQuery's native AJAX features."
msgstr ""

#: ../../guides/javascript.rst:310
msgid "``elgg.get()``"
msgstr ""

#: ../../guides/javascript.rst:312
msgid "Wrapper for jQuery's ``$.ajax()``, but forces GET and does URL normalization. Accepts all standard jQuery options."
msgstr ""

#: ../../guides/javascript.rst:323
msgid "``elgg.post()``"
msgstr ""

#: ../../guides/javascript.rst:325
msgid "Wrapper for jQuery's $.ajax(), but forces POST and does URL normalization. Accepts all standard jQuery options."
msgstr ""

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

#: ../../guides/javascript.rst:329
msgid "Calls an Elgg action with the data passed. This handles outputting of system messages and errors."
msgstr ""

#: ../../guides/javascript.rst:343
msgid "Hooks"
msgstr ""

#: ../../guides/javascript.rst:345
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:348
msgid "Registering a callback to a hook"
msgstr ""

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

#: ../../guides/javascript.rst:352
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:362
msgid "The callback"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../guides/javascript.rst:392
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:134
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:266
#: ../../guides/web-services.rst:272
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:150
msgid "``provides`` only supports ``plugin`` and ``php_extension`` types."
msgstr ""

#: ../../guides/plugins/dependencies.rst:152
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:163
msgid "elgg_version and elgg_release"
msgstr ""

#: ../../guides/plugins/dependencies.rst:165
msgid "These concern the API and release versions of Elgg and requires the following option element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:167
msgid "**version** - The API or release version"
msgstr ""

#: ../../guides/plugins/dependencies.rst:169
msgid "The following option element is supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:171
#: ../../guides/plugins/dependencies.rst:183
msgid "**comparison** - The comparison operator to use. Defaults to >= if not passed"
msgstr ""

#: ../../guides/plugins/dependencies.rst:174
msgid "plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:176
msgid "Specifies an Elgg plugin by its ID (directory name). This requires the following option element:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:178
msgid "**name** - The ID of the plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:180
#: ../../guides/plugins/dependencies.rst:200
msgid "The following option elements are supported, but not required:"
msgstr ""

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

#: ../../guides/plugins/dependencies.rst:186
msgid "priority"
msgstr ""

#: ../../guides/plugins/dependencies.rst:188
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:190
msgid "**plugin** - The plugin ID to base the load order on"
msgstr ""

#: ../../guides/plugins/dependencies.rst:191
msgid "**priority** - The load order: 'before' or 'after'"
msgstr ""

#: ../../guides/plugins/dependencies.rst:194
msgid "php_extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:196
msgid "This checks PHP extensions. The follow option element is required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:198
msgid "**name** - The name of the PHP extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:202
msgid "**version** - The version of the extension"
msgstr ""

#: ../../guides/plugins/dependencies.rst:203
#: ../../guides/plugins/dependencies.rst:219
msgid "**comparison** - The comparison operator to use. Defaults to =="
msgstr ""

#: ../../guides/plugins/dependencies.rst:207
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:210
msgid "php_ini"
msgstr ""

#: ../../guides/plugins/dependencies.rst:212
msgid "This checks PHP settings. The following option elements are required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:214
msgid "**name** - The name of the setting to check"
msgstr ""

#: ../../guides/plugins/dependencies.rst:215
msgid "**value** - The value of the setting to compare against"
msgstr ""

#: ../../guides/plugins/dependencies.rst:217
msgid "The following options are supported, but not required:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:222
msgid "Comparison Operators"
msgstr ""

#: ../../guides/plugins/dependencies.rst:224
msgid "Dependencies that check versions support passing a custom operator via the ``<comparison>`` element."
msgstr ""

#: ../../guides/plugins/dependencies.rst:226
msgid "The follow are valid comparison operators:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:228
msgid "< or lt"
msgstr ""

#: ../../guides/plugins/dependencies.rst:229
msgid "<= or le"
msgstr ""

#: ../../guides/plugins/dependencies.rst:230
msgid "=, ==, or eq"
msgstr ""

#: ../../guides/plugins/dependencies.rst:231
msgid "!=, <>, or ne"
msgstr ""

#: ../../guides/plugins/dependencies.rst:232
msgid "> or gt"
msgstr ""

#: ../../guides/plugins/dependencies.rst:233
msgid ">= or ge"
msgstr ""

#: ../../guides/plugins/dependencies.rst:235
msgid "If ``<comparison>`` is not passed, the follow are used as defaults, depending upon the dependency type:"
msgstr ""

#: ../../guides/plugins/dependencies.rst:237
msgid "requires->elgg_version and elgg_release: >="
msgstr ""

#: ../../guides/plugins/dependencies.rst:238
msgid "requires->plugin: >="
msgstr ""

#: ../../guides/plugins/dependencies.rst:239
msgid "requires->php_extension: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:240
msgid "requires->php_ini: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:241
msgid "all conflicts: ="
msgstr ""

#: ../../guides/plugins/dependencies.rst:245
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:248
msgid "Quick Examples"
msgstr ""

#: ../../guides/plugins/dependencies.rst:251
msgid "Requires Elgg 1.8.2 or higher"
msgstr ""

#: ../../guides/plugins/dependencies.rst:261
msgid "Requires the Groups plugin is active"
msgstr ""

#: ../../guides/plugins/dependencies.rst:271
msgid "Requires to be after the Profile plugin if Profile is active"
msgstr ""

#: ../../guides/plugins/dependencies.rst:282
msgid "Conflicts with The Wire plugin"
msgstr ""

#: ../../guides/plugins/dependencies.rst:292
msgid "Requires at least 256 MB memory in PHP"
msgstr ""

#: ../../guides/plugins/dependencies.rst:304
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:39
msgid "Retrieving settings in your code"
msgstr ""

#: ../../guides/settings.rst:41
msgid "To retrieve settings from your code use:"
msgstr ""

#: ../../guides/settings.rst:47
msgid "or for user settings"
msgstr ""

#: ../../guides/settings.rst:53
msgid "where:"
msgstr ""

#: ../../guides/settings.rst:55
msgid "``$name`` Is the value you want to retrieve"
msgstr ""

#: ../../guides/settings.rst:56
msgid "``$user_guid`` Is the user you want to retrieve these for (defaults to the currently logged in user)"
msgstr ""

#: ../../guides/settings.rst:57
msgid "``$plugin_name`` Is the name of the plugin (detected if run from within a plugin)"
msgstr ""

#: ../../guides/settings.rst:60
msgid "Setting values while in code"
msgstr ""

#: ../../guides/settings.rst:62
msgid "Values may also be set from within your plugin code, to do this use one of the following functions:"
msgstr ""

#: ../../guides/settings.rst:68
msgid "or"
msgstr ""

#: ../../guides/settings.rst:76
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.9 to 1.10"
msgstr ""

#: ../../guides/upgrading.rst:16
msgid "File uploads"
msgstr ""

#: ../../guides/upgrading.rst:18
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:20
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:22
msgid "``'mime_type','file'`` for filtering detected mime types"
msgstr ""

#: ../../guides/upgrading.rst:23
msgid "``'simple_type','file'`` for filtering parsed simple types"
msgstr ""

#: ../../guides/upgrading.rst:26
msgid "From 1.8 to 1.9"
msgstr ""

#: ../../guides/upgrading.rst:28
msgid "In the examples we are upgrading an imaginary \"Photos\" plugin."
msgstr ""

#: ../../guides/upgrading.rst:30
msgid "Only the key changes are included. For example some of the deprecated functions are not mentioned here separately."
msgstr ""

#: ../../guides/upgrading.rst:32
msgid "Each section will include information whether the change is backwards compatible with Elgg 1.8."
msgstr ""

#: ../../guides/upgrading.rst:35
msgid "The manifest file"
msgstr ""

#: ../../guides/upgrading.rst:37
msgid "No changes are needed if your plugin is compatible with 1.8."
msgstr ""

#: ../../guides/upgrading.rst:39
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:41
msgid "If you make changes that break BC, you must update the plugin version and the required Elgg release."
msgstr ""

#: ../../guides/upgrading.rst:43
msgid "Example of (shortened) old version:"
msgstr ""

#: ../../guides/upgrading.rst:59
msgid "Example of (shortened) new version:"
msgstr ""

#: ../../guides/upgrading.rst:77
msgid "$CONFIG and $vars['config']"
msgstr ""

#: ../../guides/upgrading.rst:79
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:81
msgid "Example of old code:"
msgstr ""

#: ../../guides/upgrading.rst:92
msgid "Example of new code:"
msgstr ""

#: ../../guides/upgrading.rst:100
#: ../../guides/upgrading.rst:289
msgid "Compatible with 1.8"
msgstr ""

#: ../../guides/upgrading.rst:104
msgid "See how the community_plugins plugin was updated: https://github.com/Elgg/community_plugins/commit/f233999bbd1478a200ee783679c2e2897c9a0483"
msgstr ""

#: ../../guides/upgrading.rst:107
msgid "Language files"
msgstr ""

#: ../../guides/upgrading.rst:109
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:112
msgid "Example of the old way in ``languages/en.php``:"
msgstr ""

#: ../../guides/upgrading.rst:121
msgid "Example of new way:"
msgstr ""

#: ../../guides/upgrading.rst:131
#: ../../guides/upgrading.rst:221
#: ../../guides/upgrading.rst:317
#: ../../guides/upgrading.rst:379
msgid "Not compatible with 1.8"
msgstr ""

#: ../../guides/upgrading.rst:136
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:138
#: ../../guides/upgrading.rst:239
#: ../../guides/upgrading.rst:324
msgid "Example of the old way:"
msgstr ""

#: ../../guides/upgrading.rst:177
#: ../../guides/upgrading.rst:259
#: ../../guides/upgrading.rst:345
msgid "Example of the new way:"
msgstr ""

#: ../../guides/upgrading.rst:225
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:227
msgid "Notifications can also be sent with the ``notify_user()`` function."
msgstr ""

#: ../../guides/upgrading.rst:229
msgid "It has however been updated to support three new optional parameters passed inside an array as the fifth parameter."
msgstr ""

#: ../../guides/upgrading.rst:231
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:233
msgid "Parameters:"
msgstr ""

#: ../../guides/upgrading.rst:235
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:236
msgid "**action** String that describes the action that triggered the notification (e.g. \"create\", \"update\", etc)."
msgstr ""

#: ../../guides/upgrading.rst:237
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:292
msgid "Adding items to the Activity listing"
msgstr ""

#: ../../guides/upgrading.rst:307
msgid "You can also add the optional ``target_guid`` parameter which tells the target of the create action."
msgstr ""

#: ../../guides/upgrading.rst:309
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:320
msgid "Entity URL handlers"
msgstr ""

#: ../../guides/upgrading.rst:322
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:382
#: ../../guides/web-services.rst:2
msgid "Web services"
msgstr ""

#: ../../guides/upgrading.rst:384
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:390
msgid "From 1.7 to 1.8"
msgstr ""

#: ../../guides/upgrading.rst:391
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:399
msgid "Updating core"
msgstr ""

#: ../../guides/upgrading.rst:400
msgid "Delete the following core directories (same level as _graphics and engine):"
msgstr ""

#: ../../guides/upgrading.rst:402
msgid "_css"
msgstr ""

#: ../../guides/upgrading.rst:403
msgid "account"
msgstr ""

#: ../../guides/upgrading.rst:404
msgid "admin"
msgstr ""

#: ../../guides/upgrading.rst:405
msgid "dashboard"
msgstr ""

#: ../../guides/upgrading.rst:406
msgid "entities"
msgstr ""

#: ../../guides/upgrading.rst:407
msgid "friends"
msgstr ""

#: ../../guides/upgrading.rst:408
msgid "search"
msgstr ""

#: ../../guides/upgrading.rst:409
msgid "settings"
msgstr ""

#: ../../guides/upgrading.rst:410
msgid "simplecache"
msgstr ""

#: ../../guides/upgrading.rst:411
msgid "views"
msgstr ""

#: ../../guides/upgrading.rst:415
msgid "If you do not delete these directories before an upgrade, you will have problems!"
msgstr ""

#: ../../guides/upgrading.rst:419
msgid "Updating plugins"
msgstr ""

#: ../../guides/upgrading.rst:423
msgid "All: /page_handler/all"
msgstr ""

#: ../../guides/upgrading.rst:424
msgid "User’s content: /page_handler/owner/:username"
msgstr ""

#: ../../guides/upgrading.rst:425
msgid "User’s friends' content: /page_handler/friends/:username"
msgstr ""

#: ../../guides/upgrading.rst:426
msgid "Single entity: /page_handler/view/:guid/:title"
msgstr ""

#: ../../guides/upgrading.rst:427
msgid "Added: /page_handler/add/:container_guid"
msgstr ""

#: ../../guides/upgrading.rst:428
msgid "Editing: /page_handler/edit/:guid"
msgstr ""

#: ../../guides/upgrading.rst:429
msgid "Group list: /page_handler/group/:guid/all"
msgstr ""

#: ../../guides/upgrading.rst:433
msgid "Include page handler scripts from the page handler"
msgstr ""

#: ../../guides/upgrading.rst:434
msgid "Almost every page handler should have a page handler script. (Example: ``bookmarks/all => mod/bookmarks/pages/bookmarks/all.php``)"
msgstr ""

#: ../../guides/upgrading.rst:438
msgid "Call ``gatekeeper()`` and ``admin_gatekeeper()`` in the page handler function if required."
msgstr ""

#: ../../guides/upgrading.rst:439
msgid "The group URL should use the ``pages/:handler/owner.php`` script."
msgstr ""

#: ../../guides/upgrading.rst:441
msgid "Update the URLs throughout the plugin. (Don't forget to remove ``/pg/``!)"
msgstr ""

#: ../../guides/upgrading.rst:446
msgid "Store page handler scripts in ``mod/:plugin/pages/:page_handler/:page_name.php``"
msgstr ""

#: ../../guides/upgrading.rst:447
msgid "Use the content page layout in page handler scripts:"
msgstr ""

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

#: ../../guides/upgrading.rst:455
msgid "No need to set page owner if the URLs are in the standardized format."
msgstr ""

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

#: ../../guides/upgrading.rst:460
msgid "The ``object/:subtype`` view"
msgstr ""

#: ../../guides/upgrading.rst:461
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:462
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:463
msgid "Return ``true`` to short circuit the view if the entity is missing or wrong."
msgstr ""

#: ../../guides/upgrading.rst:464
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:468
msgid "Update action structure"
msgstr ""

#: ../../guides/upgrading.rst:472
msgid "Add: ``action/:plugin/save``"
msgstr ""

#: ../../guides/upgrading.rst:473
msgid "Edit: ``action/:plugin/save``"
msgstr ""

#: ../../guides/upgrading.rst:474
msgid "Delete: ``action/:plugin/delete``"
msgstr ""

#: ../../guides/upgrading.rst:476
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:480
msgid "Update deprecated functions"
msgstr ""

#: ../../guides/upgrading.rst:481
msgid "Functions deprecated in 1.7 will produce visible errors in 1.8."
msgstr ""

#: ../../guides/upgrading.rst:483
msgid "See ``/engine/lib/deprecated-1.7.php`` for the full list."
msgstr ""

#: ../../guides/upgrading.rst:485
msgid "You can also update functions deprecated in 1.8."
msgstr ""

#: ../../guides/upgrading.rst:487
msgid "Many registration functions simply added an ``elgg_`` prefix for consistency, and should be easy to update."
msgstr ""

#: ../../guides/upgrading.rst:488
msgid "See ``/engine/lib/deprecated-1.8.php`` for the full list."
msgstr ""

#: ../../guides/upgrading.rst:489
msgid "You can set the debug level to “warning” to get visual reminders of deprecated functions."
msgstr ""

#: ../../guides/upgrading.rst:493
msgid "Update the widget views"
msgstr ""

#: ../../guides/upgrading.rst:494
msgid "See the blog or file widgets for examples."
msgstr ""

#: ../../guides/upgrading.rst:498
msgid "Update the group profile module"
msgstr ""

#: ../../guides/upgrading.rst:499
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:503
msgid "Update forms"
msgstr ""

#: ../../guides/upgrading.rst:504
msgid "Move form bodies to the ``forms/:action`` view to use Evan's new ``elgg_view_form``."
msgstr ""

#: ../../guides/upgrading.rst:505
msgid "Use input views in form bodies rather than html. This helps with theming and future-proofing."
msgstr ""

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

#: ../../guides/upgrading.rst:507
msgid "Make your forms sticky (see the file plugin's upload action and form prepare function)."
msgstr ""

#: ../../guides/upgrading.rst:509
msgid "The forms API is discussed in more detail in :doc:`/guides/actions`."
msgstr ""

#: ../../guides/upgrading.rst:514
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:516
msgid "Reduce maintenance costs, since you can delete most custom CSS."
msgstr ""

#: ../../guides/upgrading.rst:517
msgid "Make your plugin more compatible with community themes."
msgstr ""

#: ../../guides/upgrading.rst:519
msgid "Look for patterns that can be moved into core if you need significant CSS."
msgstr ""

#: ../../guides/upgrading.rst:521
msgid "We use hyphens rather than underscores in classes/ids and encourage you do the same for consistency."
msgstr ""

#: ../../guides/upgrading.rst:523
msgid "If you do need your own CSS, you should use your own namespace, rather than ``elgg-``."
msgstr ""

#: ../../guides/upgrading.rst:527
msgid "Update manifest.xml"
msgstr ""

#: ../../guides/upgrading.rst:528
msgid "Use http://el.gg/manifest17to18 to automate this."
msgstr ""

#: ../../guides/upgrading.rst:529
msgid "Don't use the \"bundled\" category with your plugins. That is only for plugins distributed with Elgg."
msgstr ""

#: ../../guides/upgrading.rst:533
msgid "Update settings and user settings views"
msgstr ""

#: ../../guides/upgrading.rst:534
msgid "The view for settings is now ``plugins/:plugin/settings`` (previously ``settings/:plugin/edit``)."
msgstr ""

#: ../../guides/upgrading.rst:535
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:60
msgid "Overriding views in plugins"
msgstr ""

#: ../../guides/views.rst:62
msgid "You may want to change the output or rendering strategy of a view that Elgg provides by default. Fortunately, Elgg's plugin system makes this easy. Each plugin may have its own ``/views`` directory, with its own viewtypes. Views in plugin directories always override views in the core directory, so this allows you to customize the behavior of any number of views without touching Elgg core."
msgstr ""

#: ../../guides/views.rst:64
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:70
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:76
msgid "Again, the best way to override views is to place them in the appropriate place in the views hierarchy."
msgstr ""

#: ../../guides/views.rst:80
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 want to use :ref:`post processing <guides/views#post-processing-views>` if the change you're making can be easily made with string replacement methods."
msgstr ""

#: ../../guides/views.rst:84
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:89
msgid "Viewtypes"
msgstr ""

#: ../../guides/views.rst:91
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:93
msgid "Great question."
msgstr ""

#: ../../guides/views.rst:95
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:97
msgid "Standard HTML for desktop browsing (This is the default view)"
msgstr ""

#: ../../guides/views.rst:98
msgid "HTML optimized for Mobile devices (iPhone, Android, Blackberry, etc.)"
msgstr ""

#: ../../guides/views.rst:99
msgid "HTML optimized Tablet devices (iPad, etc.)"
msgstr ""

#: ../../guides/views.rst:100
msgid "RSS"
msgstr ""

#: ../../guides/views.rst:101
msgid "Atom"
msgstr ""

#: ../../guides/views.rst:102
msgid "JSON"
msgstr ""

#: ../../guides/views.rst:103
msgid "etc..."
msgstr ""

#: ../../guides/views.rst:105
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:107
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:113
msgid "The plugin would presumably also supply a set of views optimized for handheld devices."
msgstr ""

#: ../../guides/views.rst:116
msgid "Extending views"
msgstr ""

#: ../../guides/views.rst:118
msgid "There may be other situations in which you don't want to override the whole view, you just want to add some more content to the end of it. In Elgg this is called *extending* a view."
msgstr ""

#: ../../guides/views.rst:120
msgid "For example, instead of overriding the ``hello/world`` view, we could extend it like so:"
msgstr ""

#: ../../guides/views.rst:126
msgid "If the contents of ``/views/default/hello/greeting.php`` is:"
msgstr ""

#: ../../guides/views.rst:132
msgid "Then every time we call ``elgg_view('hello/world');``, we'll get:"
msgstr ""

#: ../../guides/views.rst:139
msgid "You can also optionally prepend views as well by passing a value to the 3rd parameter that is less than 500:"
msgstr ""

#: ../../guides/views.rst:149
msgid "Note that if you extend the core css view like this:"
msgstr ""

#: ../../guides/views.rst:155
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:160
msgid "Post processing views"
msgstr ""

#: ../../guides/views.rst:162
msgid "Sometimes it is preferable to process or rewrite the output of a view instead of overriding it."
msgstr ""

#: ../../guides/views.rst:164
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:166
msgid "``$hook`` - the string ``\"view\"``"
msgstr ""

#: ../../guides/views.rst:167
msgid "``$type`` - the view name being rendered (the first argument passed to ``elgg_view()``)"
msgstr ""

#: ../../guides/views.rst:168
msgid "``$returnvalue`` - the rendered output of the view (or the return value of the last handler)"
msgstr ""

#: ../../guides/views.rst:169
msgid "``$params`` - an array containing the key ``viewtype`` with value being the :ref:`viewtype <guides/views#viewtypes>` being rendered"
msgstr ""

#: ../../guides/views.rst:171
msgid "To alter the view output, the handler just needs to alter ``$returnvalue`` and return a new string."
msgstr ""

#: ../../guides/views.rst:174
msgid "Post pocessing view example"
msgstr ""

#: ../../guides/views.rst:176
msgid "Here we'll eliminate breadcrumbs that don't have at least one link."
msgstr ""

#: ../../guides/views.rst:197
msgid "If you don't know what an entity is, :doc:`check this page out first </design/database>`."
msgstr ""

#: ../../guides/views.rst:199
msgid "The following code will automatically display the entity in ``$entity``:"
msgstr ""

#: ../../guides/views.rst:205
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:207
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:210
msgid "Full and partial entity views"
msgstr ""

#: ../../guides/views.rst:212
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:214
msgid "``$entity`` - The entity to display"
msgstr ""

#: ../../guides/views.rst:215
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:216
msgid "``$full_view`` - Whether to display a *full* version of the entity. (Defaults to false.)"
msgstr ""

#: ../../guides/views.rst:218
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:223
msgid "Listing entities"
msgstr ""

#: ../../guides/views.rst:225
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:234
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:236
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:238
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:240
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:252
msgid "See also :doc:`check this page out first </design/database>`."
msgstr ""

#: ../../guides/views.rst:255
msgid "Using a different templating system"
msgstr ""

#: ../../guides/views.rst:257
msgid "You can write your own templating system if you want to."
msgstr ""

#: ../../guides/views.rst:259
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/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:27
msgid "Exposing methods"
msgstr ""

#: ../../guides/web-services.rst:29
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:39
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:55
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:70
msgid "Response formats"
msgstr ""

#: ../../guides/web-services.rst:72
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:78
msgid "API authentication"
msgstr ""

#: ../../guides/web-services.rst:80
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:88
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:99
msgid "Key-based authentication"
msgstr ""

#: ../../guides/web-services.rst:101
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:112
msgid "Now, let's expose it and make the number of minutes an optional parameter:"
msgstr ""

#: ../../guides/web-services.rst:127
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:140
msgid "Signature-based authentication"
msgstr ""

#: ../../guides/web-services.rst:142
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:152
msgid "OAuth"
msgstr ""

#: ../../guides/web-services.rst:154
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:159
msgid "User authentication"
msgstr ""

#: ../../guides/web-services.rst:161
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:175
msgid "Let's write our wire posting function:"
msgstr ""

#: ../../guides/web-services.rst:189
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:204
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:213
msgid "Building out your API"
msgstr ""

#: ../../guides/web-services.rst:215
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:227
msgid "Determining the authentication available"
msgstr ""

#: ../../guides/web-services.rst:229
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:235
msgid "The first step is registering a callback function for the *rest, init* plugin hook:"
msgstr ""

#: ../../guides/web-services.rst:242
msgid "Then in the callback function, you register the PAMs that you want to use:"
msgstr ""

#: ../../guides/web-services.rst:258
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:263
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 ""

