# SOME DESCRIPTIVE TITLE. # Copyright (C) 2013, Various # This file is distributed under the same license as the Elgg package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Elgg 1.12\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2016-03-06 18:02+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../../guides/accessibility.rst:2 msgid "Accessibility" msgstr "" #: ../../guides/accessibility.rst:4 msgid "This page aims to list and document accessibility rules and best practices, to help core and plugins developpers to make Elgg the most accessible social engine framework that everyone dreams of." msgstr "" #: ../../guides/accessibility.rst:8 msgid "This is an ongoing work, please contribute on `Github `_ 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 `_" msgstr "" #: ../../guides/accessibility.rst:14 msgid "`Official WCAG Accessibility Guidelines `_" msgstr "" #: ../../guides/accessibility.rst:15 msgid "`Resources for planning and implementing for accessibility `_" msgstr "" #: ../../guides/accessibility.rst:16 msgid "`Practical tips from the W3C for improving accessibility `_" msgstr "" #: ../../guides/accessibility.rst:17 msgid "`Preliminary review of websites for accessibility `_" msgstr "" #: ../../guides/accessibility.rst:18 msgid "`Tools for checking the accessibility of websites `_" msgstr "" #: ../../guides/accessibility.rst:19 msgid "`List of practical techniques for implementing accessibility `_ (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 ```` tags should have text or an accessible image inside. Otherwise screen readers will have to read the URL, which is a poor experience ```` 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 `_" msgstr "" #: ../../guides/accessibility.rst:35 msgid "Try different font-size/zoom settings in your browser and make sure the theme remains usable" msgstr "" #: ../../guides/accessibility.rst:36 msgid "Turn off css to make sure the sequential order of the page makes sense" msgstr "" #: ../../guides/accessibility.rst:39 msgid "Documentation objectives and principles" msgstr "" #: ../../guides/accessibility.rst:41 msgid "Main accessibility rules" msgstr "" #: ../../guides/accessibility.rst:42 msgid "collect and document best practices" msgstr "" #: ../../guides/accessibility.rst:43 msgid "Provide code examples" msgstr "" #: ../../guides/accessibility.rst:44 msgid "Keep the document simple and usable" msgstr "" #: ../../guides/accessibility.rst:45 msgid "Make it usable for both beginner developpers and experts (from most common and easiest changes to elaborate techniques)" msgstr "" #: ../../guides/actions.rst:2 msgid "Forms + Actions" msgstr "" #: ../../guides/actions.rst:4 msgid "Create, update, or delete content." msgstr "" #: ../../guides/actions.rst:6 msgid "Elgg forms submit to actions. Actions define the behavior for form submission." msgstr "" #: ../../guides/actions.rst:8 msgid "This guide assumes basic familiarity with:" msgstr "" #: ../../guides/actions.rst:10 #: ../../guides/themes.rst:9 msgid ":doc:`/admin/plugins`" msgstr "" #: ../../guides/actions.rst:11 #: ../../guides/themes.rst:10 msgid ":doc:`views`" msgstr "" #: ../../guides/actions.rst:12 msgid ":doc:`i18n`" msgstr "" #: ../../guides/actions.rst:0 #: ../../guides/database.rst:0 #: ../../guides/events-list.rst:0 #: ../../guides/guidelines.rst:0 #: ../../guides/hooks-list.rst:0 #: ../../guides/javascript.rst:0 #: ../../guides/menus.rst:0 #: ../../guides/notifications.rst:0 #: ../../guides/plugins/dependencies.rst:0 #: ../../guides/themes.rst:0 #: ../../guides/upgrading.rst:0 #: ../../guides/views.rst:0 #: ../../guides/web-services.rst:0 #: ../../guides/widgets.rst:0 msgid "Contents" msgstr "" #: ../../guides/actions.rst:19 msgid "Registering actions" msgstr "" #: ../../guides/actions.rst:21 msgid "Actions must be registered before use. Use ``elgg_register_action`` for this:" msgstr "" #: ../../guides/actions.rst:27 msgid "The ``mod/example/actions/example.php`` script will now be run whenever a form is submitted to ``http://localhost/elgg/action/example``." msgstr "" #: ../../guides/actions.rst:29 msgid "A stumbling point for many new developers is the URL for actions. The URL always uses ``/action/`` (singular) and never ``/actions/`` (plural). However, action script files are usually saved under the directory ``/actions/`` (plural) and always have an extension." msgstr "" #: ../../guides/actions.rst:33 msgid "Permissions" msgstr "" #: ../../guides/actions.rst:34 msgid "By default, actions are only available to logged in users." msgstr "" #: ../../guides/actions.rst:36 msgid "To make an action available to logged out users, pass ``\"public\"`` as the third parameter:" msgstr "" #: ../../guides/actions.rst:42 msgid "To restrict an action to only administrators, pass ``\"admin\"`` for the last parameter:" msgstr "" #: ../../guides/actions.rst:50 msgid "Writing action files" msgstr "" #: ../../guides/actions.rst:52 msgid "Use the ``get_input`` function to get access to request parameters:" msgstr "" #: ../../guides/actions.rst:58 msgid "You can then use the :doc:`database` api to load entities and perform actions on them accordingly." msgstr "" #: ../../guides/actions.rst:60 msgid "To redirect the page once you've completed your actions, use the ``forward`` function:" msgstr "" #: ../../guides/actions.rst:66 msgid "For example, to forward to the user's profile:" msgstr "" #: ../../guides/actions.rst:73 msgid "URLs can be relative to the Elgg root:" msgstr "" #: ../../guides/actions.rst:80 msgid "Redirect to the referring page by using the ``REFERRER`` constant:" msgstr "" #: ../../guides/actions.rst:87 msgid "Give feedback to the user about the status of the action by using ``system_message`` for positive feedback or ``register_error`` for warnings and errors:" msgstr "" #: ../../guides/actions.rst:100 msgid "Customizing actions" msgstr "" #: ../../guides/actions.rst:102 msgid "Before executing any action, Elgg triggers a hook:" msgstr "" #: ../../guides/actions.rst:108 msgid "Where ``$action`` is the action being called. If the hook returns ``false`` then the action will not be executed." msgstr "" #: ../../guides/actions.rst:111 msgid "Example: Captcha" msgstr "" #: ../../guides/actions.rst:113 msgid "The captcha module uses this to intercept the ``register`` and ``user/requestnewpassword`` actions and redirect them to a function which checks the captcha code. This check returns ``true`` if valid or ``false`` if not (which prevents the associated action from executing)." msgstr "" #: ../../guides/actions.rst:115 msgid "This is done as follows:" msgstr "" #: ../../guides/actions.rst:137 msgid "This lets a plugin extend an existing action without the need to replace the whole action. In the case of the captcha plugin it allows the plugin to provide captcha support in a very loosely coupled way." msgstr "" #: ../../guides/actions.rst:140 msgid "To output a form, use the elgg_view_form function like so:" msgstr "" #: ../../guides/actions.rst:146 msgid "Doing this generates something like the following markup:" msgstr "" #: ../../guides/actions.rst:157 msgid "Elgg does some things automatically for you when you generate forms this way:" msgstr "" #: ../../guides/actions.rst:159 msgid "It sets the action to the appropriate URL based on the name of the action you pass to it" msgstr "" #: ../../guides/actions.rst:160 msgid "It adds some anti-csrf tokens (``__elgg_ts`` and ``__elgg_token``) to help keep your actions secure" msgstr "" #: ../../guides/actions.rst:161 msgid "It automatically looks for the body of the form in the ``forms/example`` view." msgstr "" #: ../../guides/actions.rst:163 msgid "Put the content of your form in your plugin’s ``forms/example`` view:" msgstr "" #: ../../guides/actions.rst:171 msgid "Now when you call ``elgg_view_form('example')``, Elgg will produce:" msgstr "" #: ../../guides/actions.rst:186 msgid "Files and images" msgstr "" #: ../../guides/actions.rst:188 msgid "Use the input/file view in your form’s content view." msgstr "" #: ../../guides/actions.rst:195 msgid "Set the enctype of the form to multipart/form-data:" msgstr "" #: ../../guides/actions.rst:203 msgid "In your action file, use the ``$_FILES`` global to access the uploaded file:" msgstr "" #: ../../guides/actions.rst:210 msgid "Sticky forms" msgstr "" #: ../../guides/actions.rst:212 msgid "Sticky forms are forms that retain user input if saving fails. They are \"sticky\" because the user's data \"sticks\" in the form after submitting, though it was never saved to the database. This greatly improves the user experience by minimizing data loss. Elgg 1.8 includes helper functions so you can make any form sticky." msgstr "" #: ../../guides/actions.rst:215 #: ../../guides/helpers.rst:2 msgid "Helper functions" msgstr "" #: ../../guides/actions.rst:217 msgid "Sticky forms are implemented in Elgg 1.8 by the following functions:" msgstr "" #: ../../guides/actions.rst:219 msgid "``elgg_make_sticky_form($name)`` Tells the engine to make all input on a form sticky." msgstr "" #: ../../guides/actions.rst:222 msgid "``elgg_clear_sticky_form($name)`` Tells the engine to discard all sticky input on a form." msgstr "" #: ../../guides/actions.rst:225 msgid "``elgg_is_sticky_form($name)`` Checks if $name is a valid sticky form." msgstr "" #: ../../guides/actions.rst:228 msgid "``elgg_get_sticky_values($name)`` Returns all sticky values saved for $name by elgg_make_sticky_form()." msgstr "" #: ../../guides/actions.rst:232 #: ../../guides/i18n.rst:9 #: ../../guides/plugins/dependencies.rst:11 msgid "Overview" msgstr "" #: ../../guides/actions.rst:234 msgid "The basic flow of using sticky forms is: Call ``elgg_make_sticky_form($name)`` at the top of actions for forms you want to be sticky. Use ``elgg_is_sticky_form($name)`` and ``elgg_get_sticky_values($name)`` to get sticky values when rendering a form view. Call ``elgg_clear_sticky_form($name)`` after the action has completed successfully or after data has been loaded by ``elgg_get_sticky_values($name)``." msgstr "" #: ../../guides/actions.rst:240 msgid "Example: User registration" msgstr "" #: ../../guides/actions.rst:242 msgid "Simple sticky forms require little logic to determine the input values for the form. This logic is placed at the top of the form body view itself." msgstr "" #: ../../guides/actions.rst:244 msgid "The registration form view first sets default values for inputs, then checks if there are sticky values. If so, it loads the sticky values before clearing the sticky form:" msgstr "" #: ../../guides/actions.rst:259 msgid "The registration action sets creates the sticky form and clears it once the action is completed:" msgstr "" #: ../../guides/actions.rst:276 msgid "Example: Bookmarks" msgstr "" #: ../../guides/actions.rst:278 msgid "The bundled plugin Bookmarks' save form and action is an example of a complex sticky form." msgstr "" #: ../../guides/actions.rst:280 msgid "The form view for the save bookmark action uses ``elgg_extract()`` to pull values from the ``$vars`` array:" msgstr "" #: ../../guides/actions.rst:294 msgid "The page handler scripts prepares the form variables and calls ``elgg_view_form()`` passing the correct values:" msgstr "" #: ../../guides/actions.rst:302 msgid "Similarly, ``mod/bookmarks/pages/edit.php`` uses the same function, but passes the entity that is being edited as an argument:" msgstr "" #: ../../guides/actions.rst:314 msgid "The library file defines ``bookmarks_prepare_form_vars()``. This function accepts an ``ElggEntity`` as an argument and does 3 things:" msgstr "" #: ../../guides/actions.rst:316 msgid "Defines the input names and default values for form inputs." msgstr "" #: ../../guides/actions.rst:317 msgid "Extracts the values from a bookmark object if it's passed." msgstr "" #: ../../guides/actions.rst:318 msgid "Extracts the values from a sticky form if it exists." msgstr "" #: ../../guides/actions.rst:320 msgid "TODO: Include directly from lib/bookmarks.php" msgstr "" #: ../../guides/actions.rst:359 msgid "The save action checks the input, then clears the sticky form upon success:" msgstr "" #: ../../guides/actions.rst:373 #: ../../guides/ajax.rst:2 msgid "Ajax" msgstr "" #: ../../guides/actions.rst:375 msgid "See the :doc:`Ajax guide` for instructions on calling actions from JavaScript." msgstr "" #: ../../guides/actions.rst:378 #: ../../guides/web-services.rst:27 msgid "Security" msgstr "" #: ../../guides/actions.rst:379 msgid "For enhanced security, all actions require an CSRF token. Calls to action URLs that do not include security tokens will be ignored and a warning will be generated." msgstr "" #: ../../guides/actions.rst:381 msgid "A few views and functions automatically generate security tokens:" msgstr "" #: ../../guides/actions.rst:389 msgid "In rare cases, you may need to generate tokens manually:" msgstr "" #: ../../guides/actions.rst:396 msgid "You can also access the tokens from javascript:" msgstr "" #: ../../guides/actions.rst:403 msgid "These are refreshed periodically so should always be up-to-date." msgstr "" #: ../../guides/actions.rst:407 msgid "Security Tokens" msgstr "" #: ../../guides/actions.rst:408 msgid "On occasion we need to pass data through an untrusted party or generate an \"unguessable token\" based on some data. The industry-standard `HMAC `_ algorithm is the right tool for this. It allows us to verify that received data were generated by our site, and were not tampered with. Note that even strong hash functions like SHA-2 should *not* be used without HMAC for these tasks." msgstr "" #: ../../guides/actions.rst:413 msgid "Elgg provides ``elgg_build_hmac()`` to generate and validate HMAC message authentication codes that are unguessable without the site's private key." msgstr "" #: ../../guides/actions.rst:438 msgid "Note: If you use a non-string as HMAC data, you must use types consistently. Consider the following:" msgstr "" #: ../../guides/ajax.rst:5 #: ../../guides/guidelines.rst:81 #: ../../guides/plugins/plugin-skeleton.rst:82 msgid "Actions" msgstr "" #: ../../guides/ajax.rst:7 msgid "From JavaScript we can execute actions via XHR POST operations. Here's an example action and script for some basic math:" msgstr "" #: ../../guides/ajax.rst:45 msgid "Basically what happens here:" msgstr "" #: ../../guides/ajax.rst:47 msgid "CSRF tokens are added to the data." msgstr "" #: ../../guides/ajax.rst:48 msgid "The data is posted via XHR to http://localhost/elgg/action/example/add." msgstr "" #: ../../guides/ajax.rst:49 msgid "The action makes sure this is an XHR request, and returns a JSON string." msgstr "" #: ../../guides/ajax.rst:50 msgid "Once the action completes, Elgg builds a JSON response wrapper containing the echoed output." msgstr "" #: ../../guides/ajax.rst:51 msgid "Client-side Elgg extracts and displays the system message \"We did it!\" from the wrapper." msgstr "" #: ../../guides/ajax.rst:52 msgid "The ``success`` function receives the full wrapper object and validates the ``output`` key." msgstr "" #: ../../guides/ajax.rst:53 msgid "The browser alerts \"3\" then \"2\"." msgstr "" #: ../../guides/ajax.rst:56 msgid "elgg.action notes" msgstr "" #: ../../guides/ajax.rst:58 msgid "It's best to echo a non-empty string, as this is easy to validate in the ``success`` function. If the action was not allowed to run for some reason, ``wrapper.output`` will be an empty string." msgstr "" #: ../../guides/ajax.rst:60 msgid "You may want to use the :doc:`elgg/spinner` module." msgstr "" #: ../../guides/ajax.rst:61 msgid "Elgg does not use ``wrapper.status`` for anything, but a call to ``register_error()`` causes it to be set to ``-1``." msgstr "" #: ../../guides/ajax.rst:63 msgid "If the action echoes a non-JSON string, ``wrapper.output`` will contain that string." msgstr "" #: ../../guides/ajax.rst:64 msgid "``elgg.action`` is based on ``jQuery.ajax`` and returns a ``jqXHR`` object (like a Promise), if you should want to use it." msgstr "" #: ../../guides/ajax.rst:65 msgid "After the PHP action completes, other plugins can alter the wrapper via the plugin hook ``'output', 'ajax'``, which filters the wrapper as an array (not a JSON string)." msgstr "" #: ../../guides/ajax.rst:67 msgid "A ``forward()`` call forces the action to be processed and output immediately, with the ``wrapper.forward_url`` value set to the normalized location given." msgstr "" #: ../../guides/ajax.rst:69 msgid "To make sure Ajax actions can only be executed via XHR, check ``elgg_is_xhr()`` first." msgstr "" #: ../../guides/ajax.rst:72 msgid "The action JSON response wrapper" msgstr "" #: ../../guides/ajax.rst:86 msgid "It's probably best to rely only on the ``output`` key, and validate it in case the PHP action could not run for some reason, e.g. the user was logged out or a CSRF attack did not provide tokens." msgstr "" #: ../../guides/ajax.rst:90 msgid "Fetching Views" msgstr "" #: ../../guides/ajax.rst:92 msgid "A plugin can use a view script to handle XHR GET requests. Here's a simple example of a view that returns a link to an object given by its GUID:" msgstr "" #: ../../guides/ajax.rst:128 msgid "The Ajax view system works significantly differently than the action system." msgstr "" #: ../../guides/ajax.rst:130 msgid "There are no access controls based on session status." msgstr "" #: ../../guides/ajax.rst:131 msgid "Non-XHR requests are automatically rejected." msgstr "" #: ../../guides/ajax.rst:132 msgid "GET vars are injected into ``$vars`` in the view." msgstr "" #: ../../guides/ajax.rst:133 msgid "If the request contains ``$_GET['guid']``, the system sets ``$vars['entity']`` to the corresponding entity or ``false`` if it can't be loaded." msgstr "" #: ../../guides/ajax.rst:135 msgid "There's no \"wrapper\" object placed around the view output." msgstr "" #: ../../guides/ajax.rst:136 msgid "System messages/errors shouldn't be used, as they don't display until the user loads another page." msgstr "" #: ../../guides/ajax.rst:137 msgid "If the view name begins with ``js/`` or ``css/``, a corresponding Content-Type header is added." msgstr "" #: ../../guides/ajax.rst:141 msgid "Unlike views rendered server-side, Ajax views must treat ``$vars`` as completely untrusted user data." msgstr "" #: ../../guides/ajax.rst:144 msgid "Returning JSON from a view" msgstr "" #: ../../guides/ajax.rst:146 msgid "If the view outputs encoded JSON, you must use ``elgg.getJSON`` to fetch it (or use some other method to set jQuery's ajax option ``dataType`` to ``json``). Your ``success`` function will be passed the decoded Object." msgstr "" #: ../../guides/ajax.rst:149 msgid "Here's an example of fetching a view that returns a JSON-encoded array of times:" msgstr "" #: ../../guides/ajax.rst:160 msgid "Fetching Forms" msgstr "" #: ../../guides/ajax.rst:162 msgid "If you register a form view (name starting with ``forms/``), you can fetch it pre-rendered with ``elgg_view_form()``. Simply use ``ajax/form/`` (instead of ``ajax/view/``):" msgstr "" #: ../../guides/ajax.rst:184 msgid "Unlike views rendered server-side, Ajax views must treat ``$vars`` as completely untrusted user data. Review the use of ``$vars`` in an existing form before registering it for Ajax fetching." msgstr "" #: ../../guides/ajax.rst:188 msgid "Ajax helper functions" msgstr "" #: ../../guides/ajax.rst:190 msgid "These functions extend jQuery's native Ajax features." msgstr "" #: ../../guides/ajax.rst:192 msgid "``elgg.get()`` is a wrapper for jQuery's ``$.ajax()``, but forces GET and does URL normalization." msgstr "" #: ../../guides/ajax.rst:203 msgid "``elgg.post()`` is a wrapper for jQuery's ``$.ajax()``, but forces POST and does URL normalization." msgstr "" #: ../../guides/authentication.rst:2 msgid "Authentication" msgstr "" #: ../../guides/authentication.rst:4 msgid "Elgg provides everything needed to authenticate users via username/email and password out of the box, including:" msgstr "" #: ../../guides/authentication.rst:7 msgid "remember-me cookies for persistent login" msgstr "" #: ../../guides/authentication.rst:8 msgid "password reset logic" msgstr "" #: ../../guides/authentication.rst:9 msgid "secure storage of passwords" msgstr "" #: ../../guides/authentication.rst:10 msgid "logout" msgstr "" #: ../../guides/authentication.rst:11 msgid "UIs for accomplishing all of the above" msgstr "" #: ../../guides/authentication.rst:13 msgid "All that's left for you to do as a developer is to use the built-in authentication functions to secure your pages and actions." msgstr "" #: ../../guides/authentication.rst:17 msgid "Working with the logged in user" msgstr "" #: ../../guides/authentication.rst:19 msgid "Check whether the current user is logged in with ``elgg_is_logged_in()``:" msgstr "" #: ../../guides/authentication.rst:27 msgid "Check if the current user is an admin with ``elgg_is_admin_logged_in()``:" msgstr "" #: ../../guides/authentication.rst:35 msgid "Get the currently logged in user with ``elgg_get_logged_in_user_entity()``:" msgstr "" #: ../../guides/authentication.rst:41 msgid "The returned object is an ``ElggUser`` so you can use all the methods and properties of that class to access information about the user. If the user is not logged in, this will return ``null``, so be sure to check for that first." msgstr "" #: ../../guides/authentication.rst:46 msgid "Gatekeepers" msgstr "" #: ../../guides/authentication.rst:48 msgid "Gatekeeper functions allow you to manage how code gets executed by applying access control rules." msgstr "" #: ../../guides/authentication.rst:50 msgid "Forward a user to the front page if they are not logged in with ``elgg_gatekeeper()``:" msgstr "" #: ../../guides/authentication.rst:60 msgid "In Elgg 1.8 and below this function was called ``gatekeeper()``" msgstr "" #: ../../guides/authentication.rst:62 msgid "Forward a user to the front page unless they are an admin with ``elgg_admin_gatekeeper()``:" msgstr "" #: ../../guides/authentication.rst:72 msgid "In Elgg 1.8 and below this function was called ``admin_gatekeeper()``" msgstr "" #: ../../guides/authentication.rst:75 msgid "Prevent CSRF attacks with ``action_gatekeeper()``." msgstr "" #: ../../guides/authentication.rst:83 msgid "This function should be used in :doc:`actions` prior to Elgg 1.8." msgstr "" #: ../../guides/authentication.rst:87 msgid "As of Elgg version 1.8 this function is called for all registered actions. There is no longer a need to call this function in your own actions. If you wish to protect other pages with action tokens then you can call this function." msgstr "" #: ../../guides/authentication.rst:94 msgid "Pluggable Authentication Modules" msgstr "" #: ../../guides/authentication.rst:96 msgid "Elgg has support for pluggable authentication modules (PAM), which enables you to write your own authentication handlers. Whenever a request needs to get authenticated the system will call ``elgg_authenticate()`` which probes the registered PAM handlers until one returns success." msgstr "" #: ../../guides/authentication.rst:98 msgid "The preferred approach is to create a separate Elgg plugin which will have one simple task: to process an authentication request. This involves setting up an authentication handler in the plugin's :doc:`start.php ` file, and to register it with the PAM module so it will get processed whenever the system needs to authenticate a request." msgstr "" #: ../../guides/authentication.rst:100 msgid "The authentication handler is a function and takes a single parameter. Registering the handler is being done by ``register_pam_handler()`` which takes the name of the authentication handler, the importance and the policy as parameters. It is advised to register the handler in the plugin's init function, for example:" msgstr "" #: ../../guides/authentication.rst:117 msgid "Importance" msgstr "" #: ../../guides/authentication.rst:119 msgid "By default an authentication module is registered with an importance of **sufficient**." msgstr "" #: ../../guides/authentication.rst:121 msgid "In a list of authentication modules; if any one marked *sufficient* returns ``true``, ``pam_authenticate()`` will also return ``true``. The exception to this is when an authentication module is registered with an importance of **required**. All required modules must return ``true`` for ``pam_authenticate()`` to return ``true``, regardless of whether all sufficient modules return ``true``." msgstr "" #: ../../guides/authentication.rst:124 msgid "Passed credentials" msgstr "" #: ../../guides/authentication.rst:126 msgid "The format of the credentials passed to the handler can vary, depending on the originating request. For example, a regular login via the login form will create a named array, with the keys ``username`` and ``password``. If a request was made for example via XML-RPC then the credentials will be set in the HTTP header, so in this case nothing will get passed to the authentication handler and the handler will need to perform steps on its own to authenticate the request." msgstr "" #: ../../guides/authentication.rst:129 msgid "Return value" msgstr "" #: ../../guides/authentication.rst:131 msgid "The authentication handle should return a ``boolean``, indicating if the request could be authenticated or not. One caveat is that in case of a regular user login where credentials are available as username and password the user will get logged in. In case of the XML-RPC example the authentication handler will need to perform this step itself since the rest of the system will not have any idea of either possible formats of credentials passed nor its contents. Logging in a user is quite simple and is being done by ``login()``, which expects an ``ElggUser`` object." msgstr "" #: ../../guides/context.rst:2 msgid "Context" msgstr "" #: ../../guides/context.rst:4 msgid "Within the Elgg framework, context can be used to by your plugin's functions to determine if they should run or not. You will be registering callbacks to be executed when particular :doc:`events are triggered `. Sometimes the events are generic and you only want to run your callback when your plugin caused the event to be triggered. In that case, you can use the page's context." msgstr "" #: ../../guides/context.rst:6 msgid "You can explicitly set the context with ``set_context()``. The context is a string and typically you set it to the name of your plugin. You can retrieve the context with the function ``get_context()``. It's however better to use ``elgg_push_context($string)`` to add a context to the stack. You can check if the context you want in in the current stack by calling ``elgg_in_context($context)``. Don't forget to pop (with ``elgg_pop_context()``) the context after you push one and don't need it anymore." msgstr "" #: ../../guides/context.rst:9 msgid "If you don't set it, Elgg tries to guess the context. If the page was called through the page handler, the context is set to the name of the handler which was set in ``elgg_register_page_handler()``. If the page wasn't called through the page handler, it uses the name of your plugin directory. If it cannot determine that, it returns main as the default context." msgstr "" #: ../../guides/context.rst:11 msgid "Sometimes a view will return different HTML depending on the context. A plugin can take advantage of that by setting the context before calling ``elgg_view()`` on the view and then setting the context back. This is frequently done with the search context." msgstr "" #: ../../guides/database.rst:2 msgid "Database" msgstr "" #: ../../guides/database.rst:4 msgid "Persist user-generated content and settings with Elgg's generic storage API." msgstr "" #: ../../guides/database.rst:11 msgid "Entities" msgstr "" #: ../../guides/database.rst:14 msgid "Creating an object" msgstr "" #: ../../guides/database.rst:16 msgid "To create an object in your code, you need to instantiate an ``ElggObject``. Setting data is simply a matter of adding instance variables or properties. The built-in properties are:" msgstr "" #: ../../guides/database.rst:20 msgid "**``guid``** The entity's GUID; set automatically" msgstr "" #: ../../guides/database.rst:21 msgid "**``owner_guid``** The owning user's GUID" msgstr "" #: ../../guides/database.rst:22 msgid "**``site_guid``** The owning site's GUID. This is set automatically when an instance of ``ElggObject`` gets created)" msgstr "" #: ../../guides/database.rst:24 msgid "**``subtype``** A single-word arbitrary string that defines what kind of object it is, for example ``blog``" msgstr "" #: ../../guides/database.rst:26 msgid "**``access_id``** An integer representing the access level of the object" msgstr "" #: ../../guides/database.rst:28 msgid "**``title``** The title of the object" msgstr "" #: ../../guides/database.rst:29 msgid "**``description``** The description of the object" msgstr "" #: ../../guides/database.rst:31 msgid "The object subtype is a special property. This is an arbitrary string that describes what the object is. For example, if you were writing a blog plugin, your subtype string might be *blog*. It's a good idea to make this unique, so that other plugins don't accidentally try and use the same subtype. For the purposes of this document, let's assume we're building a simple forum. Therefore, the subtype will be *forum*:" msgstr "" #: ../../guides/database.rst:45 msgid "``access_id`` is another important property. If you don't set this, your object will be private, and only the creator user will be able to see it. Elgg defines constants for the special values of ``access_id``:" msgstr "" #: ../../guides/database.rst:49 msgid "**ACCESS_PRIVATE** Only the owner can see it" msgstr "" #: ../../guides/database.rst:50 msgid "**ACCESS_FRIENDS** Only the owner and his/her friends can see it" msgstr "" #: ../../guides/database.rst:51 msgid "**ACCESS_LOGGED_IN** Any logged in user can see it" msgstr "" #: ../../guides/database.rst:52 msgid "**ACCESS_PUBLIC** Even visitors not logged in can see it" msgstr "" #: ../../guides/database.rst:54 msgid "Saving the object will automatically populate the ``$object->guid`` property if successful. If you change any more base properties, you can call ``$object->save()`` again, and it will update the database for you." msgstr "" #: ../../guides/database.rst:58 msgid "You can set metadata on an object just like a standard property. Let's say we want to set the SKU of a product:" msgstr "" #: ../../guides/database.rst:65 msgid "If you assign an array, all the values will be set for that metadata. This is how, for example, you set tags." msgstr "" #: ../../guides/database.rst:68 msgid "Metadata cannot be persisted to the database until the entity has been saved, but for convenience, ElggEntity can cache it internally and save it when saving the entity." msgstr "" #: ../../guides/database.rst:73 msgid "Loading an object" msgstr "" #: ../../guides/database.rst:76 msgid "By GUID" msgstr "" #: ../../guides/database.rst:85 msgid "But what if you don't know the GUID? There are several options." msgstr "" #: ../../guides/database.rst:88 msgid "By user, subtype or site" msgstr "" #: ../../guides/database.rst:90 msgid "If you know the user ID you want to get objects for, or the subtype, or the site, you have several options. The easiest is probably to call the procedural function ``elgg_get_entities``:" msgstr "" #: ../../guides/database.rst:102 msgid "This will return an array of ``ElggEntity`` objects that you can iterate through. ``elgg_get_entities`` paginates by default, with a limit of 10; and offset 0." msgstr "" #: ../../guides/database.rst:106 msgid "You can leave out ``owner_guid`` to get all objects and leave out subtype or type to get objects of all types/subtypes." msgstr "" #: ../../guides/database.rst:109 msgid "If you already have an ``ElggUser`` – e.g. ``elgg_get_logged_in_user_entity``, which always has the current user's object when you're logged in – you can simply use:" msgstr "" #: ../../guides/database.rst:117 msgid "But what about getting objects with a particular piece of metadata?" msgstr "" #: ../../guides/database.rst:120 msgid "By metadata" msgstr "" #: ../../guides/database.rst:122 msgid "The function ``elgg_get_entities_from_metadata`` allows fetching entities with metadata in a variety of ways." msgstr "" #: ../../guides/database.rst:126 msgid "By annotation" msgstr "" #: ../../guides/database.rst:128 msgid "The function ``elgg_get_entities_from_annotations`` allows fetching entities with metadata in a variety of ways." msgstr "" #: ../../guides/database.rst:133 msgid "As of Elgg 1.10 the default behaviour of `elgg_get_entities_from_annotations` was brought inline with the rest of the `elgg_get_entities*` functions." msgstr "" #: ../../guides/database.rst:135 msgid "Pre Elgg 1.10 the sorting of the entities was based on the latest addition of an annotation (in $options your could add `$options['order_by'] = 'maxtime ASC'` or `$options['order_by'] = 'maxtime DESC'`. As of Elgg 1.10 this was changed to the creation time of the entity, just like the rest of the `elgg_get_entities*` functions. To get the old behaviour back add the following to your `$options`:" msgstr "" #: ../../guides/database.rst:150 #: ../../guides/views.rst:239 msgid "Displaying entities" msgstr "" #: ../../guides/database.rst:152 msgid "In order for entities to be displayed in listing functions you need to provide a view for the entity in the views system." msgstr "" #: ../../guides/database.rst:155 msgid "To display an entity, create a view EntityType/subtype where EntityType is one of the following:" msgstr "" #: ../../guides/database.rst:158 msgid "object: for entities derived from ElggObject user: for entities derived from ElggUser site: for entities derived from ElggSite group: for entities derived from ElggGroup" msgstr "" #: ../../guides/database.rst:163 msgid "A default view for all entities has already been created, this is called EntityType/default." msgstr "" #: ../../guides/database.rst:169 msgid "Entity Icons" msgstr "" #: ../../guides/database.rst:171 msgid "Every entity can be assigned an icon which is retrieved using the ``ElggEntity::getIconURL($params)`` method. This method accepts a ``$params`` argument that can be either a string specifying on of the configured icon sizes, or an array of parameters, that specify the size and provide additional context for the hook to determine the icon to serve." msgstr "" #: ../../guides/database.rst:176 msgid "Use ``elgg_get_config('icon_sizes')`` to get all possible values. The following sizes exist by default: ``'large'``, ``'medium'``, ``'small'``, ``'tiny'``, and ``'topbar'``. The method triggers the ``entity:icon:url`` :ref:`hook `." msgstr "" #: ../../guides/database.rst:180 msgid "Use ``elgg_view_entity_icon($entity, $size, $vars)`` to render an icon. This will scan the following locations for a view and include the first match." msgstr "" #: ../../guides/database.rst:183 msgid "views/$viewtype/icon/$type/$subtype.php" msgstr "" #: ../../guides/database.rst:184 msgid "views/$viewtype/icon/$type/default.php" msgstr "" #: ../../guides/database.rst:185 msgid "views/$viewtype/icon/default.php" msgstr "" #: ../../guides/database.rst:187 msgid "Where" msgstr "" #: ../../guides/database.rst:189 msgid "$viewtype" msgstr "" #: ../../guides/database.rst:190 msgid "Type of view, e.g. ``'default'`` or ``'json'``." msgstr "" #: ../../guides/database.rst:191 msgid "$type" msgstr "" #: ../../guides/database.rst:192 msgid "Type of entity, e.g. ``'group'`` or ``'user'``." msgstr "" #: ../../guides/database.rst:194 msgid "$subtype" msgstr "" #: ../../guides/database.rst:194 msgid "Entity subtype, e.g. ``'blog'`` or ``'page'``." msgstr "" #: ../../guides/database.rst:196 msgid "By convention entities that have an uploaded avatar or icon will have the ``icontime`` property assigned. This means that you can use ``$entity->icontime`` to check if an icon exists for the given entity." msgstr "" #: ../../guides/database.rst:201 msgid "Adding, reading and deleting annotations" msgstr "" #: ../../guides/database.rst:203 msgid "Annotations could be used, for example, to track ratings. To annotate an entity you can use the object's ``annotate()`` method. For example, to give a blog post a rating of 5, you could use:" msgstr "" #: ../../guides/database.rst:213 msgid "To retrieve the ratings on the blog post, use ``$blogpost->getAnnotations('rating')`` and if you want to delete an annotation, you can operate on the ``ElggAnnotation`` class, eg ``$annotation->delete()``." msgstr "" #: ../../guides/database.rst:218 msgid "Retrieving a single annotation can be done with ``get_annotation()`` if you have the annotation's ID. If you delete an ElggEntity of any kind, all its metadata, annotations, and relationships will be automatically deleted as well." msgstr "" #: ../../guides/database.rst:224 msgid "Extending ElggEntity" msgstr "" #: ../../guides/database.rst:226 msgid "If you derive from one of the Elgg core classes, you'll need to tell Elgg how to properly instantiate the new type of object so that get\\_entity() et al. will return the appropriate PHP class. For example, if I customize ElggGroup in a class called \"Committee\", I need to make Elgg aware of the new mapping. Following is an example class extension:" msgstr "" #: ../../guides/database.rst:256 msgid "Now if you invoke ``get_entity()`` with the GUID of a committee object, you'll get back an object of type Committee." msgstr "" #: ../../guides/database.rst:259 msgid "This template was extracted from the definition of ElggFile." msgstr "" #: ../../guides/database.rst:262 msgid "Advanced features" msgstr "" #: ../../guides/database.rst:265 msgid "Entity URLs" msgstr "" #: ../../guides/database.rst:267 msgid "Entity urls are provided by the ``getURL()`` interface and provide the Elgg framework with a common way of directing users to the appropriate display handler for any given object." msgstr "" #: ../../guides/database.rst:271 msgid "For example, a profile page in the case of users." msgstr "" #: ../../guides/database.rst:273 msgid "The url is set using the ``elgg\\_register\\_entity\\_url\\_handler()`` function. The function you register must return the appropriate url for the given type - this itself can be an address set up by a page handler." msgstr "" #: ../../guides/database.rst:280 msgid "The default handler is to use the default export interface." msgstr "" #: ../../guides/database.rst:283 msgid "Entity loading performance" msgstr "" #: ../../guides/database.rst:285 msgid "``elgg_get_entities`` has a couple options that can sometimes be useful to improve performance." msgstr "" #: ../../guides/database.rst:287 msgid "**preload_owners**: If the entities fetched will be displayed in a list with the owner information, you can set this option to ``true`` to efficiently load the owner users of the fetched entities." msgstr "" #: ../../guides/database.rst:288 msgid "**preload_containers**: If the entities fetched will be displayed in a list using info from their containers, you can set this option to ``true`` to efficiently load them." msgstr "" #: ../../guides/database.rst:289 msgid "**distinct**: When Elgg fetches entities using an SQL query, Elgg must be sure that each entity row appears only once in the result set. By default it includes a ``DISTINCT`` modifier on the GUID column to enforce this, but some queries naturally return unique entities. Setting the ``distinct`` option to false will remove this modifier, and rely on the query to enforce its own uniqueness." msgstr "" #: ../../guides/database.rst:291 msgid "The internals of Elgg entity queries is a complex subject and it's recommended to seek help on the Elgg Community site before using the ``distinct`` option." msgstr "" #: ../../guides/database.rst:294 msgid "Pre-1.8 Notes" msgstr "" #: ../../guides/database.rst:296 msgid "update\\_subtype(): This function is new in 1.8. In prior versions, you would need to edit the database by hand if you updated the class name associated with a given subtype." msgstr "" #: ../../guides/database.rst:300 msgid "elgg\\_register\\_entity\\_url\\_handler(): This function is new in 1.8. It deprecates register\\_entity\\_url\\_handler(), which you should use if developing for a pre-1.8 version of Elgg." msgstr "" #: ../../guides/database.rst:304 msgid "elgg\\_get\\_entities\\_from\\_metadata(): This function is new in 1.8. It deprecates get\\_entities\\_from\\_metadata(), which you should use if developing for a pre-1.8 version of Elgg." msgstr "" #: ../../guides/database.rst:309 msgid "Custom database functionality" msgstr "" #: ../../guides/database.rst:311 msgid "It is strongly recommended to use entities wherever possible. However, Elgg supports custom SQL queries using the database API." msgstr "" #: ../../guides/database.rst:315 msgid "Example: Run SQL script on plugin activation" msgstr "" #: ../../guides/database.rst:317 msgid "This example shows how you can populate your database on plugin activation." msgstr "" #: ../../guides/database.rst:319 msgid "my_plugin/activate.php:" msgstr "" #: ../../guides/database.rst:329 msgid "my_plugin/sql/activate.sql:" msgstr "" #: ../../guides/database.rst:345 msgid "Note that Elgg execute statements through PHPs built-in functions and have limited support for comments. I.e. only single line comments are supported and must be prefixed by \"-- \" or \"# \". A comment must start at the very beginning of a line." msgstr "" #: ../../guides/database.rst:351 msgid "Systemlog" msgstr "" #: ../../guides/database.rst:355 msgid "This section need some attention and will contain outdated information" msgstr "" #: ../../guides/database.rst:357 msgid "The default Elgg system log is a simple way of recording what happens within an Elgg system. It's viewable and searchable directly from the administration panel." msgstr "" #: ../../guides/database.rst:360 msgid "System log storage" msgstr "" #: ../../guides/database.rst:362 msgid "A system log row is stored whenever an event concerning an object whose class implements the :doc:`/design/loggable` interface is triggered. ``ElggEntity`` and ``ElggExtender`` implement :doc:`/design/loggable`, so a system log row is created whenever an event is performed on all objects, users, groups, sites, metadata and annotations." msgstr "" #: ../../guides/database.rst:364 msgid "Common events include:" msgstr "" #: ../../guides/database.rst:366 msgid "create" msgstr "" #: ../../guides/database.rst:367 msgid "update" msgstr "" #: ../../guides/database.rst:368 msgid "delete" msgstr "" #: ../../guides/database.rst:369 msgid "login" msgstr "" #: ../../guides/database.rst:372 msgid "Creating your own system log" msgstr "" #: ../../guides/database.rst:374 msgid "There are some reasons why you might want to create your own system log. For example, you might need to store a full copy of entities when they are updated or deleted, for auditing purposes. You might also need to notify an administrator when certain types of events occur." msgstr "" #: ../../guides/database.rst:376 msgid "To do this, you can create a function that listens to all events for all types of object:" msgstr "" #: ../../guides/database.rst:382 msgid "Your function can then be defined as:" msgstr "" #: ../../guides/database.rst:392 msgid "You can then use the extra methods defined by :doc:`/design/loggable` to extract the information you need." msgstr "" #: ../../guides/dont-modify-core.rst:2 msgid "Don't Modify Core" msgstr "" #: ../../guides/dont-modify-core.rst:6 msgid "Don't modify any non-config files that come with Elgg." msgstr "" #: ../../guides/dont-modify-core.rst:8 msgid "Instead, create a :doc:`custom plugin` and alter behavior through the rich Elgg plugin API." msgstr "" #: ../../guides/dont-modify-core.rst:10 msgid "Here are the main reasons not to modify the core of Elgg, or of any other third party software that offers better extensibility routes through plugins." msgstr "" #: ../../guides/dont-modify-core.rst:13 msgid "It makes it hard to get help" msgstr "" #: ../../guides/dont-modify-core.rst:15 msgid "When you don't share the same codebase as everyone else, it's impossible for others to know what is going on in your system and whether your changes are to blame. This can frustrate those who offer help because it can add considerable noise to the support process." msgstr "" #: ../../guides/dont-modify-core.rst:18 msgid "It makes upgrading tricky and potentially disastrous" msgstr "" #: ../../guides/dont-modify-core.rst:20 msgid "You will certainly want or need to upgrade Elgg to take advantage of security patches, new features, new plugin APIs, new stability and performance improvements. If you've modified core files, then you must be very careful when upgrading that your changes are not overwritten and that they are compatible with the new Elgg code. If your changes are lost or incompatible, then the upgrade may remove features you've added or even completely break your site." msgstr "" #: ../../guides/dont-modify-core.rst:22 msgid "This can also be a slippery slope. Lots of modifications can lead you to an upgrade process so complex that it's practically impossible. There are lots of sites stuck running old versions software due to taking this path." msgstr "" #: ../../guides/dont-modify-core.rst:25 msgid "It may break plugins" msgstr "" #: ../../guides/dont-modify-core.rst:27 msgid "You may not realize until much later that your \"quick fix\" broke seemingly unrelated functionality that plugins depended on." msgstr "" #: ../../guides/dont-modify-core.rst:30 msgid "Summary" msgstr "" #: ../../guides/dont-modify-core.rst:32 msgid "Resist the temptation" msgstr "" #: ../../guides/dont-modify-core.rst:33 msgid "Editing existing files is quick and easy, but doing so heavily risks the maintainability, security, and stability of your site." msgstr "" #: ../../guides/dont-modify-core.rst:34 msgid "When receiving advice, consider if the person telling you to modify core will be around to rescue you if you run into trouble later!" msgstr "" #: ../../guides/dont-modify-core.rst:35 msgid "Apply these principle to software in general." msgstr "" #: ../../guides/dont-modify-core.rst:36 msgid "If you can avoid it, don't modify third party plugins either, for many of the same reasons: Plugin authors release new versions, too, and you will want those updates." msgstr "" #: ../../guides/events-list.rst:2 msgid "List of events in core" msgstr "" #: ../../guides/events-list.rst:9 msgid "System events" msgstr "" #: ../../guides/events-list.rst:12 msgid "**boot, system**" msgstr "" #: ../../guides/events-list.rst:12 msgid "First event triggered. Triggered before plugins have been loaded." msgstr "" #: ../../guides/events-list.rst:15 msgid "**plugins_boot, system**" msgstr "" #: ../../guides/events-list.rst:15 msgid "Triggered just after the plugins are loaded. Rarely used. init, system is used instead." msgstr "" #: ../../guides/events-list.rst:18 msgid "**init, system**" msgstr "" #: ../../guides/events-list.rst:18 msgid "Plugins tend to use this event for initialization (extending views, registering callbacks, etc.)" msgstr "" #: ../../guides/events-list.rst:22 msgid "**ready, system**" msgstr "" #: ../../guides/events-list.rst:21 msgid "Triggered after the ``init, system`` event. All plugins are fully loaded and the engine is ready to serve pages." msgstr "" #: ../../guides/events-list.rst:25 msgid "**pagesetup, system**" msgstr "" #: ../../guides/events-list.rst:25 msgid "Called just before the first content is produced. Is triggered by ``elgg_view()``." msgstr "" #: ../../guides/events-list.rst:29 msgid "**shutdown, system**" msgstr "" #: ../../guides/events-list.rst:28 msgid "Triggered after the page has been sent to the user. Expensive operations could be done here and not make the user wait." msgstr "" #: ../../guides/events-list.rst:31 msgid "Depending upon your server configuration the PHP output might not be shown until after the process is completed. This means that any long-running processes will still delay the page load." msgstr "" #: ../../guides/events-list.rst:37 msgid "**regenerate_site_secret:before, system**" msgstr "" #: ../../guides/events-list.rst:36 msgid "Return false to cancel regenerating the site secret. You should also provide a message to the user." msgstr "" #: ../../guides/events-list.rst:40 msgid "**regenerate_site_secret:after, system**" msgstr "" #: ../../guides/events-list.rst:40 msgid "Triggered after the site secret has been regenerated." msgstr "" #: ../../guides/events-list.rst:44 msgid "**log, systemlog**" msgstr "" #: ../../guides/events-list.rst:43 msgid "Called for all triggered events. Used internally by ``system_log_default_logger()`` to populate the ``system_log`` table." msgstr "" #: ../../guides/events-list.rst:48 msgid "**upgrade, system**" msgstr "" #: ../../guides/events-list.rst:47 msgid "Triggered after a system upgrade has finished. All upgrade scripts have run, but the caches are not cleared." msgstr "" #: ../../guides/events-list.rst:53 msgid "**upgrade, upgrade**" msgstr "" #: ../../guides/events-list.rst:53 msgid "A single upgrade script finished executing. Handlers are passed a ``stdClass`` object with the properties" msgstr "" #: ../../guides/events-list.rst:52 msgid "from - The version of Elgg upgrading from." msgstr "" #: ../../guides/events-list.rst:53 msgid "to - The version just upgraded to." msgstr "" #: ../../guides/events-list.rst:56 msgid "**activate, plugin**" msgstr "" #: ../../guides/events-list.rst:56 msgid "Return false to prevent activation of the plugin." msgstr "" #: ../../guides/events-list.rst:59 msgid "**deactivate, plugin**" msgstr "" #: ../../guides/events-list.rst:59 msgid "Return false to prevent deactivation of the plugin." msgstr "" #: ../../guides/events-list.rst:62 msgid "**init:cookie, **" msgstr "" #: ../../guides/events-list.rst:62 msgid "Return false to override setting a cookie." msgstr "" #: ../../guides/events-list.rst:65 msgid "**cache:flush, system**" msgstr "" #: ../../guides/events-list.rst:65 msgid "Reset internal and external caches, by default including system_cache, simplecache, and memcache. One might use it to reset others such as APC, OPCache, or WinCache." msgstr "" #: ../../guides/events-list.rst:68 msgid "User events" msgstr "" #: ../../guides/events-list.rst:71 msgid "**login:before, user**" msgstr "" #: ../../guides/events-list.rst:71 msgid "Triggered during login. Returning false prevents the user from logging" msgstr "" #: ../../guides/events-list.rst:74 msgid "**login:after, user**" msgstr "" #: ../../guides/events-list.rst:74 msgid "Triggered after the user logs in." msgstr "" #: ../../guides/events-list.rst:77 msgid "**logout:before, user**" msgstr "" #: ../../guides/events-list.rst:77 msgid "Triggered during logout. Returning false should prevent the user from logging out." msgstr "" #: ../../guides/events-list.rst:80 msgid "**logout:after, user**" msgstr "" #: ../../guides/events-list.rst:80 msgid "Triggered after the user logouts." msgstr "" #: ../../guides/events-list.rst:85 msgid "**validate, user**" msgstr "" #: ../../guides/events-list.rst:83 msgid "When a user registers, the user's account is disabled. This event is triggered to allow a plugin to determine how the user should be validated (for example, through an email with a validation link)." msgstr "" #: ../../guides/events-list.rst:88 msgid "**profileupdate, user**" msgstr "" #: ../../guides/events-list.rst:88 msgid "User has changed profile" msgstr "" #: ../../guides/events-list.rst:91 msgid "**profileiconupdate, user**" msgstr "" #: ../../guides/events-list.rst:91 msgid "User has changed profile icon" msgstr "" #: ../../guides/events-list.rst:94 msgid "**ban, user**" msgstr "" #: ../../guides/events-list.rst:94 msgid "Triggered before a user is banned. Return false to prevent." msgstr "" #: ../../guides/events-list.rst:97 msgid "**unban, user**" msgstr "" #: ../../guides/events-list.rst:97 msgid "Triggered before a user is unbanned. Return false to prevent." msgstr "" #: ../../guides/events-list.rst:100 msgid "**make_admin, user**" msgstr "" #: ../../guides/events-list.rst:100 msgid "Triggered before a user is promoted to an admin. Return false to prevent." msgstr "" #: ../../guides/events-list.rst:103 msgid "**remove_admin, user**" msgstr "" #: ../../guides/events-list.rst:103 msgid "Triggered before a user is demoted from an admin. Return false to prevent." msgstr "" #: ../../guides/events-list.rst:106 msgid "Relationship events" msgstr "" #: ../../guides/events-list.rst:110 msgid "**create, relationship**" msgstr "" #: ../../guides/events-list.rst:109 msgid "Triggered after a relationship has been created. Returning false deletes the relationship that was just created." msgstr "" #: ../../guides/events-list.rst:112 msgid "This event was broken in Elgg 1.9 - 1.12.3, returning false would *not* delete the relationship. This is working as of 1.12.4" msgstr "" #: ../../guides/events-list.rst:117 msgid "**delete, relationship**" msgstr "" #: ../../guides/events-list.rst:116 msgid "Triggered before a relationship is deleted. Return false to prevent it from being deleted." msgstr "" #: ../../guides/events-list.rst:120 msgid "**join, group**" msgstr "" #: ../../guides/events-list.rst:120 msgid "Triggered after the user ``$params['user']`` has joined the group ``$params['group']``." msgstr "" #: ../../guides/events-list.rst:123 msgid "**leave, group**" msgstr "" #: ../../guides/events-list.rst:123 msgid "Triggered before the user ``$params['user']`` has left the group ``$params['group']``." msgstr "" #: ../../guides/events-list.rst:126 msgid "Entity events" msgstr "" #: ../../guides/events-list.rst:129 msgid "**create, **" msgstr "" #: ../../guides/events-list.rst:129 msgid "Triggered for user, group, object, and site entities after creation. Return false to delete entity." msgstr "" #: ../../guides/events-list.rst:132 msgid "**update, **" msgstr "" #: ../../guides/events-list.rst:132 msgid "Triggered before an update for the user, group, object, and site entities. Return false to prevent update." msgstr "" #: ../../guides/events-list.rst:135 msgid "**update:after, **" msgstr "" #: ../../guides/events-list.rst:135 msgid "Triggered after an update for the user, group, object, and site entities." msgstr "" #: ../../guides/events-list.rst:138 msgid "**delete, **" msgstr "" #: ../../guides/events-list.rst:138 msgid "Triggered before entity deletion. Return false to prevent deletion." msgstr "" #: ../../guides/events-list.rst:141 msgid "**disable, **" msgstr "" #: ../../guides/events-list.rst:141 msgid "Triggered before the entity is disabled. Return false to prevent disabling." msgstr "" #: ../../guides/events-list.rst:144 msgid "**disable:after, **" msgstr "" #: ../../guides/events-list.rst:144 msgid "Triggered after the entity is disabled." msgstr "" #: ../../guides/events-list.rst:147 msgid "**enable, **" msgstr "" #: ../../guides/events-list.rst:147 msgid "Return false to prevent enabling." msgstr "" #: ../../guides/events-list.rst:150 msgid "**enable:after, **" msgstr "" #: ../../guides/events-list.rst:150 msgid "Triggered after the entity is enabled." msgstr "" #: ../../guides/events-list.rst:153 msgid "Metadata events" msgstr "" #: ../../guides/events-list.rst:157 msgid "**create, metadata**" msgstr "" #: ../../guides/events-list.rst:156 msgid "Called after the metadata has been created. Return false to delete the metadata that was just created." msgstr "" #: ../../guides/events-list.rst:160 msgid "**update, metadata**" msgstr "" #: ../../guides/events-list.rst:160 msgid "Called after the metadata has been updated. Return false to *delete the metadata.*" msgstr "" #: ../../guides/events-list.rst:163 msgid "**delete, metadata**" msgstr "" #: ../../guides/events-list.rst:163 msgid "Called before metadata is deleted. Return false to prevent deletion." msgstr "" #: ../../guides/events-list.rst:166 msgid "**enable, metadata**" msgstr "" #: ../../guides/events-list.rst:166 msgid "Called when enabling metadata. Return false to prevent enabling." msgstr "" #: ../../guides/events-list.rst:169 msgid "**disable, metadata**" msgstr "" #: ../../guides/events-list.rst:169 msgid "Called when disabling metadata. Return false to prevent disabling." msgstr "" #: ../../guides/events-list.rst:172 msgid "Annotation events" msgstr "" #: ../../guides/events-list.rst:176 msgid "**annotate, **" msgstr "" #: ../../guides/events-list.rst:175 msgid "Called before the annotation has been created. Return false to prevent annotation of this entity." msgstr "" #: ../../guides/events-list.rst:180 msgid "**create, annotation**" msgstr "" #: ../../guides/events-list.rst:179 msgid "Called after the annotation has been created. Return false to delete the annotation." msgstr "" #: ../../guides/events-list.rst:183 msgid "**update, annotation**" msgstr "" #: ../../guides/events-list.rst:183 msgid "Called after the annotation has been updated. Return false to *delete the annotation.*" msgstr "" #: ../../guides/events-list.rst:186 msgid "**delete, annotation**" msgstr "" #: ../../guides/events-list.rst:186 msgid "Called before annotation is deleted. Return false to prevent deletion." msgstr "" #: ../../guides/events-list.rst:189 msgid "**enable, annotation**" msgstr "" #: ../../guides/events-list.rst:189 msgid "Called when enabling annotations. Return false to prevent enabling." msgstr "" #: ../../guides/events-list.rst:192 msgid "**disable, annotations**" msgstr "" #: ../../guides/events-list.rst:192 msgid "Called when disabling annotations. Return false to prevent disabling." msgstr "" #: ../../guides/events-list.rst:195 msgid "River events" msgstr "" #: ../../guides/events-list.rst:198 msgid "**created, river**" msgstr "" #: ../../guides/events-list.rst:198 msgid "Called after a river item is created." msgstr "" #: ../../guides/events-list.rst:201 msgid "Notes" msgstr "" #: ../../guides/events-list.rst:203 msgid "Because of bugs in the Elgg core, some events may be thrown more than once on the same action. For example, ``update, object`` is thrown twice." msgstr "" #: ../../guides/guidelines.rst:2 msgid "Plugin coding guidelines" msgstr "" #: ../../guides/guidelines.rst:4 msgid "In addition to the Elgg Coding Standards, these are guidelines for creating plugins. Core plugins are being updated to this format and all plugin authors should follow these guidelines in their own plugins." msgstr "" #: ../../guides/guidelines.rst:8 msgid "Be sure to follow the :doc:`plugins/plugin-skeleton` for your plugin's layout." msgstr "" #: ../../guides/guidelines.rst:12 msgid ":doc:`dont-modify-core`" msgstr "" #: ../../guides/guidelines.rst:19 #: ../../guides/upgrading.rst:445 msgid "Use standardized routing with page handlers" msgstr "" #: ../../guides/guidelines.rst:21 #: ../../guides/guidelines.rst:50 #: ../../guides/guidelines.rst:61 msgid "Example: Bookmarks plugin" msgstr "" #: ../../guides/guidelines.rst:38 msgid "Page handlers should accept the following standard URLs:" msgstr "" #: ../../guides/guidelines.rst:24 #: ../../guides/guidelines.rst:69 msgid "Purpose" msgstr "" #: ../../guides/guidelines.rst:24 #: ../../guides/guidelines.rst:69 msgid "URL" msgstr "" #: ../../guides/guidelines.rst:26 msgid "All" msgstr "" #: ../../guides/guidelines.rst:26 msgid "page_handler/all" msgstr "" #: ../../guides/guidelines.rst:28 msgid "User" msgstr "" #: ../../guides/guidelines.rst:28 msgid "page_handler/owner/" msgstr "" #: ../../guides/guidelines.rst:30 msgid "User friends’" msgstr "" #: ../../guides/guidelines.rst:30 msgid "page_handler/friends/" msgstr "" #: ../../guides/guidelines.rst:32 msgid "Single entity" msgstr "" #: ../../guides/guidelines.rst:32 msgid "page_handler/view//" msgstr "" #: ../../guides/guidelines.rst:34 #: ../../guides/guidelines.rst:71 msgid "Add" msgstr "" #: ../../guides/guidelines.rst:34 msgid "page_handler/add/<container_guid>" msgstr "" #: ../../guides/guidelines.rst:36 #: ../../guides/guidelines.rst:73 msgid "Edit" msgstr "" #: ../../guides/guidelines.rst:36 msgid "page_handler/edit/<guid>" msgstr "" #: ../../guides/guidelines.rst:38 msgid "Group list" msgstr "" #: ../../guides/guidelines.rst:38 msgid "page_handler/group/<guid>/owner" msgstr "" #: ../../guides/guidelines.rst:40 msgid "Include page handler scripts from the page handler. Almost every page handler should have a page handler script. (Example: ``bookmarks/all`` => ``mod/bookmarks/pages/bookmarks/all.php``)" msgstr "" #: ../../guides/guidelines.rst:41 #: ../../guides/upgrading.rst:460 msgid "Call ``set_input()`` for entity guids in the page handler and use ``get_input()`` in the page handler scripts." msgstr "" #: ../../guides/guidelines.rst:42 msgid "Call ``elgg_gatekeeper()`` and ``elgg_admin_gatekeeper()`` in the page handler function if required." msgstr "" #: ../../guides/guidelines.rst:43 msgid "The group URL should use the ``pages/<handler>/owner.php`` script." msgstr "" #: ../../guides/guidelines.rst:44 #: ../../guides/upgrading.rst:463 msgid "Page handlers should not contain HTML." msgstr "" #: ../../guides/guidelines.rst:45 msgid "If upgrading a 1.7 plugin, update the URLs throughout the plugin. (Don’t forget to remove ``/pg/``!)" msgstr "" #: ../../guides/guidelines.rst:48 #: ../../guides/upgrading.rst:468 msgid "Use standardized page handlers and scripts" msgstr "" #: ../../guides/guidelines.rst:51 msgid "Store page handler scripts in ``mod/<plugin>/pages/<page_handler>/<page_name>``" msgstr "" #: ../../guides/guidelines.rst:52 msgid "Use the content page layout in page handler scripts: ``$content = elgg_view_layout('content', $options);``" msgstr "" #: ../../guides/guidelines.rst:53 msgid "Page handler scripts should not contain HTML" msgstr "" #: ../../guides/guidelines.rst:54 #: ../../guides/upgrading.rst:477 msgid "Call ``elgg_push_breadcrumb()`` in the page handler scripts." msgstr "" #: ../../guides/guidelines.rst:55 msgid "No need to worry about setting the page owner if the URLs are in the standardized format" msgstr "" #: ../../guides/guidelines.rst:56 msgid "For group content, check the ``container_guid`` by using ``elgg_get_page_owner_entity()``" msgstr "" #: ../../guides/guidelines.rst:59 msgid "The object/<subtype> view" msgstr "" #: ../../guides/guidelines.rst:62 msgid "Make sure there are views for ``$vars[‘full’] == true`` and ``$vars[‘full’] == false``" msgstr "" #: ../../guides/guidelines.rst:63 msgid "Check for the object in ``$vars[‘entity’]`` . Use ``elgg_instance_of()`` to make sure it’s the type entity you want. Return ``true`` to short circuit the view if the entity is missing or wrong." msgstr "" #: ../../guides/guidelines.rst:64 msgid "Use the new list body and list metadata views to help format. You should use almost no markup in these views." msgstr "" #: ../../guides/guidelines.rst:65 msgid "Update action structure - Example: Bookmarks plugin." msgstr "" #: ../../guides/guidelines.rst:66 #: ../../guides/upgrading.rst:492 msgid "Namespace action files and action names (example: ``mod/blog/actions/blog/save.php`` => ``action/blog/save``)" msgstr "" #: ../../guides/guidelines.rst:75 #: ../../guides/upgrading.rst:493 msgid "Use the following action URLs:" msgstr "" #: ../../guides/guidelines.rst:71 #: ../../guides/guidelines.rst:73 msgid "action/plugin/save" msgstr "" #: ../../guides/guidelines.rst:75 msgid "Delete" msgstr "" #: ../../guides/guidelines.rst:75 msgid "action/plugin/delete" msgstr "" #: ../../guides/guidelines.rst:77 msgid "Make the delete action accept ``action/<handler>/delete?guid=<guid>`` so the metadata entity menu has the correct URL by default" msgstr "" #: ../../guides/guidelines.rst:78 msgid "If updating a 1.7 plugin, replace calls to functions deprecated in 1.7 because these will produce visible errors on every load in 1.8" msgstr "" #: ../../guides/guidelines.rst:83 msgid "Actions are transient states to perform an action such as updating the database or sending a notification to a user. Used correctly, actions are secure and prevent against CSRF and XSS attacks." msgstr "" #: ../../guides/guidelines.rst:87 msgid "As of Elgg 1.7 all actions require action tokens." msgstr "" #: ../../guides/guidelines.rst:90 msgid "Action best practices" msgstr "" #: ../../guides/guidelines.rst:92 msgid "Never call an action directly by saying:" msgstr "" #: ../../guides/guidelines.rst:98 msgid "This circumvents the security systems in Elgg." msgstr "" #: ../../guides/guidelines.rst:100 msgid "There is no need to include the ``engine/start.php`` file in your actions. Actions should never be called directly, so the engine will be started automatically when called correctly." msgstr "" #: ../../guides/guidelines.rst:102 msgid "Because actions are time-sensitive they are not suitable for links in emails or other delayed notifications. An example of this would be invitations to join a group. The clean way to create an invitation link is to create a page handler for invitations and email that link to the user. It is then the page handler's responsibility to create the action links for a user to join or ignore the invitation request." msgstr "" #: ../../guides/guidelines.rst:105 msgid "Directly calling a file" msgstr "" #: ../../guides/guidelines.rst:107 msgid "This is an easy one: **Don't do it**. With the exception of 3rd party application integration, there is not a reason to directly call a file in mods directory." msgstr "" #: ../../guides/guidelines.rst:110 msgid "Recommended" msgstr "" #: ../../guides/guidelines.rst:112 msgid "These points are good ideas, but are not yet in the official guidelines. Following these suggestions will help to keep your plugin consistent with Elgg core." msgstr "" #: ../../guides/guidelines.rst:114 msgid "Update the widget views (see the blog or file widgets)" msgstr "" #: ../../guides/guidelines.rst:115 msgid "Update the group profile “widget” using blog or file plugins as example" msgstr "" #: ../../guides/guidelines.rst:119 msgid "Update the forms" msgstr "" #: ../../guides/guidelines.rst:117 msgid "Move form bodies to ``/forms/<handler>/<action>`` to use Evan’s new ``elgg_view_form()``" msgstr "" #: ../../guides/guidelines.rst:118 msgid "Use input views in form bodies rather than html" msgstr "" #: ../../guides/guidelines.rst:119 msgid "Add a function that prepares the form (see ``mod/file/lib/file.php`` for example)" msgstr "" #: ../../guides/guidelines.rst:120 msgid "Integrate sticky forms (see the file plugin’s upload action and form prepare function)" msgstr "" #: ../../guides/guidelines.rst:121 #: ../../guides/upgrading.rst:536 msgid "Clean up CSS/HTML" msgstr "" #: ../../guides/guidelines.rst:122 msgid "Should be able to remove almost all CSS (look for patterns that can be moved into core if you need CSS)" msgstr "" #: ../../guides/guidelines.rst:123 msgid "Use hyphens rather than underscores in classes/ids" msgstr "" #: ../../guides/guidelines.rst:124 msgid "Update the ``manifest.xml`` file to the 1.8 format. Use http://el.gg/manifest17to18 to automate this" msgstr "" #: ../../guides/guidelines.rst:125 msgid "Do not use the ``bundled`` category with your plugins. That is for plugins distributed with Elgg" msgstr "" #: ../../guides/guidelines.rst:127 msgid "Update functions deprecated in 1.8." msgstr "" #: ../../guides/guidelines.rst:127 msgid "Many registration functions simply added an ``elgg_`` prefix for consistency" msgstr "" #: ../../guides/guidelines.rst:128 msgid "See ``/engine/lib/deprecated-1.8.php`` for the full list. You can also set the debug level to warning to get visual reminders of deprecated functions" msgstr "" #: ../../guides/helpers.rst:5 msgid "Input and output" msgstr "" #: ../../guides/helpers.rst:7 msgid "``get_input($name)`` Grabs information from a form field (or any variable passed using GET or POST). Also sanitises input, stripping Javascript etc." msgstr "" #: ../../guides/helpers.rst:8 msgid "``set_input($name, $value)`` Forces a value to a particular variable for subsequent retrieval by ``get_input()``" msgstr "" #: ../../guides/helpers.rst:11 msgid "Entity methods" msgstr "" #: ../../guides/helpers.rst:13 msgid "``$entity->getURL()`` Returns the URL of any entity in the system" msgstr "" #: ../../guides/helpers.rst:14 msgid "``$entity->getGUID()`` Returns the GUID of any entity in the system" msgstr "" #: ../../guides/helpers.rst:15 msgid "``$entity->canEdit()`` Returns whether or not the current user can edit the entity" msgstr "" #: ../../guides/helpers.rst:16 msgid "``$entity->getOwnerEntity()`` Returns the ElggUser owner of a particular entity" msgstr "" #: ../../guides/helpers.rst:19 msgid "Entity and context retrieval" msgstr "" #: ../../guides/helpers.rst:21 msgid "``elgg_get_logged_in_user_entity()`` Returns the ElggUser for the current user" msgstr "" #: ../../guides/helpers.rst:22 msgid "``elgg_get_logged_in_user_guid()`` Returns the GUID of the current user" msgstr "" #: ../../guides/helpers.rst:23 msgid "``elgg_is_logged_in()`` Is the viewer logged in" msgstr "" #: ../../guides/helpers.rst:24 msgid "``elgg_is_admin_logged_in()`` Is the view an admin and logged in" msgstr "" #: ../../guides/helpers.rst:25 msgid "``elgg_gatekeeper()`` Shorthand for checking if a user is logged in. Forwards user to front page if not" msgstr "" #: ../../guides/helpers.rst:26 msgid "``elgg_admin_gatekeeper()`` Shorthand for checking the user is logged in and is an admin. Forwards user to front page if not" msgstr "" #: ../../guides/helpers.rst:27 msgid "``get_user($user_guid)`` Given a GUID, returns a full ElggUser entity" msgstr "" #: ../../guides/helpers.rst:28 msgid "``elgg_get_page_owner_guid()`` Returns the GUID of the current page owner, if there is one" msgstr "" #: ../../guides/helpers.rst:29 msgid "``elgg_get_page_owner_entity()`` Like elgg_get_page_owner_guid() but returns the full entity" msgstr "" #: ../../guides/helpers.rst:30 msgid "``get_context()`` Returns the current page's context - eg \"blog\" for the blog plugin, \"thewire\" for the wire, etc. Returns \"main\" as default" msgstr "" #: ../../guides/helpers.rst:31 msgid "``set_context($context)`` Forces the context to be a particular value" msgstr "" #: ../../guides/helpers.rst:32 msgid "``elgg_push_context($context)`` Adds a context to the stack" msgstr "" #: ../../guides/helpers.rst:33 msgid "``elgg_pop_context()`` Removes the top context from the stack" msgstr "" #: ../../guides/helpers.rst:34 msgid "``elgg_in_context($context)`` Checks if you're in a context (this checks the complete stack, eg. 'widget' in 'groups')" msgstr "" #: ../../guides/helpers.rst:37 #: ../../guides/hooks-list.rst:470 #: ../../guides/plugins.rst:2 msgid "Plugins" msgstr "" #: ../../guides/helpers.rst:39 msgid "``elgg_is_active_plugin($plugin_id)`` Check if a plugin is installed and enabled" msgstr "" #: ../../guides/helpers.rst:42 msgid "Interface and annotations" msgstr "" #: ../../guides/helpers.rst:44 msgid "``elgg_view_image_block($icon, $info)`` Return the result in a formatted list" msgstr "" #: ../../guides/helpers.rst:45 msgid "``elgg_view_comments($entity)`` Returns any comments associated with the given entity" msgstr "" #: ../../guides/helpers.rst:46 msgid "``elgg_get_friendly_time($unix_timestamp)`` Returns a date formatted in a friendlier way - \"18 minutes ago\", \"2 days ago\", etc." msgstr "" #: ../../guides/helpers.rst:47 msgid "You can pass ``'use_hover' => false`` to the user icon view if you don't want the avatar drop down menu to appear e.g." msgstr "" #: ../../guides/hooks-list.rst:2 msgid "List of plugin hooks in core" msgstr "" #: ../../guides/hooks-list.rst:9 msgid "System hooks" msgstr "" #: ../../guides/hooks-list.rst:20 msgid "**email, system**" msgstr "" #: ../../guides/hooks-list.rst:12 msgid "Triggered when sending email. ``$params`` contains:" msgstr "" #: ../../guides/hooks-list.rst:14 msgid "to" msgstr "" #: ../../guides/hooks-list.rst:15 msgid "from" msgstr "" #: ../../guides/hooks-list.rst:16 msgid "subject" msgstr "" #: ../../guides/hooks-list.rst:17 msgid "body" msgstr "" #: ../../guides/hooks-list.rst:18 msgid "headers" msgstr "" #: ../../guides/hooks-list.rst:19 msgid "params" msgstr "" #: ../../guides/hooks-list.rst:23 msgid "**page_owner, system**" msgstr "" #: ../../guides/hooks-list.rst:23 msgid "Filter the page_owner for the current page. No options are passed." msgstr "" #: ../../guides/hooks-list.rst:25 msgid "**siteid, system**" msgstr "" #: ../../guides/hooks-list.rst:28 msgid "**gc, system**" msgstr "" #: ../../guides/hooks-list.rst:28 msgid "Allows plugins to run garbage collection for ``$params['period']``." msgstr "" #: ../../guides/hooks-list.rst:31 msgid "**unit_test, system**" msgstr "" #: ../../guides/hooks-list.rst:31 msgid "Add a Simple Test test. (Deprecated.)" msgstr "" #: ../../guides/hooks-list.rst:34 #: ../../guides/hooks-list.rst:48 msgid "**diagnostics:report, system**" msgstr "" #: ../../guides/hooks-list.rst:34 msgid "Filter the output for the diagnostics report download." msgstr "" #: ../../guides/hooks-list.rst:36 #: ../../guides/hooks-list.rst:534 msgid "**search_types, get_types**" msgstr "" #: ../../guides/hooks-list.rst:39 msgid "**cron, <period>**" msgstr "" #: ../../guides/hooks-list.rst:39 msgid "Triggered by cron for each period." msgstr "" #: ../../guides/hooks-list.rst:42 msgid "**validate, input**" msgstr "" #: ../../guides/hooks-list.rst:42 msgid "Filter GET and POST input. This is used by ``get_input()`` to sanitize user input." msgstr "" #: ../../guides/hooks-list.rst:45 msgid "**geocode, location**" msgstr "" #: ../../guides/hooks-list.rst:45 msgid "Deprecated as of 1.9." msgstr "" #: ../../guides/hooks-list.rst:48 msgid "Filters the output for a diagnostic report." msgstr "" #: ../../guides/hooks-list.rst:60 msgid "**debug, log**" msgstr "" #: ../../guides/hooks-list.rst:51 msgid "Triggered by the Logger. Return false to stop the default logging method. ``$params`` includes:" msgstr "" #: ../../guides/hooks-list.rst:57 msgid "level - The debug level. One of:" msgstr "" #: ../../guides/hooks-list.rst:54 msgid "``Elgg_Logger::OFF``" msgstr "" #: ../../guides/hooks-list.rst:55 msgid "``Elgg_Logger::ERROR``" msgstr "" #: ../../guides/hooks-list.rst:56 msgid "``Elgg_Logger::WARNING``" msgstr "" #: ../../guides/hooks-list.rst:57 msgid "``Elgg_Logger::NOTICE``" msgstr "" #: ../../guides/hooks-list.rst:58 msgid "``Elgg_Logger::INFO``" msgstr "" #: ../../guides/hooks-list.rst:59 msgid "msg - The message" msgstr "" #: ../../guides/hooks-list.rst:60 msgid "display - Should this message be displayed?" msgstr "" #: ../../guides/hooks-list.rst:63 msgid "**format, friendly:title**" msgstr "" #: ../../guides/hooks-list.rst:63 msgid "Formats the \"friendly\" title for strings. This is used for generating URLs." msgstr "" #: ../../guides/hooks-list.rst:66 msgid "**format, friendly:time**" msgstr "" #: ../../guides/hooks-list.rst:66 msgid "Formats the \"friendly\" time for the timestamp ``$params['time']``." msgstr "" #: ../../guides/hooks-list.rst:70 msgid "**format, strip_tags**" msgstr "" #: ../../guides/hooks-list.rst:69 msgid "Filters a string to remove tags. The original string is passed as ``$params['original_string']`` and an optional set of allowed tags is passed as ``$params['allowed_tags']``." msgstr "" #: ../../guides/hooks-list.rst:75 msgid "**output:before, page**" msgstr "" #: ../../guides/hooks-list.rst:73 msgid "In ``elgg_view_page()``, this filters ``$vars`` before it's passed to the page shell view (``page/<page_shell>``). To stop sending the X-Frame-Options header, unregister the handler ``_elgg_views_send_header_x_frame_options()`` from this hook." msgstr "" #: ../../guides/hooks-list.rst:78 msgid "**output, page**" msgstr "" #: ../../guides/hooks-list.rst:78 msgid "In ``elgg_view_page()``, this filters the output return value." msgstr "" #: ../../guides/hooks-list.rst:81 msgid "**output:before, layout**" msgstr "" #: ../../guides/hooks-list.rst:81 msgid "In ``elgg_view_layout()``, filters ``$params`` before it's passed to the layout view." msgstr "" #: ../../guides/hooks-list.rst:84 msgid "**output:after, layout**" msgstr "" #: ../../guides/hooks-list.rst:84 msgid "In ``elgg_view_layout()``, filters the return value of the layout view." msgstr "" #: ../../guides/hooks-list.rst:88 msgid "**output, ajax**" msgstr "" #: ../../guides/hooks-list.rst:87 msgid "Triggered in the ajax forward hook that is called for ajax requests. Allows plugins to alter the output returned, including the forward URL, system messages, and errors." msgstr "" #: ../../guides/hooks-list.rst:91 msgid "**parameters, menu:<menu_name>**" msgstr "" #: ../../guides/hooks-list.rst:91 msgid "Triggered by ``elgg_view_menu()``. Used to change menu variables (like sort order) before it is generated." msgstr "" #: ../../guides/hooks-list.rst:94 msgid "**register, menu:<menu_name>**" msgstr "" #: ../../guides/hooks-list.rst:94 msgid "Triggered by ``elgg_view_menu()``. Used to add dynamic menu items." msgstr "" #: ../../guides/hooks-list.rst:97 msgid "**prepare, menu:<menu_name>**" msgstr "" #: ../../guides/hooks-list.rst:97 msgid "Trigger by ``elgg_view_menu()``. Used to sort, add, remove, and modify menu items." msgstr "" #: ../../guides/hooks-list.rst:100 msgid "**creating, river**" msgstr "" #: ../../guides/hooks-list.rst:100 msgid "Triggered before a river item is created. Return false to prevent river item from being created." msgstr "" #: ../../guides/hooks-list.rst:103 msgid "**simplecache:generate, <view>**" msgstr "" #: ../../guides/hooks-list.rst:103 msgid "Triggered when generating the cached content of a view." msgstr "" #: ../../guides/hooks-list.rst:107 msgid "**get, subscriptions**" msgstr "" #: ../../guides/hooks-list.rst:106 msgid "Filter notification subscriptions for users for the Elgg_Notifications_Event ``$params['event']``. Return an array like:" msgstr "" #: ../../guides/hooks-list.rst:118 msgid "**prepare, breadcrumbs**" msgstr "" #: ../../guides/hooks-list.rst:117 msgid "In elgg_get_breadcrumbs(), this filters the registered breadcrumbs before returning them, allowing a plugin to alter breadcrumb strategy site-wide." msgstr "" #: ../../guides/hooks-list.rst:120 msgid "**add, river**" msgstr "" #: ../../guides/hooks-list.rst:123 msgid "User hooks" msgstr "" #: ../../guides/hooks-list.rst:127 msgid "**usersettings:save, user**" msgstr "" #: ../../guides/hooks-list.rst:126 msgid "Triggered in the aggregate action to save user settings. Return false prevent sticky forms from being cleared." msgstr "" #: ../../guides/hooks-list.rst:131 #: ../../guides/hooks-list.rst:251 msgid "**access:collections:write, user**" msgstr "" #: ../../guides/hooks-list.rst:130 msgid "Filters an array of access permissions that the user ``$params['user_id']`` is allowed to save content with. Permissions returned are of the form (id => 'Human Readable Name')." msgstr "" #: ../../guides/hooks-list.rst:134 msgid "**registeruser:validate:username, all**" msgstr "" #: ../../guides/hooks-list.rst:134 msgid "Return boolean for if the string in ``$params['username']`` is valid for a username." msgstr "" #: ../../guides/hooks-list.rst:137 msgid "**registeruser:validate:password, all**" msgstr "" #: ../../guides/hooks-list.rst:137 msgid "Return boolean for if the string in ``$params['password']`` is valid for a password." msgstr "" #: ../../guides/hooks-list.rst:140 msgid "**registeruser:validate:email, all**" msgstr "" #: ../../guides/hooks-list.rst:140 msgid "Return boolean for if the string in ``$params['email']`` is valid for an email address." msgstr "" #: ../../guides/hooks-list.rst:144 msgid "**register, user**" msgstr "" #: ../../guides/hooks-list.rst:143 msgid "Triggered by the ``register`` action after the user registers. Return ``false`` to delete the user. Note the function ``register_user`` does *not* trigger this hook." msgstr "" #: ../../guides/hooks-list.rst:147 msgid "**login:forward, user**" msgstr "" #: ../../guides/hooks-list.rst:147 msgid "Filters the URL to which the user will be forwarded after login." msgstr "" #: ../../guides/hooks-list.rst:150 msgid "**find_active_users, system**" msgstr "" #: ../../guides/hooks-list.rst:150 msgid "Return the number of active users." msgstr "" #: ../../guides/hooks-list.rst:153 msgid "**status, user**" msgstr "" #: ../../guides/hooks-list.rst:153 msgid "Triggered by The Wire when adding a post." msgstr "" #: ../../guides/hooks-list.rst:158 msgid "**username:character_blacklist, user**" msgstr "" #: ../../guides/hooks-list.rst:156 msgid "Filters the string of blacklisted characters used to validate username during registration. The return value should be a string consisting of the disallowed characters. The default string can be found from ``$params['blacklist']``." msgstr "" #: ../../guides/hooks-list.rst:161 msgid "Object hooks" msgstr "" #: ../../guides/hooks-list.rst:165 msgid "**comments, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:164 msgid "Triggered in ``elgg_view_comments()``. If returning content, this overrides the ``page/elements/comments`` view." msgstr "" #: ../../guides/hooks-list.rst:168 msgid "**comments:count, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:168 msgid "Return the number of comments on ``$params['entity']``." msgstr "" #: ../../guides/hooks-list.rst:171 msgid "**likes:count, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:171 msgid "Return the number of likes for ``$params['entity']``." msgstr "" #: ../../guides/hooks-list.rst:174 msgid "Action hooks" msgstr "" #: ../../guides/hooks-list.rst:177 msgid "**action, <action>**" msgstr "" #: ../../guides/hooks-list.rst:177 msgid "Triggered before executing action scripts. Return false to abort action." msgstr "" #: ../../guides/hooks-list.rst:180 msgid "**action_gatekeeper:permissions:check, all**" msgstr "" #: ../../guides/hooks-list.rst:180 msgid "Triggered after a CSRF token is validated. Return false to prevent validation." msgstr "" #: ../../guides/hooks-list.rst:184 msgid "**action_gatekeeper:upload_exceeded_msg, all**" msgstr "" #: ../../guides/hooks-list.rst:183 msgid "Triggered when a POST exceeds the max size allowed by the server. Return an error message to display." msgstr "" #: ../../guides/hooks-list.rst:187 msgid "**forward, <reason>**" msgstr "" #: ../../guides/hooks-list.rst:187 msgid "Filter the URL to forward a user to when ``forward($url, $reason)`` is called." msgstr "" #: ../../guides/hooks-list.rst:192 msgid "Permission hooks" msgstr "" #: ../../guides/hooks-list.rst:196 msgid "**container_permissions_check, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:195 msgid "Return boolean for if the user ``$params['user']`` can use the entity ``$params['container']`` as a container for an entity of ``<entity_type>`` and subtype ``$params['subtype']``." msgstr "" #: ../../guides/hooks-list.rst:199 msgid "**permissions_check, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:199 msgid "Return boolean for if the user ``$params['user']`` can edit the entity ``$params['entity']``." msgstr "" #: ../../guides/hooks-list.rst:202 msgid "**permissions_check:delete, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:202 msgid "Return boolean for if the user ``$params['user']`` can delete the entity ``$params['entity']``. Defaults to ``$entity->canEdit()``." msgstr "" #: ../../guides/hooks-list.rst:206 msgid "**permissions_check, widget_layout**" msgstr "" #: ../../guides/hooks-list.rst:205 msgid "Return boolean for if ``$params['user']`` can edit the widgets in the context passed as ``$params['context']`` and with a page owner of ``$params['page_owner']``." msgstr "" #: ../../guides/hooks-list.rst:210 msgid "**permissions_check:metadata, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:209 msgid "Return boolean for if the user ``$params['user']`` can edit the metadata ``$params['metadata']`` on the entity ``$params['entity']``." msgstr "" #: ../../guides/hooks-list.rst:213 msgid "**permissions_check:comment, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:213 msgid "Return boolean for if the user ``$params['user']`` can comment on the entity ``$params['entity']``." msgstr "" #: ../../guides/hooks-list.rst:219 msgid "**permissions_check:annotate:<annotation_name>, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:216 msgid "Return boolean for if the user ``$params['user']`` can create an annotation ``<annotation_name>`` on the entity ``$params['entity']``. If logged in, the default is true." msgstr "" #: ../../guides/hooks-list.rst:219 msgid "This is called before the more general ``permissions_check:annotate`` hook, and its return value is that hook's initial value." msgstr "" #: ../../guides/hooks-list.rst:225 msgid "**permissions_check:annotate, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:222 msgid "Return boolean for if the user ``$params['user']`` can create an annotation ``$params['annotation_name']`` on the entity ``$params['entity']``. if logged in, the default is true." msgstr "" #: ../../guides/hooks-list.rst:225 msgid "This is functions differently than the ``permissions_check:metadata`` hook by passing the annotation name instead of the metadata object." msgstr "" #: ../../guides/hooks-list.rst:229 msgid "**permissions_check:annotation**" msgstr "" #: ../../guides/hooks-list.rst:228 msgid "Return boolean for if the user in ``$params['user']`` can edit the annotation ``$params['annotation']`` on the entity ``$params['entity']``. The user can be null." msgstr "" #: ../../guides/hooks-list.rst:233 msgid "**fail, auth**" msgstr "" #: ../../guides/hooks-list.rst:232 msgid "Return the failure message if authentication failed. An array of previous PAM failure methods is passed as ``$params``." msgstr "" #: ../../guides/hooks-list.rst:236 msgid "**api_key, use**" msgstr "" #: ../../guides/hooks-list.rst:236 msgid "Triggered by ``api_auth_key()``. Returning false prevents the key from being authenticated." msgstr "" #: ../../guides/hooks-list.rst:241 msgid "**access:collections:read, user**" msgstr "" #: ../../guides/hooks-list.rst:239 msgid "Filters an array of access IDs that the user ``$params['user_id']`` can see." msgstr "" #: ../../guides/hooks-list.rst:241 #: ../../guides/hooks-list.rst:251 msgid "The handler needs to either not use parts of the API that use the access system (triggering the hook again) or to ignore the second call. Otherwise, an infinite loop will be created." msgstr "" #: ../../guides/hooks-list.rst:244 msgid "Filters an array of access IDs that the user ``$params['user_id']`` can write to. In get_write_access_array(), this hook filters the return value, so it can be used to alter the available options in the input/access view. For core plugins, the value \"input_params\" has the keys \"entity\" (ElggEntity|false), \"entity_type\" (string), \"entity_subtype\" (string), \"container_guid\" (int) are provided. An empty entity value generally means the form is to create a new object." msgstr "" #: ../../guides/hooks-list.rst:254 msgid "**access:collections:addcollection, collection**" msgstr "" #: ../../guides/hooks-list.rst:254 msgid "Triggered after an access collection ``$params['collection_id']`` is created." msgstr "" #: ../../guides/hooks-list.rst:258 msgid "**access:collections:deletecollection, collection**" msgstr "" #: ../../guides/hooks-list.rst:257 msgid "Triggered before an access collection ``$params['collection_id']`` is deleted. Return false to prevent deletion." msgstr "" #: ../../guides/hooks-list.rst:262 msgid "**access:collections:add_user, collection**" msgstr "" #: ../../guides/hooks-list.rst:261 msgid "Triggered before adding user ``$params['user_id']`` to collection ``$params['collection_id']``. Return false to prevent adding." msgstr "" #: ../../guides/hooks-list.rst:266 msgid "**access:collections:remove_user, collection**" msgstr "" #: ../../guides/hooks-list.rst:265 msgid "Triggered before removing user ``$params['user_id']`` to collection ``$params['collection_id']``. Return false to prevent removal." msgstr "" #: ../../guides/hooks-list.rst:269 msgid "**get_sql, access**" msgstr "" #: ../../guides/hooks-list.rst:269 msgid "Filters the SQL clauses used in ``_elgg_get_access_where_sql()``." msgstr "" #: ../../guides/hooks-list.rst:274 #: ../../guides/plugins/plugin-skeleton.rst:152 #: ../../guides/views.rst:2 msgid "Views" msgstr "" #: ../../guides/hooks-list.rst:277 msgid "**view_vars, <view_name>**" msgstr "" #: ../../guides/hooks-list.rst:277 msgid "Filters the ``$vars`` array passed to the view" msgstr "" #: ../../guides/hooks-list.rst:280 msgid "**view, <view_name>**" msgstr "" #: ../../guides/hooks-list.rst:280 msgid "Filters the returned content of the view" msgstr "" #: ../../guides/hooks-list.rst:283 msgid "**layout, page**" msgstr "" #: ../../guides/hooks-list.rst:283 msgid "In ``elgg_view_layout()``, filters the layout name" msgstr "" #: ../../guides/hooks-list.rst:286 msgid "**shell, page**" msgstr "" #: ../../guides/hooks-list.rst:286 msgid "In ``elgg_view_page()``, filters the page shell name" msgstr "" #: ../../guides/hooks-list.rst:289 msgid "**head, page**" msgstr "" #: ../../guides/hooks-list.rst:289 msgid "In ``elgg_view_page()``, filters ``$vars['head']``" msgstr "" #: ../../guides/hooks-list.rst:292 msgid "Files" msgstr "" #: ../../guides/hooks-list.rst:296 msgid "**mime_type, file**" msgstr "" #: ../../guides/hooks-list.rst:295 msgid "Return the mimetype for the filename ``$params['filename']`` with original filename ``$params['original_filename']`` and with the default detected mimetype of ``$params['default']``." msgstr "" #: ../../guides/hooks-list.rst:303 msgid "**simple_type, file**" msgstr "" #: ../../guides/hooks-list.rst:299 msgid "In ``elgg_get_file_simple_type()``, filters the return value. The hook uses ``$params['mime_type']`` (e.g. ``application/pdf`` or ``image/jpeg``) and determines an overall category like ``document`` or ``image``. The bundled file plugin and other-third party plugins usually store ``simpletype`` metadata on file entities and make use of it when serving icons and constructing ``ege*`` filters and menus." msgstr "" #: ../../guides/hooks-list.rst:308 msgid "Other" msgstr "" #: ../../guides/hooks-list.rst:311 msgid "**config, comments_per_page**" msgstr "" #: ../../guides/hooks-list.rst:311 msgid "Filters the number of comments displayed per page. Default is 25." msgstr "" #: ../../guides/hooks-list.rst:318 msgid "**default, access**" msgstr "" #: ../../guides/hooks-list.rst:314 msgid "In get_default_access(), this hook filters the return value, so it can be used to alter the default value in the input/access view. For core plugins, the value \"input_params\" has the keys \"entity\" (ElggEntity|false), \"entity_type\" (string), \"entity_subtype\" (string), \"container_guid\" (int) are provided. An empty entity value generally means the form is to create a new object." msgstr "" #: ../../guides/hooks-list.rst:333 msgid "**entity:icon:url, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:321 msgid "Triggered when entity icon URL is requested, see :ref:`entity icons <guides/database#entity-icons>`. Callback should return URL for the icon of size ``$params['size']`` for the entity ``$params['entity']``. Following parameters are available through the ``$params`` array:" msgstr "" #: ../../guides/hooks-list.rst:325 msgid "entity" msgstr "" #: ../../guides/hooks-list.rst:326 msgid "Entity for which icon url is requested." msgstr "" #: ../../guides/hooks-list.rst:327 msgid "viewtype" msgstr "" #: ../../guides/hooks-list.rst:328 msgid "The type of :ref:`view <guides/views#listing-entities>` e.g. ``'default'`` or ``'json'``." msgstr "" #: ../../guides/hooks-list.rst:330 msgid "size" msgstr "" #: ../../guides/hooks-list.rst:330 msgid "Size requested, see :ref:`entity icons <guides/database#entity-icons>` for possible values." msgstr "" #: ../../guides/hooks-list.rst:332 msgid "Example on how one could default to a Gravatar icon for users that have not yet uploaded an avatar:" msgstr "" #: ../../guides/hooks-list.rst:369 msgid "**entity:url, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:367 msgid "Return the URL for the entity ``$params['entity']``. Note: Generally it is better to override the ``getUrl()`` method of ElggEntity. This hook should be used when it's not possible to subclass (like if you want to extend a bundled plugin without overriding many views)." msgstr "" #: ../../guides/hooks-list.rst:373 msgid "**to:object, <entity_type|metadata|annotation|relationship|river_item>**" msgstr "" #: ../../guides/hooks-list.rst:372 msgid "Converts the entity ``$params['entity']`` to a StdClass object. This is used mostly for exporting entity properties for portable data formats like JSON and XML." msgstr "" #: ../../guides/hooks-list.rst:376 msgid "**extender:url, <annotation|metadata>**" msgstr "" #: ../../guides/hooks-list.rst:376 msgid "Return the URL for the annotation or metadatum ``$params['extender']``." msgstr "" #: ../../guides/hooks-list.rst:379 msgid "**file:icon:url, override**" msgstr "" #: ../../guides/hooks-list.rst:379 msgid "Override a file icon URL." msgstr "" #: ../../guides/hooks-list.rst:382 msgid "**is_member, group**" msgstr "" #: ../../guides/hooks-list.rst:382 msgid "Return boolean for if the user ``$params['user']`` is a member of the group ``$params['group']``." msgstr "" #: ../../guides/hooks-list.rst:386 msgid "**entity:annotate, <entity_type>**" msgstr "" #: ../../guides/hooks-list.rst:385 msgid "Triggered in ``elgg_view_entity_annotations()``, which is called by ``elgg_view_entity()``. Can be used to add annotations to all full entity views." msgstr "" #: ../../guides/hooks-list.rst:395 msgid "**usersetting, plugin**" msgstr "" #: ../../guides/hooks-list.rst:389 msgid "Filter user settings for plugins. ``$params`` contains:" msgstr "" #: ../../guides/hooks-list.rst:391 msgid "``user`` - An ElggUser instance" msgstr "" #: ../../guides/hooks-list.rst:392 #: ../../guides/hooks-list.rst:400 msgid "``plugin`` - An ElggPlugin instance" msgstr "" #: ../../guides/hooks-list.rst:393 #: ../../guides/hooks-list.rst:401 msgid "``plugin_id`` - The plugin ID" msgstr "" #: ../../guides/hooks-list.rst:394 #: ../../guides/hooks-list.rst:402 msgid "``name`` - The name of the setting" msgstr "" #: ../../guides/hooks-list.rst:395 #: ../../guides/hooks-list.rst:403 msgid "``value`` - The value to set" msgstr "" #: ../../guides/hooks-list.rst:403 msgid "**setting, plugin**" msgstr "" #: ../../guides/hooks-list.rst:398 msgid "Filter plugin settings. ``$params`` contains:" msgstr "" #: ../../guides/hooks-list.rst:406 msgid "**relationship:url, <relationship_name>**" msgstr "" #: ../../guides/hooks-list.rst:406 msgid "Filter the URL for the relationship object ``$params['relationship']``." msgstr "" #: ../../guides/hooks-list.rst:410 msgid "**profile:fields, group**" msgstr "" #: ../../guides/hooks-list.rst:409 #: ../../guides/hooks-list.rst:420 msgid "Filter an array of profile fields. The result should be returned as an array in the format ``name => input view name``. For example:" msgstr "" #: ../../guides/hooks-list.rst:421 msgid "**profile:fields, profile**" msgstr "" #: ../../guides/hooks-list.rst:431 msgid "**widget_settings, <widget_handler>**" msgstr "" #: ../../guides/hooks-list.rst:430 msgid "Triggered when saving a widget settings ``$params['params']`` for widget ``$params['widget']``. If handling saving the settings, the handler should return true to prevent the default code from running." msgstr "" #: ../../guides/hooks-list.rst:435 msgid "**get_list, default_widgets**" msgstr "" #: ../../guides/hooks-list.rst:434 msgid "Filters a list of default widgets to add for newly registered users. The list is an array of arrays in the format:" msgstr "" #: ../../guides/hooks-list.rst:448 msgid "**rest, init**" msgstr "" #: ../../guides/hooks-list.rst:447 msgid "Triggered by the web services rest handler. Plugins can set up their own authentication handlers, then return true to prevent the default handlers from being registered." msgstr "" #: ../../guides/hooks-list.rst:452 msgid "**public_pages, walled_garden**" msgstr "" #: ../../guides/hooks-list.rst:451 msgid "Filter the URLs that are can be seen by logged out users if Walled Garden is enabled. ``$value`` is an array of regex strings that will allow access if matched." msgstr "" #: ../../guides/hooks-list.rst:457 msgid "**volatile, metadata**" msgstr "" #: ../../guides/hooks-list.rst:455 msgid "Triggered when exporting an entity through the export handler. This is rare. This allows handler to handle any volatile (non-persisted) metadata on the entity. It's preferred to use the ``to:object, <type>`` hook." msgstr "" #: ../../guides/hooks-list.rst:461 msgid "**maintenance:allow, url**" msgstr "" #: ../../guides/hooks-list.rst:461 msgid "Return boolean if the URL ``$params['current_url']`` and the path ``$params['current_path']``" msgstr "" #: ../../guides/hooks-list.rst:461 msgid "is allowed during maintenance mode." msgstr "" #: ../../guides/hooks-list.rst:464 msgid "**robots.txt, site**" msgstr "" #: ../../guides/hooks-list.rst:464 msgid "Filter the robots.txt values for ``$params['site']``." msgstr "" #: ../../guides/hooks-list.rst:467 msgid "**config, amd**" msgstr "" #: ../../guides/hooks-list.rst:467 msgid "Filter the AMD config for the requirejs library." msgstr "" #: ../../guides/hooks-list.rst:473 msgid "Embed" msgstr "" #: ../../guides/hooks-list.rst:475 msgid "**embed_get_items, <active_section>**" msgstr "" #: ../../guides/hooks-list.rst:477 msgid "**embed_get_sections, all**" msgstr "" #: ../../guides/hooks-list.rst:479 msgid "**embed_get_upload_sections, all**" msgstr "" #: ../../guides/hooks-list.rst:482 msgid "HTMLawed" msgstr "" #: ../../guides/hooks-list.rst:485 msgid "**allowed_styles, htmlawed**" msgstr "" #: ../../guides/hooks-list.rst:485 msgid "Filter the HTMLawed allowed style array." msgstr "" #: ../../guides/hooks-list.rst:488 msgid "**config, htmlawed**" msgstr "" #: ../../guides/hooks-list.rst:488 msgid "Filter the HTMLawed config array." msgstr "" #: ../../guides/hooks-list.rst:491 msgid "Members" msgstr "" #: ../../guides/hooks-list.rst:494 msgid "**members:list, <page_segment>**" msgstr "" #: ../../guides/hooks-list.rst:494 msgid "To handle the page ``/members/$page_segment``, register for this hook and return the HTML of the list." msgstr "" #: ../../guides/hooks-list.rst:498 msgid "**members:config, tabs**" msgstr "" #: ../../guides/hooks-list.rst:497 msgid "This hook is used to assemble an array of tabs to be passed to the navigation/tabs view for the members pages." msgstr "" #: ../../guides/hooks-list.rst:501 msgid "Twitter API" msgstr "" #: ../../guides/hooks-list.rst:505 msgid "**authorize, twitter_api**" msgstr "" #: ../../guides/hooks-list.rst:504 msgid "Triggered when a user is authorizes Twitter for a login. ``$params['token']`` contains the Twitter authorization token." msgstr "" #: ../../guides/hooks-list.rst:508 msgid "Reported Content" msgstr "" #: ../../guides/hooks-list.rst:511 msgid "**reportedcontent:add, system**" msgstr "" #: ../../guides/hooks-list.rst:511 msgid "Triggered after adding the reported content object ``$params['report']``. Return false to delete report." msgstr "" #: ../../guides/hooks-list.rst:514 msgid "**reportedcontent:archive, system**" msgstr "" #: ../../guides/hooks-list.rst:514 msgid "Triggered before archiving the reported content object ``$params['report']``. Return false to prevent archiving." msgstr "" #: ../../guides/hooks-list.rst:517 msgid "**reportedcontent:delete, system**" msgstr "" #: ../../guides/hooks-list.rst:517 msgid "Triggered before deleting the reported content object ``$params['report']``. Return false to prevent deleting." msgstr "" #: ../../guides/hooks-list.rst:520 msgid "Search" msgstr "" #: ../../guides/hooks-list.rst:524 msgid "**search, <type>:<subtype>**" msgstr "" #: ../../guides/hooks-list.rst:523 msgid "Filter more granular search results than searching by type alone. Must return an array with ``count`` as the total count of results and ``entities`` an array of ElggUser entities." msgstr "" #: ../../guides/hooks-list.rst:526 msgid "**search, tags**" msgstr "" #: ../../guides/hooks-list.rst:530 msgid "**search, <type>**" msgstr "" #: ../../guides/hooks-list.rst:529 msgid "Filter the search for entities for type ``$type``. Must return an array with ``count`` as the total count of results and ``entities`` an array of ElggUser entities." msgstr "" #: ../../guides/hooks-list.rst:533 msgid "Filter an array of search types. This allows plugins to add custom types that don't correspond directly to entities." msgstr "" #: ../../guides/hooks-list.rst:537 msgid "**search_types, get_queries**" msgstr "" #: ../../guides/hooks-list.rst:537 msgid "Before a search this filters the types queried. This can be used to reorder the display of search results." msgstr "" #: ../../guides/i18n.rst:2 msgid "Internationalization" msgstr "" #: ../../guides/i18n.rst:4 msgid "Make your UI translatable into many different languages." msgstr "" #: ../../guides/i18n.rst:6 msgid "If you’d like to contribute translations to Elgg, see :doc:`the contributors' guide </about/contributing>`." msgstr "" #: ../../guides/i18n.rst:11 msgid "Translations are stored in PHP files in the ``/languages`` directory of your plugin. Each file corresponds to a language. The format is ``/languages/{language-code}.php`` where ``{language-code}`` is the ISO 639-1 short code for the language. For example:" msgstr "" #: ../../guides/i18n.rst:22 msgid "The default language is “en” for English." msgstr "" #: ../../guides/i18n.rst:24 msgid "To change the wording of any phrase, provide a new mapping in your plugin’s ``{language}.php`` file for the associated key:" msgstr "" #: ../../guides/i18n.rst:36 msgid "Unless you are overriding core’s or another plugin’s language strings, it is good practice for the language keys to start with your plugin name. For example: “yourplugin:success,” “yourplugin:title,” etc. This helps avoid conflicts with other language keys." msgstr "" #: ../../guides/i18n.rst:40 msgid "Server-side API" msgstr "" #: ../../guides/i18n.rst:42 msgid "``elgg_echo($key, $args, $language)``" msgstr "" #: ../../guides/i18n.rst:44 msgid "Output the translation of the key in the current language." msgstr "" #: ../../guides/i18n.rst:46 #: ../../guides/notifications.rst:24 #: ../../guides/notifications.rst:167 #: ../../guides/notifications.rst:191 #: ../../guides/notifications.rst:246 msgid "Example:" msgstr "" #: ../../guides/i18n.rst:52 msgid "It also supports variable replacement using sprintf syntax:" msgstr "" #: ../../guides/i18n.rst:62 msgid "To force which language should be used for translation, set the third parameter:" msgstr "" #: ../../guides/i18n.rst:71 msgid "Javascript API" msgstr "" #: ../../guides/i18n.rst:73 msgid "``elgg.echo(key, args, language)``" msgstr "" #: ../../guides/i18n.rst:75 msgid "This function is the exact counterpart to ``elgg_echo`` in PHP." msgstr "" #: ../../guides/i18n.rst:77 msgid "Client-side translations are loaded asynchronously. Ensure translations are available by requiring the \"elgg\" AMD module:" msgstr "" #: ../../guides/i18n.rst:87 msgid "Translations are also available after the ``init, system`` JavaScript event." msgstr "" #: ../../guides/index.rst:2 msgid "Developer Guides" msgstr "" #: ../../guides/index.rst:4 msgid "Customize Elgg's behavior with plugins." msgstr "" #: ../../guides/javascript.rst:2 msgid "JavaScript" msgstr "" #: ../../guides/javascript.rst:4 msgid "As of Elgg 1.9, we encourage all developers to adopt the `AMD (Asynchronous Module Definition) <http://requirejs.org/docs/whyamd.html>`_ standard for writing JavaScript code in Elgg. The 1.8 version is still functional and is :ref:`described below<1.8-js>`." msgstr "" #: ../../guides/javascript.rst:13 msgid "AMD" msgstr "" #: ../../guides/javascript.rst:15 msgid "Here we'll describe making and executing AMD modules. The RequireJS documentation for `defining modules <http://requirejs.org/docs/api.html#define>`_ may also be of use." msgstr "" #: ../../guides/javascript.rst:19 msgid "Executing a module in the current page" msgstr "" #: ../../guides/javascript.rst:21 msgid "Telling Elgg to load an existing module in the current page is easy:" msgstr "" #: ../../guides/javascript.rst:28 msgid "On the client-side, this will asynchronously load the module, load any dependencies, and execute the module's definition function, if it has one." msgstr "" #: ../../guides/javascript.rst:32 msgid "Defining the Module" msgstr "" #: ../../guides/javascript.rst:34 msgid "Here we define a basic module that alters the page, by passing a \"definition function\" to ``define()``:" msgstr "" #: ../../guides/javascript.rst:47 msgid "The module's name is determined by the view name, which here is ``js/myplugin/say_hello.js``. We strip the leading ``js/`` and the ``.js`` extension, leaving ``myplugin/say_hello``." msgstr "" #: ../../guides/javascript.rst:52 msgid "The definition function **must** have one argument named ``require``." msgstr "" #: ../../guides/javascript.rst:55 msgid "Making modules dependent on other modules" msgstr "" #: ../../guides/javascript.rst:57 msgid "Below we refactor a bit so that the module depends on a new ``myplugin/hello`` module to provide the greeting:" msgstr "" #: ../../guides/javascript.rst:82 msgid "Passing plugin/Elgg settings to modules" msgstr "" #: ../../guides/javascript.rst:84 msgid "You can use a PHP-based module to pass values from the server. To make the module ``myplugin/settings``, create the view file ``views/default/js/myplugin/settings.js.php`` (note the double extension ``.js.php``)." msgstr "" #: ../../guides/javascript.rst:101 msgid "You must also manually register the view as an external resource:" msgstr "" #: ../../guides/javascript.rst:111 msgid "The PHP view is cached, so you should treat the output as static (the same for all users) and avoid session-specific logic." msgstr "" #: ../../guides/javascript.rst:116 msgid "Setting the URL of a module" msgstr "" #: ../../guides/javascript.rst:118 msgid "You may have a script outside your views you wish to make available as a module." msgstr "" #: ../../guides/javascript.rst:120 msgid "In your PHP ``init, system`` event handler, you can use ``elgg_define_js()`` to do this:" msgstr "" #: ../../guides/javascript.rst:131 msgid "The ``src`` option in ``elgg_define_js()`` is passed through ``elgg_normalize_url``, so you can use paths relative to the site URL." msgstr "" #: ../../guides/javascript.rst:135 msgid "Using traditional JS libraries as modules" msgstr "" #: ../../guides/javascript.rst:137 msgid "JavaScript libraries that define global resources can also be defined as AMD modules if you shim them by setting ``exports`` and optionally ``deps``:" msgstr "" #: ../../guides/javascript.rst:150 msgid "When this is requested client-side:" msgstr "" #: ../../guides/javascript.rst:152 msgid "The jQuery module is loaded, as it's marked as a dependency." msgstr "" #: ../../guides/javascript.rst:153 msgid "``http://example.org/elgg/mod/myplugin/vendors/jquery/jquery.form.js`` is loaded and executed." msgstr "" #: ../../guides/javascript.rst:154 msgid "The value of ``window.jQuery.fn.ajaxForm`` is returned by the module." msgstr "" #: ../../guides/javascript.rst:156 msgid "Calls to ``elgg_define_js()`` must be in an ``init, system`` event handler." msgstr "" #: ../../guides/javascript.rst:159 msgid "Some things to note" msgstr "" #: ../../guides/javascript.rst:161 msgid "Do not use ``elgg.provide()`` anymore nor other means to attach code to ``elgg`` or other global objects. Use modules." msgstr "" #: ../../guides/javascript.rst:163 msgid "Return the value of the module instead of adding to a global variable." msgstr "" #: ../../guides/javascript.rst:164 msgid "JS and CSS views (names starting with ``js/`` or ``css/``) as well as static (.js/.css) files are automatically minified and cached by Elgg's simplecache system." msgstr "" #: ../../guides/javascript.rst:169 msgid "Migrating JS from Elgg 1.8 to AMD / 1.9" msgstr "" #: ../../guides/javascript.rst:171 msgid "**Current 1.8 JavaScript modules will continue to work with Elgg**." msgstr "" #: ../../guides/javascript.rst:173 msgid "We do not anticipate any backwards compatibility issues with this new direction and will fix any issues that do come up. The old system will still be functional in Elgg 1.9, but developers are encouraged to begin looking to AMD as the future of JS in Elgg." msgstr "" #: ../../guides/javascript.rst:180 msgid "Traditional JavaScript (1.8)" msgstr "" #: ../../guides/javascript.rst:183 msgid "Register third-party libraries with ``elgg_register_js``:" msgstr "" #: ../../guides/javascript.rst:189 msgid "This will override any URLs previously registered under this name." msgstr "" #: ../../guides/javascript.rst:191 msgid "Load a library on the current page with ``elgg_load_js``:" msgstr "" #: ../../guides/javascript.rst:197 msgid "This will include and execute the linked code." msgstr "" #: ../../guides/javascript.rst:204 msgid "Using inline scripts is strongly discouraged because:" msgstr "" #: ../../guides/javascript.rst:202 msgid "They are not testable (maintainability)" msgstr "" #: ../../guides/javascript.rst:203 msgid "They are not cacheable (performance)" msgstr "" #: ../../guides/javascript.rst:204 msgid "Doing so forces some scripts to be loaded in ``<head>`` (performance)" msgstr "" #: ../../guides/javascript.rst:206 msgid "Inline scripts in core or bundled plugins are considered legacy bugs." msgstr "" #: ../../guides/javascript.rst:209 msgid "Core functions available in JS" msgstr "" #: ../../guides/javascript.rst:211 msgid "``elgg.echo()``" msgstr "" #: ../../guides/javascript.rst:213 msgid "Translate interface text" msgstr "" #: ../../guides/javascript.rst:220 msgid "``elgg.system_message()``" msgstr "" #: ../../guides/javascript.rst:222 msgid "Display a status message to the user." msgstr "" #: ../../guides/javascript.rst:229 msgid "``elgg.register_error()``" msgstr "" #: ../../guides/javascript.rst:231 msgid "Display an error message to the user." msgstr "" #: ../../guides/javascript.rst:238 msgid "``elgg.forward()``" msgstr "" #: ../../guides/javascript.rst:240 msgid "``elgg.normalize_url()``" msgstr "" #: ../../guides/javascript.rst:242 msgid "Normalize a URL relative to the elgg root:" msgstr "" #: ../../guides/javascript.rst:251 msgid "Redirect to a new page." msgstr "" #: ../../guides/javascript.rst:257 msgid "This function automatically normalizes the URL." msgstr "" #: ../../guides/javascript.rst:260 msgid "``elgg.parse_url()``" msgstr "" #: ../../guides/javascript.rst:262 msgid "Parse a URL into its component parts:" msgstr "" #: ../../guides/javascript.rst:276 msgid "``elgg.get_page_owner_guid()``" msgstr "" #: ../../guides/javascript.rst:278 msgid "Get the GUID of the current page's owner." msgstr "" #: ../../guides/javascript.rst:281 msgid "``elgg.register_hook_handler()``" msgstr "" #: ../../guides/javascript.rst:283 msgid "Register a hook handler with the event system." msgstr "" #: ../../guides/javascript.rst:298 msgid "``elgg.trigger_hook()``" msgstr "" #: ../../guides/javascript.rst:300 msgid "Emit a hook event in the event system." msgstr "" #: ../../guides/javascript.rst:308 msgid "``elgg.security.refreshToken()``" msgstr "" #: ../../guides/javascript.rst:310 msgid "Force a refresh of all XSRF tokens on the page." msgstr "" #: ../../guides/javascript.rst:312 msgid "This is automatically called every 5 minutes by default." msgstr "" #: ../../guides/javascript.rst:314 msgid "This requires a valid security token in 1.8, but not in 1.9." msgstr "" #: ../../guides/javascript.rst:316 msgid "The user will be warned if their session has expired." msgstr "" #: ../../guides/javascript.rst:319 msgid "``elgg.security.addToken()``" msgstr "" #: ../../guides/javascript.rst:321 msgid "Add a security token to an object, URL, or query string:" msgstr "" #: ../../guides/javascript.rst:339 msgid "``elgg.get_logged_in_user_entity()``" msgstr "" #: ../../guides/javascript.rst:341 msgid "Returns the logged in user as an JS ElggUser object." msgstr "" #: ../../guides/javascript.rst:344 msgid "``elgg.get_logged_in_user_guid()``" msgstr "" #: ../../guides/javascript.rst:346 msgid "Returns the logged in user's guid." msgstr "" #: ../../guides/javascript.rst:349 msgid "``elgg.is_logged_in()``" msgstr "" #: ../../guides/javascript.rst:351 msgid "True if the user is logged in." msgstr "" #: ../../guides/javascript.rst:354 msgid "``elgg.is_admin_logged_in()``" msgstr "" #: ../../guides/javascript.rst:356 msgid "True if the user is logged in and is an admin." msgstr "" #: ../../guides/javascript.rst:359 msgid "``elgg.config.get_language()``" msgstr "" #: ../../guides/javascript.rst:361 msgid "Get the current page's language." msgstr "" #: ../../guides/javascript.rst:364 msgid "There are a number of configuration values set in the elgg object:" msgstr "" #: ../../guides/javascript.rst:380 msgid "Module ``elgg/spinner``" msgstr "" #: ../../guides/javascript.rst:382 msgid "The ``elgg/spinner`` module can be used to create an Ajax loading indicator fixed to the top of the window." msgstr "" #: ../../guides/javascript.rst:399 msgid "Hooks" msgstr "" #: ../../guides/javascript.rst:401 msgid "The JS engine has a hooks system similar to the PHP engine's plugin hooks: hooks are triggered and plugins can register callbacks to react or alter information. There is no concept of Elgg events in the JS engine; everything in the JS engine is implemented as a hook." msgstr "" #: ../../guides/javascript.rst:404 msgid "Registering a callback to a hook" msgstr "" #: ../../guides/javascript.rst:406 msgid "Callbacks are registered using ``elgg.register_hook_handler()``. Multiple callbacks can be registered for the same hook." msgstr "" #: ../../guides/javascript.rst:408 msgid "The following example registers the ``elgg.ui.initDatePicker`` callback for the *init*, *system* event. Note that a difference in the JS engine is that instead of passing a string you pass the function itself to ``elgg.register_hook_handler()`` as the callback." msgstr "" #: ../../guides/javascript.rst:418 msgid "The callback" msgstr "" #: ../../guides/javascript.rst:420 msgid "The callback accepts 4 arguments:" msgstr "" #: ../../guides/javascript.rst:422 msgid "**hook** - The hook name" msgstr "" #: ../../guides/javascript.rst:423 msgid "**type** - The hook type" msgstr "" #: ../../guides/javascript.rst:424 msgid "**params** - An object or set of parameters specific to the hook" msgstr "" #: ../../guides/javascript.rst:425 msgid "**value** - The current value" msgstr "" #: ../../guides/javascript.rst:427 msgid "The ``value`` will be passed through each hook. Depending on the hook, callbacks can simply react or alter data." msgstr "" #: ../../guides/javascript.rst:430 msgid "Triggering custom hooks" msgstr "" #: ../../guides/javascript.rst:432 msgid "Plugins can trigger their own hooks:" msgstr "" #: ../../guides/javascript.rst:439 msgid "Available hooks" msgstr "" #: ../../guides/javascript.rst:442 msgid "init, system" msgstr "" #: ../../guides/javascript.rst:442 msgid "This hook is fired when the JS system is ready. Plugins should register their init functions for this hook." msgstr "" #: ../../guides/javascript.rst:445 msgid "ready, system" msgstr "" #: ../../guides/javascript.rst:445 msgid "This hook is fired when the system has fully booted." msgstr "" #: ../../guides/javascript.rst:447 msgid "getOptions, ui.popup" msgstr "" #: ../../guides/javascript.rst:448 msgid "This hook is fired for pop up displays (\"rel\"=\"popup\") and allows for customized placement options." msgstr "" #: ../../guides/menus.rst:2 msgid "Menus" msgstr "" #: ../../guides/menus.rst:4 msgid "Elgg contains helper code to build menus throughout the site." msgstr "" #: ../../guides/menus.rst:6 msgid "Every single menu requires a name, as does every single menu item. These are required in order to allow easy overriding and manipulation, as well as to provide hooks for theming." msgstr "" #: ../../guides/menus.rst:15 msgid "Basic usage" msgstr "" #: ../../guides/menus.rst:17 msgid "Basic functionalities can be achieved through these two functions:" msgstr "" #: ../../guides/menus.rst:19 msgid "`elgg_register_menu_item()`__ to add an item to a menu" msgstr "" #: ../../guides/menus.rst:20 msgid "`elgg_unregister_menu_item()`__ to remove an item from a menu" msgstr "" #: ../../guides/menus.rst:22 msgid "You normally want to call them from your plugin's init function." msgstr "" #: ../../guides/menus.rst:28 #: ../../guides/menus.rst:65 msgid "Examples" msgstr "" #: ../../guides/menus.rst:45 msgid "Advanced usage" msgstr "" #: ../../guides/menus.rst:47 msgid "You can get more control over menus by using :doc:`plugin hooks </design/events>` and the public methods provided by the ElggMenuItem__ class." msgstr "" #: ../../guides/menus.rst:52 msgid "There are two hooks that can be used to modify a menu:" msgstr "" #: ../../guides/menus.rst:51 msgid "``'register', 'menu:<menu name>'`` to add or modify items (especially in dynamic menus)" msgstr "" #: ../../guides/menus.rst:52 msgid "``'prepare', 'menu:<menu name>'`` to modify the structure of the menu before it is displayed" msgstr "" #: ../../guides/menus.rst:54 msgid "When you register a plugin hook handler, replace the ``<menu name>`` part with the internal name of the menu." msgstr "" #: ../../guides/menus.rst:57 msgid "The third parameter passed into a menu handler contains all the menu items that have been registered so far by Elgg core and other enabled plugins. In the handler we can loop through the menu items and use the class methods to interact with the properties of the menu item." msgstr "" #: ../../guides/menus.rst:67 msgid "**Example 1:** Change the URL for menu item called \"albums\" in the ``owner_block`` menu:" msgstr "" #: ../../guides/menus.rst:109 msgid "**Example 2:** Modify the ``entity`` menu for the ``ElggBlog`` objects" msgstr "" #: ../../guides/menus.rst:108 msgid "Remove the thumb icon" msgstr "" #: ../../guides/menus.rst:109 msgid "Change the \"Edit\" text into a custom icon" msgstr "" #: ../../guides/menus.rst:151 msgid "Creating a new menu" msgstr "" #: ../../guides/menus.rst:153 msgid "Elgg provides multiple different menus by default. Sometimes you may however need some menu items that don't fit in any of the existing menus. If this is the case, you can create your very own menu with the `elgg_view_menu()`__ function. You must call the function from the view, where you want to menu to be displayed." msgstr "" #: ../../guides/menus.rst:161 msgid "**Example:** Display a menu called \"my_menu\" that displays it's menu items in alphapetical order:" msgstr "" #: ../../guides/menus.rst:168 msgid "You can now add new items to the menu like this:" msgstr "" #: ../../guides/menus.rst:178 msgid "Furthermore it is now possible to modify the menu using the hooks ``'register', 'menu:my_menu'`` and ``'prepare', 'menu:my_menu'``." msgstr "" #: ../../guides/menus.rst:182 msgid "Theming" msgstr "" #: ../../guides/menus.rst:184 msgid "The menu name, section names, and item names are all embedded into the HTML as CSS classes (normalized to contain only hyphens, rather that underscores or colons). This increases the size of the markup slightly but provides themers with a high degree of control and flexibility when styling the site." msgstr "" #: ../../guides/menus.rst:189 msgid "**Example:** The following would be the output of the ``foo`` menu with sections ``alt`` and ``default`` containing items ``baz`` and ``bar`` respectively." msgstr "" #: ../../guides/notifications.rst:2 #: ../../guides/upgrading.rst:157 msgid "Notifications" msgstr "" #: ../../guides/notifications.rst:6 msgid "There are two ways to send notifications in Elgg:" msgstr "" #: ../../guides/notifications.rst:5 #: ../../guides/notifications.rst:13 msgid "Instant notifications" msgstr "" #: ../../guides/notifications.rst:6 msgid "Event-based notifications send using a notifications queue" msgstr "" #: ../../guides/notifications.rst:15 msgid "The generic method to send a notification to a user is via the function `notify_user()`__. It is normally used when we want to notify only a single user. Notification like this might for example inform that someone has liked or commented the user's post." msgstr "" #: ../../guides/notifications.rst:19 msgid "The function usually gets called in an :doc:`action <actions>` file." msgstr "" #: ../../guides/notifications.rst:26 msgid "In this example a user (``$user``) is triggering an action to rate a post created by another user (``$owner``). After saving the rating (``ElggAnnotation $rating``) to database, we could use the following code to send a notification about the new rating to the owner." msgstr "" #: ../../guides/notifications.rst:57 msgid "The language used by the recipient isn't necessarily the same as the language of the person who triggers the notification. Therefore you must always remember to pass the recipient's language as the third parameter to ``elgg_echo()``." msgstr "" #: ../../guides/notifications.rst:63 msgid "The ``'summary'`` parameter is meant for notification plugins that only want to display a short message instead of both the subject and the body. Therefore the summary should be terse but still contain all necessary information." msgstr "" #: ../../guides/notifications.rst:68 msgid "Enqueued notifications" msgstr "" #: ../../guides/notifications.rst:70 msgid "On large sites there may be many users who have subscribed to receive notifications about a particular event. Sending notifications immediately when a user triggers such an event might remarkably slow down page loading speed. This is why sending of such notifications shoud be left for Elgg's notification queue." msgstr "" #: ../../guides/notifications.rst:75 msgid "New notification events can be registered with the `elgg_register_notification_event()`__ function. Notifications about registered events will be sent automatically to all subscribed users." msgstr "" #: ../../guides/notifications.rst:82 #: ../../guides/notifications.rst:104 msgid "Example" msgstr "" #: ../../guides/notifications.rst:84 msgid "Tell Elgg to send notifications when a new object of subtype \"photo\" is created:" msgstr "" #: ../../guides/notifications.rst:97 msgid "In order to send the event-based notifications you must have the one-minute :doc:`CRON </admin/cron>` interval configured." msgstr "" #: ../../guides/notifications.rst:100 msgid "Contents of the notification message can be defined with the ``'prepare', 'notification:[action]:[type]:[subtype]'`` hook." msgstr "" #: ../../guides/notifications.rst:106 msgid "Tell Elgg to use the function ``photos_prepare_notification()`` to format the contents of the notification when a new objects of subtype 'photo' is created:" msgstr "" #: ../../guides/notifications.rst:154 msgid "Make sure the notification will be in the correct language by passing the reciepient's language into the ``elgg_echo()`` function." msgstr "" #: ../../guides/notifications.rst:158 msgid "Registering a new notification method" msgstr "" #: ../../guides/notifications.rst:160 msgid "By default Elgg has two notification methods: email and the bundled site_notifications plugin. You can register a new notification method with the `elgg_register_notification_method()`__ function." msgstr "" #: ../../guides/notifications.rst:169 msgid "Register a handler that will send the notifications via SMS." msgstr "" #: ../../guides/notifications.rst:180 msgid "After registering the new method, it will appear to the notification settings page at ``www.example.com/notifications/personal/[username]``." msgstr "" #: ../../guides/notifications.rst:184 msgid "Sending the notifications using your own method" msgstr "" #: ../../guides/notifications.rst:186 msgid "Besides registering the notification method, you also need to register a handler that takes care of actually sending the SMS notifications. This happens with the ``'send', 'notification:[method]'`` hook." msgstr "" #: ../../guides/notifications.rst:230 msgid "Subscriptions" msgstr "" #: ../../guides/notifications.rst:232 msgid "In most cases Elgg core takes care of handling the subscriptions, so notification plugins don't usually have to alter them." msgstr "" #: ../../guides/notifications.rst:237 msgid "Subscriptions can however be:" msgstr "" #: ../../guides/notifications.rst:236 msgid "Added using the `elgg_add_subscription()`__ function" msgstr "" #: ../../guides/notifications.rst:237 msgid "Removed using the `elgg_remove_subscription()`__ function" msgstr "" #: ../../guides/notifications.rst:242 msgid "It's possible to modify the recipients of a notification dynamically with the ``'get', 'subscriptions'`` hook." msgstr "" #: ../../guides/page-owner.rst:2 msgid "Page ownership" msgstr "" #: ../../guides/page-owner.rst:4 msgid "One recurring task of any plugin will be to determine the page ownership in order to decide which actions are allowed or not. Elgg has a number of functions related to page ownership and also offers plugin developers flexibility by letting the plugin handle page ownership requests as well. Determining the owner of a page can be determined with ``elgg_get_page_owner_guid()``, which will return the GUID of the owner. Alternatively, ``elgg_get_page_owner_entity()`` will retrieve the whole page owner entity. If the page already knows who the page owner is, but the system doesn't, the it be can set by passing the GUID to ``elgg_set_page_owner_guid($guid)``." msgstr "" #: ../../guides/page-owner.rst:8 msgid "Custom page owner handlers" msgstr "" #: ../../guides/page-owner.rst:10 msgid "Plugin developers can create page owner handlers, which could be necessary in certain cases, for example when integrating third party functionality. The handler will be a function which will need to get registered with ``elgg_register_plugin_hook_handler('page_owner', 'system', 'your_page_owner_function_name');`` . The handler will only need to return a value (an integer GUID) when it knows for certain who the page owner is." msgstr "" #: ../../guides/page-owner.rst:12 msgid "By default, the system determines the page_owner from the following elements:" msgstr "" #: ../../guides/page-owner.rst:14 msgid "The ``username`` URL parameter" msgstr "" #: ../../guides/page-owner.rst:15 msgid "The ``owner_guid`` URL parameter" msgstr "" #: ../../guides/page-owner.rst:17 msgid "It then passes off to any page owner handlers defined using the :ref:`plugin hook <design/events#plugin-hooks>`. If no page owner can be determined, the page owner is set to 0, which is the same as the logged out user." msgstr "" #: ../../guides/pagehandler.rst:2 msgid "Page handler" msgstr "" #: ../../guides/pagehandler.rst:4 msgid "Elgg offers a facility to manage your plugin pages via a page handler, enabling custom urls like ``http://yoursite/your_plugin/section``. To add a page handler to a plugin, a handler function needs to be registered in the plugin's ``start.php`` file with ``elgg_register_page_handler()``:" msgstr "" #: ../../guides/pagehandler.rst:10 msgid "The plugin's page handler is passed two parameters:" msgstr "" #: ../../guides/pagehandler.rst:12 msgid "an array containing the sections of the URL exploded by '/'. With this information the handler will be able to apply any logic necessary, for example loading the appropriate view and returning its contents." msgstr "" #: ../../guides/pagehandler.rst:13 msgid "the handler, this is the handler that is currently used (in our example ``your_plugin``). If you don't register multiple page handlers to the same function you'll never need this." msgstr "" #: ../../guides/pagehandler.rst:16 msgid "Code flow" msgstr "" #: ../../guides/pagehandler.rst:18 msgid "Pages in plugins should be served only through page handlers, stored in ``pages/`` of your plugin's directory and do not need to ``include`` or ``require`` Elgg's ``engine/start.php`` file. The purpose of these files are to knit together output from different views to form the page that the user sees. The program flow is something like this:" msgstr "" #: ../../guides/pagehandler.rst:20 msgid "A user requests ``/plugin_name/section/entity``" msgstr "" #: ../../guides/pagehandler.rst:21 msgid "Elgg checks if ``plugin_name`` is registered to a page handler and calls that function, passing ``array('section', 'entity')`` as the first argument" msgstr "" #: ../../guides/pagehandler.rst:22 msgid "The page handler function determines which page to display, optionally sets some values, and then includes the correct page under ``plugin_name/pages/plugin_name/``" msgstr "" #: ../../guides/pagehandler.rst:23 msgid "The included file combines many separate views, calls formatting functions like ``elgg_view_layout()`` and ``elgg_view_page()``, and then echos the final output" msgstr "" #: ../../guides/pagehandler.rst:24 msgid "The user sees a fully rendered page" msgstr "" #: ../../guides/pagehandler.rst:26 msgid "There is no syntax enforced on the URLs, but Elgg's coding standards suggests a certain format." msgstr "" #: ../../guides/permissions-check.rst:2 msgid "Permissions Check" msgstr "" #: ../../guides/permissions-check.rst:6 msgid "As stated in the page, this method works **only** for granting **write** access to entities. You **cannot** use this method to retrieve or view entities for which the user does not have read access." msgstr "" #: ../../guides/permissions-check.rst:8 msgid "Elgg provides a mechanism of overriding write permissions check through the :ref:`permissions_check plugin hook <guides/hooks-list#permission-hooks>` . This is useful for allowing plugin write to all accessible entities regardless of access settings. Entities that are hidden, however, will still be unavailable to the plugin." msgstr "" #: ../../guides/permissions-check.rst:11 msgid "Hooking permissions_check" msgstr "" #: ../../guides/permissions-check.rst:13 msgid "In your plugin, you must register the plugin hook for ``permissions_check``." msgstr "" #: ../../guides/permissions-check.rst:20 msgid "The override function" msgstr "" #: ../../guides/permissions-check.rst:22 msgid "Now create the function that will be called by the permissions check hook. In this function we determine if the entity (in parameters) has write access. Since it is important to keep Elgg secure, write access should be given only after checking a variety of situations including page context, logged in user, etc. Note that this function can return 3 values: true if the entity has write access, false if the entity does not, and null if this plugin doesn't care and the security system should consult other plugins." msgstr "" #: ../../guides/permissions-check.rst:40 msgid "Full Example" msgstr "" #: ../../guides/permissions-check.rst:42 msgid "This is a full example using the context to determine if the entity has write access." msgstr "" #: ../../guides/plugins.rst:4 msgid "Plugins must provide a start.php and manifest.xml file in the plugin root in order to be recognized by Elgg." msgstr "" #: ../../guides/plugins.rst:8 msgid "start.php" msgstr "" #: ../../guides/plugins.rst:10 msgid "The start.php file bootstraps plugin by registering event listeners and plugin hooks." msgstr "" #: ../../guides/plugins.rst:14 msgid "activate.php, deactivate.php" msgstr "" #: ../../guides/plugins.rst:16 msgid "The activate.php and deactivate.php files contain procedural code that will run upon plugin activation and deactivation. Use these files to perform one-time events such as registering a persistent admin notice, registering subtypes, or performing garbage collection when deactivated." msgstr "" #: ../../guides/plugins.rst:22 msgid "manifest.xml" msgstr "" #: ../../guides/plugins.rst:24 msgid "Elgg plugins are required to have a ``manifest.xml`` file in the root of a plugin." msgstr "" #: ../../guides/plugins.rst:26 msgid "The ``manifest.xml`` file includes information about the plugin itself, requirements to run the plugin, and optional information including where to display the plugin in the admin area and what APIs the plugin provides." msgstr "" #: ../../guides/plugins.rst:29 msgid "Syntax" msgstr "" #: ../../guides/plugins.rst:31 msgid "The manifest file is a standard XML file in UTF-8. Everything is a child of the ``<plugin_manifest>`` element." msgstr "" #: ../../guides/plugins.rst:38 msgid "The manifest syntax is as follows:" msgstr "" #: ../../guides/plugins.rst:44 msgid "Many elements can contain children attributes:" msgstr "" #: ../../guides/plugins.rst:54 msgid "Required Elements" msgstr "" #: ../../guides/plugins.rst:56 msgid "All plugins are required to define the following elements in their manifest files:" msgstr "" #: ../../guides/plugins.rst:58 msgid "id - This has the name as the directory that the plugin uses." msgstr "" #: ../../guides/plugins.rst:59 msgid "name - The display name of the plugin." msgstr "" #: ../../guides/plugins.rst:60 msgid "author - The name of the author who wrote the plugin." msgstr "" #: ../../guides/plugins.rst:61 msgid "version - The version of the plugin." msgstr "" #: ../../guides/plugins.rst:62 msgid "description - A description of the what the plugin provides, its features, and other relevant information" msgstr "" #: ../../guides/plugins.rst:63 msgid "requires - Each plugin must specify the release of Elgg it was developed for. See the plugin Dependencies page for more information." msgstr "" #: ../../guides/plugins.rst:66 msgid "Available Elements" msgstr "" #: ../../guides/plugins.rst:68 msgid "In addition to the require elements above, the follow elements are available to use:" msgstr "" #: ../../guides/plugins.rst:70 msgid "blurb - A short description of the plugin." msgstr "" #: ../../guides/plugins.rst:71 msgid "category - The category of the plugin. It is recommended to follow the [[Plugin_Guidelines|plugin guidelines]] and use one of the defined categories. There can be multiple entries." msgstr "" #: ../../guides/plugins.rst:72 msgid "conflicts - Specifies that the plugin conflicts with a certain system configuration." msgstr "" #: ../../guides/plugins.rst:73 msgid "copyright - The plugin's copyright information." msgstr "" #: ../../guides/plugins.rst:74 msgid "license - The plugin's license information." msgstr "" #: ../../guides/plugins.rst:75 msgid "provides - Specifies that this plugin provides the same functionality as another Elgg plugin or a PHP extension." msgstr "" #: ../../guides/plugins.rst:76 msgid "screenshot - Screenshots of the plugin. There can be multiple entries. See the advanced example for syntax." msgstr "" #: ../../guides/plugins.rst:77 msgid "suggests - Parallels the requires system, but doesn't affect if the plugin can be enabled. Used to suggest other plugins that interact or build on the plugin." msgstr "" #: ../../guides/plugins.rst:78 msgid "website - A link to the website for the plugin." msgstr "" #: ../../guides/plugins.rst:82 msgid ":doc:`plugins/dependencies`" msgstr "" #: ../../guides/plugins.rst:85 #: ../../guides/widgets.rst:115 msgid "Simple Example" msgstr "" #: ../../guides/plugins.rst:87 msgid "This manifest file is the bare minimum a plugin must have." msgstr "" #: ../../guides/plugins.rst:105 msgid "Advanced example" msgstr "" #: ../../guides/plugins.rst:107 msgid "This example uses all of the available elements:" msgstr "" #: ../../guides/plugins.rst:149 #: ../../guides/views.rst:344 #: ../../guides/web-services.rst:329 msgid "Related" msgstr "" #: ../../guides/plugins/dependencies.rst:2 msgid "Plugin Dependencies" msgstr "" #: ../../guides/plugins/dependencies.rst:4 msgid "In Elgg 1.8 a plugin dependencies system was introduced to prevent plugins from being used on incompatible systems." msgstr "" #: ../../guides/plugins/dependencies.rst:13 msgid "The dependencies system is controlled through a plugin's ``manifest.xml`` file. Plugin authors can specify that a plugin:" msgstr "" #: ../../guides/plugins/dependencies.rst:15 msgid "Requires certain Elgg versions, Elgg plugins, PHP extensions, and PHP settings." msgstr "" #: ../../guides/plugins/dependencies.rst:16 msgid "Suggests certain Elgg versions, Elgg plugins, PHP extensions, and PHP settings." msgstr "" #: ../../guides/plugins/dependencies.rst:17 msgid "Conflicts with certain Elgg versions or Elgg plugins." msgstr "" #: ../../guides/plugins/dependencies.rst:18 msgid "Provides the equivalent of another Elgg plugin or PHP extension." msgstr "" #: ../../guides/plugins/dependencies.rst:20 msgid "The dependency system uses the four verbs above (``requires``, ``suggests``, ``conflicts``, and ``provides``) as parent elements to indicate what type of dependency is described by its children. All dependencies have a similar format with similar options:" msgstr "" #: ../../guides/plugins/dependencies.rst:32 msgid "``type`` is always required" msgstr "" #: ../../guides/plugins/dependencies.rst:35 msgid "Verbs" msgstr "" #: ../../guides/plugins/dependencies.rst:37 msgid "With the exception of ``provides``, all verbs use the same six types with differing effects, and the type options are the same among the verbs. ``provides`` only supports ``plugin`` and ``php_extension``." msgstr "" #: ../../guides/plugins/dependencies.rst:40 msgid "Requires" msgstr "" #: ../../guides/plugins/dependencies.rst:42 msgid "Using a ``requires`` dependency means that the plugin cannot be enabled unless the dependency is exactly met." msgstr "" #: ../../guides/plugins/dependencies.rst:45 msgid "Mandatory requires: elgg_version and elgg_release" msgstr "" #: ../../guides/plugins/dependencies.rst:47 msgid "Every plugin must have at least one requires: the version of Elgg the plugin is developed for. This is specified either by the Elgg API ``version`` (2011010401) or the ``release`` (1.8). The default comparison ``>=``, but you can specify your own by passing the ``<comparison>`` element." msgstr "" #: ../../guides/plugins/dependencies.rst:49 msgid "Using elgg_version:" msgstr "" #: ../../guides/plugins/dependencies.rst:58 msgid "Using elgg_release:" msgstr "" #: ../../guides/plugins/dependencies.rst:68 msgid "Suggests" msgstr "" #: ../../guides/plugins/dependencies.rst:70 msgid "``suggests`` dependencies signify that the plugin author suggests a specific system configuration, but it is not required to use the plugin. The suggestions can also be another plugin itself which could interact, extend, or be extended by this plugin, but is not required for it to function." msgstr "" #: ../../guides/plugins/dependencies.rst:72 msgid "Suggest another plugin:" msgstr "" #: ../../guides/plugins/dependencies.rst:82 msgid "Suggest a certain PHP setting:" msgstr "" #: ../../guides/plugins/dependencies.rst:94 msgid "Conflicts" msgstr "" #: ../../guides/plugins/dependencies.rst:96 msgid "``conflicts`` dependencies mean the plugin cannot be used under a specific system configuration." msgstr "" #: ../../guides/plugins/dependencies.rst:98 msgid "Conflict with any version of the profile plugin:" msgstr "" #: ../../guides/plugins/dependencies.rst:107 msgid "Conflict with a specific version of Elgg:" msgstr "" #: ../../guides/plugins/dependencies.rst:118 msgid "Provides" msgstr "" #: ../../guides/plugins/dependencies.rst:120 msgid "``provides`` dependencies tell Elgg that this plugin is providing the functionality of another plugin or PHP extension. Unlike the other verbs, it only supports two types: ``plugin`` and ``php_extension``." msgstr "" #: ../../guides/plugins/dependencies.rst:122 msgid "The purpose of this is to provide interchangeable APIs implemented by different plugins. For example, the twitter_services plugin provides an API for other plugins to Tweet on behalf of the user via curl and Oauth. A plugin author could write a compatible plugin for servers without curl support that uses sockets streams and specify that it provides twitter_services. Any plugins that suggest or require twitter_services would then know they can work." msgstr "" #: ../../guides/plugins/dependencies.rst:134 msgid "All plugins provide themselves as their plugin id (directory name) at the version defined in the their manifest." msgstr "" #: ../../guides/plugins/dependencies.rst:137 msgid "Types" msgstr "" #: ../../guides/plugins/dependencies.rst:139 msgid "Every dependency verb has a mandatory ``<type>`` element that must be one of the following six values:" msgstr "" #: ../../guides/plugins/dependencies.rst:141 msgid "**elgg_version** - The API version of Elgg (2011010401)" msgstr "" #: ../../guides/plugins/dependencies.rst:142 msgid "**elgg_release** - The release version of Elgg (1.8)" msgstr "" #: ../../guides/plugins/dependencies.rst:143 msgid "**plugin** - An Elgg plugin" msgstr "" #: ../../guides/plugins/dependencies.rst:144 msgid "**priority** - A plugin load priority" msgstr "" #: ../../guides/plugins/dependencies.rst:145 msgid "**php_extension** - A PHP extension" msgstr "" #: ../../guides/plugins/dependencies.rst:146 msgid "**php_ini** - A PHP setting" msgstr "" #: ../../guides/plugins/dependencies.rst:147 msgid "**php_version** - A PHP version" msgstr "" #: ../../guides/plugins/dependencies.rst:151 msgid "``provides`` only supports ``plugin`` and ``php_extension`` types." msgstr "" #: ../../guides/plugins/dependencies.rst:153 msgid "Every type is defined with a dependency verb as the parent element. Additional option elements are at the same level as the type element:" msgstr "" #: ../../guides/plugins/dependencies.rst:164 msgid "elgg_version and elgg_release" msgstr "" #: ../../guides/plugins/dependencies.rst:166 msgid "These concern the API and release versions of Elgg and requires the following option element:" msgstr "" #: ../../guides/plugins/dependencies.rst:168 msgid "**version** - The API or release version" msgstr "" #: ../../guides/plugins/dependencies.rst:170 #: ../../guides/plugins/dependencies.rst:229 msgid "The following option element is supported, but not required:" msgstr "" #: ../../guides/plugins/dependencies.rst:172 #: ../../guides/plugins/dependencies.rst:184 #: ../../guides/plugins/dependencies.rst:231 msgid "**comparison** - The comparison operator to use. Defaults to >= if not passed" msgstr "" #: ../../guides/plugins/dependencies.rst:175 msgid "plugin" msgstr "" #: ../../guides/plugins/dependencies.rst:177 msgid "Specifies an Elgg plugin by its ID (directory name). This requires the following option element:" msgstr "" #: ../../guides/plugins/dependencies.rst:179 msgid "**name** - The ID of the plugin" msgstr "" #: ../../guides/plugins/dependencies.rst:181 #: ../../guides/plugins/dependencies.rst:201 msgid "The following option elements are supported, but not required:" msgstr "" #: ../../guides/plugins/dependencies.rst:183 msgid "**version** - The version of the plugin" msgstr "" #: ../../guides/plugins/dependencies.rst:187 msgid "priority" msgstr "" #: ../../guides/plugins/dependencies.rst:189 msgid "This requires the plugin to be loaded before or after another plugin, if that plugin exists. ``requires`` should be used to require that a plugin exists. The following option elements are required:" msgstr "" #: ../../guides/plugins/dependencies.rst:191 msgid "**plugin** - The plugin ID to base the load order on" msgstr "" #: ../../guides/plugins/dependencies.rst:192 msgid "**priority** - The load order: 'before' or 'after'" msgstr "" #: ../../guides/plugins/dependencies.rst:195 msgid "php_extension" msgstr "" #: ../../guides/plugins/dependencies.rst:197 msgid "This checks PHP extensions. The follow option element is required:" msgstr "" #: ../../guides/plugins/dependencies.rst:199 msgid "**name** - The name of the PHP extension" msgstr "" #: ../../guides/plugins/dependencies.rst:203 msgid "**version** - The version of the extension" msgstr "" #: ../../guides/plugins/dependencies.rst:204 #: ../../guides/plugins/dependencies.rst:220 msgid "**comparison** - The comparison operator to use. Defaults to ==" msgstr "" #: ../../guides/plugins/dependencies.rst:208 msgid "The format of extension versions varies greatly among PHP extensions and is sometimes not even set. This is generally worthless to check." msgstr "" #: ../../guides/plugins/dependencies.rst:211 msgid "php_ini" msgstr "" #: ../../guides/plugins/dependencies.rst:213 msgid "This checks PHP settings. The following option elements are required:" msgstr "" #: ../../guides/plugins/dependencies.rst:215 msgid "**name** - The name of the setting to check" msgstr "" #: ../../guides/plugins/dependencies.rst:216 msgid "**value** - The value of the setting to compare against" msgstr "" #: ../../guides/plugins/dependencies.rst:218 msgid "The following options are supported, but not required:" msgstr "" #: ../../guides/plugins/dependencies.rst:223 msgid "php_version" msgstr "" #: ../../guides/plugins/dependencies.rst:225 msgid "This checks the PHP version. The following option elements are required:" msgstr "" #: ../../guides/plugins/dependencies.rst:227 msgid "**version** - The PHP version" msgstr "" #: ../../guides/plugins/dependencies.rst:234 msgid "Comparison Operators" msgstr "" #: ../../guides/plugins/dependencies.rst:236 msgid "Dependencies that check versions support passing a custom operator via the ``<comparison>`` element." msgstr "" #: ../../guides/plugins/dependencies.rst:238 msgid "The follow are valid comparison operators:" msgstr "" #: ../../guides/plugins/dependencies.rst:240 msgid "< or lt" msgstr "" #: ../../guides/plugins/dependencies.rst:241 msgid "<= or le" msgstr "" #: ../../guides/plugins/dependencies.rst:242 msgid "=, ==, or eq" msgstr "" #: ../../guides/plugins/dependencies.rst:243 msgid "!=, <>, or ne" msgstr "" #: ../../guides/plugins/dependencies.rst:244 msgid "> or gt" msgstr "" #: ../../guides/plugins/dependencies.rst:245 msgid ">= or ge" msgstr "" #: ../../guides/plugins/dependencies.rst:247 msgid "If ``<comparison>`` is not passed, the follow are used as defaults, depending upon the dependency type:" msgstr "" #: ../../guides/plugins/dependencies.rst:249 msgid "requires->elgg_version and elgg_release: >=" msgstr "" #: ../../guides/plugins/dependencies.rst:250 msgid "requires->plugin: >=" msgstr "" #: ../../guides/plugins/dependencies.rst:251 msgid "requires->php_extension: =" msgstr "" #: ../../guides/plugins/dependencies.rst:252 msgid "requires->php_ini: =" msgstr "" #: ../../guides/plugins/dependencies.rst:253 msgid "all conflicts: =" msgstr "" #: ../../guides/plugins/dependencies.rst:257 msgid "You must escape < and > to ``>`` and ``<``. For comparisons that use these values, it is recommended you use the string equivalents instead!" msgstr "" #: ../../guides/plugins/dependencies.rst:260 msgid "Quick Examples" msgstr "" #: ../../guides/plugins/dependencies.rst:263 msgid "Requires Elgg 1.8.2 or higher" msgstr "" #: ../../guides/plugins/dependencies.rst:273 msgid "Requires the Groups plugin is active" msgstr "" #: ../../guides/plugins/dependencies.rst:283 msgid "Requires to be after the Profile plugin if Profile is active" msgstr "" #: ../../guides/plugins/dependencies.rst:294 msgid "Conflicts with The Wire plugin" msgstr "" #: ../../guides/plugins/dependencies.rst:304 msgid "Requires at least 256 MB memory in PHP" msgstr "" #: ../../guides/plugins/dependencies.rst:317 msgid "Requires at least PHP version 5.3" msgstr "" #: ../../guides/plugins/dependencies.rst:327 msgid "Suggest the TidyPics plugin is loaded" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:2 msgid "Plugin skeleton" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:4 msgid "The following is the standard for plugin structure in Elgg as of Elgg 1.8. Plugins written for Elgg 1.7 and down are strongly encouraged to use this structure as well, though some of the benefits are not as apparent as when used in 1.8." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:7 msgid "Example Structure" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:9 msgid "The following is an example of a plugin with standard structure. For further explanation of this structure, see the details in the following sections. Your plugin may not need all the files listed" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:11 msgid "The following files for plugin ``example`` would go in ``/mod/example/``" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:69 msgid "Required Files" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:71 msgid "Plugins **must** provide a ``start.php`` and ``manifest.xml`` file in the plugin root in order to be recognized by Elgg." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:73 msgid "Therefore the following is the minimally compliant structure:" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:84 msgid "Plugins *should* place scripts for actions an ``actions/`` directory, and furthermore *should* use the name of the action to determine the location within that directory." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:86 msgid "For example, the action ``my/example/action`` would go in ``my_plugin/actions/my/example/action.php``. This makes it very obvious which script is associated with which action." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:88 msgid "Similarly, the body of the form that submits to this action should be located in ``forms/my/example/action.php``. Not only does this make the connection b/w action handler, form code, and action name obvious, but it allows you to use the new (as of Elgg 1.8) ``elgg_view_form()`` function easily." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:91 msgid "Text Files" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:93 msgid "Plugins *may* provide various \\*.txt as additional documentation for the plugin. These files **must** be in Markdown syntax and will generate links on the plugin management sections." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:96 msgid "README.txt" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:96 msgid "*should* provide additional information about the plugin of an unspecified nature" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:99 msgid "COPYRIGHT.txt" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:99 msgid "If included, **must** provide an explanation of the plugin's copyright, besides what is included in ``manifest.xml``" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:102 msgid "LICENSE.txt" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:102 msgid "If included, **must** provide the text of the license that the plugin is released under." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:105 msgid "INSTALL.txt" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:105 msgid "If included, **must** provide additional instructions for installing the plugin if the process is sufficiently complicated (e.g. if it requires installing third party libraries on the host machine, or requires acquiring an API key from a third party)." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:108 msgid "CHANGES.txt" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:108 msgid "If included, **must** provide a list of changes for their plugin, grouped by version number, with the most recent version at the top." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:110 msgid "Plugins *may* include additional \\*.txt files besides these, but no interface is given for reading them." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:113 msgid "Pages" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:115 msgid "Plugins *should* put page-generating scripts in a ``pages/`` directory inside their plugin root. Furthermore, plugins *should* put page-generating scripts under a directory named for their handler. For example, the script for page ``yoursite.com/my_handler/view/1234`` *should* be located at ``mod/my_plugin/pages/my_handler/view.php``." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:117 msgid "In the past, these scripts were included directly in the plugin root. Plugins *should not* do this anymore, and if any core plugins are found to do this, that is a bug if not present solely for the sake of backwards compatibility." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:121 msgid "The reason we encourage this structure is" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:123 msgid "To form a logical relationship between urls and scripts, so that people examining the code can have an idea of what it does just by examining the structure." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:124 msgid "To clean up the root plugin directory, which historically has quickly gotten cluttered with the page handling scripts." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:128 msgid "Classes" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:130 msgid "All classes that your plugin defines *should* be included in a ``classes/`` directory. This directory has special meaning to Elgg. Classes placed in this directory are autoloaded on demand, and do not need to be included explicitly." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:134 msgid "Each file **must** have exactly one class defined inside it. The file name **must** match the name of the one class that the file defines (except for the \".php\" suffix)." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:139 msgid "Files with a \".class.php\" extension will **not** be recognized by Elgg." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:142 msgid "Vendors" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:144 msgid "Included third-party libraries of any kind *should* be included in the ``vendors/`` folder in the plugin root. Though this folder has no special significance to the Elgg engine, this has historically been the location where Elgg core stores its third-party libraries, so we encourage the same format for the sake of consistency and familiarity." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:147 msgid "Lib" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:149 msgid "Procedural code defined by your plugin *should* be placed in the `lib/` directory. Though this folder has no special significance to the Elgg engine, this has historically been the location where Elgg core stores its procedural code, so we encourage the same format for the sake of consistency and familiarity." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:154 msgid "In order to override core views, a plugin's views **must** be placed in a ``views/``. This directory has special meaning to Elgg as views defined here automatically override Elgg core's version of those views. For more info, see :doc:`/guides/views`." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:157 msgid "Javascript" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:159 msgid "Javascript that will be included on every page *should* be put in the ``plugin/js`` view and your plugin *should* extend ``js/elgg`` with this view. Javascript that does not need to be included on every page *should* be put in a static javascript file under the ``js/`` directory. For more information on Javascript in Elgg, see :doc:`/guides/javascript`." msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:162 msgid "activate.php and deactivate.php" msgstr "" #: ../../guides/plugins/plugin-skeleton.rst:164 msgid "The ``activate.php`` and ``deactivate.php`` files contain procedural code that will run respectively upon plugin activation or deactivation. Use these files to perform one-time events such as registering a persistent admin notice, registering subtypes, or performing garbage collection when deactivated." msgstr "" #: ../../guides/river.rst:2 msgid "River" msgstr "" #: ../../guides/river.rst:4 msgid "Elgg natively supports the \"river\", an activity stream containing descriptions of activities performed by site members. This page gives an overview of adding events to the river in an Elgg plugin." msgstr "" #: ../../guides/river.rst:9 msgid "Pushing river items" msgstr "" #: ../../guides/river.rst:11 msgid "Items are pushed to the activity river through a function call, which you must include in your plugins for the items to appear." msgstr "" #: ../../guides/river.rst:14 msgid "Here we add a river item telling that a user has created a new blog post:" msgstr "" #: ../../guides/river.rst:27 msgid "All available parameters:" msgstr "" #: ../../guides/river.rst:29 msgid "``view`` => STR The view that will handle the river item (must exist)" msgstr "" #: ../../guides/river.rst:30 msgid "``action_type`` => STR An arbitrary string to define the action (e.g. 'create', 'update', 'vote', 'review', etc)" msgstr "" #: ../../guides/river.rst:31 msgid "``subject_guid`` => INT The GUID of the entity doing the action" msgstr "" #: ../../guides/river.rst:32 msgid "``object_guid`` => INT The GUID of the entity being acted upon" msgstr "" #: ../../guides/river.rst:33 msgid "``target_guid`` => INT The GUID of the the object entity's container (optional)" msgstr "" #: ../../guides/river.rst:34 msgid "``access_id`` => INT The access ID of the river item (default: same as the object)" msgstr "" #: ../../guides/river.rst:35 msgid "``posted`` => INT The UNIX epoch timestamp of the river item (default: now)" msgstr "" #: ../../guides/river.rst:36 msgid "``annotation_id`` => INT The annotation ID associated with this river entry (optional)" msgstr "" #: ../../guides/river.rst:38 msgid "When an item is deleted or changed, the river item will be updated automatically." msgstr "" #: ../../guides/river.rst:41 msgid "River views" msgstr "" #: ../../guides/river.rst:43 msgid "In order for events to appear in the river you need to provide a corresponding :doc:`view <views>` with the name specified in the function above." msgstr "" #: ../../guides/river.rst:46 msgid "We recommend ``/river/{type}/{subtype}/{action}``, where:" msgstr "" #: ../../guides/river.rst:48 msgid "{type} is the entity type of the content we're interested in (``object`` for objects, ``user`` for users, etc)" msgstr "" #: ../../guides/river.rst:49 msgid "{subtype} is the entity subtype of the content we're interested in (``blog`` for blogs, ``photo_album`` for albums, etc)" msgstr "" #: ../../guides/river.rst:50 msgid "{action} is the action that took place (''create'', ''update'', etc)" msgstr "" #: ../../guides/river.rst:52 msgid "River item information will be passed in an object called ``$vars['item']``, which contains the following important parameters:" msgstr "" #: ../../guides/river.rst:54 msgid "``$vars['item']->subject_guid`` The GUID of the user performing the action" msgstr "" #: ../../guides/river.rst:55 msgid "``$vars['item']->object_guid`` The GUID of the entity being acted upon" msgstr "" #: ../../guides/river.rst:57 msgid "Timestamps etc will be generated for you." msgstr "" #: ../../guides/river.rst:59 msgid "For example, the blog plugin uses the following code for its river view:" msgstr "" #: ../../guides/routing.rst:2 msgid "Routing" msgstr "" #: ../../guides/routing.rst:4 msgid "Elgg has two mechanisms to respond to HTTP requests that don't already go through the :doc:`/design/actions` and :doc:`/guides/views/simplecache` systems." msgstr "" #: ../../guides/routing.rst:8 msgid "URL Identifier and Segments" msgstr "" #: ../../guides/routing.rst:10 msgid "After removing the site URL, Elgg splits the URL path by ``/`` into an array. The first element, the **identifier**, is shifted off, and the remaining elements are called the **segments**. For example, if the site URL is ``http://example.com/elgg/``, the URL ``http://example.com/elgg/blog/owner/jane?foo=123`` produces:" msgstr "" #: ../../guides/routing.rst:15 msgid "Identifier: ``'blog'``. Segments: ``['owner', 'jane']``. (the query string parameters are available via ``get_input()``)" msgstr "" #: ../../guides/routing.rst:18 msgid "The site URL (home page) is a special case that produces an empty string identifier and an empty segments array." msgstr "" #: ../../guides/routing.rst:23 msgid "Page Handler" msgstr "" #: ../../guides/routing.rst:25 msgid "To handle all URLs that begin with a particular identifier, you can register a function to act as a :doc:`/guides/pagehandler`. When the handler is called, the segments array is passed in as the first argument." msgstr "" #: ../../guides/routing.rst:29 msgid "The following code registers a page handler for \"blog\" URLs and shows how one might route the request to a resource view." msgstr "" #: ../../guides/routing.rst:56 msgid "The ``route`` Plugin Hook" msgstr "" #: ../../guides/routing.rst:58 msgid "The ``route`` plugin hook is triggered earlier, before page handlers are called. The URL identifier is given as the type of the hook. This hook can be used to modify the identifier or segments, to take over page rendering completely, or just to add some logic before the request is handled elsewhere." msgstr "" #: ../../guides/routing.rst:63 msgid "Generally devs should use a page handler unless they need to affect a single page or a wider variety of URLs." msgstr "" #: ../../guides/routing.rst:65 msgid "The following code intercepts requests to the page handler for ``customblog`` and internally redirects them to the ``blog`` page handler." msgstr "" #: ../../guides/routing.rst:78 msgid "The following code results in ``/blog/all`` requests being completely handled by the plugin hook handler. For these requests the ``blog`` page handler is never called." msgstr "" #: ../../guides/routing.rst:103 msgid "Routing overview" msgstr "" #: ../../guides/routing.rst:105 msgid "For regular pages, Elgg's program flow is something like this:" msgstr "" #: ../../guides/routing.rst:107 msgid "A user requests ``http://example.com/blog/owner/jane``." msgstr "" #: ../../guides/routing.rst:108 msgid "Plugins are initialized." msgstr "" #: ../../guides/routing.rst:109 msgid "Elgg parses the URL to identifier ``blog`` and segments ``['owner', 'jane']``." msgstr "" #: ../../guides/routing.rst:110 msgid "Elgg triggers the plugin hook ``route, blog`` (see above)." msgstr "" #: ../../guides/routing.rst:111 msgid "Elgg finds a registered page handler (see above) for ``blog``, and calls the function, passing in the segments." msgstr "" #: ../../guides/routing.rst:113 msgid "The page handler function determines it needs to render a single user's blog. It stores the username via ``set_input()`` and calls the view ``resources/blog/owner``." msgstr "" #: ../../guides/routing.rst:115 msgid "The ``resources/blog/owner`` view gets the username via ``get_input()``, and uses many other views and formatting functions like ``elgg_view_layout()`` and ``elgg_view_page()`` to create the entire HTML page." msgstr "" #: ../../guides/routing.rst:117 msgid "The page handler echos the view HTML and returns ``true`` to indicate it handled the request." msgstr "" #: ../../guides/routing.rst:118 msgid "PHP invokes Elgg's shutdown sequence." msgstr "" #: ../../guides/routing.rst:119 msgid "The user receives a fully rendered page." msgstr "" #: ../../guides/routing.rst:121 msgid "Elgg's coding standards suggest a particular URL layout, but there is no syntax enforced." msgstr "" #: ../../guides/settings.rst:2 msgid "Plugin settings" msgstr "" #: ../../guides/settings.rst:4 msgid "You need to perform some extra steps if your plugin needs settings to be saved and controlled via the administration panel:" msgstr "" #: ../../guides/settings.rst:6 msgid "Create a file in your plugin’s default view folder called ``plugins/your_plugin/settings.php``, where ``your_plugin`` is the name of your plugin’s directory in the ``mod`` hierarchy" msgstr "" #: ../../guides/settings.rst:7 msgid "Fill this file with the form elements you want to display together with :doc:`internationalised <i18n>` text labels" msgstr "" #: ../../guides/settings.rst:8 msgid "Set the name attribute in your form components to ``param[`varname`]`` where ``varname`` is the name of the variable. These will be saved as private settings attached to a plugin entity. So, if your variable is called ``param[myparameter]`` your plugin (which is also passed to this view as ``$vars['entity']``) will be called ``$vars['entity']->myparameter``" msgstr "" #: ../../guides/settings.rst:10 msgid "An example ``settings.php`` would look like:" msgstr "" #: ../../guides/settings.rst:27 msgid "You don’t need to add a save button or the form, this will be handled by the framework." msgstr "" #: ../../guides/settings.rst:31 msgid "You cannot use form components that send no value when \"off.\" These include radio inputs and check boxes." msgstr "" #: ../../guides/settings.rst:34 msgid "User settings" msgstr "" #: ../../guides/settings.rst:36 msgid "Your plugin might need to store per user settings too, and you would like to have your plugin's options to appear in the user's settings page. This is also easy to do and follows the same pattern as setting up the global plugin configuration explained earlier. The only difference is that instead of using a ``settings`` file you will use ``usersettings``. So, the path to the user edit view for your plugin would be ``plugins/your_plugin/usersettings.php``." msgstr "" #: ../../guides/settings.rst:40 msgid "The title of the usersettings form will default to the plugin name. If you want to change this, add a translation for ``plugin_id:usersettings:title``." msgstr "" #: ../../guides/settings.rst:43 msgid "Retrieving settings in your code" msgstr "" #: ../../guides/settings.rst:45 msgid "To retrieve settings from your code use:" msgstr "" #: ../../guides/settings.rst:51 msgid "or for user settings" msgstr "" #: ../../guides/settings.rst:57 msgid "where:" msgstr "" #: ../../guides/settings.rst:59 msgid "``$name`` Is the value you want to retrieve" msgstr "" #: ../../guides/settings.rst:60 msgid "``$user_guid`` Is the user you want to retrieve these for (defaults to the currently logged in user)" msgstr "" #: ../../guides/settings.rst:61 msgid "``$plugin_name`` Is the name of the plugin (detected if run from within a plugin)" msgstr "" #: ../../guides/settings.rst:64 msgid "Setting values while in code" msgstr "" #: ../../guides/settings.rst:66 msgid "Values may also be set from within your plugin code, to do this use one of the following functions:" msgstr "" #: ../../guides/settings.rst:72 msgid "or" msgstr "" #: ../../guides/settings.rst:80 msgid "The ``$plugin_id`` needs to be provided when setting plugin (user)settings." msgstr "" #: ../../guides/themes.rst:2 msgid "Themes" msgstr "" #: ../../guides/themes.rst:4 msgid "Customize the look and feel of Elgg." msgstr "" #: ../../guides/themes.rst:6 msgid "A theme is a type of :doc:`plugin </admin/plugins>` that overrides display aspects of Elgg." msgstr "" #: ../../guides/themes.rst:10 msgid "This guide assumes you are familiar with:" msgstr "" #: ../../guides/themes.rst:17 msgid "Create your plugin" msgstr "" #: ../../guides/themes.rst:19 msgid "Create your plugin as described in the :doc:`developer guide </guides/index>`." msgstr "" #: ../../guides/themes.rst:21 msgid "Create a new directory under mod/" msgstr "" #: ../../guides/themes.rst:22 msgid "Create a new start.php" msgstr "" #: ../../guides/themes.rst:23 msgid "Create a manifest.xml file describing your theme." msgstr "" #: ../../guides/themes.rst:26 msgid "Customize the CSS" msgstr "" #: ../../guides/themes.rst:28 msgid "As of Elgg 1.8, the css is split into several files based on what aspects of the site you're theming. This allows you to tackle them one at a time, giving you a chance to make real progress without getting overwhelmed." msgstr "" #: ../../guides/themes.rst:33 msgid "Here is a list of the existing CSS views:" msgstr "" #: ../../guides/themes.rst:35 msgid "css/elements/buttons: Provides a way to style all the different kinds of buttons your site will use. There are 5 kinds of buttons that plugins will expect to be available: action, cancel, delete, submit, and special." msgstr "" #: ../../guides/themes.rst:36 msgid "css/elements/chrome: This file has some miscellaneous look-and-feel classes." msgstr "" #: ../../guides/themes.rst:37 msgid "css/elements/components: This file contains many “css objects” that are used all over the site: media block, list, gallery, table, owner block, system messages, river, tags, photo, and comments." msgstr "" #: ../../guides/themes.rst:38 msgid "css/elements/forms: This file determines what your forms and input elements will look like." msgstr "" #: ../../guides/themes.rst:39 msgid "css/elements/icons: Contains styles for the sprite icons and avatars used on your site." msgstr "" #: ../../guides/themes.rst:40 msgid "css/elements/layout: Determines what your page layout will look like: sidebars, page wrapper, main body, header, footer, etc." msgstr "" #: ../../guides/themes.rst:41 msgid "css/elements/modules: Lots of content in Elgg is displayed in boxes with a title and a content body. We called these modules. There are a few kinds: info, aside, featured, dropdown, popup, widget. Widget styles are included in this file too, since they are a subset of modules." msgstr "" #: ../../guides/themes.rst:42 msgid "css/elements/navigation: This file determines what all your menus will look like." msgstr "" #: ../../guides/themes.rst:43 msgid "css/elements/typography: This file determines what the content and headings of your site will look like." msgstr "" #: ../../guides/themes.rst:44 msgid "css/rtl: Custom rules for users viewing your site in a right-to-left language." msgstr "" #: ../../guides/themes.rst:45 msgid "css/admin: A completely separate theme for the admin area (usually not overridden)." msgstr "" #: ../../guides/themes.rst:46 msgid "css/elgg: Compiles all the core css/elements/\\* files into one file (DO NOT OVERRIDE)." msgstr "" #: ../../guides/themes.rst:47 msgid "css/elements/core: Contains base styles for the more complicated “css objects”. If you find yourself wanting to override this, you probably need to report a bug to Elgg core instead (DO NOT OVERRIDE)." msgstr "" #: ../../guides/themes.rst:48 msgid "css/elements/reset: Contains a reset stylesheet that forces elements to have the same default" msgstr "" #: ../../guides/themes.rst:52 msgid "View extension" msgstr "" #: ../../guides/themes.rst:54 msgid "There are two ways you can modify views:" msgstr "" #: ../../guides/themes.rst:56 msgid "The first way is to add extra stuff to an existing view via the extend view function from within your start.php’s initialization function." msgstr "" #: ../../guides/themes.rst:59 msgid "For example, the following start.php will add mytheme/css to Elgg's core css file:" msgstr "" #: ../../guides/themes.rst:74 msgid "View overloading" msgstr "" #: ../../guides/themes.rst:76 msgid "Plugins can have a view hierarchy, any file that exists here will replace any files in the existing core view hierarchy... so for example, if my plugin has a file:" msgstr "" #: ../../guides/themes.rst:80 msgid "``/mod/myplugin/views/default/css/elements/typography.php``" msgstr "" #: ../../guides/themes.rst:82 msgid "it will replace:" msgstr "" #: ../../guides/themes.rst:84 msgid "``/views/default/css/elements/typography.php``" msgstr "" #: ../../guides/themes.rst:86 msgid "But only when the plugin is active." msgstr "" #: ../../guides/themes.rst:88 msgid "This gives you total control over the way Elgg looks and behaves. It gives you the option to either slightly modify or totally replace existing views." msgstr "" #: ../../guides/themes.rst:93 msgid "Tools" msgstr "" #: ../../guides/themes.rst:95 msgid "Starting in Elgg 1.8, we've provided you with some development tools to help you with theming: Turn on the “Developers” plugin and go to the “Theme Preview” page to start tracking your theme's progress." msgstr "" #: ../../guides/themes.rst:100 msgid "Customizing the front page" msgstr "" #: ../../guides/themes.rst:101 msgid "The main Elgg index page runs a plugin hook called 'index,system'. If this returns true, it assumes that another front page has been drawn and doesn't display the default page." msgstr "" #: ../../guides/themes.rst:105 msgid "Therefore, you can override it by registering a function to the 'index,system' plugin hook and then returning true from that function." msgstr "" #: ../../guides/themes.rst:108 msgid "Here's a quick overview:" msgstr "" #: ../../guides/themes.rst:110 msgid "Create your new plugin" msgstr "" #: ../../guides/themes.rst:112 msgid "In the start.php you will need something like the following:" msgstr "" #: ../../guides/themes.rst:134 msgid "Then, create an index page (/pluginname/pages/index.php) and use that to put the content you would like on the front page of your Elgg site." msgstr "" #: ../../guides/upgrading.rst:2 msgid "Upgrading Plugins" msgstr "" #: ../../guides/upgrading.rst:4 msgid "Prepare your plugin for the next version of Elgg." msgstr "" #: ../../guides/upgrading.rst:6 msgid "See the administator guides for :doc:`how to upgrade a live site </admin/upgrading>`." msgstr "" #: ../../guides/upgrading.rst:13 msgid "From 1.10 to 1.11" msgstr "" #: ../../guides/upgrading.rst:16 msgid "Comment highlighting" msgstr "" #: ../../guides/upgrading.rst:18 msgid "If your theme is using the file ``views/default/css/elements/components.php``, you must add the following style definitions in it to enable highlighting for comments and discussion replies:" msgstr "" #: ../../guides/upgrading.rst:36 msgid "From 1.9 to 1.10" msgstr "" #: ../../guides/upgrading.rst:39 msgid "File uploads" msgstr "" #: ../../guides/upgrading.rst:41 msgid "If your plugin is using a snippet copied from the ``file/upload`` action to fix detected mime types for Microsoft zipped formats, it can now be safely removed." msgstr "" #: ../../guides/upgrading.rst:43 msgid "If your upload action performs other manipulations on detected mime and simple types, it is recommended to make use of available plugin hooks:" msgstr "" #: ../../guides/upgrading.rst:45 msgid "``'mime_type','file'`` for filtering detected mime types" msgstr "" #: ../../guides/upgrading.rst:46 msgid "``'simple_type','file'`` for filtering parsed simple types" msgstr "" #: ../../guides/upgrading.rst:49 msgid "From 1.8 to 1.9" msgstr "" #: ../../guides/upgrading.rst:51 msgid "In the examples we are upgrading an imaginary \"Photos\" plugin." msgstr "" #: ../../guides/upgrading.rst:53 msgid "Only the key changes are included. For example some of the deprecated functions are not mentioned here separately." msgstr "" #: ../../guides/upgrading.rst:55 msgid "Each section will include information whether the change is backwards compatible with Elgg 1.8." msgstr "" #: ../../guides/upgrading.rst:58 msgid "The manifest file" msgstr "" #: ../../guides/upgrading.rst:60 msgid "No changes are needed if your plugin is compatible with 1.8." msgstr "" #: ../../guides/upgrading.rst:62 msgid "It's however recommended to add the ``<id>`` tag. It's value should be the name of the directory where the plugin is located inside the ``mod/`` directory." msgstr "" #: ../../guides/upgrading.rst:64 msgid "If you make changes that break BC, you must update the plugin version and the required Elgg release." msgstr "" #: ../../guides/upgrading.rst:66 msgid "Example of (shortened) old version:" msgstr "" #: ../../guides/upgrading.rst:82 msgid "Example of (shortened) new version:" msgstr "" #: ../../guides/upgrading.rst:100 msgid "$CONFIG and $vars['config']" msgstr "" #: ../../guides/upgrading.rst:102 msgid "Both the global ``$CONFIG`` variable and the ``$vars['config']`` parameter have been deprecated. They should be replaced with the ``elgg_get_config()`` function." msgstr "" #: ../../guides/upgrading.rst:104 msgid "Example of old code:" msgstr "" #: ../../guides/upgrading.rst:115 msgid "Example of new code:" msgstr "" #: ../../guides/upgrading.rst:123 #: ../../guides/upgrading.rst:312 msgid "Compatible with 1.8" msgstr "" #: ../../guides/upgrading.rst:127 msgid "See how the community_plugins plugin was updated: https://github.com/Elgg/community_plugins/commit/f233999bbd1478a200ee783679c2e2897c9a0483" msgstr "" #: ../../guides/upgrading.rst:130 msgid "Language files" msgstr "" #: ../../guides/upgrading.rst:132 msgid "In Elgg 1.8 the language files needed to use the ``add_translation()`` function. In 1.9 it is enough to just return the array that was previously passed to the function as a parameter. Elgg core will use the file name (e.g. en.php) to tell which language the file contains." msgstr "" #: ../../guides/upgrading.rst:135 msgid "Example of the old way in ``languages/en.php``:" msgstr "" #: ../../guides/upgrading.rst:144 msgid "Example of new way:" msgstr "" #: ../../guides/upgrading.rst:154 #: ../../guides/upgrading.rst:244 #: ../../guides/upgrading.rst:340 #: ../../guides/upgrading.rst:402 msgid "Not compatible with 1.8" msgstr "" #: ../../guides/upgrading.rst:159 msgid "One of the biggest changes in Elgg 1.9 is the notifications system. The new system allows more flexible and scalable way of sending notifications." msgstr "" #: ../../guides/upgrading.rst:161 #: ../../guides/upgrading.rst:262 #: ../../guides/upgrading.rst:347 msgid "Example of the old way:" msgstr "" #: ../../guides/upgrading.rst:200 #: ../../guides/upgrading.rst:282 #: ../../guides/upgrading.rst:368 msgid "Example of the new way:" msgstr "" #: ../../guides/upgrading.rst:248 msgid "See how the community_plugins plugin was updated to use the new system: https://github.com/Elgg/community_plugins/commit/bfa356cfe8fb99ebbca4109a1b8a1383b70ff123" msgstr "" #: ../../guides/upgrading.rst:250 msgid "Notifications can also be sent with the ``notify_user()`` function." msgstr "" #: ../../guides/upgrading.rst:252 msgid "It has however been updated to support three new optional parameters passed inside an array as the fifth parameter." msgstr "" #: ../../guides/upgrading.rst:254 msgid "The parameters give notification plugins more control over the notifications, so they should be included whenever possible. For example the bundled site_notifications plugin won't work properly if the parameters are missing." msgstr "" #: ../../guides/upgrading.rst:256 msgid "Parameters:" msgstr "" #: ../../guides/upgrading.rst:258 msgid "**object** The object that we are notifying about (e.g. ElggEntity or ElggAnnotation). This is needed so that notification plugins can provide a link to the object." msgstr "" #: ../../guides/upgrading.rst:259 msgid "**action** String that describes the action that triggered the notification (e.g. \"create\", \"update\", etc)." msgstr "" #: ../../guides/upgrading.rst:260 msgid "**summary** String that contains a summary of the notification. (It should be more informative than the notification subject but less informative than the notification body.)" msgstr "" #: ../../guides/upgrading.rst:315 msgid "Adding items to the Activity listing" msgstr "" #: ../../guides/upgrading.rst:330 msgid "You can also add the optional ``target_guid`` parameter which tells the target of the create action." msgstr "" #: ../../guides/upgrading.rst:332 msgid "If the photo would had been added for example into a photo album, we could add it by passing in also:" msgstr "" #: ../../guides/upgrading.rst:343 msgid "Entity URL handlers" msgstr "" #: ../../guides/upgrading.rst:345 msgid "The ``elgg_register_entity_url_handler()`` function has been deprecated. In 1.9 you should use the ``'entity:url', 'object'`` plugin hook instead." msgstr "" #: ../../guides/upgrading.rst:405 #: ../../guides/web-services.rst:2 msgid "Web services" msgstr "" #: ../../guides/upgrading.rst:407 msgid "In Elgg 1.8 the web services API was included in core and methods were exposed using ``expose_function()``. To enable the same functionality for Elgg 1.9, enable the \"Web services 1.9\" plugin and replace all calls to ``expose_function()`` with ``elgg_ws_expose_function()``." msgstr "" #: ../../guides/upgrading.rst:413 msgid "From 1.7 to 1.8" msgstr "" #: ../../guides/upgrading.rst:414 msgid "Elgg 1.8 is the biggest leap forward in the development of Elgg since version 1.0. As such, there is more work to update core and plugins than with previous upgrades. There were a small number of API changes and following our standard practice, the methods we deprecated have been updated to work with the new API. The biggest changes are in the standardization of plugins and in the views system." msgstr "" #: ../../guides/upgrading.rst:422 msgid "Updating core" msgstr "" #: ../../guides/upgrading.rst:423 msgid "Delete the following core directories (same level as _graphics and engine):" msgstr "" #: ../../guides/upgrading.rst:425 msgid "_css" msgstr "" #: ../../guides/upgrading.rst:426 msgid "account" msgstr "" #: ../../guides/upgrading.rst:427 msgid "admin" msgstr "" #: ../../guides/upgrading.rst:428 msgid "dashboard" msgstr "" #: ../../guides/upgrading.rst:429 msgid "entities" msgstr "" #: ../../guides/upgrading.rst:430 msgid "friends" msgstr "" #: ../../guides/upgrading.rst:431 msgid "search" msgstr "" #: ../../guides/upgrading.rst:432 msgid "settings" msgstr "" #: ../../guides/upgrading.rst:433 msgid "simplecache" msgstr "" #: ../../guides/upgrading.rst:434 msgid "views" msgstr "" #: ../../guides/upgrading.rst:438 msgid "If you do not delete these directories before an upgrade, you will have problems!" msgstr "" #: ../../guides/upgrading.rst:442 msgid "Updating plugins" msgstr "" #: ../../guides/upgrading.rst:446 msgid "All: /page_handler/all" msgstr "" #: ../../guides/upgrading.rst:447 msgid "User’s content: /page_handler/owner/:username" msgstr "" #: ../../guides/upgrading.rst:448 msgid "User’s friends' content: /page_handler/friends/:username" msgstr "" #: ../../guides/upgrading.rst:449 msgid "Single entity: /page_handler/view/:guid/:title" msgstr "" #: ../../guides/upgrading.rst:450 msgid "Added: /page_handler/add/:container_guid" msgstr "" #: ../../guides/upgrading.rst:451 msgid "Editing: /page_handler/edit/:guid" msgstr "" #: ../../guides/upgrading.rst:452 msgid "Group list: /page_handler/group/:guid/all" msgstr "" #: ../../guides/upgrading.rst:456 msgid "Include page handler scripts from the page handler" msgstr "" #: ../../guides/upgrading.rst:457 msgid "Almost every page handler should have a page handler script. (Example: ``bookmarks/all => mod/bookmarks/pages/bookmarks/all.php``)" msgstr "" #: ../../guides/upgrading.rst:461 msgid "Call ``gatekeeper()`` and ``admin_gatekeeper()`` in the page handler function if required." msgstr "" #: ../../guides/upgrading.rst:462 msgid "The group URL should use the ``pages/:handler/owner.php`` script." msgstr "" #: ../../guides/upgrading.rst:464 msgid "Update the URLs throughout the plugin. (Don't forget to remove ``/pg/``!)" msgstr "" #: ../../guides/upgrading.rst:469 msgid "Store page handler scripts in ``mod/:plugin/pages/:page_handler/:page_name.php``" msgstr "" #: ../../guides/upgrading.rst:470 msgid "Use the content page layout in page handler scripts:" msgstr "" #: ../../guides/upgrading.rst:476 msgid "Page handler scripts should not contain HTML." msgstr "" #: ../../guides/upgrading.rst:478 msgid "No need to set page owner if the URLs are in the standardized format." msgstr "" #: ../../guides/upgrading.rst:479 msgid "For group content, check the container_guid by using elgg_get_page_owner_entity()." msgstr "" #: ../../guides/upgrading.rst:483 msgid "The ``object/:subtype`` view" msgstr "" #: ../../guides/upgrading.rst:484 msgid "Make sure there are views for ``$vars['full_view'] == true`` and ``$vars['full_view'] == false``. ``$vars['full_view']`` replaced ``$vars['full]``." msgstr "" #: ../../guides/upgrading.rst:485 msgid "Check for the object in ``$vars['entity']``. Use ``elgg_instance_of()`` to make sure it's the type of entity you want." msgstr "" #: ../../guides/upgrading.rst:486 msgid "Return ``true`` to short circuit the view if the entity is missing or wrong." msgstr "" #: ../../guides/upgrading.rst:487 msgid "Use ``elgg_view(‘object/elements/summary’, array(‘entity’ => $entity));`` and ``elgg_view_menu(‘entity’, array(‘entity’ => $entity));`` to help format. You should use very little markup in these views." msgstr "" #: ../../guides/upgrading.rst:491 msgid "Update action structure" msgstr "" #: ../../guides/upgrading.rst:495 msgid "Add: ``action/:plugin/save``" msgstr "" #: ../../guides/upgrading.rst:496 msgid "Edit: ``action/:plugin/save``" msgstr "" #: ../../guides/upgrading.rst:497 msgid "Delete: ``action/:plugin/delete``" msgstr "" #: ../../guides/upgrading.rst:499 msgid "Make the delete action accept ``action/:handler/delete?guid=:guid`` so the metadata entity menu has the correct URL by default." msgstr "" #: ../../guides/upgrading.rst:503 msgid "Update deprecated functions" msgstr "" #: ../../guides/upgrading.rst:504 msgid "Functions deprecated in 1.7 will produce visible errors in 1.8." msgstr "" #: ../../guides/upgrading.rst:506 msgid "See ``/engine/lib/deprecated-1.7.php`` for the full list." msgstr "" #: ../../guides/upgrading.rst:508 msgid "You can also update functions deprecated in 1.8." msgstr "" #: ../../guides/upgrading.rst:510 msgid "Many registration functions simply added an ``elgg_`` prefix for consistency, and should be easy to update." msgstr "" #: ../../guides/upgrading.rst:511 msgid "See ``/engine/lib/deprecated-1.8.php`` for the full list." msgstr "" #: ../../guides/upgrading.rst:512 msgid "You can set the debug level to “warning” to get visual reminders of deprecated functions." msgstr "" #: ../../guides/upgrading.rst:516 msgid "Update the widget views" msgstr "" #: ../../guides/upgrading.rst:517 msgid "See the blog or file widgets for examples." msgstr "" #: ../../guides/upgrading.rst:521 msgid "Update the group profile module" msgstr "" #: ../../guides/upgrading.rst:522 msgid "Use the blog or file plugins for examples. This will help with making your plugin themeable by the new CSS framework." msgstr "" #: ../../guides/upgrading.rst:526 msgid "Update forms" msgstr "" #: ../../guides/upgrading.rst:527 msgid "Move form bodies to the ``forms/:action`` view to use Evan's new ``elgg_view_form``." msgstr "" #: ../../guides/upgrading.rst:528 msgid "Use input views in form bodies rather than html. This helps with theming and future-proofing." msgstr "" #: ../../guides/upgrading.rst:529 msgid "Add a function that prepares the form (see ``mod/file/lib/file.php`` for an example)" msgstr "" #: ../../guides/upgrading.rst:530 msgid "Make your forms sticky (see the file plugin's upload action and form prepare function)." msgstr "" #: ../../guides/upgrading.rst:532 msgid "The forms API is discussed in more detail in :doc:`/guides/actions`." msgstr "" #: ../../guides/upgrading.rst:537 msgid "We have added many CSS patterns to the base CSS file (modules, image block, spacing primitives). We encourage you to use these patterns and classes wherever possible. Doing so should:" msgstr "" #: ../../guides/upgrading.rst:539 msgid "Reduce maintenance costs, since you can delete most custom CSS." msgstr "" #: ../../guides/upgrading.rst:540 msgid "Make your plugin more compatible with community themes." msgstr "" #: ../../guides/upgrading.rst:542 msgid "Look for patterns that can be moved into core if you need significant CSS." msgstr "" #: ../../guides/upgrading.rst:544 msgid "We use hyphens rather than underscores in classes/ids and encourage you do the same for consistency." msgstr "" #: ../../guides/upgrading.rst:546 msgid "If you do need your own CSS, you should use your own namespace, rather than ``elgg-``." msgstr "" #: ../../guides/upgrading.rst:550 msgid "Update manifest.xml" msgstr "" #: ../../guides/upgrading.rst:551 msgid "Use http://el.gg/manifest17to18 to automate this." msgstr "" #: ../../guides/upgrading.rst:552 msgid "Don't use the \"bundled\" category with your plugins. That is only for plugins distributed with Elgg." msgstr "" #: ../../guides/upgrading.rst:556 msgid "Update settings and user settings views" msgstr "" #: ../../guides/upgrading.rst:557 msgid "The view for settings is now ``plugins/:plugin/settings`` (previously ``settings/:plugin/edit``)." msgstr "" #: ../../guides/upgrading.rst:558 msgid "The view for user settings is now ``plugins/:plugin/usersettings`` (previously ``usersettings/:plugin/edit``)." msgstr "" #: ../../guides/views.rst:9 msgid "Introduction" msgstr "" #: ../../guides/views.rst:11 msgid "Elgg follows a MVC pattern and Views are the V in MVC. Views are responsible for creating the output. Generally, this will be HTML sent to a web browser, but it could also be RSS, JSON or any number of other data formats." msgstr "" #: ../../guides/views.rst:13 msgid "The Views system handles everything from the layout of pages and chunks of presentation output (like a footer or a toolbar) down to individual links and form inputs. It also allows for advanced features like automatic RSS generation, a swift-to-develop mobile interface, and the alternative interfaces suggested below." msgstr "" #: ../../guides/views.rst:16 msgid "Using views" msgstr "" #: ../../guides/views.rst:18 msgid "At their most basic level, the default views are just PHP files with snippets of html. For example:" msgstr "" #: ../../guides/views.rst:24 msgid "Assuming this view is located at ``/views/default/hello.php``, we could output it like so:" msgstr "" #: ../../guides/views.rst:30 msgid "For your convenience, Elgg comes with quite a lot of views by default. In order to keep things manageable, they are organized into subdirectories. Elgg handles this situation quite nicely. For example, our simple view might live in ``/views/default/hello/world.php``, in which case it would be called like so:" msgstr "" #: ../../guides/views.rst:36 msgid "Well that's easy enough to remember! The name of the view simply reflects the location of the view in the views directory." msgstr "" #: ../../guides/views.rst:39 msgid "Views as templates" msgstr "" #: ../../guides/views.rst:41 msgid "Views would be pretty useless if they could only contain static information. Fortunately, you can pass arbitrary data to a view via the ``$vars`` array. Our ``hello/world`` view might be modified to accept a variable like so:" msgstr "" #: ../../guides/views.rst:47 msgid "In this case, we can pass an arbitrary name parameter to the view like so:" msgstr "" #: ../../guides/views.rst:53 msgid "which would produce the following output:" msgstr "" #: ../../guides/views.rst:62 msgid "Viewtypes" msgstr "" #: ../../guides/views.rst:64 msgid "You might be wondering, \"what's with the 'default' in the directory structure? Why don't we just put the ``hello/world`` view at ``/views/hello/world.php``?\"." msgstr "" #: ../../guides/views.rst:66 msgid "Great question." msgstr "" #: ../../guides/views.rst:68 msgid "This subdirectory (the one under ``/views``) determines the *viewtype* of the views below it. It's possible that you might want your Elgg site to have several sets of interface pages. For example:" msgstr "" #: ../../guides/views.rst:70 msgid "Standard HTML for desktop browsing (This is the default view)" msgstr "" #: ../../guides/views.rst:71 msgid "HTML optimized for Mobile devices (iPhone, Android, Blackberry, etc.)" msgstr "" #: ../../guides/views.rst:72 msgid "HTML optimized Tablet devices (iPad, etc.)" msgstr "" #: ../../guides/views.rst:73 msgid "RSS" msgstr "" #: ../../guides/views.rst:74 msgid "Atom" msgstr "" #: ../../guides/views.rst:75 msgid "JSON" msgstr "" #: ../../guides/views.rst:76 msgid "etc..." msgstr "" #: ../../guides/views.rst:78 msgid "In Elgg, one set of these interface pages is called a *viewtype*. You can force Elgg to use a particular viewtype to render the page simply by setting the ``$view`` input variable. For example, to get an RSS version of the home page, you would access ``http://localhost/elgg/?view=rss``." msgstr "" #: ../../guides/views.rst:80 msgid "You could also write a plugin to set this automatically using the ``set_input()`` function. For example, your plugin might detect that the page was accessed with an iPhone's browser string, and set the viewtype to *handheld* by calling:" msgstr "" #: ../../guides/views.rst:86 msgid "The plugin would presumably also supply a set of views optimized for handheld devices." msgstr "" #: ../../guides/views.rst:91 msgid "Altering views via plugins" msgstr "" #: ../../guides/views.rst:93 msgid "Without modifying Elgg's core, Elgg provides several ways to customize almost all output:" msgstr "" #: ../../guides/views.rst:95 msgid "You can `override a view <#overriding-views>`_, completely changing the file used to render it." msgstr "" #: ../../guides/views.rst:96 msgid "You can `extend a view <#extending-views>`_ by prepending or appending the output of another view to it." msgstr "" #: ../../guides/views.rst:97 msgid "You can `alter a view's inputs <#altering-view-input>`_ by plugin hook." msgstr "" #: ../../guides/views.rst:98 msgid "You can `alter a view's output <#altering-view-output>`_ by plugin hook." msgstr "" #: ../../guides/views.rst:101 msgid "Overriding views" msgstr "" #: ../../guides/views.rst:103 msgid "Via plugin you can completely replace the rendering strategy of a view provided by Elgg or another plugin. Each plugin may have its own ``/views`` directory, and within it define its own view implementations." msgstr "" #: ../../guides/views.rst:105 msgid "Views in plugin directories always override views in the core directory, however, when plugins override the views of other plugins, :ref:`later plugins take precedent <admin/plugins#plugin-order>`." msgstr "" #: ../../guides/views.rst:107 msgid "For example, if we wanted to customize the ``hello/world`` view to use an ``h2`` instead of an ``h1``, we could create a file at ``/mod/example/views/default/hello/world.php`` like this:" msgstr "" #: ../../guides/views.rst:113 msgid "While it is **not recommended**, one *could* alternatively force the location of a view using the ``set_view_location`` function:" msgstr "" #: ../../guides/views.rst:119 msgid "Again, the best way to override views is to place them in the appropriate place in the views hierarchy." msgstr "" #: ../../guides/views.rst:123 msgid "When considering long-term maintenance, overriding views in the core and bundled plugins has a cost: Upgrades may bring changes in views, and if you have overridden them, you will not get those changes. You may instead want to :ref:`alter the input <guides/views#altering-view-input>` or the :ref:`the output <guides/views#altering-view-output>` of the view via plugin hooks." msgstr "" #: ../../guides/views.rst:127 msgid "Elgg caches view locations. This means that you should disable the system cache while working with views. When you install the changes to a production environment you mush flush the caches." msgstr "" #: ../../guides/views.rst:130 msgid "Extending views" msgstr "" #: ../../guides/views.rst:132 msgid "There may be other situations in which you don't want to override the whole view, you just want to prepend or append some more content to it. In Elgg this is called *extending* a view." msgstr "" #: ../../guides/views.rst:134 msgid "For example, instead of overriding the ``hello/world`` view, we could extend it like so:" msgstr "" #: ../../guides/views.rst:140 msgid "If the contents of ``/views/default/hello/greeting.php`` is:" msgstr "" #: ../../guides/views.rst:146 msgid "Then every time we call ``elgg_view('hello/world');``, we'll get:" msgstr "" #: ../../guides/views.rst:153 msgid "You can prepend views by passing a value to the 3rd parameter that is less than 500:" msgstr "" #: ../../guides/views.rst:163 msgid "Note that if you extend the core css view like this:" msgstr "" #: ../../guides/views.rst:169 msgid "You **must** do so within code that is executed by engine/start.php (normally this would mean your plugin's init code). Because the core css view is loaded separately via a ``<link>`` tag, any extensions you add will not have the same context as the rest of your page." msgstr "" #: ../../guides/views.rst:174 msgid "Altering view input" msgstr "" #: ../../guides/views.rst:176 msgid "It may be useful to alter a view's ``$vars`` array before it's rendered." msgstr "" #: ../../guides/views.rst:178 msgid "Since 1.11, before each view rendering the ``$vars`` array is filtered by the :ref:`plugin hook <guides/hooks-list#views>` ``[view_vars, view_name]``. Each registered handler function is passed these arguments:" msgstr "" #: ../../guides/views.rst:180 msgid "``$hook`` - the string ``\"view_vars\"``" msgstr "" #: ../../guides/views.rst:181 #: ../../guides/views.rst:211 msgid "``$type`` - the view name being rendered (the first argument passed to ``elgg_view()``)" msgstr "" #: ../../guides/views.rst:182 msgid "``$returnvalue`` - the ``$vars`` array" msgstr "" #: ../../guides/views.rst:183 msgid "``$params`` - an array containing: the unaltered ``$vars`` under the key ``vars``; :ref:`viewtype <guides/views#viewtypes>` being rendered under the key ``viewtype``; the view name under the key ``view``." msgstr "" #: ../../guides/views.rst:186 msgid "Altering view input example" msgstr "" #: ../../guides/views.rst:188 msgid "Here we'll alter the default pagination limit for the comments view:" msgstr "" #: ../../guides/views.rst:204 msgid "Altering view output" msgstr "" #: ../../guides/views.rst:206 msgid "Sometimes it is preferable to alter the output of a view instead of overriding it." msgstr "" #: ../../guides/views.rst:208 msgid "The output of each view is run through the :ref:`plugin hook <guides/hooks-list#views>` ``[view, view_name]`` before being returned by ``elgg_view()``. Each registered handler function is passed these arguments:" msgstr "" #: ../../guides/views.rst:210 msgid "``$hook`` - the string ``\"view\"``" msgstr "" #: ../../guides/views.rst:212 msgid "``$returnvalue`` - the rendered output of the view (or the return value of the last handler)" msgstr "" #: ../../guides/views.rst:213 msgid "``$params`` - an array containing the key ``viewtype`` with value being the :ref:`viewtype <guides/views#viewtypes>` being rendered" msgstr "" #: ../../guides/views.rst:215 msgid "To alter the view output, the handler just needs to alter ``$returnvalue`` and return a new string." msgstr "" #: ../../guides/views.rst:218 msgid "Altering view output example" msgstr "" #: ../../guides/views.rst:220 msgid "Here we'll eliminate breadcrumbs that don't have at least one link." msgstr "" #: ../../guides/views.rst:241 msgid "If you don't know what an entity is, :doc:`check this page out first </design/database>`." msgstr "" #: ../../guides/views.rst:243 msgid "The following code will automatically display the entity in ``$entity``:" msgstr "" #: ../../guides/views.rst:249 msgid "As you'll know from the data model introduction, all entities have a *type* (object, site, user or group), and optionally a subtype (which could be anything - 'blog', 'forumpost', 'banana'). ``elgg_view_entity`` will automatically look for a view called ``type/subtype``; if there's no subtype, it will look for ``type/type``. Failing that, before it gives up completely it tries ``type/default``. (RSS feeds in Elgg generally work by outputting the ``object/default`` view in the 'rss' viewtype.)" msgstr "" #: ../../guides/views.rst:251 msgid "So for example, the view to display a blogpost might be ``object/blog``. The view to display a user is ``user/user``." msgstr "" #: ../../guides/views.rst:254 msgid "Full and partial entity views" msgstr "" #: ../../guides/views.rst:256 msgid "``elgg_view_entity`` actually has a number of parameters, although only the very first one is required. The first three are:" msgstr "" #: ../../guides/views.rst:258 msgid "``$entity`` - The entity to display" msgstr "" #: ../../guides/views.rst:259 msgid "``$viewtype`` - The viewtype to display in (defaults to the one we're currently in, but it can be forced - eg to display a snippet of RSS within an HTML page)" msgstr "" #: ../../guides/views.rst:260 msgid "``$full_view`` - Whether to display a *full* version of the entity. (Defaults to false.)" msgstr "" #: ../../guides/views.rst:262 msgid "This last parameter is passed to the view as ``$vars['full_view']``. It's up to you what you do with it; the usual behaviour is to only display comments and similar information if this is set to true." msgstr "" #: ../../guides/views.rst:267 msgid "Listing entities" msgstr "" #: ../../guides/views.rst:269 msgid "This is then used in the provided listing functions. To automatically display a list of blog posts (:doc:`see the full tutorial </tutorials/blog>`), you can call:" msgstr "" #: ../../guides/views.rst:278 msgid "This function checks to see if there are any entities; if there are, it first displays the ``navigation/pagination`` view in order to display a way to move from page to page. It then repeatedly calls ``elgg_view_entity`` on each entity, before returning the result." msgstr "" #: ../../guides/views.rst:280 msgid "Note that ``elgg_list_entities`` allows the URL to set its ``limit`` and ``offset`` options, so set those explicitly if you need particular values (e.g. if you're not using it for pagination)." msgstr "" #: ../../guides/views.rst:282 msgid "Because it does this, Elgg knows that it can automatically supply an RSS feed - it extends the ``metatags`` view (which is called by the header) in order to provide RSS autodiscovery, which is why you can see the orange RSS icon on those pages." msgstr "" #: ../../guides/views.rst:284 msgid "If your entity list will display the entity owners, you can improve performance a bit by preloading all owner entities:" msgstr "" #: ../../guides/views.rst:296 msgid "See also :doc:`check this page out first </design/database>`." msgstr "" #: ../../guides/views.rst:298 msgid "Since 1.11, you can define an alternative view to render list items using ```'item_view'``` parameter." msgstr "" #: ../../guides/views.rst:300 msgid "In some cases, default entity views may be unsuitable for your needs. Using ```item_view``` allows you to customize the look, while preserving pagination, list's HTML markup etc." msgstr "" #: ../../guides/views.rst:302 msgid "Consider these two examples:" msgstr "" #: ../../guides/views.rst:324 msgid "In the first example, we are displaying a list of groups a user is a member of using the default group view. In the second example, we want to display a list of groups the user was invited to. Since invitations are not entities, they do not have their own views and can not be listed using ``elgg_list_*``. We are providing an alternative item view, that will use the group entity to display an invitation that contains a group name and buttons to access or reject the invitation." msgstr "" #: ../../guides/views.rst:327 msgid "Using a different templating system" msgstr "" #: ../../guides/views.rst:331 msgid "This functionality is deprecated as of Elgg 1.12. It will be removed in 2.0. It affects the behavior of templates globally, which is almost sure to cause breakages and therefore we suspect no one uses it in practice." msgstr "" #: ../../guides/views.rst:335 msgid "You can write your own templating system if you want to." msgstr "" #: ../../guides/views.rst:337 msgid "Before going through the motions of drawing views, Elgg checks the ``$CONFIG->template_handler`` variable to see if it contains the name of a callable function. If it does, the function will be passed the view name and template vars, and the return value of this function will be returned instead of the standard output:" msgstr "" #: ../../guides/views/foot-vs-footer.rst:2 msgid "Page/elements/foot vs footer" msgstr "" #: ../../guides/views/foot-vs-footer.rst:4 msgid "``page/elements/footer`` is the content that goes inside this part of the page:" msgstr "" #: ../../guides/views/foot-vs-footer.rst:14 msgid "It's content is visible to end users and usually where you would put a sitemap or other secondary global navigation, copyright info, powered by elgg, etc." msgstr "" #: ../../guides/views/foot-vs-footer.rst:16 msgid "``page/elements/foot`` is inserted just before the ending ``</body>`` tag and is mostly meant as a place to insert scripts that don't already work with ``elgg_register_js(array('location' => 'footer'));`` or ``elgg_require_js('amd/module');``. In other words, you should never override this view and probably don't need to extend it either. Just use the ``elgg_*_js`` functions instead" msgstr "" #: ../../guides/views/page-structure.rst:2 msgid "Page structure best practice" msgstr "" #: ../../guides/views/page-structure.rst:4 msgid "Elgg pages have an overall pageshell and a main content area. In Elgg 1.0+, we've marked out a space \\\"the canvas\\\" for items to write to the page. This means the user always has a very consistent experience, while giving maximum flexibility to plugin authors for laying out their functionality." msgstr "" #: ../../guides/views/page-structure.rst:6 msgid "Think of the canvas area as a big rectangle that you can do what you like in. We've created a couple of standard canvases for you:" msgstr "" #: ../../guides/views/page-structure.rst:8 msgid "one column" msgstr "" #: ../../guides/views/page-structure.rst:9 msgid "two column" msgstr "" #: ../../guides/views/page-structure.rst:10 msgid "content" msgstr "" #: ../../guides/views/page-structure.rst:11 msgid "widgets" msgstr "" #: ../../guides/views/page-structure.rst:13 msgid "are the main ones. You can access these with the function:" msgstr "" #: ../../guides/views/page-structure.rst:22 msgid "The content sections are passed as an ``array`` in the second parameter. The array keys correspond to sections in the layout, the choice of layout will determine which sections to pass. The array values contain the html that should be displayed in those areas. Examples of two common layouts:" msgstr "" #: ../../guides/views/page-structure.rst:37 msgid "You can then, ultimately, pass this into the ``elgg_view_page`` function:" msgstr "" #: ../../guides/views/page-structure.rst:43 msgid "You may also have noticed that we've started including a standard title area at the top of each plugin page (or at least, most plugin pages). This is created using the following wrapper function, and should usually be included at the top of the plugin content:" msgstr "" #: ../../guides/views/page-structure.rst:49 msgid "This will also display any submenu items that exist (unless you set the second, optional parameter to false). So how do you add submenu items?" msgstr "" #: ../../guides/views/page-structure.rst:51 msgid "In your plugin_init function, include the following call:" msgstr "" #: ../../guides/views/page-structure.rst:61 msgid "The submenu will then automatically display when your page is rendered. The 'identifier' is a machine name for the link, it should be unique per menu." msgstr "" #: ../../guides/views/simplecache.rst:2 msgid "Simplecache" msgstr "" #: ../../guides/views/simplecache.rst:6 msgid ":doc:`/admin/performance`" msgstr "" #: ../../guides/views/simplecache.rst:7 msgid ":doc:`/guides/views`" msgstr "" #: ../../guides/views/simplecache.rst:9 msgid "The Simplecache is a mechanism designed to alleviate the need for certain views to be regenerated dynamically. Instead, they are generated once, saved as a static file, and served in a way that entirely bypasses the Elgg engine." msgstr "" #: ../../guides/views/simplecache.rst:11 msgid "If Simplecache is turned off (which can be done from the administration panel), these views will be served as normal, with the exception of site CSS." msgstr "" #: ../../guides/views/simplecache.rst:13 msgid "The criteria for whether a view is suitable for the Simplecache is as follows:" msgstr "" #: ../../guides/views/simplecache.rst:15 msgid "The view must not change depending on who or when it is being looked at" msgstr "" #: ../../guides/views/simplecache.rst:16 msgid "The view must not depend on variables fed to it (except for global variables like site URL that never change)" msgstr "" #: ../../guides/views/simplecache.rst:19 msgid "Regenerating the Simplecache" msgstr "" #: ../../guides/views/simplecache.rst:21 msgid "You can regenerate the Simplecache at any time by:" msgstr "" #: ../../guides/views/simplecache.rst:23 msgid "Loading ``/upgrade.php``, even if you have nothing to upgrade" msgstr "" #: ../../guides/views/simplecache.rst:24 msgid "In the admin panel click on 'Flush the caches'" msgstr "" #: ../../guides/views/simplecache.rst:25 msgid "Enabling or disabling a plugin" msgstr "" #: ../../guides/views/simplecache.rst:26 msgid "Reordering your plugins" msgstr "" #: ../../guides/views/simplecache.rst:29 msgid "Using the Simplecache in your plugins" msgstr "" #: ../../guides/views/simplecache.rst:31 msgid "**Registering views with the Simplecache**" msgstr "" #: ../../guides/views/simplecache.rst:33 msgid "You can register a view with the Simplecache with the following function at init-time:" msgstr "" #: ../../guides/views/simplecache.rst:39 msgid "**Accessing the cached view**" msgstr "" #: ../../guides/views/simplecache.rst:41 msgid "If you registered a JavaScript or CSS file with Simplecache and put in in the view folder ``js/your_view`` or ``css/your_view`` you can very easily the the url to this cached view by calling" msgstr "" #: ../../guides/views/simplecache.rst:47 msgid "Where:" msgstr "" #: ../../guides/views/simplecache.rst:49 msgid "``$type`` is js or css" msgstr "" #: ../../guides/views/simplecache.rst:50 msgid "``$view`` the view name after css/ or js/" msgstr "" #: ../../guides/walled-garden.rst:2 msgid "Walled Garden" msgstr "" #: ../../guides/walled-garden.rst:4 msgid "Elgg supports a \"Walled Garden\" mode. In this mode, almost all pages are restricted to logged in users. This is useful for sites that don't allow public registration." msgstr "" #: ../../guides/walled-garden.rst:7 msgid "Activating Walled Garden mode" msgstr "" #: ../../guides/walled-garden.rst:9 msgid "To activate Walled Garden mode in Elgg 1.8, go to the Administration section. On the right sidebar menu, under the \"Configure\" section, expand \"Settings,\" then click on \"Advanced.\"" msgstr "" #: ../../guides/walled-garden.rst:11 msgid "From the Advanced Settings page, find the option labelled \"Restrict pages to logged-in users.\" Enable this option, then click \"Save\" to switch your site into Walled Garden mode." msgstr "" #: ../../guides/walled-garden.rst:14 msgid "Exposing pages through Walled Gardens" msgstr "" #: ../../guides/walled-garden.rst:16 msgid "Many plugins extend Elgg by adding pages. Walled Garden mode will prevent these pages from being viewed by logged out users. Elgg uses :ref:`plugin hook <design/events#plugin-hooks>` to manage which pages are visible through the Walled Garden." msgstr "" #: ../../guides/walled-garden.rst:18 msgid "Plugin authors must register pages as public if they should be viewable through Walled Gardens by responding to the ``public_pages``, ``walled_garden`` plugin hook." msgstr "" #: ../../guides/walled-garden.rst:20 msgid "The returned value is an array of regexp expressions for public pages." msgstr "" #: ../../guides/walled-garden.rst:22 msgid "The following code shows how to expose http://example.org/my_plugin/public_page through a Walled Garden. This assumes the plugin has registered a :doc:`pagehandler` for ``my_plugin``." msgstr "" #: ../../guides/web-services.rst:4 msgid "Build an HTTP API for your site." msgstr "" #: ../../guides/web-services.rst:6 msgid "Elgg provides a powerful framework for building web services. This allows developers to expose functionality to other web sites and desktop applications along with doing integrations with third-party web applications. While we call the API RESTful, it is actually a REST/RPC hybrid similar to the APIs provided by sites like Flickr and Twitter." msgstr "" #: ../../guides/web-services.rst:12 msgid "To create an API for your Elgg site, you need to do 4 things:" msgstr "" #: ../../guides/web-services.rst:14 msgid "enable the web services plugin" msgstr "" #: ../../guides/web-services.rst:15 msgid "expose methods" msgstr "" #: ../../guides/web-services.rst:16 msgid "setup API authentication" msgstr "" #: ../../guides/web-services.rst:17 msgid "setup user authentication" msgstr "" #: ../../guides/web-services.rst:19 msgid "Additionally, you may want to control what types of authentication are available on your site. This will also be covered." msgstr "" #: ../../guides/web-services.rst:29 msgid "It is crucial that the web services are consumed via secure protocols. Do not enable web services if your site is not served via HTTPs. This is especially important if you allow API key only authentication." msgstr "" #: ../../guides/web-services.rst:33 msgid "If you are using third-party tools that expose API methods, make sure to carry out a thorough security audit. You may want to make sure that API authentication is required for ALL methods, even if they require user authentication. Methods that do not require API authentication can be easily abused to spam your site." msgstr "" #: ../../guides/web-services.rst:38 msgid "Ensure that the validity of API keys is limited and provide mechanisms for your API clients to renew their keys." msgstr "" #: ../../guides/web-services.rst:42 msgid "Exposing methods" msgstr "" #: ../../guides/web-services.rst:44 msgid "The function to use to expose a method is ``elgg_ws_expose_function()``. As an example, let's assume you want to expose a function that echos text back to the calling application. The function could look like this" msgstr "" #: ../../guides/web-services.rst:54 msgid "Since we are providing this function to allow developers to test their API clients, we will require neither API authentication nor user authentication. This call registers the function with the web services API framework:" msgstr "" #: ../../guides/web-services.rst:70 msgid "If you add this code to a plugin and then go to http://yoursite.com/services/api/rest/xml/?method=system.api.list, you should now see your test.echo method listed as an API call. Further, to test the exposed method from a web browser, you could hit the url: http://yoursite.com/services/api/rest/xml/?method=test.echo&string=testing and you should see xml data like this:" msgstr "" #: ../../guides/web-services.rst:85 msgid "Response formats" msgstr "" #: ../../guides/web-services.rst:87 msgid "The web services API framework provides three different response formats by default: xml, json, and serialized php. You can request the different formats for substituting “json” or “php” for “xml” in the above URLs. You can also add additional response formats by defining new viewtypes." msgstr "" #: ../../guides/web-services.rst:93 msgid "Parameters" msgstr "" #: ../../guides/web-services.rst:95 msgid "Parameters expected by each method should be listed as an associative array, where the key represents the parameter name, and the value contains an array with ``type``, ``default`` and ``required`` fields." msgstr "" #: ../../guides/web-services.rst:97 msgid "Values submitted with the API request for each parameter should match the declared type. API will throw on exception if validation fails." msgstr "" #: ../../guides/web-services.rst:99 msgid "Recognized parameter types are:" msgstr "" #: ../../guides/web-services.rst:101 msgid "``integer`` (or ``int``)" msgstr "" #: ../../guides/web-services.rst:102 msgid "``boolean`` (or ``bool``)" msgstr "" #: ../../guides/web-services.rst:103 msgid "``string``" msgstr "" #: ../../guides/web-services.rst:104 msgid "``float``" msgstr "" #: ../../guides/web-services.rst:105 msgid "``array``" msgstr "" #: ../../guides/web-services.rst:107 msgid "Unrecognized types will throw an API exception." msgstr "" #: ../../guides/web-services.rst:109 msgid "You can use additional fields to describe your parameter, e.g. ``description``." msgstr "" #: ../../guides/web-services.rst:135 msgid "API authentication" msgstr "" #: ../../guides/web-services.rst:137 msgid "You may want to control access to some of the functions that you expose. Perhaps you are exposing functions in order to integrate Elgg with another open source platform on the same server. In that case, you only want to allow that other application access to these methods. Another possibility is that you want to limit what external developers have access to your API. Or maybe you want to limit how many calls a developer can make against your API in a single day." msgstr "" #: ../../guides/web-services.rst:145 msgid "In all of these cases, you can use Elgg's API authentication functions to control access. Elgg provides two built-in methods to perform API authentication: key based and HMAC signature based. You can also add your own authentication methods. The key based approach is very similar to what Google, Flickr, or Twitter. Developers can request a key (a random string) and pass that key with all calls that require API authentication. The keys are stored in the database and if an API call is made without a key or a bad key, the call is denied and an error message is returned." msgstr "" #: ../../guides/web-services.rst:156 msgid "Key-based authentication" msgstr "" #: ../../guides/web-services.rst:158 msgid "As an example, let's write a function that returns the number of users that have viewed the site in the last x minutes." msgstr "" #: ../../guides/web-services.rst:169 msgid "Now, let's expose it and make the number of minutes an optional parameter:" msgstr "" #: ../../guides/web-services.rst:184 msgid "This function is now available and if you check ``system.api.list``, you will see that it requires API authentication. If you hit the method with a web browser, it will return an error message about failing the API authentication. To test this method, you need an API key. Fortunately, there is a plugin called apiadmin that creates keys for you. It is available in the Elgg plugin repository. It will return a public and private key and you will use the public key for this kind of API authentication. Grab a key and then do a GET request with your browser on this API method passing in the key string as the parameter ``api_key``. It might look something like this: http://yoursite.com/services/api/rest/xml/?method=users.active&api_key=1140321cb56c71710c38feefdf72bc462938f59f." msgstr "" #: ../../guides/web-services.rst:197 msgid "Signature-based authentication" msgstr "" #: ../../guides/web-services.rst:199 msgid "The :doc:`web-services/hmac` is similar to what is used with OAuth or Amazon's S3 service. This involves both the public and private key. If you want to be very sure that the API calls are coming from the developer you think they are coming from and you want to make sure the data is not being tampered with during transmission, you would use this authentication method. Be aware that it is much more involved and could turn off developers when there are other sites out there with key-based authentication." msgstr "" #: ../../guides/web-services.rst:209 msgid "OAuth" msgstr "" #: ../../guides/web-services.rst:211 msgid "With the addition of the OAuth plugin, Elgg also fully supports the OAuth 1.0a authorization standard. Clients can then use standard OAuth libraries to make any API calls to the site." msgstr "" #: ../../guides/web-services.rst:216 msgid "User authentication" msgstr "" #: ../../guides/web-services.rst:218 msgid "So far you have been allowing developers to pull data out of your Elgg site. Now we'll move on to pushing data into Elgg. In this case, it is going to be done by a user. Maybe you have created a desktop application that allows your Users to post to the wire without going to the site. You need to expose a method for posting to the wire and you need to make sure that a user cannot post using someone else's account. Elgg provides a token-based approach for user authentication. It allows a user to submit their username and password in exchange for a token using the method ``auth.gettoken``. This token can then be used for some amount of time to authenticate all calls to the API before it expires by passing it as the parameter ``auth_token``. If you do not want to have your users trusting their passwords to 3rd-party applications, you can also extend the current capability to use an approach like OAuth." msgstr "" #: ../../guides/web-services.rst:232 msgid "Let's write our wire posting function:" msgstr "" #: ../../guides/web-services.rst:246 msgid "Exposing this function is the same as the previous except we require user authentication and we're going to make this use POST rather than GET HTTP requests." msgstr "" #: ../../guides/web-services.rst:261 msgid "Please note that you will not be able to test this using a web browser as you did with the other methods. You need to write some client code to do this. There is some example client code in ``/engine/lib/api.php``. Take a look at `send\\_api\\_post\\_call()`_. You can also do a search for clients that have been written for the APIs of Flickr or Twitter or any other similar API. You will find a wide variety written in almost any language you can think of." msgstr "" #: ../../guides/web-services.rst:270 msgid "Building out your API" msgstr "" #: ../../guides/web-services.rst:272 msgid "As soon as you feel comfortable with Elgg's web services API framework, you will want to step back and design your API. What sort of data are you trying to expose? Who or what will be API users? How do you want them to get access to authentication keys? How are you going to document your API? Be sure to take a look at the APIs created by popular Web 2.0 sites for inspiration. If you are looking for 3rd party developers to build applications using your API, you will probably want to provide one or more language-specific clients." msgstr "" #: ../../guides/web-services.rst:284 msgid "Determining the authentication available" msgstr "" #: ../../guides/web-services.rst:286 msgid "Elgg's web services API uses a type of `pluggable authentication module (PAM)`_ architecture to manage how users and developers are authenticated. This provides you the flexibility to add and remove authentication modules. Do you want to not use the default user authentication PAM but would prefer using OAuth? You can do this." msgstr "" #: ../../guides/web-services.rst:292 msgid "The first step is registering a callback function for the *rest, init* plugin hook:" msgstr "" #: ../../guides/web-services.rst:299 msgid "Then in the callback function, you register the PAMs that you want to use:" msgstr "" #: ../../guides/web-services.rst:315 msgid "When testing, you may find it useful to register the ``pam_auth_session`` PAM so that you can easily test your methods from the browser. Be careful not to use this PAM on a production site because it could open up your users to a `CSRF attack`_." msgstr "" #: ../../guides/web-services.rst:320 msgid "Right now, the only other PAMs publicly available besides those provided by the Elgg core are the OAuth PAMs. See `Justin Richer's OAuth plugin`_ for more detail." msgstr "" #: ../../guides/web-services/hmac.rst:2 msgid "HMAC Authentication" msgstr "" #: ../../guides/web-services/hmac.rst:4 msgid "Elgg's RESTful API framework provides functions to support a `HMAC`_ signature scheme for API authentication. The client must send the HMAC signature together with a set of special HTTP headers when making a call that requires API authentication. This ensures that the API call is being made from the stated client and that the data has not been tampered with." msgstr "" #: ../../guides/web-services/hmac.rst:8 msgid "The HMAC must be constructed over the following data:" msgstr "" #: ../../guides/web-services/hmac.rst:10 msgid "The public API key identifying you to the Elgg api server as provided by the APIAdmin plugin" msgstr "" #: ../../guides/web-services/hmac.rst:11 msgid "The private API Key provided by Elgg (that is companion to the public key)" msgstr "" #: ../../guides/web-services/hmac.rst:12 msgid "The current unix time in seconds" msgstr "" #: ../../guides/web-services/hmac.rst:13 msgid "A nonce to guarantee two requests the same second have different signatures" msgstr "" #: ../../guides/web-services/hmac.rst:14 msgid "URL encoded string representation of any GET variable parameters, eg ``method=test.test&foo=bar``" msgstr "" #: ../../guides/web-services/hmac.rst:15 msgid "If you are sending post data, the hash of this data" msgstr "" #: ../../guides/web-services/hmac.rst:17 msgid "Some extra information must be added to the HTTP header in order for this data to be correctly processed:" msgstr "" #: ../../guides/web-services/hmac.rst:19 msgid "**X-Elgg-apikey** - The public API key" msgstr "" #: ../../guides/web-services/hmac.rst:20 msgid "**X-Elgg-time** - Unix time used in the HMAC calculation" msgstr "" #: ../../guides/web-services/hmac.rst:21 msgid "**X-Elgg-none** - a random string" msgstr "" #: ../../guides/web-services/hmac.rst:22 msgid "**X-Elgg-hmac** - The HMAC as base64 encoded" msgstr "" #: ../../guides/web-services/hmac.rst:23 msgid "**X-Elgg-hmac-algo** - The algorithm used in the HMAC calculation - eg, sha1, md5 etc." msgstr "" #: ../../guides/web-services/hmac.rst:25 msgid "If you are sending POST data you must also send:" msgstr "" #: ../../guides/web-services/hmac.rst:27 msgid "**X-Elgg-posthash** - The hash of the POST data" msgstr "" #: ../../guides/web-services/hmac.rst:28 msgid "**X-Elgg-posthash-algo** - The algorithm used to produce the POST data hash - eg, md5" msgstr "" #: ../../guides/web-services/hmac.rst:29 msgid "**Content-type** - The content type of the data you are sending (if in doubt use application/octet-stream)" msgstr "" #: ../../guides/web-services/hmac.rst:30 msgid "**Content-Length** - The length in bytes of your POST data" msgstr "" #: ../../guides/web-services/hmac.rst:32 msgid "Elgg provides a sample API client that implements this HMAC signature: send_api_call(). It serves as a good reference on how to implement it." msgstr "" #: ../../guides/widgets.rst:2 msgid "Widgets" msgstr "" #: ../../guides/widgets.rst:4 msgid "Widgets are content areas that users can drag around their page to customize the layout. They can typically be customized by their owner to show more/less content and determine who sees the widget. By default Elgg provides plugins for customizing the profile page and dashboard via widgets." msgstr "" #: ../../guides/widgets.rst:6 msgid "TODO: Screenshot" msgstr "" #: ../../guides/widgets.rst:13 msgid "Structure" msgstr "" #: ../../guides/widgets.rst:15 msgid "To create a widget, create two views:" msgstr "" #: ../../guides/widgets.rst:17 msgid "``widgets/widget/edit``" msgstr "" #: ../../guides/widgets.rst:18 msgid "``widgets/widget/content``" msgstr "" #: ../../guides/widgets.rst:20 msgid "``content.php`` is responsible for all the content that will output within the widget. The ``edit.php`` file contains any extra edit functions you wish to present to the user. You do not need to add access level as this comes as part of the widget framework." msgstr "" #: ../../guides/widgets.rst:24 msgid "Using HTML checkboxes to set widget flags is problematic because if unchecked, the checkbox input is omitted from form submission. The effect is that you can only set and not clear flags. The \"input/checkboxes\" view will not work properly in a widget's edit panel." msgstr "" #: ../../guides/widgets.rst:30 msgid "Initialise the widget" msgstr "" #: ../../guides/widgets.rst:32 msgid "Once you have created your edit and view pages, you need to initialize the plugin widget. This is done within the plugins ``init()`` function." msgstr "" #: ../../guides/widgets.rst:41 msgid "It is possible to add multiple widgets for a plugin. You just initialize as many widget directories as you need." msgstr "" #: ../../guides/widgets.rst:55 msgid "Multiple widgets" msgstr "" #: ../../guides/widgets.rst:57 msgid "Make sure you have the corrosponding directories within your plugin views structure:" msgstr "" #: ../../guides/widgets.rst:77 msgid "Elgg 1.8: Default widgets" msgstr "" #: ../../guides/widgets.rst:79 msgid "If your plugin uses the widget canvas, you can register default widget support with Elgg core, which will handle everything else." msgstr "" #: ../../guides/widgets.rst:81 msgid "To announce default widget support in your plugin, register for the ``get_list, default_widgets`` plugin hook:" msgstr "" #: ../../guides/widgets.rst:87 msgid "In the plugin hook handler, push an array into the return value defining your default widget support and when to create default widgets. Arrays require the following keys to be defined:" msgstr "" #: ../../guides/widgets.rst:89 msgid "name - The name of the widgets page. This is displayed on the tab in the admin interface." msgstr "" #: ../../guides/widgets.rst:90 msgid "widget\\_context - The context the widgets page is called from. (If not explicitly set, this is your plugin's id.)" msgstr "" #: ../../guides/widgets.rst:91 msgid "widget\\_columns - How many columns the widgets page will use." msgstr "" #: ../../guides/widgets.rst:92 msgid "event - The Elgg event to create new widgets for. This is usually ``create``." msgstr "" #: ../../guides/widgets.rst:93 msgid "entity\\_type - The entity type to create new widgets for." msgstr "" #: ../../guides/widgets.rst:94 msgid "entity\\_subtype - The entity subtype to create new widgets for. The can be ELGG\\_ENTITIES\\_ANY\\_VALUE to create for all entity types." msgstr "" #: ../../guides/widgets.rst:96 msgid "When an object triggers an event that matches the event, entity\\_type, and entity\\_subtype parameters passed, Elgg core will look for default widgets that match the widget\\_context and will copy them to that object's owner\\_guid and container\\_guid. All widget settings will also be copied." msgstr "" #: ../../guides/widgets.rst:117 msgid "Here is a simple Flickr widget that uses Flickr's JSON output." msgstr "" #: ../../guides/widgets.rst:119 msgid "Widget edit page:" msgstr "" #: ../../guides/widgets.rst:130 msgid "Widget view page:" msgstr "" #: ../../guides/widgets.rst:201 msgid "How to restrict where widgets can be used" msgstr "" #: ../../guides/widgets.rst:203 msgid "Any plugin that has a widget must register that widget with Elgg. The widget can specify the context that it can be used in (all, just profile, just dashboard, etc.). If you want to change where your users can use a widget, you can make a quick edit to the plugin's source." msgstr "" #: ../../guides/widgets.rst:206 msgid "Find where the plugin registers the widget" msgstr "" #: ../../guides/widgets.rst:208 msgid "The function you are looking for is ``add_widget_type()``. It is typically used in an init function in ``start.php``. You should be able to go to ``/mod/<plugin name>/``, open ``start.php`` in a text editor, and find the string ``add_widget_type``." msgstr "" #: ../../guides/widgets.rst:211 msgid "Changing the function's parameters" msgstr "" #: ../../guides/widgets.rst:213 msgid "Let's use the friends plugin as an example. We want to restrict it so that it can only be used on a user's profile. Currently, the function call looks like this:" msgstr "" #: ../../guides/widgets.rst:217 msgid "Keep in mind :doc:`dont-modify-core`" msgstr "" #: ../../guides/widgets.rst:223 msgid "To restrict it to the profile, change it to this:" msgstr "" #: ../../guides/widgets.rst:229 msgid "Notice that the context was not specified originally (there were only 3 parameters and we added a 4th). That means it defaulted to the \"all\" context. Besides \"all\" and \"profile\", the only other context available in default Elgg is \"dashboard\"." msgstr ""