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

#: ../../design/actions.rst:2
msgid "Actions"
msgstr ""

#: ../../design/actions.rst:4
msgid "Actions are the primary way users interact with an Elgg site."
msgstr ""

#: ../../design/actions.rst:10
#: ../../design/amd.rst:8
#: ../../design/database.rst:11
#: ../../design/events.rst:9
msgid "Overview"
msgstr ""

#: ../../design/actions.rst:12
msgid "An action in Elgg is the code that runs to make changes to the database when a user does something. For example, logging in, posting a comment, and making a blog post are actions. The action script processes input, makes the appropriate modifications to the database, and provides feedback to the user about the action."
msgstr ""

#: ../../design/actions.rst:15
msgid "Action Handler"
msgstr ""

#: ../../design/actions.rst:17
msgid "Actions are registered during the boot process by calling ``elgg_register_action()``. All actions URLs start with ``action/`` and are served by Elgg's front end controller through the action service. This approach is different from traditional PHP applications that send information to a specific file. The action service performs :doc:`CSRF security checks </design/security>`, and calls the registered action script file, then optionally forwards the user to a new page. By using the action service instead of a single script file, Elgg automatically provides increased security and extensibility."
msgstr ""

#: ../../design/actions.rst:19
msgid "In Elgg 1.8 and before, actions were handled by an action handler script in ```engine/handlers/action_handler.php``. This required specific rewrite rules for URLs beginning with ``/action/``."
msgstr ""

#: ../../design/actions.rst:21
msgid "See :doc:`/guides/actions` for details on how to register and construct an action. To look at the core actions, check out the directory /actions."
msgstr ""

#: ../../design/amd.rst:2
msgid "AMD"
msgstr ""

#: ../../design/amd.rst:10
msgid "There are two JavaScript system in Elgg: the deprecated 1.8 system, and the newer `AMD (Asynchronous Module Definition) <http://requirejs.org/docs/whyamd.html>`_ compatible system introduced in 1.9."
msgstr ""

#: ../../design/amd.rst:13
msgid "This discusses the benefits of using AMD in Elgg."
msgstr ""

#: ../../design/amd.rst:16
msgid "Why AMD?"
msgstr ""

#: ../../design/amd.rst:18
msgid "We have been working hard to make Elgg's JavaScript more maintainable and useful. We made some strides in 1.8 with the introduction of the \"``elgg``\" JavaScript object and library, but have quickly realized the approach we were taking was not scalable."
msgstr ""

#: ../../design/amd.rst:22
msgid "The size of `JS on the web is growing <http://httparchive.org/trends.php?s=All&minlabel=Feb+11+2011&maxlabel=Feb+1+2013#bytesJS&reqJS>`_ quickly, and JS in Elgg is growing too. We want Elgg to be able to offer a solution that makes JS development as productive and maintainable as possible going forward."
msgstr ""

#: ../../design/amd.rst:27
msgid "The `reasons to choose AMD <http://requirejs.org/docs/whyamd.html>`_ are plenteous and well-documented. Let's highlight just a few of the most relevant reasons as they relate to Elgg specifically."
msgstr ""

#: ../../design/amd.rst:32
msgid "1. Simplified dependency management"
msgstr ""

#: ../../design/amd.rst:33
msgid "AMD modules load asynchronously and execute as soon as their dependencies are available, so this eliminates the need to specify \"priority\" and \"location\" when registering JS libs in Elgg. Also, you don't need to worry about explicitly loading a module's dependencies in PHP. The AMD loader (RequireJS in this case) takes care of all that hassle for you. It's also possible have `text dependencies <http://requirejs.org/docs/api.html#text>`_ with the RequireJS text plugin, so client-side templating should be a breeze."
msgstr ""

#: ../../design/amd.rst:41
msgid "2. AMD works in all browsers. Today."
msgstr ""

#: ../../design/amd.rst:42
msgid "Elgg developers are already writing lots of JavaScript. We know you want to write more. We cannot accept waiting 5-10 years for a native JS modules solution to be available in all browsers before we can organize our JavaScript in a maintainable way."
msgstr ""

#: ../../design/amd.rst:47
msgid "3. You do not need a build step to develop in AMD."
msgstr ""

#: ../../design/amd.rst:48
msgid "We like the edit-refresh cycle of web development. We wanted to make sure everyone developing in Elgg could continue experiencing that joy. Synchronous module formats like Closure or CommonJS just weren't an option for us. But even though AMD doesn't require a build step, *it is still very build-friendly*. Because of the ``define()`` wrapper, it's possible to concatenate multiple modules into a single file and ship them all at once in a production environment. [#]_"
msgstr ""

#: ../../design/amd.rst:54
msgid "AMD is a battle-tested and well thought out module loading system for the web today. We're very thankful for the work that has gone into it, and are excited to offer it as the standard solution for JavaScript development in Elgg starting with Elgg 1.9."
msgstr ""

#: ../../design/amd.rst:58
msgid "This is not currently supported by Elgg core, but we'll be looking into it since reducing round-trips is critical for a good first-view experience, especially on mobile devices."
msgstr ""

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

#: ../../design/database.rst:4
msgid "A thorough discussion of Elgg's data model design and motivation."
msgstr ""

#: ../../design/database.rst:0
#: ../../design/events.rst:0
#: ../../design/security.rst:0
msgid "Contents"
msgstr ""

#: ../../design/database.rst:13
msgid "In Elgg, everything runs on a unified data model based on atomic units of data called entities."
msgstr ""

#: ../../design/database.rst:16
msgid "Plugins are discouraged from interacting directly with the database, which creates a more stable system and a better user experience becase content created by different plugins can be mixed together in consistent ways. With this approach, plugins are faster to develop, and are at the same time much more powerful."
msgstr ""

#: ../../design/database.rst:22
msgid "Every entity in the system inherits the ``ElggEntity`` class. This class controls access permissions, ownership"
msgstr ""

#: ../../design/database.rst:27
msgid "You can extend entities with extra information in two ways:"
msgstr ""

#: ../../design/database.rst:31
msgid "``Metadata``: This is information describing the entity, usually"
msgstr ""

#: ../../design/database.rst:30
msgid "added by the author of the entity when the entity is created. For example, tags, an ISBN number, a file location, or source language is metadata."
msgstr ""

#: ../../design/database.rst:36
msgid "``Annotations``: This is information about the entity, usually"
msgstr ""

#: ../../design/database.rst:34
msgid "added by a third party after the entity is created. For example, ratings, likes, and votes are annotations. (Comments were before 1.9.)"
msgstr ""

#: ../../design/database.rst:39
msgid "Datamodel"
msgstr ""

#: ../../design/database.rst:46
msgid "The Elgg data model diagram"
msgstr ""

#: ../../design/database.rst:49
msgid "Entities"
msgstr ""

#: ../../design/database.rst:51
msgid "ElggEntity is the base class for the Elgg data model."
msgstr ""

#: ../../design/database.rst:54
msgid "Users, Objects, Groups, Sites"
msgstr ""

#: ../../design/database.rst:56
msgid "``ElggEntity`` has four main specializations, which provide extra properties and methods to more easily handle different kinds of data."
msgstr ""

#: ../../design/database.rst:59
msgid "``ElggObject``: content like blog posts, uploaded files and bookmarks ``ElggUser``: a system user ``ElggSite``: each Elgg site within an Elgg installation ``ElggGroup``: multi-user collaborative systems (called \"Communities\" in prior versions of Elgg)"
msgstr ""

#: ../../design/database.rst:65
msgid "The benefit of such an approach is that, apart from modelling data with greater ease, a common set of functions is available to handle objects, regardless of their (sub)type."
msgstr ""

#: ../../design/database.rst:69
msgid "Each of these have their own properties that they bring to the table: ElggObjects have a title and description, ElggUsers have a username and password, and so on. However, because they all inherit ElggEntity, they each have a number of core properties and behaviours in common."
msgstr ""

#: ../../design/database.rst:74
msgid "A numeric Globally Unique IDentifier (See `GUIDs`_)."
msgstr ""

#: ../../design/database.rst:75
msgid "Access permissions. (When a plugin requests data, it never gets to touch data that the current user doesn't have permission to see.)"
msgstr ""

#: ../../design/database.rst:77
msgid "An arbitrary subtype. For example, a blog post is an ElggObject with a subtype of \"blog\". Subtypes aren't predefined; they can be any unique way to describe a particular kind of entity. \"blog\", \"forum\", \"foo\", \"bar\", \"loafofbread\" and \"pyjamas\" are all valid subtypes."
msgstr ""

#: ../../design/database.rst:81
msgid "An owner."
msgstr ""

#: ../../design/database.rst:82
msgid "The site that the entity belongs to."
msgstr ""

#: ../../design/database.rst:83
msgid "A container, usually used to associate a group's content with the group."
msgstr ""

#: ../../design/database.rst:86
msgid "GUIDs"
msgstr ""

#: ../../design/database.rst:88
msgid "A GUID is an integer that uniquely identifies every entity in an Elgg installation (a Globally Unique IDentifier). It's assigned automatically when the entity is first saved and can never be changed."
msgstr ""

#: ../../design/database.rst:92
msgid "Some Elgg API functions work with GUIDs instead of ``ElggEntity`` objects."
msgstr ""

#: ../../design/database.rst:95
msgid "ElggObject"
msgstr ""

#: ../../design/database.rst:97
msgid "The ``ElggObject`` entity type represents arbitrary content within an Elgg install; things like blog posts, uploaded files, etc."
msgstr ""

#: ../../design/database.rst:100
msgid "Beyond the standard ElggEntity properties, ElggObjects also support:"
msgstr ""

#: ../../design/database.rst:102
msgid "``title`` The title of the object (HTML escaped text)"
msgstr ""

#: ../../design/database.rst:103
msgid "``description`` A description of the object (HTML)"
msgstr ""

#: ../../design/database.rst:105
msgid "Most other data about the object is generally stored via metadata."
msgstr ""

#: ../../design/database.rst:108
msgid "ElggUser"
msgstr ""

#: ../../design/database.rst:110
msgid "The ``ElggUser`` entity type represents users within an Elgg install. These will be set to disabled until their accounts have been activated (unless they were created from within the admin panel)."
msgstr ""

#: ../../design/database.rst:114
msgid "Beyond the standard ElggEntity properties, ElggUsers also support:"
msgstr ""

#: ../../design/database.rst:116
msgid "``name`` The user's plain text name. e.g. \"Hugh Jackman\""
msgstr ""

#: ../../design/database.rst:117
msgid "``username`` Their login name. E.g. \"hjackman\""
msgstr ""

#: ../../design/database.rst:118
msgid "``password`` A hashed version of their password"
msgstr ""

#: ../../design/database.rst:119
msgid "``salt`` The salt that their password has been hashed with"
msgstr ""

#: ../../design/database.rst:120
msgid "``email`` Their email address"
msgstr ""

#: ../../design/database.rst:121
msgid "``language`` Their default language code."
msgstr ""

#: ../../design/database.rst:122
msgid "``code`` Their session code (moved to a separate table in 1.9)."
msgstr ""

#: ../../design/database.rst:123
msgid "``last_action`` The UNIX timestamp of the last time they loaded a page"
msgstr ""

#: ../../design/database.rst:124
msgid "``prev_last_action`` The previous value of ``last_action``"
msgstr ""

#: ../../design/database.rst:125
msgid "``last_login`` The UNIX timestamp of their last log in"
msgstr ""

#: ../../design/database.rst:126
msgid "``prev_last_login`` the previous value of ``last_login``"
msgstr ""

#: ../../design/database.rst:129
msgid "ElggSite"
msgstr ""

#: ../../design/database.rst:131
msgid "The ``ElggSite`` entity type represents sites within your Elgg install. Most installs will have only one."
msgstr ""

#: ../../design/database.rst:134
msgid "Beyond the standard ElggEntity properties, ElggSites also support:"
msgstr ""

#: ../../design/database.rst:136
msgid "``name`` The site name"
msgstr ""

#: ../../design/database.rst:137
msgid "``description`` A description of the site"
msgstr ""

#: ../../design/database.rst:138
msgid "``url`` The address of the site"
msgstr ""

#: ../../design/database.rst:141
msgid "ElggGroup"
msgstr ""

#: ../../design/database.rst:143
msgid "The ``ElggGroup`` entity type represents an association of Elgg users. Users can join, leave, and post content to groups."
msgstr ""

#: ../../design/database.rst:146
msgid "Beyond the standard ElggEntity properties, ElggGroups also support:"
msgstr ""

#: ../../design/database.rst:148
msgid "``name`` The group's name (HTML escaped text)"
msgstr ""

#: ../../design/database.rst:149
msgid "``description`` A description of the group (HTML)"
msgstr ""

#: ../../design/database.rst:151
msgid "``ElggGroup`` has addition methods to manage content and membership."
msgstr ""

#: ../../design/database.rst:154
msgid "The Groups plugin"
msgstr ""

#: ../../design/database.rst:156
msgid "Not to be confused with the entity type ``ElggGroup``, Elgg comes with a plugin called \"Groups\" that provides a default UI/UX for site users to interact with groups. Each group is given a discussion forum and a profile page linking users to content within the group."
msgstr ""

#: ../../design/database.rst:161
msgid "You can alter the user experience via the traditional means of extending plugins or completely replace the Groups plugin with your own."
msgstr ""

#: ../../design/database.rst:164
msgid "Because ``ElggGroup`` can be subtyped like all other ElggEntities, you can have multiple types of groups running on the same site."
msgstr ""

#: ../../design/database.rst:168
msgid "Writing a group-aware plugin"
msgstr ""

#: ../../design/database.rst:170
msgid "Plugin owners need not worry too much about writing group-aware functionality, but there are a few key points:"
msgstr ""

#: ../../design/database.rst:174
msgid "Adding content"
msgstr ""

#: ../../design/database.rst:176
msgid "By passing along the group as ``container_guid`` via a hidden input field, you can use a single form and action to add both user and group content."
msgstr ""

#: ../../design/database.rst:179
msgid "Use `can_write_to_container <http://reference.elgg.org/entities_8php.html#16a972909c7cb75f646cb707be001a6f>`_ to determine whether or not the current user has the right to add content to a group."
msgstr ""

#: ../../design/database.rst:184
msgid "Be aware that you will then need to pass the container GUID or username to the page responsible for posting and the accompanying value, so that this can then be stored in your form as a hidden input field, for easy passing to your actions. Within a \"create\" action, you'll need to take in this input field and save it as a property of your new element (defaulting to the current user's container):"
msgstr ""

#: ../../design/database.rst:212
msgid "Usernames and page ownership"
msgstr ""

#: ../../design/database.rst:214
msgid "Groups have a simulated username of the form *group:\\ GUID*, which you can get the value of by checking ``$group->username``. If you pass this username to a page on the URL line as part of the ``username`` variable (i.e., ``/yourpage?username=group:nnn``), Elgg will automatically register that group as being the owner of the page (unless overridden)."
msgstr ""

#: ../../design/database.rst:221
msgid "Juggling users and groups"
msgstr ""

#: ../../design/database.rst:223
msgid "In fact, ``[[Engine/DataModel/Entities/ElggGroup|ElggGroup]]`` simulates most of the methods of ``[[Engine/DataModel/Entities/ElggUser|ElggUser]]``. You can grab the icon, name etc using the same calls, and if you ask for a group's friends, you'll get its members. This has been designed specifically for you to alternate between groups and users in your code easily."
msgstr ""

#: ../../design/database.rst:231
msgid "Menu options"
msgstr ""

#: ../../design/database.rst:233
msgid "***This section is deprecated as of Elgg 1.8***"
msgstr ""

#: ../../design/database.rst:235
msgid "The final piece of the puzzle, for default groups, is to add a link to your functionality from the group's profile. Here we'll use the file plugin as an example."
msgstr ""

#: ../../design/database.rst:239
msgid "This involves creating a view within your plugin - in this case file/menu - which will extend the group's menu. File/menu consists of a link within paragraph tags that points to the file repository of the page\\_owner():"
msgstr ""

#: ../../design/database.rst:252
msgid "You can then extend the group's menu view with this one, within your plugin's input function (in this case file\\_init):"
msgstr ""

#: ../../design/database.rst:260
msgid "Ownership"
msgstr ""

#: ../../design/database.rst:262
msgid "Entities have a ``owner_guid`` GUID property, which defines its owner. Typically this refers to the GUID of a user, although sites and users themselves often have no owner (a value of 0)."
msgstr ""

#: ../../design/database.rst:266
msgid "The ownership of an entity dictates, in part, whether or not you can access or edit that entity."
msgstr ""

#: ../../design/database.rst:270
msgid "Containers"
msgstr ""

#: ../../design/database.rst:272
msgid "In order to easily search content by group or by user, content is generally set to be \"contained\" by either the user who posted it, or the group to which the user posted. This means the new object's ``container_guid`` property will be set to the GUID of the current ElggUser or the target ElggGroup."
msgstr ""

#: ../../design/database.rst:277
msgid "E.g., three blog posts may be owned by different authors, but all be contained by the group they were posted to."
msgstr ""

#: ../../design/database.rst:280
msgid "Note: This is not always true. Comment entities are contained by the object commented upon, and in some 3rd party plugins the container may be used to model a parent-child relationship between entities (e.g. a \"folder\" object containing a file object)."
msgstr ""

#: ../../design/database.rst:286
msgid "Annotations"
msgstr ""

#: ../../design/database.rst:288
msgid "Annotations are pieces of data attached to an entity that allow users to leave ratings, or other relevant feedback. A poll plugin might register votes as annotations. Before Elgg 1.9, comments and group discussion replies were stored as annotations."
msgstr ""

#: ../../design/database.rst:293
msgid "Annotations are stored as instances of the ``ElggAnnotation`` class."
msgstr ""

#: ../../design/database.rst:295
msgid "Each annotation has:"
msgstr ""

#: ../../design/database.rst:297
msgid "An internal annotation type (like *comment*)"
msgstr ""

#: ../../design/database.rst:298
msgid "A value (which can be a string or integer)"
msgstr ""

#: ../../design/database.rst:299
msgid "An access permission distinct from the entity it's attached to"
msgstr ""

#: ../../design/database.rst:300
msgid "An owner"
msgstr ""

#: ../../design/database.rst:303
msgid "Adding an annotation"
msgstr ""

#: ../../design/database.rst:305
msgid "The easiest way to annotate is to use the ``annotate`` method on an entity, which is defined as:"
msgstr ""

#: ../../design/database.rst:318
msgid "For example, to leave a rating on an entity, you might call:"
msgstr ""

#: ../../design/database.rst:325
msgid "Reading annotations"
msgstr ""

#: ../../design/database.rst:327
msgid "To retrieve annotations on an object, you can call the following method:"
msgstr ""

#: ../../design/database.rst:338
msgid "If your annotation type largely deals with integer values, a couple of useful mathematical functions are provided:"
msgstr ""

#: ../../design/database.rst:349
msgid "Useful helper functions"
msgstr ""

#: ../../design/database.rst:352
msgid "Comments"
msgstr ""

#: ../../design/database.rst:354
msgid "If you want to provide comment functionality on your plugin objects, the following function will provide the full listing, form and actions:"
msgstr ""

#: ../../design/database.rst:363
msgid "Metadata"
msgstr ""

#: ../../design/database.rst:365
msgid "Metadata in Elgg allows you to store extra data on an ``entity`` beyond the built-in fields that entity supports. For example, ``ElggObjects`` only support the basic entity fields plus title and description, but you might want to include tags or an ISBN number. Similarly, you might want users to be able to save a date of birth."
msgstr ""

#: ../../design/database.rst:371
msgid "Under the hood, metadata is stored as an instance of the ``ElggMetadata`` class, but you don't need to worry about that in practice (although if you're interested, see the ``ElggMetadata`` class reference). What you need to know is:"
msgstr ""

#: ../../design/database.rst:376
msgid "Metadata has an owner and access ID, both of which may be different to the owner of the entity it's attached to"
msgstr ""

#: ../../design/database.rst:378
msgid "You can potentially have multiple items of each type of metadata attached to a single entity"
msgstr ""

#: ../../design/database.rst:382
msgid "The simple case"
msgstr ""

#: ../../design/database.rst:385
#: ../../design/database.rst:454
msgid "Adding metadata"
msgstr ""

#: ../../design/database.rst:387
msgid "To add a piece of metadata to an entity, just call:"
msgstr ""

#: ../../design/database.rst:393
msgid "For example, to add a date of birth to a user:"
msgstr ""

#: ../../design/database.rst:399
msgid "Or to add a couple of tags to an object:"
msgstr ""

#: ../../design/database.rst:405
msgid "When adding metadata like this:"
msgstr ""

#: ../../design/database.rst:407
msgid "The owner is set to the currently logged-in user"
msgstr ""

#: ../../design/database.rst:408
msgid "Access permissions are inherited from the entity"
msgstr ""

#: ../../design/database.rst:409
msgid "Reassigning a piece of metadata will overwrite the old value"
msgstr ""

#: ../../design/database.rst:411
msgid "This is suitable for most purposes. Be careful to note which attributes are metadata and which are built in to the entity type that you are working with. You do not need to save an entity after adding or updating metadata. You do need to save an entity if you have changed one of its built in attributes. As an example, if you changed the access id of an ElggObject, you need to save it or the change isn't pushed to the database."
msgstr ""

#: ../../design/database.rst:420
#: ../../design/database.rst:496
msgid "Reading metadata"
msgstr ""

#: ../../design/database.rst:422
msgid "To retrieve metadata, treat it as a property of the entity:"
msgstr ""

#: ../../design/database.rst:428
msgid "Note that this will return the absolute value of the metadata. To get metadata as an ElggMetadata object, you will need to use the methods described in the *finer control* section below."
msgstr ""

#: ../../design/database.rst:432
msgid "If you stored multiple values in this piece of metadata (as in the \"tags\" example above), you will get an array of all those values back. If you stored only one value, you will get a string or integer back. Storing an array with only one value will return a string back to you. E.g."
msgstr ""

#: ../../design/database.rst:444
msgid "To always get an array back, simply cast to an array;"
msgstr ""

#: ../../design/database.rst:451
msgid "Finer control"
msgstr ""

#: ../../design/database.rst:456
msgid "If you need more control, for example to assign an access ID other than the default, you can use the ``create_metadata`` function, which is defined as follows:"
msgstr ""

#: ../../design/database.rst:472
msgid "For single values, you can therefore write metadata as follows (taking the example of a date of birth attached to a user):"
msgstr ""

#: ../../design/database.rst:479
msgid "For multiple values, you will need to iterate through and call ``create_metadata`` on each one. The following piece of code comes from the profile save action:"
msgstr ""

#: ../../design/database.rst:492
msgid "Note that the *allow multiple* setting is set to *false* in the first iteration and *true* thereafter."
msgstr ""

#: ../../design/database.rst:498
msgid "``elgg_get_metadata`` is the best function for retrieving metadata as ElggMetadata objects:"
msgstr ""

#: ../../design/database.rst:501
msgid "E.g., to retrieve a user's DOB"
msgstr ""

#: ../../design/database.rst:510
msgid "Or to get all metadata objects:"
msgstr ""

#: ../../design/database.rst:522
msgid "Common mistakes"
msgstr ""

#: ../../design/database.rst:525
msgid "\"Appending\" metadata"
msgstr ""

#: ../../design/database.rst:527
msgid "Note that you cannot \"append\" values to metadata arrays as if they were normal php arrays. For example, the following will not do what it looks like it should do."
msgstr ""

#: ../../design/database.rst:536
msgid "Trying to store hashmaps"
msgstr ""

#: ../../design/database.rst:538
msgid "Elgg does not support storing ordered maps (name/value pairs) in metadata. For example, the following does not work as you might first expect it to:"
msgstr ""

#: ../../design/database.rst:547
msgid "You can instead store the information like so:"
msgstr ""

#: ../../design/database.rst:556
msgid "Storing GUIDs in metadata"
msgstr ""

#: ../../design/database.rst:558
msgid "Though there are some cases to store entity GUIDs in metadata, `Relationships`_ are a much better construct for relating entities to each other."
msgstr ""

#: ../../design/database.rst:563
msgid "Relationships"
msgstr ""

#: ../../design/database.rst:565
msgid "Relationships allow you to bind entities together. Examples: an artist has fans, a user is a member of an organization, etc."
msgstr ""

#: ../../design/database.rst:568
msgid "The class ``ElggRelationship`` models a directed relationship between two entities, making the statement:"
msgstr ""

#: ../../design/database.rst:571
msgid "\"**{subject}** is a **{noun}** of **{target}**.\""
msgstr ""

#: ../../design/database.rst:574
msgid "API name"
msgstr ""

#: ../../design/database.rst:574
msgid "Models"
msgstr ""

#: ../../design/database.rst:574
msgid "Represents"
msgstr ""

#: ../../design/database.rst:576
msgid "``guid_one``"
msgstr ""

#: ../../design/database.rst:576
msgid "The subject"
msgstr ""

#: ../../design/database.rst:576
msgid "Which entity is being bound"
msgstr ""

#: ../../design/database.rst:577
msgid "``relationship``"
msgstr ""

#: ../../design/database.rst:577
msgid "The noun"
msgstr ""

#: ../../design/database.rst:577
msgid "The type of relationship"
msgstr ""

#: ../../design/database.rst:578
msgid "``guid_two``"
msgstr ""

#: ../../design/database.rst:578
msgid "The target"
msgstr ""

#: ../../design/database.rst:578
msgid "The entity to which the subject is bound"
msgstr ""

#: ../../design/database.rst:581
msgid "The type of relationship may alternately be a verb, making the statement:"
msgstr ""

#: ../../design/database.rst:583
msgid "\"**{subject}** **{verb}** **{target}**.\""
msgstr ""

#: ../../design/database.rst:585
msgid "E.g. User A \"likes\" blog post B"
msgstr ""

#: ../../design/database.rst:587
msgid "**Each relationship has direction.** Imagine an archer shoots an arrow at a target; The arrow moves in one direction, binding the subject (the archer) to the target."
msgstr ""

#: ../../design/database.rst:591
msgid "**A relationship does not imply reciprocity**. **A** follows **B** does not imply that **B** follows **A**."
msgstr ""

#: ../../design/database.rst:594
msgid "**Relationships_ do not have access control.** They're never hidden from view and can be edited with code at any privilege level, with the caveat that *the entities* in a relationship may be invisible due to access control!"
msgstr ""

#: ../../design/database.rst:600
msgid "Working with relationships"
msgstr ""

#: ../../design/database.rst:603
msgid "Creating a relationship"
msgstr ""

#: ../../design/database.rst:605
msgid "E.g. to establish that \"**$user** is a **fan** of **$artist**\" (user is the subject, artist is the target):"
msgstr ""

#: ../../design/database.rst:616
msgid "This triggers the event [create, relationship], passing in the created ``ElggRelationship`` object. If a handler returns ``false``, the relationship will not be created and ``$success`` will be ``false``."
msgstr ""

#: ../../design/database.rst:622
msgid "Verifying a relationship"
msgstr ""

#: ../../design/database.rst:624
msgid "E.g. to verify that \"**$user** is a **fan** of **$artist**\":"
msgstr ""

#: ../../design/database.rst:632
msgid "Note that, if the relationship exists, ``check_entity_relationship()`` returns an ``ElggRelationship`` object:"
msgstr ""

#: ../../design/database.rst:643
msgid "Deleting a relationship"
msgstr ""

#: ../../design/database.rst:645
msgid "E.g. to be able to assert that \"**$user** is no longer a **fan** of **$artist**\":"
msgstr ""

#: ../../design/database.rst:651
msgid "This triggers the event [delete, relationship], passing in the associated ``ElggRelationship`` object. If a handler returns ``false``, the relationship will remain, and ``$was_removed`` will be ``false``."
msgstr ""

#: ../../design/database.rst:656
msgid "Other useful functions:"
msgstr ""

#: ../../design/database.rst:658
msgid "``delete_relationship()`` : delete by ID"
msgstr ""

#: ../../design/database.rst:659
msgid "``remove_entity_relationships()`` : delete those relating to an entity (*note:* in versions before Elgg 1.9, this did not trigger delete events)"
msgstr ""

#: ../../design/database.rst:662
msgid "Finding relationships and related entities"
msgstr ""

#: ../../design/database.rst:664
msgid "Below are a few functions to fetch relationship objects and/or related entities. A few are listed below:"
msgstr ""

#: ../../design/database.rst:667
msgid "``get_entity_relationships()`` : fetch relationships by subject or target entity"
msgstr ""

#: ../../design/database.rst:668
msgid "``get_relationship()`` : get a relationship object by ID"
msgstr ""

#: ../../design/database.rst:669
msgid "``elgg_get_entities_from_relationship()`` : fetch entities in relationships in a variety of ways"
msgstr ""

#: ../../design/database.rst:672
msgid "E.g. retrieving users who joined your site in January 2014."
msgstr ""

#: ../../design/database.rst:686
msgid "Access Control"
msgstr ""

#: ../../design/database.rst:688
msgid "Granular access controls are one of the fundamental design principles in Elgg, and a feature that has been at the centre of the system throughout its development. The idea is simple: a user should have full control over who sees an item of data he or she creates."
msgstr ""

#: ../../design/database.rst:694
msgid "Access controls in the data model"
msgstr ""

#: ../../design/database.rst:696
msgid "In order to achieve this, every entity, annotation and piece of metadata contains an ``access_id`` property, which in turn corresponds to one of the pre-defined access controls or an entry in the ``access_collections`` database table."
msgstr ""

#: ../../design/database.rst:702
msgid "Pre-defined access controls"
msgstr ""

#: ../../design/database.rst:704
msgid "**0** Private."
msgstr ""

#: ../../design/database.rst:705
msgid "**1** Logged in users."
msgstr ""

#: ../../design/database.rst:706
msgid "**2** Public data."
msgstr ""

#: ../../design/database.rst:709
msgid "User defined access controls"
msgstr ""

#: ../../design/database.rst:711
msgid "You may define additional access groups and assign them to an entity, annotation or metadata. A number of functions have been defined to assist you; see the `access library reference`_ for more information."
msgstr ""

#: ../../design/database.rst:716
msgid "How access affects data retrieval"
msgstr ""

#: ../../design/database.rst:718
msgid "All data retrieval functions above the database layer - for example ``get_entities`` and its cousins - will only return items that the current user has access to see. It is not possible to retrieve items that the current user does not have access to. This makes it very hard to create a security hole for retrieval."
msgstr ""

#: ../../design/database.rst:727
msgid "Write access"
msgstr ""

#: ../../design/database.rst:729
msgid "The following rules govern write access:"
msgstr ""

#: ../../design/database.rst:731
msgid "The owner of an entity can always edit it"
msgstr ""

#: ../../design/database.rst:732
msgid "The owner of a container can edit anything therein (note that this does not mean that the owner of a group can edit anything therein)"
msgstr ""

#: ../../design/database.rst:734
msgid "Admins can edit anything"
msgstr ""

#: ../../design/database.rst:736
msgid "You can override this behaviour using a :ref:`plugin hook <design/events#plugin-hooks>` called ``permissions_check``, which passes the entity in question to any function that has announced it wants to be referenced. Returning ``true`` will allow write access; returning ``false`` will deny it. See :ref:`the plugin hook reference for permissions\\_check <guides/hooks-list#permission-hooks>` for more details."
msgstr ""

#: ../../design/database.rst:744
msgid "`Access library reference`_"
msgstr ""

#: ../../design/database.rst:749
msgid "Schema"
msgstr ""

#: ../../design/database.rst:751
msgid "The database contains a number of primary tables and secondary tables. Its schema table is stored in ``/engine/schema/mysql.sql``."
msgstr ""

#: ../../design/database.rst:754
msgid "Each table is prefixed by \"prefix\\_\", this is replaced by the Elgg framework during installation."
msgstr ""

#: ../../design/database.rst:758
msgid "Main tables"
msgstr ""

#: ../../design/database.rst:760
msgid "This is a description of the main tables. Keep in mind that in a given Elgg installation, the tables will have a prefix (typically \"elgg\\_\")."
msgstr ""

#: ../../design/database.rst:764
msgid "Table: entities"
msgstr ""

#: ../../design/database.rst:766
msgid "This is the main `Entities`_ table containing Elgg users, sites, objects and groups. When you first install Elgg this is automatically populated with your first site."
msgstr ""

#: ../../design/database.rst:770
msgid "It contains the following fields:"
msgstr ""

#: ../../design/database.rst:772
msgid "**guid** An auto-incrementing counter producing a GUID that uniquely identifies this entity in the system."
msgstr ""

#: ../../design/database.rst:774
msgid "**type** The type of entity - object, user, group or site"
msgstr ""

#: ../../design/database.rst:775
msgid "**subtype** A link to the `entity_subtypes` table."
msgstr ""

#: ../../design/database.rst:776
msgid "**owner\\_guid** The GUID of the owner's entity."
msgstr ""

#: ../../design/database.rst:777
msgid "**site\\_guid** The site the entity belongs to."
msgstr ""

#: ../../design/database.rst:778
msgid "**container\\_guid** The GUID this entity is contained by - either a user or a group."
msgstr ""

#: ../../design/database.rst:780
msgid "**access\\_id** Access controls on this entity."
msgstr ""

#: ../../design/database.rst:781
msgid "**time\\_created** Unix timestamp of when the entity is created."
msgstr ""

#: ../../design/database.rst:782
msgid "**time\\_updated** Unix timestamp of when the entity was updated."
msgstr ""

#: ../../design/database.rst:783
msgid "**enabled** If this is 'yes' an entity is accessible, if 'no' the entity has been disabled (Elgg treats it as if it were deleted without actually removing it from the database)."
msgstr ""

#: ../../design/database.rst:788
msgid "Table: entity\\_subtypes"
msgstr ""

#: ../../design/database.rst:790
msgid "This table contains entity subtype information:"
msgstr ""

#: ../../design/database.rst:792
#: ../../design/database.rst:802
#: ../../design/database.rst:820
msgid "**id** A counter."
msgstr ""

#: ../../design/database.rst:793
msgid "**type** The type of entity - object, user, group or site."
msgstr ""

#: ../../design/database.rst:794
msgid "**subtype** The subtype name as a string."
msgstr ""

#: ../../design/database.rst:795
msgid "**class** Optional class name if this subtype is linked with a class"
msgstr ""

#: ../../design/database.rst:798
msgid "Table: metadata"
msgstr ""

#: ../../design/database.rst:800
msgid "This table contains `Metadata`_, extra information attached to an entity."
msgstr ""

#: ../../design/database.rst:803
#: ../../design/database.rst:821
msgid "**entity\\_guid** The entity this is attached to."
msgstr ""

#: ../../design/database.rst:804
msgid "**name\\_id** A link to the metastrings table defining the name table."
msgstr ""

#: ../../design/database.rst:806
#: ../../design/database.rst:824
msgid "**value\\_id** A link to the metastrings table defining the value."
msgstr ""

#: ../../design/database.rst:807
#: ../../design/database.rst:825
msgid "**value\\_type** The value class, either text or an integer."
msgstr ""

#: ../../design/database.rst:808
#: ../../design/database.rst:826
msgid "**owner\\_guid** The owner GUID of the owner who set this item of metadata."
msgstr ""

#: ../../design/database.rst:810
#: ../../design/database.rst:828
msgid "**access\\_id** An Access controls on this item of metadata."
msgstr ""

#: ../../design/database.rst:811
#: ../../design/database.rst:829
msgid "**time\\_created** Unix timestamp of when the metadata is created."
msgstr ""

#: ../../design/database.rst:812
#: ../../design/database.rst:830
msgid "**enabled** If this is 'yes' an item is accessible, if 'no' the item has been deleted."
msgstr ""

#: ../../design/database.rst:816
msgid "Table: annotations"
msgstr ""

#: ../../design/database.rst:818
msgid "This table contains `Annotations`_, this is distinct from `Metadata`_."
msgstr ""

#: ../../design/database.rst:822
msgid "**name\\_id** A link to the metastrings table defining the type of annotation."
msgstr ""

#: ../../design/database.rst:834
msgid "Table: relationships"
msgstr ""

#: ../../design/database.rst:836
msgid "This table defines `Relationships`_, these link one entity with another."
msgstr ""

#: ../../design/database.rst:838
msgid "**guid\\_one** The GUID of the subject entity."
msgstr ""

#: ../../design/database.rst:839
msgid "**relationship** The type of the relationship."
msgstr ""

#: ../../design/database.rst:840
msgid "**guid\\_two** The GUID of the target entity."
msgstr ""

#: ../../design/database.rst:843
msgid "Table: objects\\_entity"
msgstr ""

#: ../../design/database.rst:845
msgid "Extra information specifically relating to objects. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata."
msgstr ""

#: ../../design/database.rst:850
msgid "Table: sites\\_entity"
msgstr ""

#: ../../design/database.rst:852
msgid "Extra information specifically relating to sites. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata."
msgstr ""

#: ../../design/database.rst:857
msgid "Table: users\\_entity"
msgstr ""

#: ../../design/database.rst:859
msgid "Extra information specifically relating to users. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata."
msgstr ""

#: ../../design/database.rst:864
msgid "Table: groups\\_entity"
msgstr ""

#: ../../design/database.rst:866
msgid "Extra information specifically relating to groups. These are split in order to reduce load on the metadata table and make an obvious difference between attributes and metadata."
msgstr ""

#: ../../design/database.rst:871
msgid "Table: metastrings"
msgstr ""

#: ../../design/database.rst:873
msgid "Metastrings contain the actual string of metadata which is linked to by the metadata and annotations tables."
msgstr ""

#: ../../design/database.rst:876
msgid "This is to avoid duplicating strings, saving space and making database lookups more efficient."
msgstr ""

#: ../../design/database.rst:879
msgid "Core developers will place schema upgrades in ``/engine/schema/upgrades/*``."
msgstr ""

#: ../../design/events.rst:2
msgid "Events and Plugin Hooks"
msgstr ""

#: ../../design/events.rst:11
msgid "Elgg has an event system that can be used to replace or extend core functionality."
msgstr ""

#: ../../design/events.rst:14
msgid "Plugins influence the system by creating handlers (`callables <http://php.net/manual/en/language.types.callable.php>`_ such as functions and methods) and registering them to handle two types of events: `Elgg Events`_ and `Plugin Hooks`_."
msgstr ""

#: ../../design/events.rst:18
msgid "When an event is triggered, a set of handlers is executed in order of priority. Each handler is passed arguments and has a chance to influence the process. After execution, the \"trigger\" function returns a value based on the behavior of the handlers."
msgstr ""

#: ../../design/events.rst:24
msgid "Elgg Events vs. Plugin Hooks"
msgstr ""

#: ../../design/events.rst:26
msgid "The main differences between `Elgg Events`_ and `Plugin Hooks`_ are:"
msgstr ""

#: ../../design/events.rst:28
msgid "Most Elgg events can be cancelled; unless the event is an \"after\" event, a handler that returns `false` can cancel the event, and no more handlers are called."
msgstr ""

#: ../../design/events.rst:31
msgid "Plugin hooks cannot be cancelled; all handlers are always called."
msgstr ""

#: ../../design/events.rst:32
msgid "Plugin hooks pass an arbitrary value through the handlers, giving each a chance to alter along the way."
msgstr ""

#: ../../design/events.rst:37
msgid "Elgg Events"
msgstr ""

#: ../../design/events.rst:39
msgid "Elgg Events are triggered when an Elgg object is created, updated, or deleted; and at important milestones while the Elgg framework is loading. Examples: a blog post being created or a user logging in."
msgstr ""

#: ../../design/events.rst:43
msgid "Unlike `Plugin Hooks`_, *most Elgg events can be cancelled*, halting the execution of the handlers, and possibly cancelling an some action in the Elgg core."
msgstr ""

#: ../../design/events.rst:47
msgid "Each Elgg event has a name and an object type (system, user, object, relationship name, annotation, group) describing the type of object passed to the handlers."
msgstr ""

#: ../../design/events.rst:52
msgid "Before and After Events"
msgstr ""

#: ../../design/events.rst:54
msgid "Some events are split into \"before\" and \"after\". This avoids confusion around the state of the system while in flux. E.g. Is the user logged in during the [login, user] event?"
msgstr ""

#: ../../design/events.rst:58
msgid "Before Events have names ending in \":before\" and are triggered before something happens. Like traditional events, handlers can cancel the event by returning `false`."
msgstr ""

#: ../../design/events.rst:62
msgid "After Events, with names ending in \":after\", are triggered after something happens. Unlike traditional events, handlers *cannot* cancel these events; all handlers will always be called."
msgstr ""

#: ../../design/events.rst:66
msgid "Where before and after events are available, developers are encouraged to transition to them, though older events will be supported for backwards compatibility."
msgstr ""

#: ../../design/events.rst:71
msgid "Elgg Event Handlers"
msgstr ""

#: ../../design/events.rst:73
msgid "Elgg event handlers should have the following prototype:"
msgstr ""

#: ../../design/events.rst:88
msgid "If the handler returns `false`, the event is cancelled, preventing execution of the other handlers. All other return values are ignored."
msgstr ""

#: ../../design/events.rst:92
msgid "Register to handle an Elgg Event"
msgstr ""

#: ../../design/events.rst:94
msgid "Register your handler to an event using ``elgg_register_event_handler``:"
msgstr ""

#: ../../design/events.rst:100
#: ../../design/events.rst:147
#: ../../design/events.rst:202
#: ../../design/events.rst:230
msgid "Parameters:"
msgstr ""

#: ../../design/events.rst:102
#: ../../design/events.rst:149
msgid "**$event** The event name."
msgstr ""

#: ../../design/events.rst:103
msgid "**$object_type** The object type (e.g. \"user\" or \"object\") or 'all' for all types on which the event is fired."
msgstr ""

#: ../../design/events.rst:105
#: ../../design/events.rst:206
msgid "**$handler** The callback of the handler function."
msgstr ""

#: ../../design/events.rst:106
#: ../../design/events.rst:207
msgid "**$priority** The priority - 0 is first and the default is 500."
msgstr ""

#: ../../design/events.rst:108
msgid "**Object** here does not refer to an ``ElggObject`` but rather a string describing any object in the framework: system, user, object, relationship, annotation, group."
msgstr ""

#: ../../design/events.rst:111
#: ../../design/events.rst:212
msgid "Example:"
msgstr ""

#: ../../design/events.rst:121
msgid "Trigger an Elgg Event"
msgstr ""

#: ../../design/events.rst:123
msgid "You can trigger a custom Elgg event using ``elgg_trigger_event``:"
msgstr ""

#: ../../design/events.rst:133
msgid "For events with ambiguous states, like logging in a user, you should use `Before and After Events`_ by calling ``elgg_trigger_before_event`` or ``elgg_trigger_after_event``. This makes it clear for the event handler what state to expect and which events can be cancelled."
msgstr ""

#: ../../design/events.rst:150
msgid "**$object_type** The object type (e.g. \"user\" or \"object\")."
msgstr ""

#: ../../design/events.rst:151
msgid "**$object** The object (e.g. an instance of ``ElggUser`` or ``ElggGroup``)"
msgstr ""

#: ../../design/events.rst:153
msgid "The function will return ``false`` if any of the selected handlers returned ``false`` and the event is stoppable, otherwise it will return ``true``."
msgstr ""

#: ../../design/events.rst:159
msgid "Plugin Hooks"
msgstr ""

#: ../../design/events.rst:161
msgid "Plugin Hooks provide a way for plugins to collaboratively determine or alter a value. For example, to decide whether a user has permission to edit an entity or to add additional configuration options to a plugin."
msgstr ""

#: ../../design/events.rst:165
msgid "A plugin hook has a value passed into the trigger function, and each handler has an opportunity to alter the value before it's passed to the next handler. After the last handler has completed, the final value is returned by the trigger."
msgstr ""

#: ../../design/events.rst:171
msgid "Plugin Hook Handlers"
msgstr ""

#: ../../design/events.rst:173
msgid "Plugin hook handlers should have the following prototype:"
msgstr ""

#: ../../design/events.rst:189
msgid "If the handler returns no value (or `null` explicitly), the plugin hook value is not altered. Otherwise the return value becomes the new value of the plugin hook. It will then be passed to the next handler as `$value`."
msgstr ""

#: ../../design/events.rst:194
msgid "Register to handle a Plugin Hook"
msgstr ""

#: ../../design/events.rst:196
msgid "Register your handler to a plugin hook using ``elgg_register_plugin_hook_handler``:"
msgstr ""

#: ../../design/events.rst:204
#: ../../design/events.rst:232
msgid "**$hook** The name of the plugin hook."
msgstr ""

#: ../../design/events.rst:205
#: ../../design/events.rst:233
msgid "**$type** The type of the hook or 'all' for all types."
msgstr ""

#: ../../design/events.rst:209
msgid "**Type** can vary in meaning. It may mean an Elgg entity type or something specific to the plugin hook name."
msgstr ""

#: ../../design/events.rst:221
msgid "Trigger a Plugin Hook"
msgstr ""

#: ../../design/events.rst:223
msgid "You can trigger a custom plugin hook using ``elgg_trigger_plugin_hook``:"
msgstr ""

#: ../../design/events.rst:234
msgid "**$params** Arbitrary data passed from the trigger to the handlers."
msgstr ""

#: ../../design/events.rst:235
msgid "**$value** The initial value of the plugin hook."
msgstr ""

#: ../../design/events.rst:237
msgid "The `$params` and `$value` arguments are reversed between the plugin hook handlers and trigger functions!"
msgstr ""

#: ../../design/i18n.rst:2
msgid "Internationalization"
msgstr ""

#: ../../design/i18n.rst:4
msgid "Elgg 1.0+ departs from previous versions in that it uses a custom text array rather than gettext. This improves system performance and reliability of the translation system."
msgstr ""

#: ../../design/i18n.rst:7
msgid "TODO: more plz"
msgstr ""

#: ../../design/index.rst:2
msgid "Design Docs"
msgstr ""

#: ../../design/index.rst:4
msgid "Gain a deep understanding of how Elgg works and why it's built the way it is."
msgstr ""

#: ../../design/loggable.rst:2
msgid "Loggable"
msgstr ""

#: ../../design/loggable.rst:4
msgid "Loggable is an interface inherited by any class that wants events relating to its member objects to be saved to the system log. ``ElggEntity`` and ``ElggExtender`` both inherit ``Loggable``."
msgstr ""

#: ../../design/loggable.rst:6
msgid "Loggable defines several class methods that are used in saving to the default system log, and can be used to define your own (as well as for other purposes):"
msgstr ""

#: ../../design/loggable.rst:8
msgid "``getSystemLogID()`` Return a unique identifier for the object for storage in the system log. This is likely to be the object's GUID"
msgstr ""

#: ../../design/loggable.rst:9
msgid "``getClassName()`` Return the class name of the object"
msgstr ""

#: ../../design/loggable.rst:10
msgid "``getType()`` Return the object type"
msgstr ""

#: ../../design/loggable.rst:11
msgid "``getSubtype()`` Get the object subtype"
msgstr ""

#: ../../design/loggable.rst:12
msgid "``getObjectFromID($id)`` For a given ID, return the object associated with it"
msgstr ""

#: ../../design/loggable.rst:13
msgid "``getObjectOwnerGUID()`` Return the GUID of the owner of this object"
msgstr ""

#: ../../design/loggable.rst:16
msgid "Database details"
msgstr ""

#: ../../design/loggable.rst:18
msgid "The default system log is stored in the ``system_log`` :doc:`database table <database>`. It contains the following fields:"
msgstr ""

#: ../../design/loggable.rst:20
msgid "**id** - A unique numeric row ID"
msgstr ""

#: ../../design/loggable.rst:21
msgid "**object_id** - The GUID of the entity being acted upon"
msgstr ""

#: ../../design/loggable.rst:22
msgid "**object_class** - The class of the entity being acted upon (eg ElggObject)"
msgstr ""

#: ../../design/loggable.rst:23
msgid "**object_type** - The type of the entity being acted upon (eg object)"
msgstr ""

#: ../../design/loggable.rst:24
msgid "**object_subtype** - The subtype of the entity being acted upon (eg blog)"
msgstr ""

#: ../../design/loggable.rst:25
msgid "**event** - The event being logged (eg create or update)"
msgstr ""

#: ../../design/loggable.rst:26
msgid "**performed_by_guid** - The GUID of the acting entity (the user performing the action)"
msgstr ""

#: ../../design/loggable.rst:27
msgid "**owner_guid** - The GUID of the user which owns the entity being acted upon"
msgstr ""

#: ../../design/loggable.rst:28
msgid "**access_id** - The access restriction associated with this log entry"
msgstr ""

#: ../../design/loggable.rst:29
msgid "**time_created** - The UNIX epoch timestamp of the time the event took place"
msgstr ""

#: ../../design/security.rst:2
msgid "Security"
msgstr ""

#: ../../design/security.rst:4
msgid "Elgg’s approach to the various security issues common to all web applications."
msgstr ""

#: ../../design/security.rst:8
msgid "To report a potential vulnerability in Elgg, email security@elgg.org."
msgstr ""

#: ../../design/security.rst:15
msgid "Passwords"
msgstr ""

#: ../../design/security.rst:18
msgid "Password validation"
msgstr ""

#: ../../design/security.rst:20
msgid "The only restriction that Elgg places on a password is that it must be at least 6 characters long by default, though this may be changed in /engine/settings.php. Additional criteria can be added by a plugin by registering for the ``registeruser:validate:password`` plugin hook."
msgstr ""

#: ../../design/security.rst:23
msgid "Password salting"
msgstr ""

#: ../../design/security.rst:27
msgid "Elgg salts passwords with a unique 8 character random string. The salt is generated each time the password is set. The main security advantages of the salting are:"
msgstr ""

#: ../../design/security.rst:26
msgid "preventing anyone with access to the database from conducting a precomputed dictionary attack"
msgstr ""

#: ../../design/security.rst:27
msgid "preventing a site administration from noting users with the same password."
msgstr ""

#: ../../design/security.rst:30
msgid "Password hashing"
msgstr ""

#: ../../design/security.rst:32
msgid "The hashed password is computed using md5 from the user's password text and the salt."
msgstr ""

#: ../../design/security.rst:35
msgid "Password storage"
msgstr ""

#: ../../design/security.rst:37
msgid "The hashed password and the salt are stored in the users table. Neither are stored in any cookies on a user's computer."
msgstr ""

#: ../../design/security.rst:40
msgid "Password throttling"
msgstr ""

#: ../../design/security.rst:42
msgid "Elgg has a password throttling mechanism to make dictionary attacks from the outside very difficult. A user is only allowed 5 login attempts over a 5 minute period."
msgstr ""

#: ../../design/security.rst:45
msgid "Password resetting"
msgstr ""

#: ../../design/security.rst:47
msgid "If a user forgets his password, a new random password can be requested. After the request, an email is sent with a unique URL. When the user visits that URL, a new random password is sent to the user through email."
msgstr ""

#: ../../design/security.rst:50
msgid "Sessions"
msgstr ""

#: ../../design/security.rst:52
msgid "Elgg uses PHP's session handling with custom handlers. Session data is stored in the database. The session cookie contains the session id that links the user to the browser. The user's metadata is stored in the session including GUID, username, email address. The session's lifetime is controlled through the server's PHP configuration."
msgstr ""

#: ../../design/security.rst:55
msgid "Session fixation"
msgstr ""

#: ../../design/security.rst:56
msgid "Elgg protects against session fixation by regenerating the session id when a user logs in."
msgstr ""

#: ../../design/security.rst:59
msgid "Session hijacking"
msgstr ""

#: ../../design/security.rst:60
msgid "This section is questionable."
msgstr ""

#: ../../design/security.rst:62
msgid "Besides protecting against session fixation attacks, Elgg also has a further check to try to defeat session hijacking if the session identifier is compromised. Elgg stores a hash of the browser's user agent and a site secret as a session fingerprint. The use of the site secret is rather superfluous but checking the user agent might prevent some session hijacking attempts."
msgstr ""

#: ../../design/security.rst:65
msgid "“Remember me” cookie"
msgstr ""

#: ../../design/security.rst:66
msgid "To allow users to stay logged in for a longer period of time regardless of whether the browser has been closed, Elgg uses a cookie (called elggperm) that contains what could be considered a super session identifier. This identifier is stored in a cookies table. When a session is being initiated, Elgg checks for the presence of the elggperm cookie. If it exists and the session code in the cookie matches the code in the cookies table, the corresponding user is automatically logged in."
msgstr ""

#: ../../design/security.rst:69
msgid "Alternative authentication"
msgstr ""

#: ../../design/security.rst:71
msgid "This section is very hand-wavy"
msgstr ""

#: ../../design/security.rst:73
msgid "To replace Elgg's default user authentication system, a plugin would have to replace the default action with its own through ``register_action()``. It would also have to register its own pam handler using ``register_pam_handler()``."
msgstr ""

#: ../../design/security.rst:75
msgid "The ``pam_authenticate()`` function used to call the different modules has a bug related to the importance variable."
msgstr ""

#: ../../design/security.rst:79
msgid "HTTPS"
msgstr ""

#: ../../design/security.rst:81
msgid "You must enable SSL support on your server for any of these techniques to work."
msgstr ""

#: ../../design/security.rst:83
msgid "To make the login form submit over https, turn on login-over-ssl from Elgg’s admin panel."
msgstr ""

#: ../../design/security.rst:85
msgid "You can also serve your whole site over SSL by simply changing the site URL to include “https” instead of just “http.”"
msgstr ""

#: ../../design/security.rst:88
msgid "XSS"
msgstr ""

#: ../../design/security.rst:90
msgid "Filtering is used in Elgg to make XSS attacks more difficult. The purpose of the filtering is to remove Javascript and other dangerous input from users."
msgstr ""

#: ../../design/security.rst:92
msgid "Filtering is performed through the function ``filter_tags()``. This function takes in a string and returns a filtered string. It triggers a ``validate, input`` plugin hook."
msgstr ""

#: ../../design/security.rst:94
msgid "By default Elgg comes with the htmLawed filtering code as a plugin. Developers can drop in any additional or replacement filtering code as a plugin."
msgstr ""

#: ../../design/security.rst:96
msgid "The ``filter_tags()`` function is called on any user input as long as the input is obtained through a call to ``get_input()``. If for some reason a developer did not want to perform the default filtering on some user input, the ``get_input()`` function has a parameter for turning off filtering."
msgstr ""

#: ../../design/security.rst:99
msgid "CSRF / XSRF"
msgstr ""

#: ../../design/security.rst:101
msgid "Elgg generates security tokens to prevent `cross-site request forgery`_. These are embedded in all forms and state-modifying AJAX requests as long as the correct API is used. Read more in the :doc:`/guides/actions` developer guide."
msgstr ""

#: ../../design/security.rst:104
msgid "SQL Injection"
msgstr ""

#: ../../design/security.rst:106
msgid "Elgg’s API sanitizes all input before issuing DB queries. Read more in the :doc:`/design/database` design doc."
msgstr ""

#: ../../design/security.rst:109
msgid "Privacy"
msgstr ""

#: ../../design/security.rst:111
msgid "Elgg uses an ACL system to control which users have access to various pieces of content. Read more in the :doc:`/design/database` design doc."
msgstr ""

