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

#: ../../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 "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 "If you want to use JavaScript in Elgg: we use a `AMD (Asynchronous Module Definition) <http://requirejs.org/docs/whyamd.html>`_ compatible system."
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:8
#: ../../design/events.rst:6
#: ../../design/security.rst:12
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 because 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, containment and provides consistent API for accessing and updating entity properties."
msgstr ""

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

#: ../../design/database.rst:33
msgid "``Metadata``: This information describes the entity, it is usually"
msgstr ""

#: ../../design/database.rst:31
msgid "added by the author of the entity when the entity is created or updated. Examples of metadata include tags, ISBN number or a third-party ID, location, geocoordinates etc. Think of metadata as a simple key-value storage."
msgstr ""

#: ../../design/database.rst:36
msgid "``Annotations``: This information extends the entity with properties usually"
msgstr ""

#: ../../design/database.rst:36
msgid "added by a third party. Such properties include ratings, likes, and votes."
msgstr ""

#: ../../design/database.rst:38
msgid "The main differences between metadata and annotations:"
msgstr ""

#: ../../design/database.rst:40
msgid "metadata does not have owners, while annotations do"
msgstr ""

#: ../../design/database.rst:41
msgid "metadata is not access controlled, while annotations are"
msgstr ""

#: ../../design/database.rst:42
msgid "metadata is preloaded when entity is constructed, while annotations are only loaded on demand"
msgstr ""

#: ../../design/database.rst:44
msgid "These differences might have implications for performance and your business logic, so consider carefully, how you would like to attach data to your entities."
msgstr ""

#: ../../design/database.rst:47
msgid "In certain cases, it may be benefitial to avoid using metadata and annotations and create new entities instead and attaching them via ``container_guid`` or a relationship."
msgstr ""

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

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

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

#: ../../design/database.rst:63
msgid "``ElggEntity`` is the base class for the Elgg data model and supports a common set of properties and methods."
msgstr ""

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

#: ../../design/database.rst:67
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:69
msgid "An arbitrary subtype (more below)."
msgstr ""

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

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

#: ../../design/database.rst:72
msgid "A container, used to associate content with a group or a user."
msgstr ""

#: ../../design/database.rst:75
msgid "Types"
msgstr ""

#: ../../design/database.rst:77
msgid "*Actual* entities will be instances of four different subclasses, each having a distinct **type** property and their own additional properties and methods."
msgstr ""

#: ../../design/database.rst:81
msgid "Type"
msgstr ""

#: ../../design/database.rst:81
msgid "PHP class"
msgstr ""

#: ../../design/database.rst:81
#: ../../design/database.rst:514
msgid "Represents"
msgstr ""

#: ../../design/database.rst:83
msgid "object"
msgstr ""

#: ../../design/database.rst:83
msgid "``ElggObject``"
msgstr ""

#: ../../design/database.rst:83
msgid "Most user-created content, like blog posts, uploads, and bookmarks."
msgstr ""

#: ../../design/database.rst:84
msgid "group"
msgstr ""

#: ../../design/database.rst:84
msgid "``ElggGroup``"
msgstr ""

#: ../../design/database.rst:84
msgid "An organized group of users with its own profile page"
msgstr ""

#: ../../design/database.rst:85
msgid "user"
msgstr ""

#: ../../design/database.rst:85
msgid "``ElggUser``"
msgstr ""

#: ../../design/database.rst:85
msgid "A user of the system"
msgstr ""

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

#: ../../design/database.rst:86
msgid "``ElggSite``"
msgstr ""

#: ../../design/database.rst:86
msgid "The site served by the Elgg installation"
msgstr ""

#: ../../design/database.rst:89
msgid "Each type has its own extended API. E.g. users can be friends with other users, group can have members, while objects can be liked and commented on."
msgstr ""

#: ../../design/database.rst:93
msgid "Subtypes"
msgstr ""

#: ../../design/database.rst:95
msgid "Each entity must define a **subtype**, which plugins use to further specialize the entity. Elgg makes it easy to query specific for entities of a given subtype(s), as well as assign them special behaviors and views."
msgstr ""

#: ../../design/database.rst:98
msgid "Subtypes are most commonly given to instances of ``ElggEntity`` to denote the kind of content created. E.g. the blog plugin creates objects with subtype ``\"blog\"``."
msgstr ""

#: ../../design/database.rst:101
msgid "By default, users, groups and sites have the the subtypes of ``user``, ``group`` and ``site`` respectively."
msgstr ""

#: ../../design/database.rst:103
msgid "Plugins can use custom entity classes that extend the base type class. To do so, they need to register their class at runtime (e.g. in the ``'init','system'`` handler), using ``elgg_set_entity_class()``. For example, the blog plugin could use ``elgg_set_entity_class('object', 'blog', \\ElggBlog::class)``."
msgstr ""

#: ../../design/database.rst:107
msgid "Plugins can use ``elgg-plugin.php`` to define entity class via shortcut ``entities`` parameter."
msgstr ""

#: ../../design/database.rst:110
msgid "Subtype Gotchas"
msgstr ""

#: ../../design/database.rst:112
msgid "Before an entity's ``save()`` method is called, the subtype must be set by writing a string to the ``subtype`` property."
msgstr ""

#: ../../design/database.rst:113
msgid "*Subtype cannot be changed after saving.*"
msgstr ""

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

#: ../../design/database.rst:118
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:122
msgid "Some Elgg API functions work with GUIDs instead of ``ElggEntity`` objects."
msgstr ""

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

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

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

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

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

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

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

#: ../../design/database.rst:140
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:144
msgid "Beyond the standard ElggEntity properties, ElggUsers also support:"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

#: ../../design/database.rst:160
msgid "The ``ElggSite`` entity type represents your Elgg installation (via your site URL)."
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

#: ../../design/database.rst:184
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:189
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:193
msgid "Writing a group-aware plugin"
msgstr ""

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

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

#: ../../design/database.rst:201
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:204
msgid "Use ``ElggEntity->canWriteToContainer(0, $type, $subtype)`` to determine whether or not the current user has the right to add content to a group."
msgstr ""

#: ../../design/database.rst:207
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:238
msgid "Ownership"
msgstr ""

#: ../../design/database.rst:240
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:244
msgid "The ownership of an entity dictates, in part, whether or not you can access or edit that entity."
msgstr ""

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

#: ../../design/database.rst:250
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:255
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:258
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:264
msgid "Annotations"
msgstr ""

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

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

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

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

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

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

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

#: ../../design/database.rst:279
msgid "Like metadata, values are stored as strings unless the value given is a PHP integer (``is_int($value)`` is true), or unless the ``$vartype`` is manually specified as ``integer``."
msgstr ""

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

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

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

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

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

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

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

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

#: ../../design/database.rst:334
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:343
msgid "Metadata"
msgstr ""

#: ../../design/database.rst:345
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:351
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:356
msgid "Metadata has an owner, which may be different to the owner of the entity it's attached to"
msgstr ""

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

#: ../../design/database.rst:360
msgid "Like annotations, values are stored as strings unless the value given is a PHP integer (``is_int($value)`` is true), or unless the ``$value_type`` is manually specified as ``integer`` (see below)."
msgstr ""

#: ../../design/database.rst:363
msgid "As of Elgg 3.0, metadata no longer have ``access_id``."
msgstr ""

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

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

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

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

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

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

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

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

#: ../../design/database.rst:394
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:402
msgid "As of Elgg 3.0, metadata's ``access_id`` property is ignored."
msgstr ""

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

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

#: ../../design/database.rst:413
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:417
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:429
msgid "To always get an array back, simply cast to an array;"
msgstr ""

#: ../../design/database.rst:436
msgid "Reading metadata as objects"
msgstr ""

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

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

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

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

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

#: ../../design/database.rst:467
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:476
msgid "Trying to store hashmaps"
msgstr ""

#: ../../design/database.rst:478
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:487
msgid "You can instead store the information like so:"
msgstr ""

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

#: ../../design/database.rst:498
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:503
msgid "Relationships"
msgstr ""

#: ../../design/database.rst:505
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:508
msgid "The class ``ElggRelationship`` models a directed relationship between two entities, making the statement:"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: ../../design/database.rst:527
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:531
msgid "**A relationship does not imply reciprocity**. **A** follows **B** does not imply that **B** follows **A**."
msgstr ""

#: ../../design/database.rst:534
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:540
msgid "Working with relationships"
msgstr ""

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

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

#: ../../design/database.rst:556
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:562
msgid "Verifying a relationship"
msgstr ""

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

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

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

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

#: ../../design/database.rst:591
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:596
msgid "Other useful functions:"
msgstr ""

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

#: ../../design/database.rst:599
msgid "``remove_entity_relationships()`` : delete those relating to an entity"
msgstr ""

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

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

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

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

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

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

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

#: ../../design/database.rst:628
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:634
msgid "Access controls in the data model"
msgstr ""

#: ../../design/database.rst:636
msgid "In order to achieve this, every entity and annotation 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:642
msgid "Pre-defined access controls"
msgstr ""

#: ../../design/database.rst:644
msgid "``ACCESS_PRIVATE`` (value: 0) Private."
msgstr ""

#: ../../design/database.rst:645
msgid "``ACCESS_LOGGED_IN`` (value: 1) Logged in users."
msgstr ""

#: ../../design/database.rst:646
msgid "``ACCESS_PUBLIC`` (value: 2) Public data."
msgstr ""

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

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

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

#: ../../design/database.rst:658
msgid "All data retrieval functions above the database layer - for example ``elgg_get_entities`` 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:665
msgid "Write access"
msgstr ""

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

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

#: ../../design/database.rst:670
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:672
msgid "Admins can edit anything"
msgstr ""

#: ../../design/database.rst:674
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:681
msgid "Schema"
msgstr ""

#: ../../design/database.rst:683
msgid "The database contains a number of primary and secondary tables. You can follow schema changes in ``engine/schema/migrations/``"
msgstr ""

#: ../../design/database.rst:685
msgid "The character set of the database should be ``utf8mb4``, this will provide full unicode character support when storing data."
msgstr ""

#: ../../design/database.rst:688
msgid "InnoDB"
msgstr ""

#: ../../design/database.rst:690
msgid "As of Elgg 3.0 the database uses the InnoDB engine. In order for a correct installation or migration some settings may need to be adjusted in the database settings."
msgstr ""

#: ../../design/database.rst:693
msgid "``innodb_large_prefix`` should be ``on``"
msgstr ""

#: ../../design/database.rst:694
msgid "``innodb_file_format`` should be ``Barracuda``"
msgstr ""

#: ../../design/database.rst:695
msgid "``innodb_file_per_table`` should be ``1``"
msgstr ""

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

#: ../../design/database.rst:700
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:704
msgid "Table: entities"
msgstr ""

#: ../../design/database.rst:706
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:710
msgid "It contains the following fields:"
msgstr ""

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

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

#: ../../design/database.rst:714
msgid "**subtype** A subtype of entity"
msgstr ""

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

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

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

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

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

#: ../../design/database.rst:720
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:725
msgid "Table: metadata"
msgstr ""

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

#: ../../design/database.rst:729
#: ../../design/database.rst:742
#: ../../design/database.rst:769
msgid "**id** A unique IDentifier"
msgstr ""

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

#: ../../design/database.rst:731
#: ../../design/database.rst:744
msgid "**name** The name string"
msgstr ""

#: ../../design/database.rst:732
#: ../../design/database.rst:745
msgid "**value** The value string"
msgstr ""

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

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

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

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

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

#: ../../design/database.rst:747
msgid "**owner\\_guid** The owner GUID of the owner who set this annotation"
msgstr ""

#: ../../design/database.rst:748
msgid "**access\\_id** An Access controls on this annotation"
msgstr ""

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

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

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

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

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

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

#: ../../design/database.rst:762
msgid "Secundairy tables"
msgstr ""

#: ../../design/database.rst:765
msgid "Table: access_collections"
msgstr ""

#: ../../design/database.rst:767
msgid "This table defines Access Collections, which grant users access to `Entities`_ or `Annotations`_."
msgstr ""

#: ../../design/database.rst:770
msgid "***name**  The name of the access collection"
msgstr ""

#: ../../design/database.rst:771
msgid "**owner_guid** The GUID of the owning entity (eg. a user or a group)"
msgstr ""

#: ../../design/database.rst:772
msgid "**subtype** the subtype of the access collection (eg. `friends` or `group_acl`)"
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: :ref:`design/events#events` and :ref:`design/events#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:25
msgid ":doc:`/guides/events-list`"
msgstr ""

#: ../../design/events.rst:26
msgid ":doc:`/guides/hooks-list`"
msgstr ""

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

#: ../../design/events.rst:31
msgid "The main differences between :ref:`design/events#events` and :ref:`design/events#plugin-hooks` are:"
msgstr ""

#: ../../design/events.rst:33
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:36
msgid "Plugin hooks cannot be cancelled; all handlers are always called."
msgstr ""

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

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

#: ../../design/events.rst:45
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:49
msgid "Unlike :ref:`design/events#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:53
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:60
msgid "Before and After Events"
msgstr ""

#: ../../design/events.rst:62
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:66
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:70
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:74
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:79
msgid "Elgg Event Handlers"
msgstr ""

#: ../../design/events.rst:81
msgid "Elgg event handlers are callables:"
msgstr ""

#: ../../design/events.rst:96
msgid "In ``event_handler``, the ``Event`` object has various methods for getting the name, object type, and object of the event. See the ``Elgg\\Event`` class for details."
msgstr ""

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

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

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

#: ../../design/events.rst:113
#: ../../design/events.rst:193
#: ../../design/events.rst:220
#: ../../design/events.rst:277
#: ../../design/events.rst:309
msgid "Parameters:"
msgstr ""

#: ../../design/events.rst:115
#: ../../design/events.rst:195
#: ../../design/events.rst:222
msgid "**$event** The event name."
msgstr ""

#: ../../design/events.rst:116
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:118
#: ../../design/events.rst:281
msgid "**$handler** The callback of the handler function."
msgstr ""

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

#: ../../design/events.rst:121
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:124
#: ../../design/events.rst:287
msgid "Example:"
msgstr ""

#: ../../design/events.rst:136
msgid "If you handle the \"update\" event on an object, avoid calling ``save()`` in your event handler. For one it's probably not necessary as the object is saved after the event completes, but also because ``save()`` calls another \"update\" event and makes ``$object->getOriginalAttributes()`` no longer available."
msgstr ""

#: ../../design/events.rst:141
msgid "Invokable classes as handlers"
msgstr ""

#: ../../design/events.rst:143
msgid "You may use a class with an ``__invoke()`` method as a handler. Just register the class name and it will be instantiated (with no arguments) for the lifetime of the event (or hook)."
msgstr ""

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

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

#: ../../design/events.rst:177
msgid "For events with ambiguous states, like logging in a user, you should use :ref:`before-after` 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:196
#: ../../design/events.rst:223
msgid "**$object_type** The object type (e.g. \"user\" or \"object\")."
msgstr ""

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

#: ../../design/events.rst:199
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:205
msgid "Trigger an Elgg Event sequence"
msgstr ""

#: ../../design/events.rst:207
msgid "Instead of triggering the ``:before`` and ``:after`` event manually, it's possible to trigger an event sequence. This will trigger the ``:before`` event, then the actual event and finally the ``:after`` event."
msgstr ""

#: ../../design/events.rst:214
msgid "When called with for example ``'cache:clear', 'system'`` the following three events are triggered"
msgstr ""

#: ../../design/events.rst:216
msgid "``'cache:clear:before', 'system'``"
msgstr ""

#: ../../design/events.rst:217
msgid "``'cache:clear', 'system'``"
msgstr ""

#: ../../design/events.rst:218
msgid "``'cache:clear:after', 'system'``"
msgstr ""

#: ../../design/events.rst:225
msgid "**$callable** Callable to run on successful event, before event:after"
msgstr ""

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

#: ../../design/events.rst:232
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:236
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:242
msgid "Plugin Hook Handlers"
msgstr ""

#: ../../design/events.rst:244
msgid "Hook handlers are callables with the following prototype:"
msgstr ""

#: ../../design/events.rst:259
msgid "In ``plugin_hook_handler``, the ``Hook`` object has various methods for getting the name, type, value, and parameters of the hook. See the ``Elgg\\Hook`` interface for details."
msgstr ""

#: ../../design/events.rst:262
msgid "If the handler returns no value (or ``null`` explicitly), the plugin hook value is not altered. Otherwise the returned value becomes the new value of the plugin hook, and it will then be available as ``$hook->getValue()`` in the next handler."
msgstr ""

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

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

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

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

#: ../../design/events.rst:284
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:298
msgid "Trigger a Plugin Hook"
msgstr ""

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

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

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

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

#: ../../design/events.rst:320
msgid "Unregister Event/Hook Handlers"
msgstr ""

#: ../../design/events.rst:322
msgid "The functions ``elgg_unregister_event_handler`` and ``elgg_unregister_plugin_hook_handler`` can be used to remove handlers already registered by another plugin or Elgg core. The parameters are in the same order as the registration functions, except there's no priority parameter."
msgstr ""

#: ../../design/events.rst:332
msgid "Anonymous functions or invokable objects cannot be unregistered, but dynamic method callbacks can be unregistered by giving the static version of the callback:"
msgstr ""

#: ../../design/events.rst:346
msgid "Even though the event handler references a dynamic method call, the code above will successfully remove the handler."
msgstr ""

#: ../../design/events.rst:350
msgid "Handler Calling Order"
msgstr ""

#: ../../design/events.rst:352
msgid "Handlers are called first in order of priority, then registration order."
msgstr ""

#: ../../design/events.rst:356
msgid "Before Elgg 2.0, registering with the ``all`` keywords caused handlers to be called later, even if they were registered with lower priorities."
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:15
msgid "Database details"
msgstr ""

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

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

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

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

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

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

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

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

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

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

#: ../../design/loggable.rst:28
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 ``/elgg-config/settings.php``. Additional criteria can be added by a plugin by registering for the ``registeruser:validate:password`` plugin hook."
msgstr ""

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

#: ../../design/security.rst:27
msgid "Passwords are never stored in plain text, only salted hashes produced with bcrypt. This is done via the standard ``password_hash()`` function. On older systems, the ``password-compat`` polyfill is used, but the algorithm is identical."
msgstr ""

#: ../../design/security.rst:30
msgid "Elgg installations created before version 1.10 may have residual \"legacy\" password hashes created using salted MD5. These are migrated to bcrypt as users log in, and will be completely removed when a system is upgraded to Elgg 3.0. In the meantime we're happy to assist site owners to manually remove these legacy hashes, though it would force those users to reset their passwords."
msgstr ""

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

#: ../../design/security.rst:37
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:41
msgid "Password resetting"
msgstr ""

#: ../../design/security.rst:43
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:47
msgid "Sessions"
msgstr ""

#: ../../design/security.rst:49
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."
msgstr ""

#: ../../design/security.rst:52
msgid "The session's lifetime is controlled through the server's PHP configuration and additionally through options in the ``/elgg-config/settings.php``."
msgstr ""

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

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

#: ../../design/security.rst:60
msgid "\"Remember me\" cookie"
msgstr ""

#: ../../design/security.rst:62
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 (default 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:67
msgid "When a user changes their password all existing permanent cookie codes are removed from the database."
msgstr ""

#: ../../design/security.rst:69
msgid "The lifetime of the persistent cookie can be controlled in the `/elgg-config/settings.php` file. The default lifetime is 30 days. The database records for the persistent cookies will be removed after the lifetime expired."
msgstr ""

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

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

#: ../../design/security.rst:77
msgid "To replace Elgg's default user authentication system, a plugin could replace the default ``login`` action with its own. Better would be to register a PAM handler using ``register_pam_handler()`` which handles the authentication of the user based on the new requirements."
msgstr ""

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

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

#: ../../design/security.rst:85
msgid "You can serve your whole site over SSL by 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:93
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:96
msgid "By default Elgg comes with the htmLawed filtering code. Developers can drop in any additional or replacement filtering code as a plugin."
msgstr ""

#: ../../design/security.rst:98
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:102
msgid "CSRF / XSRF"
msgstr ""

#: ../../design/security.rst:104
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:108
msgid "Signed URLs"
msgstr ""

#: ../../design/security.rst:110
msgid "It's possible to protect URLs with a unique signature. Read more in the :doc:`/guides/actions` developer guide."
msgstr ""

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

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

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

#: ../../design/security.rst:120
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 ""

#: ../../design/security.rst:125
msgid "Hardening"
msgstr ""

#: ../../design/security.rst:127
msgid "Site administrators can configure settings which will help with hardening the website. Read more in the Administrator guide :doc:`/admin/security`."
msgstr ""

