# SOME DESCRIPTIVE TITLE. # Copyright (C) 2013, Various # This file is distributed under the same license as the Elgg package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Elgg 1.12\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2016-03-06 18:02+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../../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 `, 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) `_ 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 `_ 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 `_ 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 `_ 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 and supports a common set of properties and methods." msgstr "" #: ../../design/database.rst:54 msgid "A numeric Globally Unique IDentifier (See `GUIDs`_)." msgstr "" #: ../../design/database.rst:55 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:57 msgid "An arbitrary subtype (more below)." msgstr "" #: ../../design/database.rst:58 msgid "An owner." msgstr "" #: ../../design/database.rst:59 msgid "The site that the entity belongs to." msgstr "" #: ../../design/database.rst:60 msgid "A container, used to associate content with a group or a user." msgstr "" #: ../../design/database.rst:63 msgid "Types" msgstr "" #: ../../design/database.rst:65 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:69 msgid "Type" msgstr "" #: ../../design/database.rst:69 msgid "PHP class" msgstr "" #: ../../design/database.rst:69 #: ../../design/database.rst:594 msgid "Represents" msgstr "" #: ../../design/database.rst:71 msgid "object" msgstr "" #: ../../design/database.rst:71 msgid "``ElggObject``" msgstr "" #: ../../design/database.rst:71 msgid "Most user-created content, like blog posts, uploads, and bookmarks." msgstr "" #: ../../design/database.rst:72 msgid "group" msgstr "" #: ../../design/database.rst:72 msgid "``ElggGroup``" msgstr "" #: ../../design/database.rst:72 msgid "An organized group of users with its own profile page" msgstr "" #: ../../design/database.rst:73 msgid "user" msgstr "" #: ../../design/database.rst:73 msgid "``ElggUser``" msgstr "" #: ../../design/database.rst:73 msgid "A system user" msgstr "" #: ../../design/database.rst:74 msgid "site" msgstr "" #: ../../design/database.rst:74 msgid "``ElggSite``" msgstr "" #: ../../design/database.rst:74 msgid "The site served by the Elgg installation" msgstr "" #: ../../design/database.rst:77 msgid "Each has its own extended API. E.g. objects have a ``title`` and ``description``, users have a ``username`` and a way to set their password, and so on." msgstr "" #: ../../design/database.rst:81 msgid "Subtypes" msgstr "" #: ../../design/database.rst:83 msgid "Each entity also has a custom string **subtype**, which plugins use to further specialize the entity. Elgg makes it easy to query specific subtypes as well as assign them special behaviors and views." msgstr "" #: ../../design/database.rst:86 msgid "Subtypes are most commonly given to instances of ElggObject to denote the kind of content created. E.g. the blog plugin creates objects with subtype ``\"blog\"``." msgstr "" #: ../../design/database.rst:89 msgid "For historic reasons, the subtype API is a bit complex, but boils down to: write to ``->subtype`` before saving, otherwise always read ``getSubtype()``. Below are more details." msgstr "" #: ../../design/database.rst:93 msgid "Subtype Gotchas" msgstr "" #: ../../design/database.rst:95 msgid "Before an entity's ``save()`` method is called, the subtype can be set by writing a string to the ``subtype`` property." msgstr "" #: ../../design/database.rst:97 msgid "*Subtype cannot be changed after saving.*" msgstr "" #: ../../design/database.rst:98 msgid "After saving, you must always use ``getSubtype()`` to read it." msgstr "" #: ../../design/database.rst:99 msgid "If no subtype was set, ``\"\"`` is returned, however some parts of the Elgg API (like Views) may map this value to the string ``\"default\"``. E.g. a group with ``getSubtype() === \"\"`` will be rendered using the view ``\"group/default\"``." msgstr "" #: ../../design/database.rst:102 msgid "Read carefully the documentation for ``elgg_get_entities()`` before trying to match subtypes; this" msgstr "" #: ../../design/database.rst:103 msgid "API is a bit of a minefield. E.g. you cannot use ``\"\"`` to fetch entities with the default subtype." msgstr "" #: ../../design/database.rst:106 msgid "GUIDs" msgstr "" #: ../../design/database.rst:108 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:112 msgid "Some Elgg API functions work with GUIDs instead of ``ElggEntity`` objects." msgstr "" #: ../../design/database.rst:115 msgid "ElggObject" msgstr "" #: ../../design/database.rst:117 msgid "The ``ElggObject`` entity type represents arbitrary content within an Elgg install; things like blog posts, uploaded files, etc." msgstr "" #: ../../design/database.rst:120 msgid "Beyond the standard ElggEntity properties, ElggObjects also support:" msgstr "" #: ../../design/database.rst:122 msgid "``title`` The title of the object (HTML escaped text)" msgstr "" #: ../../design/database.rst:123 msgid "``description`` A description of the object (HTML)" msgstr "" #: ../../design/database.rst:125 msgid "Most other data about the object is generally stored via metadata." msgstr "" #: ../../design/database.rst:128 msgid "ElggUser" msgstr "" #: ../../design/database.rst:130 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:134 msgid "Beyond the standard ElggEntity properties, ElggUsers also support:" msgstr "" #: ../../design/database.rst:136 msgid "``name`` The user's plain text name. e.g. \"Hugh Jackman\"" msgstr "" #: ../../design/database.rst:137 msgid "``username`` Their login name. E.g. \"hjackman\"" msgstr "" #: ../../design/database.rst:138 msgid "``password`` A hashed version of their password" msgstr "" #: ../../design/database.rst:139 msgid "``salt`` The salt that their password has been hashed with" msgstr "" #: ../../design/database.rst:140 msgid "``email`` Their email address" msgstr "" #: ../../design/database.rst:141 msgid "``language`` Their default language code." msgstr "" #: ../../design/database.rst:142 msgid "``code`` Their session code (moved to a separate table in 1.9)." msgstr "" #: ../../design/database.rst:143 msgid "``last_action`` The UNIX timestamp of the last time they loaded a page" msgstr "" #: ../../design/database.rst:144 msgid "``prev_last_action`` The previous value of ``last_action``" msgstr "" #: ../../design/database.rst:145 msgid "``last_login`` The UNIX timestamp of their last log in" msgstr "" #: ../../design/database.rst:146 msgid "``prev_last_login`` the previous value of ``last_login``" msgstr "" #: ../../design/database.rst:149 msgid "ElggSite" msgstr "" #: ../../design/database.rst:151 msgid "The ``ElggSite`` entity type represents sites within your Elgg install. Most installs will have only one." msgstr "" #: ../../design/database.rst:154 msgid "Beyond the standard ElggEntity properties, ElggSites also support:" msgstr "" #: ../../design/database.rst:156 msgid "``name`` The site name" msgstr "" #: ../../design/database.rst:157 msgid "``description`` A description of the site" msgstr "" #: ../../design/database.rst:158 msgid "``url`` The address of the site" msgstr "" #: ../../design/database.rst:161 msgid "ElggGroup" msgstr "" #: ../../design/database.rst:163 msgid "The ``ElggGroup`` entity type represents an association of Elgg users. Users can join, leave, and post content to groups." msgstr "" #: ../../design/database.rst:166 msgid "Beyond the standard ElggEntity properties, ElggGroups also support:" msgstr "" #: ../../design/database.rst:168 msgid "``name`` The group's name (HTML escaped text)" msgstr "" #: ../../design/database.rst:169 msgid "``description`` A description of the group (HTML)" msgstr "" #: ../../design/database.rst:171 msgid "``ElggGroup`` has addition methods to manage content and membership." msgstr "" #: ../../design/database.rst:174 msgid "The Groups plugin" msgstr "" #: ../../design/database.rst:176 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:181 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:184 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:188 msgid "Writing a group-aware plugin" msgstr "" #: ../../design/database.rst:190 msgid "Plugin owners need not worry too much about writing group-aware functionality, but there are a few key points:" msgstr "" #: ../../design/database.rst:194 msgid "Adding content" msgstr "" #: ../../design/database.rst:196 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:199 msgid "Use `can_write_to_container `_ to determine whether or not the current user has the right to add content to a group." msgstr "" #: ../../design/database.rst:204 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:232 msgid "Usernames and page ownership" msgstr "" #: ../../design/database.rst:234 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:241 msgid "Juggling users and groups" msgstr "" #: ../../design/database.rst:243 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:251 msgid "Menu options" msgstr "" #: ../../design/database.rst:253 msgid "***This section is deprecated as of Elgg 1.8***" msgstr "" #: ../../design/database.rst:255 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:259 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:272 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:280 msgid "Ownership" msgstr "" #: ../../design/database.rst:282 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:286 msgid "The ownership of an entity dictates, in part, whether or not you can access or edit that entity." msgstr "" #: ../../design/database.rst:290 msgid "Containers" msgstr "" #: ../../design/database.rst:292 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:297 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:300 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:306 msgid "Annotations" msgstr "" #: ../../design/database.rst:308 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:313 msgid "Annotations are stored as instances of the ``ElggAnnotation`` class." msgstr "" #: ../../design/database.rst:315 msgid "Each annotation has:" msgstr "" #: ../../design/database.rst:317 msgid "An internal annotation type (like *comment*)" msgstr "" #: ../../design/database.rst:318 msgid "A value (which can be a string or integer)" msgstr "" #: ../../design/database.rst:319 msgid "An access permission distinct from the entity it's attached to" msgstr "" #: ../../design/database.rst:320 msgid "An owner" msgstr "" #: ../../design/database.rst:323 msgid "Adding an annotation" msgstr "" #: ../../design/database.rst:325 msgid "The easiest way to annotate is to use the ``annotate`` method on an entity, which is defined as:" msgstr "" #: ../../design/database.rst:338 msgid "For example, to leave a rating on an entity, you might call:" msgstr "" #: ../../design/database.rst:345 msgid "Reading annotations" msgstr "" #: ../../design/database.rst:347 msgid "To retrieve annotations on an object, you can call the following method:" msgstr "" #: ../../design/database.rst:358 msgid "If your annotation type largely deals with integer values, a couple of useful mathematical functions are provided:" msgstr "" #: ../../design/database.rst:369 msgid "Useful helper functions" msgstr "" #: ../../design/database.rst:372 msgid "Comments" msgstr "" #: ../../design/database.rst:374 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:383 msgid "Metadata" msgstr "" #: ../../design/database.rst:385 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:391 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:396 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:398 msgid "You can potentially have multiple items of each type of metadata attached to a single entity" msgstr "" #: ../../design/database.rst:402 msgid "The simple case" msgstr "" #: ../../design/database.rst:405 #: ../../design/database.rst:474 msgid "Adding metadata" msgstr "" #: ../../design/database.rst:407 msgid "To add a piece of metadata to an entity, just call:" msgstr "" #: ../../design/database.rst:413 msgid "For example, to add a date of birth to a user:" msgstr "" #: ../../design/database.rst:419 msgid "Or to add a couple of tags to an object:" msgstr "" #: ../../design/database.rst:425 msgid "When adding metadata like this:" msgstr "" #: ../../design/database.rst:427 msgid "The owner is set to the currently logged-in user" msgstr "" #: ../../design/database.rst:428 msgid "Access permissions are inherited from the entity" msgstr "" #: ../../design/database.rst:429 msgid "Reassigning a piece of metadata will overwrite the old value" msgstr "" #: ../../design/database.rst:431 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:440 #: ../../design/database.rst:516 msgid "Reading metadata" msgstr "" #: ../../design/database.rst:442 msgid "To retrieve metadata, treat it as a property of the entity:" msgstr "" #: ../../design/database.rst:448 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:452 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:464 msgid "To always get an array back, simply cast to an array;" msgstr "" #: ../../design/database.rst:471 msgid "Finer control" msgstr "" #: ../../design/database.rst:476 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:492 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:499 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:512 msgid "Note that the *allow multiple* setting is set to *false* in the first iteration and *true* thereafter." msgstr "" #: ../../design/database.rst:518 msgid "``elgg_get_metadata`` is the best function for retrieving metadata as ElggMetadata objects:" msgstr "" #: ../../design/database.rst:521 msgid "E.g., to retrieve a user's DOB" msgstr "" #: ../../design/database.rst:530 msgid "Or to get all metadata objects:" msgstr "" #: ../../design/database.rst:542 msgid "Common mistakes" msgstr "" #: ../../design/database.rst:545 msgid "\"Appending\" metadata" msgstr "" #: ../../design/database.rst:547 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:556 msgid "Trying to store hashmaps" msgstr "" #: ../../design/database.rst:558 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:567 msgid "You can instead store the information like so:" msgstr "" #: ../../design/database.rst:576 msgid "Storing GUIDs in metadata" msgstr "" #: ../../design/database.rst:578 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:583 msgid "Relationships" msgstr "" #: ../../design/database.rst:585 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:588 msgid "The class ``ElggRelationship`` models a directed relationship between two entities, making the statement:" msgstr "" #: ../../design/database.rst:591 msgid "\"**{subject}** is a **{noun}** of **{target}**.\"" msgstr "" #: ../../design/database.rst:594 msgid "API name" msgstr "" #: ../../design/database.rst:594 msgid "Models" msgstr "" #: ../../design/database.rst:596 msgid "``guid_one``" msgstr "" #: ../../design/database.rst:596 msgid "The subject" msgstr "" #: ../../design/database.rst:596 msgid "Which entity is being bound" msgstr "" #: ../../design/database.rst:597 msgid "``relationship``" msgstr "" #: ../../design/database.rst:597 msgid "The noun" msgstr "" #: ../../design/database.rst:597 msgid "The type of relationship" msgstr "" #: ../../design/database.rst:598 msgid "``guid_two``" msgstr "" #: ../../design/database.rst:598 msgid "The target" msgstr "" #: ../../design/database.rst:598 msgid "The entity to which the subject is bound" msgstr "" #: ../../design/database.rst:601 msgid "The type of relationship may alternately be a verb, making the statement:" msgstr "" #: ../../design/database.rst:603 msgid "\"**{subject}** **{verb}** **{target}**.\"" msgstr "" #: ../../design/database.rst:605 msgid "E.g. User A \"likes\" blog post B" msgstr "" #: ../../design/database.rst:607 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:611 msgid "**A relationship does not imply reciprocity**. **A** follows **B** does not imply that **B** follows **A**." msgstr "" #: ../../design/database.rst:614 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:620 msgid "Working with relationships" msgstr "" #: ../../design/database.rst:623 msgid "Creating a relationship" msgstr "" #: ../../design/database.rst:625 msgid "E.g. to establish that \"**$user** is a **fan** of **$artist**\" (user is the subject, artist is the target):" msgstr "" #: ../../design/database.rst:636 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:642 msgid "Verifying a relationship" msgstr "" #: ../../design/database.rst:644 msgid "E.g. to verify that \"**$user** is a **fan** of **$artist**\":" msgstr "" #: ../../design/database.rst:652 msgid "Note that, if the relationship exists, ``check_entity_relationship()`` returns an ``ElggRelationship`` object:" msgstr "" #: ../../design/database.rst:663 msgid "Deleting a relationship" msgstr "" #: ../../design/database.rst:665 msgid "E.g. to be able to assert that \"**$user** is no longer a **fan** of **$artist**\":" msgstr "" #: ../../design/database.rst:671 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:676 msgid "Other useful functions:" msgstr "" #: ../../design/database.rst:678 msgid "``delete_relationship()`` : delete by ID" msgstr "" #: ../../design/database.rst:679 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:682 msgid "Finding relationships and related entities" msgstr "" #: ../../design/database.rst:684 msgid "Below are a few functions to fetch relationship objects and/or related entities. A few are listed below:" msgstr "" #: ../../design/database.rst:687 msgid "``get_entity_relationships()`` : fetch relationships by subject or target entity" msgstr "" #: ../../design/database.rst:688 msgid "``get_relationship()`` : get a relationship object by ID" msgstr "" #: ../../design/database.rst:689 msgid "``elgg_get_entities_from_relationship()`` : fetch entities in relationships in a variety of ways" msgstr "" #: ../../design/database.rst:692 msgid "E.g. retrieving users who joined your site in January 2014." msgstr "" #: ../../design/database.rst:706 msgid "Access Control" msgstr "" #: ../../design/database.rst:708 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:714 msgid "Access controls in the data model" msgstr "" #: ../../design/database.rst:716 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:722 msgid "Pre-defined access controls" msgstr "" #: ../../design/database.rst:724 msgid "``ACCESS_PRIVATE`` (value: 0) Private." msgstr "" #: ../../design/database.rst:725 msgid "``ACCESS_LOGGED_IN`` (value: 1) Logged in users." msgstr "" #: ../../design/database.rst:726 msgid "``ACCESS_PUBLIC`` (value: 2) Public data." msgstr "" #: ../../design/database.rst:727 msgid "``ACCESS_FRIENDS`` (value: -2) Owner and his/her friends." msgstr "" #: ../../design/database.rst:730 msgid "User defined access controls" msgstr "" #: ../../design/database.rst:732 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:737 msgid "How access affects data retrieval" msgstr "" #: ../../design/database.rst:739 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:748 msgid "Write access" msgstr "" #: ../../design/database.rst:750 msgid "The following rules govern write access:" msgstr "" #: ../../design/database.rst:752 msgid "The owner of an entity can always edit it" msgstr "" #: ../../design/database.rst:753 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:755 msgid "Admins can edit anything" msgstr "" #: ../../design/database.rst:757 msgid "You can override this behaviour using a :ref:`plugin hook ` 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 ` for more details." msgstr "" #: ../../design/database.rst:765 msgid "`Access library reference`_" msgstr "" #: ../../design/database.rst:770 msgid "Schema" msgstr "" #: ../../design/database.rst:772 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:775 msgid "Each table is prefixed by \"prefix\\_\", this is replaced by the Elgg framework during installation." msgstr "" #: ../../design/database.rst:779 msgid "Main tables" msgstr "" #: ../../design/database.rst:781 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:785 msgid "Table: entities" msgstr "" #: ../../design/database.rst:787 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:791 msgid "It contains the following fields:" msgstr "" #: ../../design/database.rst:793 msgid "**guid** An auto-incrementing counter producing a GUID that uniquely identifies this entity in the system." msgstr "" #: ../../design/database.rst:795 msgid "**type** The type of entity - object, user, group or site" msgstr "" #: ../../design/database.rst:796 msgid "**subtype** A reference to the `entity_subtypes` table, or ``0`` for the default subtype." msgstr "" #: ../../design/database.rst:797 msgid "**owner\\_guid** The GUID of the owner's entity." msgstr "" #: ../../design/database.rst:798 msgid "**site\\_guid** The site the entity belongs to." msgstr "" #: ../../design/database.rst:799 msgid "**container\\_guid** The GUID this entity is contained by - either a user or a group." msgstr "" #: ../../design/database.rst:801 msgid "**access\\_id** Access controls on this entity." msgstr "" #: ../../design/database.rst:802 msgid "**time\\_created** Unix timestamp of when the entity is created." msgstr "" #: ../../design/database.rst:803 msgid "**time\\_updated** Unix timestamp of when the entity was updated." msgstr "" #: ../../design/database.rst:804 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:809 msgid "Table: entity\\_subtypes" msgstr "" #: ../../design/database.rst:811 msgid "This table contains entity subtype information:" msgstr "" #: ../../design/database.rst:813 #: ../../design/database.rst:823 #: ../../design/database.rst:841 msgid "**id** A counter." msgstr "" #: ../../design/database.rst:814 msgid "**type** The type of entity - object, user, group or site." msgstr "" #: ../../design/database.rst:815 msgid "**subtype** The subtype name as a string." msgstr "" #: ../../design/database.rst:816 msgid "**class** Optional class name if this subtype is linked with a class" msgstr "" #: ../../design/database.rst:819 msgid "Table: metadata" msgstr "" #: ../../design/database.rst:821 msgid "This table contains `Metadata`_, extra information attached to an entity." msgstr "" #: ../../design/database.rst:824 #: ../../design/database.rst:842 msgid "**entity\\_guid** The entity this is attached to." msgstr "" #: ../../design/database.rst:825 msgid "**name\\_id** A link to the metastrings table defining the name table." msgstr "" #: ../../design/database.rst:827 #: ../../design/database.rst:845 msgid "**value\\_id** A link to the metastrings table defining the value." msgstr "" #: ../../design/database.rst:828 #: ../../design/database.rst:846 msgid "**value\\_type** The value class, either text or an integer." msgstr "" #: ../../design/database.rst:829 #: ../../design/database.rst:847 msgid "**owner\\_guid** The owner GUID of the owner who set this item of metadata." msgstr "" #: ../../design/database.rst:831 #: ../../design/database.rst:849 msgid "**access\\_id** An Access controls on this item of metadata." msgstr "" #: ../../design/database.rst:832 #: ../../design/database.rst:850 msgid "**time\\_created** Unix timestamp of when the metadata is created." msgstr "" #: ../../design/database.rst:833 #: ../../design/database.rst:851 msgid "**enabled** If this is 'yes' an item is accessible, if 'no' the item has been deleted." msgstr "" #: ../../design/database.rst:837 msgid "Table: annotations" msgstr "" #: ../../design/database.rst:839 msgid "This table contains `Annotations`_, this is distinct from `Metadata`_." msgstr "" #: ../../design/database.rst:843 msgid "**name\\_id** A link to the metastrings table defining the type of annotation." msgstr "" #: ../../design/database.rst:855 msgid "Table: relationships" msgstr "" #: ../../design/database.rst:857 msgid "This table defines `Relationships`_, these link one entity with another." msgstr "" #: ../../design/database.rst:859 msgid "**guid\\_one** The GUID of the subject entity." msgstr "" #: ../../design/database.rst:860 msgid "**relationship** The type of the relationship." msgstr "" #: ../../design/database.rst:861 msgid "**guid\\_two** The GUID of the target entity." msgstr "" #: ../../design/database.rst:864 msgid "Table: objects\\_entity" msgstr "" #: ../../design/database.rst:866 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:871 msgid "Table: sites\\_entity" msgstr "" #: ../../design/database.rst:873 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:878 msgid "Table: users\\_entity" msgstr "" #: ../../design/database.rst:880 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:885 msgid "Table: groups\\_entity" msgstr "" #: ../../design/database.rst:887 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:892 msgid "Table: metastrings" msgstr "" #: ../../design/database.rst:894 msgid "Metastrings contain the actual string of metadata which is linked to by the metadata and annotations tables." msgstr "" #: ../../design/database.rst:897 msgid "This is to avoid duplicating strings, saving space and making database lookups more efficient." msgstr "" #: ../../design/database.rst:900 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 `_ 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/events.rst:241 msgid "Unregister Event/Hook Handlers" msgstr "" #: ../../design/events.rst:243 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:251 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:263 msgid "Even though the event handler references a dynamic method call, the code above will successfully remove the handler." 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 `. 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 ""