{"action":"created","comment":{"url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/comments/43049163","id":43049163,"diff_hunk":"@@ -0,0 +1,133 @@\n+---\n+title: IoC API\n+layout: default\n+category: Infusion\n+---\n+\n+# Infusion IoC API\n+\n+Whilst Infusion's [IoC](HowToUseInfusionIoC.md) is primarily a declarative system, operated by a declarative dialect of\n+JSON configuration, there are a few language-level APIs which are useful in dealing with the system. Some of these\n+are externalisable in that there is a reasonable semantic for operating them from outside the JavaScript VM housing the \n+component tree - these special APIs are grouped under the heading [Nexus API methods](#nexus-api-methods), named after the \n+[Nexus component](https://wiki.gpii.net/w/Nexus_API) that will shortly be built around them.\n+\n+## IoC utility methods\n+\n+### fluid.pathForComponent(component)\n+\n+* `component: {Component}` The component whose global path is required\n+* Returns: `{Array of String}` The component's global path, as an array of path segments\n+\n+Each instantiated component in the Infusion system has a stable base path in the system's global [component tree](Contexts.md).\n+Records about the component are held in Infusion's [instantiator](#fluid-globalinstantiator) where the path and numerous other\n+details can be looked up. This utility method accepts a currently instantiated (not [destroyed](CoreAPI.md#fluid-isdestroyed-component-)\n+component and returns its path as a set of parsed array segments. This information can be very useful for making calculations about\n+the _geometry_ of component trees - that is, which components are descended from which others and which are siblings, etc.\n+\n+### fluid.queryIoCSelector(root, selector[, flat])\n+\n+Query for all components matching a selector in a particular tree.\n+* `root {Component}` The root component at which to start the search. A reasonable choice for this can be [`fluid.rootComponent`](#fluid-rootcomponent) although\n+such global searches can be very slow. A more reasonable choice will be some particular component in the tree whose descendents are of interest.  \n+* `selector {String}` An [IoCSS selector](IoCSS.md), in form of a string. Note that since selectors supplied to this function implicitly\n+match downwards, they need not contain the \"head context\" followed by whitespace required in the distributeOptions form. E.g.\n+simply `fluid.viewComponent` will match all viewComponents below the root.\n+* `flat {Boolean}` [optional] `true` if the search should just be performed at top level of the component tree\n+ Note that with `flat=true` this search will scan every component in the tree and may well be very slow.\n+\n+### fluid.expand(material, that)\n+\n+[Expands](ExpansionOfComponentOptions.md) some options material in the context of a particular component - any [IoC References](IocReferences.md) and expanders held at any\n+depth in the material will be expanded to hold their resolved contents. The source `material` will not be modified.\n+\n+* `material {Object}` The configuration material to be expanded\n+* `that {Component}` The component in whose [context](Contexts.md) the material is to be expanded\n+* Returns: `{Object}` An expanded version of the input `material`.\n+\n+### fluid.getForComponent(component, path)\n+\n+This is a fairly interesting method. During the instantiation of an IoC component tree, the framework's \"focus of attention\" moves around the tree\n+in a data-driven way. If an [IoC reference](#IoCReferences.md) is seen to a particular path, this will direct attention to instantiate the\n+material referenced by the path. `fluid.getForComponent` is the method used internally by the framework in order to ensure that any referenced\n+material has actually been instantiated before the results from any IoC reference are filled in in the [expanded](ExpansionOfComponentOptions.md)\n+options material. You can use this method too, in order to make sure that any member of a component has been instantiated before you look at it. This\n+should not normally be necessary - and the use of this API only makes sense during a construction \"fit\" - during the \"semi-static period\", you can\n+assume that all members of all visible components are concrete. \n+\n+This is an analogue of the API [`fluid.get`](CoreAPI.md#fluid-get-model-path-) for use during the \"ginger construction process.\n+\n+* `component {Component}` The component whose resolved member is required\n+* `path {String|Array of String}` The path within the component which is to be resolved\n+* Returns: `{Any}` The fully observed value held at `path` of component `component`.\n+\n+### fluid.resolveContext (context, that)\n+\n+Another method for enthusiasts. Given a particular IoC [Context](Contexts.md), determine which (if any) component in the tree it refers to, from the point\n+of view of component `that`.\n+\n+* `context {String}` The context to be resolved. For example, in an [IoC reference](IoCReferences.md) of the form `\"{myContext}.myPath1.myPath2\"`, the context is `myContext`.\n+* `that {Component}` The component from whose point of view the context is to be resolved\n+* Returns: `{Component|None}` Returns the component to which the context refers, or `undefined` if the reference cannot be resolved.\n+\n+### fluid.parseContextReference(reference) {\n+\n+Parse an [IoC reference](IoCReferences.md) of the form `\"{myContext}.myPath1.myPath2\"` into an object form. In this case, for example, the output would be \n+\n+```json\n+{\n+    context: \"myContext\", \n+    path: \"myPath1.myPath2\"\n+}\n+```\n+\n+From here it is a simple matter to resolve them in a DIY fashion with reference to the APIs `fluid.resolveContext` and `fluid.getForComponent` or `fluid.get`.\n+\n+* `reference {String}` An [IoC reference](IoCReferences.md) expressed as a String\n+* Returns: `{Object}` The parsed form of the reference, with the following fields:\n+    * `context {String}` The context portion of the IoC reference\n+    * `path {String}` The path portion of the IoC reference\n+\n+### fluid.globalInstantiator\n+\n+This path holds the global ***instantiator*** which holds all the records for Infusion's IoC system. Whilst any methods \n+on this object should not be called by applications, there are many entries in here that can aid debugging, especially\n+the members `instantiator.pathToComponent` which holds a mapping for every instantiated component from its global path\n+in the component tree, and `instantiator.idToShadow` which holds a mapping from every component's `id` to its ***shadow record***\n+which holds many useful pieces of bookkeeping, including the `mergeOptions` structure which can be used to inspect the details\n+of the options merging process resulting in the component's final options.\n+\n+### fluid.rootComponent\n+\n+Holds the global root component for the global instantiator's component tree.\n+\n+\n+## Nexus API methods \n+\n+### fluid.construct(path, options[, instantiator])\n+\n+Construct a component with the supplied options at the specified path in the component tree. The parent path of the location must already be a component.\n+\n+* `path {String|Array of String}` Path where the new component is to be constructed, represented as a string or array of segments\n+* `options {Object}` Top-level options supplied to the component - must at the very least include a field `type` holding the component's type. Note that these are expressed\n+in the currently hypothetical [post-FLUID-5750](https://issues.fluidproject.org/browse/FLUID-5750) format with `type` alongside the component's options rather than at\n+a higher nested level as is currently required in local configuration supplied as [subcomponents](SubcomponentDeclaration.md). \n+* `instantiator {Instantiator}` [optional] The instantiator holding the component to be created - if blank, the [global instantiator](#fluid-globalinstantiator) will be used\n+\n+### fluid.destroy(path[, instantiator])\n+\n+Destroys a component held at the specified path. The parent path must represent a component, although the component itself may be nonexistent.\n+\n+* `path {String|Array of String}` Path where the new component is to be destroyed, represented as a string or array of segments","path":"src/documents/IoCAPI.md","position":121,"original_position":121,"commit_id":"49d791bb36aa04b080a0e8f041ef82c7c9bcc019","original_commit_id":"49d791bb36aa04b080a0e8f041ef82c7c9bcc019","user":{"login":"acheetham","id":562946,"avatar_url":"https://avatars.githubusercontent.com/u/562946?v=3","gravatar_id":"","url":"https://api.github.com/users/acheetham","html_url":"https://github.com/acheetham","followers_url":"https://api.github.com/users/acheetham/followers","following_url":"https://api.github.com/users/acheetham/following{/other_user}","gists_url":"https://api.github.com/users/acheetham/gists{/gist_id}","starred_url":"https://api.github.com/users/acheetham/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/acheetham/subscriptions","organizations_url":"https://api.github.com/users/acheetham/orgs","repos_url":"https://api.github.com/users/acheetham/repos","events_url":"https://api.github.com/users/acheetham/events{/privacy}","received_events_url":"https://api.github.com/users/acheetham/received_events","type":"User","site_admin":false},"body":"Should \"new\" be in this line?","created_at":"2015-10-26T20:37:22Z","updated_at":"2015-10-26T20:37:22Z","html_url":"https://github.com/fluid-project/infusion-docs/pull/77#discussion_r43049163","pull_request_url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77","_links":{"self":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/comments/43049163"},"html":{"href":"https://github.com/fluid-project/infusion-docs/pull/77#discussion_r43049163"},"pull_request":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77"}}},"pull_request":{"url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77","id":48000073,"html_url":"https://github.com/fluid-project/infusion-docs/pull/77","diff_url":"https://github.com/fluid-project/infusion-docs/pull/77.diff","patch_url":"https://github.com/fluid-project/infusion-docs/pull/77.patch","issue_url":"https://api.github.com/repos/fluid-project/infusion-docs/issues/77","number":77,"state":"open","locked":false,"title":"FLUID-5791:  Comprehensive documentation for the Core API, Promises API, jqUnit API, IoC API and API for use in node.js","user":{"login":"amb26","id":561418,"avatar_url":"https://avatars.githubusercontent.com/u/561418?v=3","gravatar_id":"","url":"https://api.github.com/users/amb26","html_url":"https://github.com/amb26","followers_url":"https://api.github.com/users/amb26/followers","following_url":"https://api.github.com/users/amb26/following{/other_user}","gists_url":"https://api.github.com/users/amb26/gists{/gist_id}","starred_url":"https://api.github.com/users/amb26/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/amb26/subscriptions","organizations_url":"https://api.github.com/users/amb26/orgs","repos_url":"https://api.github.com/users/amb26/repos","events_url":"https://api.github.com/users/amb26/events{/privacy}","received_events_url":"https://api.github.com/users/amb26/received_events","type":"User","site_admin":false},"body":"together with various updates for consistency, as well as fixes for CSS ToC height issue and implementation of \"hover to link\" functionality as per github's own support for rendering .md files","created_at":"2015-10-18T02:22:02Z","updated_at":"2015-10-26T20:37:22Z","closed_at":null,"merged_at":null,"merge_commit_sha":"2739b497fe5a30ecfd207c0ddfc7cbb1149b13ec","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77/commits","review_comments_url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77/comments","review_comment_url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/fluid-project/infusion-docs/issues/77/comments","statuses_url":"https://api.github.com/repos/fluid-project/infusion-docs/statuses/49d791bb36aa04b080a0e8f041ef82c7c9bcc019","head":{"label":"amb26:FLUID-5791","ref":"FLUID-5791","sha":"49d791bb36aa04b080a0e8f041ef82c7c9bcc019","user":{"login":"amb26","id":561418,"avatar_url":"https://avatars.githubusercontent.com/u/561418?v=3","gravatar_id":"","url":"https://api.github.com/users/amb26","html_url":"https://github.com/amb26","followers_url":"https://api.github.com/users/amb26/followers","following_url":"https://api.github.com/users/amb26/following{/other_user}","gists_url":"https://api.github.com/users/amb26/gists{/gist_id}","starred_url":"https://api.github.com/users/amb26/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/amb26/subscriptions","organizations_url":"https://api.github.com/users/amb26/orgs","repos_url":"https://api.github.com/users/amb26/repos","events_url":"https://api.github.com/users/amb26/events{/privacy}","received_events_url":"https://api.github.com/users/amb26/received_events","type":"User","site_admin":false},"repo":{"id":22699996,"name":"infusion-docs","full_name":"amb26/infusion-docs","owner":{"login":"amb26","id":561418,"avatar_url":"https://avatars.githubusercontent.com/u/561418?v=3","gravatar_id":"","url":"https://api.github.com/users/amb26","html_url":"https://github.com/amb26","followers_url":"https://api.github.com/users/amb26/followers","following_url":"https://api.github.com/users/amb26/following{/other_user}","gists_url":"https://api.github.com/users/amb26/gists{/gist_id}","starred_url":"https://api.github.com/users/amb26/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/amb26/subscriptions","organizations_url":"https://api.github.com/users/amb26/orgs","repos_url":"https://api.github.com/users/amb26/repos","events_url":"https://api.github.com/users/amb26/events{/privacy}","received_events_url":"https://api.github.com/users/amb26/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/amb26/infusion-docs","description":"Documentation space for Infusion","fork":true,"url":"https://api.github.com/repos/amb26/infusion-docs","forks_url":"https://api.github.com/repos/amb26/infusion-docs/forks","keys_url":"https://api.github.com/repos/amb26/infusion-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/amb26/infusion-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/amb26/infusion-docs/teams","hooks_url":"https://api.github.com/repos/amb26/infusion-docs/hooks","issue_events_url":"https://api.github.com/repos/amb26/infusion-docs/issues/events{/number}","events_url":"https://api.github.com/repos/amb26/infusion-docs/events","assignees_url":"https://api.github.com/repos/amb26/infusion-docs/assignees{/user}","branches_url":"https://api.github.com/repos/amb26/infusion-docs/branches{/branch}","tags_url":"https://api.github.com/repos/amb26/infusion-docs/tags","blobs_url":"https://api.github.com/repos/amb26/infusion-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/amb26/infusion-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/amb26/infusion-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/amb26/infusion-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/amb26/infusion-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/amb26/infusion-docs/languages","stargazers_url":"https://api.github.com/repos/amb26/infusion-docs/stargazers","contributors_url":"https://api.github.com/repos/amb26/infusion-docs/contributors","subscribers_url":"https://api.github.com/repos/amb26/infusion-docs/subscribers","subscription_url":"https://api.github.com/repos/amb26/infusion-docs/subscription","commits_url":"https://api.github.com/repos/amb26/infusion-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/amb26/infusion-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/amb26/infusion-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/amb26/infusion-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/amb26/infusion-docs/contents/{+path}","compare_url":"https://api.github.com/repos/amb26/infusion-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/amb26/infusion-docs/merges","archive_url":"https://api.github.com/repos/amb26/infusion-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/amb26/infusion-docs/downloads","issues_url":"https://api.github.com/repos/amb26/infusion-docs/issues{/number}","pulls_url":"https://api.github.com/repos/amb26/infusion-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/amb26/infusion-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/amb26/infusion-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/amb26/infusion-docs/labels{/name}","releases_url":"https://api.github.com/repos/amb26/infusion-docs/releases{/id}","created_at":"2014-08-06T22:13:06Z","updated_at":"2014-06-29T09:31:28Z","pushed_at":"2015-10-18T03:05:05Z","git_url":"git://github.com/amb26/infusion-docs.git","ssh_url":"git@github.com:amb26/infusion-docs.git","clone_url":"https://github.com/amb26/infusion-docs.git","svn_url":"https://github.com/amb26/infusion-docs","homepage":null,"size":4000,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"fluid-project:master","ref":"master","sha":"70127a172d812ad1f7721642e45196eedc77f6d8","user":{"login":"fluid-project","id":560119,"avatar_url":"https://avatars.githubusercontent.com/u/560119?v=3","gravatar_id":"","url":"https://api.github.com/users/fluid-project","html_url":"https://github.com/fluid-project","followers_url":"https://api.github.com/users/fluid-project/followers","following_url":"https://api.github.com/users/fluid-project/following{/other_user}","gists_url":"https://api.github.com/users/fluid-project/gists{/gist_id}","starred_url":"https://api.github.com/users/fluid-project/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fluid-project/subscriptions","organizations_url":"https://api.github.com/users/fluid-project/orgs","repos_url":"https://api.github.com/users/fluid-project/repos","events_url":"https://api.github.com/users/fluid-project/events{/privacy}","received_events_url":"https://api.github.com/users/fluid-project/received_events","type":"Organization","site_admin":false},"repo":{"id":18303292,"name":"infusion-docs","full_name":"fluid-project/infusion-docs","owner":{"login":"fluid-project","id":560119,"avatar_url":"https://avatars.githubusercontent.com/u/560119?v=3","gravatar_id":"","url":"https://api.github.com/users/fluid-project","html_url":"https://github.com/fluid-project","followers_url":"https://api.github.com/users/fluid-project/followers","following_url":"https://api.github.com/users/fluid-project/following{/other_user}","gists_url":"https://api.github.com/users/fluid-project/gists{/gist_id}","starred_url":"https://api.github.com/users/fluid-project/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fluid-project/subscriptions","organizations_url":"https://api.github.com/users/fluid-project/orgs","repos_url":"https://api.github.com/users/fluid-project/repos","events_url":"https://api.github.com/users/fluid-project/events{/privacy}","received_events_url":"https://api.github.com/users/fluid-project/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/fluid-project/infusion-docs","description":"Documentation space for Infusion","fork":false,"url":"https://api.github.com/repos/fluid-project/infusion-docs","forks_url":"https://api.github.com/repos/fluid-project/infusion-docs/forks","keys_url":"https://api.github.com/repos/fluid-project/infusion-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/fluid-project/infusion-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/fluid-project/infusion-docs/teams","hooks_url":"https://api.github.com/repos/fluid-project/infusion-docs/hooks","issue_events_url":"https://api.github.com/repos/fluid-project/infusion-docs/issues/events{/number}","events_url":"https://api.github.com/repos/fluid-project/infusion-docs/events","assignees_url":"https://api.github.com/repos/fluid-project/infusion-docs/assignees{/user}","branches_url":"https://api.github.com/repos/fluid-project/infusion-docs/branches{/branch}","tags_url":"https://api.github.com/repos/fluid-project/infusion-docs/tags","blobs_url":"https://api.github.com/repos/fluid-project/infusion-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/fluid-project/infusion-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/fluid-project/infusion-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/fluid-project/infusion-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/fluid-project/infusion-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/fluid-project/infusion-docs/languages","stargazers_url":"https://api.github.com/repos/fluid-project/infusion-docs/stargazers","contributors_url":"https://api.github.com/repos/fluid-project/infusion-docs/contributors","subscribers_url":"https://api.github.com/repos/fluid-project/infusion-docs/subscribers","subscription_url":"https://api.github.com/repos/fluid-project/infusion-docs/subscription","commits_url":"https://api.github.com/repos/fluid-project/infusion-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/fluid-project/infusion-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/fluid-project/infusion-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/fluid-project/infusion-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/fluid-project/infusion-docs/contents/{+path}","compare_url":"https://api.github.com/repos/fluid-project/infusion-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/fluid-project/infusion-docs/merges","archive_url":"https://api.github.com/repos/fluid-project/infusion-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/fluid-project/infusion-docs/downloads","issues_url":"https://api.github.com/repos/fluid-project/infusion-docs/issues{/number}","pulls_url":"https://api.github.com/repos/fluid-project/infusion-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/fluid-project/infusion-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/fluid-project/infusion-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/fluid-project/infusion-docs/labels{/name}","releases_url":"https://api.github.com/repos/fluid-project/infusion-docs/releases{/id}","created_at":"2014-03-31T18:22:31Z","updated_at":"2015-04-30T15:50:58Z","pushed_at":"2015-10-18T03:05:06Z","git_url":"git://github.com/fluid-project/infusion-docs.git","ssh_url":"git@github.com:fluid-project/infusion-docs.git","clone_url":"https://github.com/fluid-project/infusion-docs.git","svn_url":"https://github.com/fluid-project/infusion-docs","homepage":null,"size":5224,"stargazers_count":1,"watchers_count":1,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":15,"mirror_url":null,"open_issues_count":4,"forks":15,"open_issues":4,"watchers":1,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77"},"html":{"href":"https://github.com/fluid-project/infusion-docs/pull/77"},"issue":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/issues/77"},"comments":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/issues/77/comments"},"review_comments":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77/comments"},"review_comment":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/pulls/77/commits"},"statuses":{"href":"https://api.github.com/repos/fluid-project/infusion-docs/statuses/49d791bb36aa04b080a0e8f041ef82c7c9bcc019"}}}}