{"action":"created","comment":{"url":"https://api.github.com/repos/edx/edx-documentation/pulls/comments/33415146","id":33415146,"diff_hunk":"@@ -0,0 +1,240 @@\n+.. _XBlock Fields:\n+\n+####################\n+XBlock Fields\n+####################\n+\n+You use XBlock fields to store state data for your XBlock.\n+\n+.. contents:: Section Contents:\n+ :local:\n+ :depth: 1\n+\n+.. link to fields api doc\n+\n+************************\n+XBlock Fields and State\n+************************\n+\n+XBlock fields are Python attributes that store user and XBlock state as JSON\n+data.\n+\n+You define the fields in the XBlock Python file. For example, the ``thumbs.py``\n+file in the XBlock SDK includes three fields.\n+\n+.. include:: ../reusable/code_thumbs_fields.rst\n+\n+When you initialize an XBlock field, you define three parameters.\n+\n+* ``help``: A help string for the field that can be used in an application such\n+  as edX Studio.\n+\n+* ``default``: The default value for the field.\n+\n+* ``scope``:  The scope of the field.  For more information, see the next\n+  section.\n+\n+.. _Field Scope:\n+\n+***********\n+Field Scope\n+***********\n+\n+Field *scope* is the relationship of the field to users and the XBlock.\n+\n+You define the field scope when initializing the field in the XBlock Python\n+file. For example, in ``thumbs.py``, the ``voted`` field is initialized to have\n+the scope ``user_state``.\n+\n+.. code-block:: python\n+\n+    voted = Boolean(help=\"Has this student voted?\", default=False, \n+        scope=Scope.user_state)\n+\n+===========\n+User Scope\n+===========\n+\n+Fields can relate to users in the following ways.\n+\n+* **No user**: the field data is not related to any users. For example, a field\n+  that contains course content is independent of users.\n+\n+  .. note:: The XBlock cannot modify the value of a field that is not related\n+    to any users.\n+\n+* **One user**: the field data is specific to a single user. For example, the\n+  answer to a problem is specific to the user who submitted it.\n+\n+* **All users**: the field data is common for all users. For example, the total\n+  number of students who answer a question is the same for all users.\n+\n+  .. note:: Field data related to all users is not the same as aggregate or \n+    query data. The same value is shared for all users, and you cannot \n+    associate specific actions to specific users.\n+\n+===========\n+Block Scope\n+===========\n+\n+Fields can relate to XBlocks in the following ways.\n+\n+* **Block usage**: the field data is related to an instance, or usage, of the\n+  XBlock in a particular course.\n+\n+* **Block definition**: the field data is related to the definition of the\n+  XBlock. The definition is specified by the content creator. A definition can\n+  be shared across one or more uses. For example, you could create a single\n+  XBlock definition with many uses, and those uses can appear across\n+  courses or within the same course.\n+\n+* **Block type**: The field data is related to the Python type of the XBlock,\n+  and is shared across all instances of the XBlock in all courses. \n+\n+* **All**: The field data is related to all XBlocks, of all types. Any\n+  XBlock can access the field data.\n+\n+  .. note:: \n+    When you use the **All** scope, there is potential for name conflicts. If\n+    you have two fields of the same name with the scope **All** in different\n+    XBlocks types, both fields point to the same data. Therefore you should use\n+    caution when using **All**.\n+\n+=================================\n+User and Block Scope Independence\n+=================================\n+\n+The user and block scope of a field are independent of each other.  The field\n+scope you define specifies both. The following examples show different ways you\n+can combine user and block scope.\n+\n+* A user's progress through a particular set of problems is stored in a field\n+  with the scope **One user** and **XBlock usage**.\n+\n+* The content to display in an XBlock is stored in a field with the scope **No\n+  user** and **Block definition**.\n+\n+* A user's preferences for a type of XBlock are stored in a field with the\n+  scope with **One user** and **XBlock type**.\n+\n+* Information about the user, such as language or timezone, is stored in a\n+  field with the scope with **One user** and **All**.\n+\n+=================================\n+Predefined Scopes\n+=================================\n+\n+XBlock includes the following predefined scopes that you can use when\n+configuring fields. Each of these scopes includes the indicated user and block\n+scope settings.\n+\n+* ``Scope.content``\n+  \n+  * **Block definition**\n+  * **No user**\n+\n+* ``Scope.settings``\n+  \n+  * **Block usage**\n+  * **No user**\n+\n+* ``Scope.user_state``\n+  \n+  * **Block usage**\n+  * **One user**\n+\n+* ``Scope.preferences``\n+  \n+  * **Block type**\n+  * **One user**\n+\n+* ``Scope.user_info``\n+  \n+  * **All blocks**\n+  * **One user**\n+\n+* ``Scope.user_state_summary``\n+  \n+  * **Block usage**\n+  * **All users**\n+\n+======================\n+Define a Custom Scope\n+======================\n+\n+TBP\n+\n+************************\n+Fields and Data Storage\n+************************\n+\n+.. What is large?\n+\n+Because XBlock fields are written and retrieved as single entities, you cannot\n+store a large amount of data in a single field.\n+\n+To store very large amounts of data, you should split the data across many\n+smaller fields.\n+\n+********************\n+Initializing Fields\n+********************\n+\n+You do not use the ``init`` method with XBlocks.\n+\n+XBlocks can be used in many contexts, and the ``init`` method might not work in\n+those contexts.\n+\n+To initialize field values, use one of the following alternatives\n+\n+* Use ``xblock.fields.UNIQUE_ID`` to set a default String value for the field. \n+\n+* Use a lazy property decorator, so that when a field is first accessed, a\n+  function is called to set the value.\n+\n+* Run the logic to set the default field value in the view instead of the\n+  ``init`` method.\n+\n+***************\n+Fields and OLX\n+***************\n+\n+XBlock fields map to attributes in the XBlock Open Learning XML (OLX)\n+definition.\n+\n+For example, you might include the fields ``href``, ``maxwidth``, and\n+``maxheight`` in a ``SimpleVideoBlock`` XBlock.  You configure the fields as in\n+the following example.\n+\n+.. code-block:: python\n+\n+  class SimpleVideoBlock(XBlock):\n+      \"\"\"\n+      An XBlock providing oEmbed capabilities for video\n+      \"\"\"\n+\n+      href = String(help=\"URL of the video page at the provider\", \n+          default=None, scope=Scope.content)\n+      maxwidth = Integer(help=\"Maximum width of the video\", default=800, \n+          scope=Scope.content)\n+      maxheight = Integer(help=\"Maximum height of the video\", default=450, \n+          scope=Scope.content)\n+\n+The ``SimpleVideoBlock`` XBlock is represented in OLX as in the following\n+example:\n+\n+.. code-block:: xml\n+\n+    <simplevideo \n+        href=\"https://vimeo.com/46100581\" \n+        maxwidth=\"800\" \n+        maxheight=\"450\" \n+    />\n+\n+*********************************************\n+Field Requirements in the edx Platform\n+*********************************************\n+\n+See :ref:`edX LMS <EdX Learning Management System as an XBlock Runtime>` and","path":"en_us/xblock/source/concepts/fields.rst","position":238,"original_position":238,"commit_id":"f8a500b5e514b5f326425b38f04342f6fbd33048","original_commit_id":"f8a500b5e514b5f326425b38f04342f6fbd33048","user":{"login":"lamagnifica","id":6392274,"avatar_url":"https://avatars.githubusercontent.com/u/6392274?v=3","gravatar_id":"","url":"https://api.github.com/users/lamagnifica","html_url":"https://github.com/lamagnifica","followers_url":"https://api.github.com/users/lamagnifica/followers","following_url":"https://api.github.com/users/lamagnifica/following{/other_user}","gists_url":"https://api.github.com/users/lamagnifica/gists{/gist_id}","starred_url":"https://api.github.com/users/lamagnifica/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lamagnifica/subscriptions","organizations_url":"https://api.github.com/users/lamagnifica/orgs","repos_url":"https://api.github.com/users/lamagnifica/repos","events_url":"https://api.github.com/users/lamagnifica/events{/privacy}","received_events_url":"https://api.github.com/users/lamagnifica/received_events","type":"User","site_admin":false},"body":"use the \"For more information\" structure. Also, this reads a little oddly in the HTML, like, you're supposed to go open the referenced applications (not some doc) to get the info...","created_at":"2015-06-27T19:05:51Z","updated_at":"2015-06-27T19:05:51Z","html_url":"https://github.com/edx/edx-documentation/pull/314#discussion_r33415146","pull_request_url":"https://api.github.com/repos/edx/edx-documentation/pulls/314","_links":{"self":{"href":"https://api.github.com/repos/edx/edx-documentation/pulls/comments/33415146"},"html":{"href":"https://github.com/edx/edx-documentation/pull/314#discussion_r33415146"},"pull_request":{"href":"https://api.github.com/repos/edx/edx-documentation/pulls/314"}}},"pull_request":{"url":"https://api.github.com/repos/edx/edx-documentation/pulls/314","id":34403563,"html_url":"https://github.com/edx/edx-documentation/pull/314","diff_url":"https://github.com/edx/edx-documentation/pull/314.diff","patch_url":"https://github.com/edx/edx-documentation/pull/314.patch","issue_url":"https://api.github.com/repos/edx/edx-documentation/issues/314","number":314,"state":"open","locked":false,"title":"WIP - XBlock Tutorial","user":{"login":"mhoeber","id":5607222,"avatar_url":"https://avatars.githubusercontent.com/u/5607222?v=3","gravatar_id":"","url":"https://api.github.com/users/mhoeber","html_url":"https://github.com/mhoeber","followers_url":"https://api.github.com/users/mhoeber/followers","following_url":"https://api.github.com/users/mhoeber/following{/other_user}","gists_url":"https://api.github.com/users/mhoeber/gists{/gist_id}","starred_url":"https://api.github.com/users/mhoeber/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mhoeber/subscriptions","organizations_url":"https://api.github.com/users/mhoeber/orgs","repos_url":"https://api.github.com/users/mhoeber/repos","events_url":"https://api.github.com/users/mhoeber/events{/privacy}","received_events_url":"https://api.github.com/users/mhoeber/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-04-29T20:39:28Z","updated_at":"2015-06-27T19:05:51Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6a1ab62783042719a6c3858cb35c2ee6aad15e12","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/edx/edx-documentation/pulls/314/commits","review_comments_url":"https://api.github.com/repos/edx/edx-documentation/pulls/314/comments","review_comment_url":"https://api.github.com/repos/edx/edx-documentation/pulls/comments{/number}","comments_url":"https://api.github.com/repos/edx/edx-documentation/issues/314/comments","statuses_url":"https://api.github.com/repos/edx/edx-documentation/statuses/f8a500b5e514b5f326425b38f04342f6fbd33048","head":{"label":"edx:markhoeber-doc-1947","ref":"markhoeber-doc-1947","sha":"f8a500b5e514b5f326425b38f04342f6fbd33048","user":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"repo":{"id":23839256,"name":"edx-documentation","full_name":"edx/edx-documentation","owner":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/edx/edx-documentation","description":"","fork":false,"url":"https://api.github.com/repos/edx/edx-documentation","forks_url":"https://api.github.com/repos/edx/edx-documentation/forks","keys_url":"https://api.github.com/repos/edx/edx-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/edx/edx-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/edx/edx-documentation/teams","hooks_url":"https://api.github.com/repos/edx/edx-documentation/hooks","issue_events_url":"https://api.github.com/repos/edx/edx-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/edx/edx-documentation/events","assignees_url":"https://api.github.com/repos/edx/edx-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/edx/edx-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/edx/edx-documentation/tags","blobs_url":"https://api.github.com/repos/edx/edx-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/edx/edx-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/edx/edx-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/edx/edx-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/edx/edx-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/edx/edx-documentation/languages","stargazers_url":"https://api.github.com/repos/edx/edx-documentation/stargazers","contributors_url":"https://api.github.com/repos/edx/edx-documentation/contributors","subscribers_url":"https://api.github.com/repos/edx/edx-documentation/subscribers","subscription_url":"https://api.github.com/repos/edx/edx-documentation/subscription","commits_url":"https://api.github.com/repos/edx/edx-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/edx/edx-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/edx/edx-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/edx/edx-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/edx/edx-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/edx/edx-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/edx/edx-documentation/merges","archive_url":"https://api.github.com/repos/edx/edx-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/edx/edx-documentation/downloads","issues_url":"https://api.github.com/repos/edx/edx-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/edx/edx-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/edx/edx-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/edx/edx-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/edx/edx-documentation/labels{/name}","releases_url":"https://api.github.com/repos/edx/edx-documentation/releases{/id}","created_at":"2014-09-09T15:29:04Z","updated_at":"2015-06-25T20:41:12Z","pushed_at":"2015-06-26T15:54:56Z","git_url":"git://github.com/edx/edx-documentation.git","ssh_url":"git@github.com:edx/edx-documentation.git","clone_url":"https://github.com/edx/edx-documentation.git","svn_url":"https://github.com/edx/edx-documentation","homepage":null,"size":81130,"stargazers_count":17,"watchers_count":17,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":60,"mirror_url":null,"open_issues_count":17,"forks":60,"open_issues":17,"watchers":17,"default_branch":"master"}},"base":{"label":"edx:master","ref":"master","sha":"1d1d836ce23052c1f3dd1f6bb2e03cc97f0a6997","user":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"repo":{"id":23839256,"name":"edx-documentation","full_name":"edx/edx-documentation","owner":{"login":"edx","id":3179841,"avatar_url":"https://avatars.githubusercontent.com/u/3179841?v=3","gravatar_id":"","url":"https://api.github.com/users/edx","html_url":"https://github.com/edx","followers_url":"https://api.github.com/users/edx/followers","following_url":"https://api.github.com/users/edx/following{/other_user}","gists_url":"https://api.github.com/users/edx/gists{/gist_id}","starred_url":"https://api.github.com/users/edx/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edx/subscriptions","organizations_url":"https://api.github.com/users/edx/orgs","repos_url":"https://api.github.com/users/edx/repos","events_url":"https://api.github.com/users/edx/events{/privacy}","received_events_url":"https://api.github.com/users/edx/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/edx/edx-documentation","description":"","fork":false,"url":"https://api.github.com/repos/edx/edx-documentation","forks_url":"https://api.github.com/repos/edx/edx-documentation/forks","keys_url":"https://api.github.com/repos/edx/edx-documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/edx/edx-documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/edx/edx-documentation/teams","hooks_url":"https://api.github.com/repos/edx/edx-documentation/hooks","issue_events_url":"https://api.github.com/repos/edx/edx-documentation/issues/events{/number}","events_url":"https://api.github.com/repos/edx/edx-documentation/events","assignees_url":"https://api.github.com/repos/edx/edx-documentation/assignees{/user}","branches_url":"https://api.github.com/repos/edx/edx-documentation/branches{/branch}","tags_url":"https://api.github.com/repos/edx/edx-documentation/tags","blobs_url":"https://api.github.com/repos/edx/edx-documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/edx/edx-documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/edx/edx-documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/edx/edx-documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/edx/edx-documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/edx/edx-documentation/languages","stargazers_url":"https://api.github.com/repos/edx/edx-documentation/stargazers","contributors_url":"https://api.github.com/repos/edx/edx-documentation/contributors","subscribers_url":"https://api.github.com/repos/edx/edx-documentation/subscribers","subscription_url":"https://api.github.com/repos/edx/edx-documentation/subscription","commits_url":"https://api.github.com/repos/edx/edx-documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/edx/edx-documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/edx/edx-documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/edx/edx-documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/edx/edx-documentation/contents/{+path}","compare_url":"https://api.github.com/repos/edx/edx-documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/edx/edx-documentation/merges","archive_url":"https://api.github.com/repos/edx/edx-documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/edx/edx-documentation/downloads","issues_url":"https://api.github.com/repos/edx/edx-documentation/issues{/number}","pulls_url":"https://api.github.com/repos/edx/edx-documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/edx/edx-documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/edx/edx-documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/edx/edx-documentation/labels{/name}","releases_url":"https://api.github.com/repos/edx/edx-documentation/releases{/id}","created_at":"2014-09-09T15:29:04Z","updated_at":"2015-06-25T20:41:12Z","pushed_at":"2015-06-26T15:54:56Z","git_url":"git://github.com/edx/edx-documentation.git","ssh_url":"git@github.com:edx/edx-documentation.git","clone_url":"https://github.com/edx/edx-documentation.git","svn_url":"https://github.com/edx/edx-documentation","homepage":null,"size":81130,"stargazers_count":17,"watchers_count":17,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":60,"mirror_url":null,"open_issues_count":17,"forks":60,"open_issues":17,"watchers":17,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/edx/edx-documentation/pulls/314"},"html":{"href":"https://github.com/edx/edx-documentation/pull/314"},"issue":{"href":"https://api.github.com/repos/edx/edx-documentation/issues/314"},"comments":{"href":"https://api.github.com/repos/edx/edx-documentation/issues/314/comments"},"review_comments":{"href":"https://api.github.com/repos/edx/edx-documentation/pulls/314/comments"},"review_comment":{"href":"https://api.github.com/repos/edx/edx-documentation/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/edx/edx-documentation/pulls/314/commits"},"statuses":{"href":"https://api.github.com/repos/edx/edx-documentation/statuses/f8a500b5e514b5f326425b38f04342f6fbd33048"}}}}