{"action":"created","comment":{"url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/comments/34146266","id":34146266,"diff_hunk":"@@ -0,0 +1,202 @@\n+# Listing Content and Locations\n+\n+Starting from Platform 2015.07, listing content and locations in a project is\n+much easier, using a couple standardized mechanisms.\n+\n+Predefined, named queries can be defined in any bundle. They can then be used from twig, using a\n+[custom controller](#query_controller), or from PHP code using the [QueryType Registry](#fixme). The controller supports\n+[template overriding](#template_override), making it easy to use different templates for different calls.\n+\n+## <a name=\"query_controller\"></a> The query controller\n+A new controller is added : `ez_query`.\n+\n+It has two actions: `locationQuery`, and `contentQuery`.\n+\n+Both requires two arguments:\n+- `queryName`, the name of the QueryType to run. Example: `AcmeBundle:LatestArticles'\n+- `viewType`, similar to what `viewContent` and `viewLocation` expect. Examples: `list`, `tree`, `full_list`...\n+\n+If the QueryType supports any, they can be provided using the `parameters` argument (hash):\n+\n+```twig\n+{{ render(controller(\n+    'ez_query:locationQuery',\n+    {\n+        'queryName': 'AcmeBundle:LatestContent',\n+        'viewType': 'list',\n+        'parameters': {'ContentType': 'article'}\n+    }\n+)) }}\n+```\n+\n+### <a name=\"template_override\"></a>Rendering of queries\n+The `ez_query` actions support template override. They support several matchers.\n+- `QueryType\\Name`: matches the QueryType's name\n+- `QueryType\\Parameter`: matches the value of one or several of the parameters passed to the QueryType\n+- `QueryType\\Expression`: matches the parameters with an [Expression](http://symfony.com/en/doc/current/components/expression_language/index.html).\n+\n+Assuming we want to render the `AcmeBundle:LatestContent` query using\n+`AcmeBundle:query/list/latest_articles.html.twig` when the `ContentType` parameter has the value 'article':\n+\n+```twig\n+system:\n+    default:\n+        # Or content_query to create a template override for a content query\n+        location_query:\n+            # Matches the ViewType passed to the controller\n+            list:\n+                latest_articles:\n+                    template: \"AcmeBundle:query/list/latest_articles.html.twig\"\n+                    match:\n+                        QueryType\\Name: 'AcmeBundle:LatestContent'\n+                        QueryType\\Parameters: {ContentType: \"article\"}\n+```\n+\n+#### Template matchers\n+\n+##### `QueryType\\Name`\n+Matches the QueryType's name (exact match).\n+\n+##### `QueryType\\Parameters`\n+Matches the parameters against a given hash. The hash must contain the parameter's name as the key,\n+and the match value as the value:\n+\n+```yaml\n+match:\n+  QueryType\\Parameters:\n+    type: \"article\",\n+    category: \"development\"\n+```\n+\n+Each parameter will be matched exactly.\n+The matcher will match if ALL of the provided parameters match what is contained in the hash.\n+\n+##### `QueryType\\Expression`\n+Uses Symfony's [Expression Language](http://symfony.com/en/doc/current/components/expression_language/index.html)\n+for advanced matching.\n+This matcher expects a valid expression language string as the input. The expression must be\n+evaluated to a boolean. The parameters hash is available as `parameters`\n+\n+In the example below, 'type' must be either 'article' or 'blog_post'.\n+\n+```yaml\n+match:\n+  QueryType\\Expression: \"parameters['type'] in ['article', 'blog_post']\"\n+```\n+\n+### Query controller templates\n+The templates used by this controller provide you with the results from the query. The results can be iterated over, and\n+displayed using the object's properties or the `ez_content` controller actions.\n+\n+#### Available variables\n+\n+`location_list`/`content_list` | array | Array of search results, depending if the action (locationQuery or contentQuery)\n+`list_count`                   | int   | Number of items in the resultset, within the limit if any\n+`total_count`                  | int   | Total number of items in the search result\n+\n+## QueryType objects\n+To make a new QueryType available to the Query Controller, you need to create a class that implements the QueryType\n+interface, and register it as such in the service container.\n+\n+The interface has two methods:\n+- `getName(): string`\n+  Returns the QueryType name.\n+- `getQuery( array $parameters = null ): Query`\n+  It returns a Query object, that can be either a LocationQuery or a (Content) Query.\n+  It accepts an optional hash of parameters that can be used in any way in the QueryType's implementation\n+\n+### Parameters\n+A QueryType may accept parameters, depending on the implementation. They can be used in any way, such as:\n+  - customizing an element's value (limit, ContentType identifier, etc)\n+  - conditionally adding/removing criteria from the query\n+  - setting the limit/offset\n+\n+The implementations should use Symfony's `OptionsResolver` for parameters handling and resolution.\n+\n+### QueryType example: latest content\n+This QueryType returns a LocationQuery that searches for the 10 last published content, order by reverse\n+publishing date. It accepts an optional `type` parameter, that can be set to a ContentType identifier.\n+identifier:\n+\n+```php\n+<?php\n+namespace AcmeBundle\\Ez\\QueryType;\n+\n+use eZ\\Publish\\Core\\MVC\\Query\\QueryType;\n+use eZ\\Publish\\API\\Repository\\Values\\Content\\Query;\n+use eZ\\Publish\\API\\Repository\\Values\\Content\\Query\\Criterion;\n+\n+class LatestContentQueryType implements QueryType\n+{\n+    public function getQuery(array $parameters = [])\n+    {\n+        $criteria[] = new Criterion\\Visibility(Criterion\\Visibility::VISIBLE);\n+        if (isset($parameters['type'])) {\n+            $criteria[] = new Criterion\\ContentTypeIdentifier('article');","path":"doc/specifications/proposed/named_queries/developer_documentation.md","position":135,"original_position":135,"commit_id":"f549b0f70fcc787a564b77df7df27b8a8dfe45e2","original_commit_id":"f549b0f70fcc787a564b77df7df27b8a8dfe45e2","user":{"login":"lolautruche","id":313528,"avatar_url":"https://avatars.githubusercontent.com/u/313528?v=3","gravatar_id":"","url":"https://api.github.com/users/lolautruche","html_url":"https://github.com/lolautruche","followers_url":"https://api.github.com/users/lolautruche/followers","following_url":"https://api.github.com/users/lolautruche/following{/other_user}","gists_url":"https://api.github.com/users/lolautruche/gists{/gist_id}","starred_url":"https://api.github.com/users/lolautruche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lolautruche/subscriptions","organizations_url":"https://api.github.com/users/lolautruche/orgs","repos_url":"https://api.github.com/users/lolautruche/repos","events_url":"https://api.github.com/users/lolautruche/events{/privacy}","received_events_url":"https://api.github.com/users/lolautruche/received_events","type":"User","site_admin":false},"body":"Yes indeed. Always show best practices in dev doc :smile: ","created_at":"2015-07-08T13:28:19Z","updated_at":"2015-07-08T13:28:19Z","html_url":"https://github.com/ezsystems/ezpublish-kernel/pull/1319#discussion_r34146266","pull_request_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319","_links":{"self":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/comments/34146266"},"html":{"href":"https://github.com/ezsystems/ezpublish-kernel/pull/1319#discussion_r34146266"},"pull_request":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319"}}},"pull_request":{"url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319","id":38555310,"html_url":"https://github.com/ezsystems/ezpublish-kernel/pull/1319","diff_url":"https://github.com/ezsystems/ezpublish-kernel/pull/1319.diff","patch_url":"https://github.com/ezsystems/ezpublish-kernel/pull/1319.patch","issue_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/1319","number":1319,"state":"open","locked":false,"title":"EZP-24556: Named queries developer doc","user":{"login":"bdunogier","id":235928,"avatar_url":"https://avatars.githubusercontent.com/u/235928?v=3","gravatar_id":"","url":"https://api.github.com/users/bdunogier","html_url":"https://github.com/bdunogier","followers_url":"https://api.github.com/users/bdunogier/followers","following_url":"https://api.github.com/users/bdunogier/following{/other_user}","gists_url":"https://api.github.com/users/bdunogier/gists{/gist_id}","starred_url":"https://api.github.com/users/bdunogier/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bdunogier/subscriptions","organizations_url":"https://api.github.com/users/bdunogier/orgs","repos_url":"https://api.github.com/users/bdunogier/repos","events_url":"https://api.github.com/users/bdunogier/events{/privacy}","received_events_url":"https://api.github.com/users/bdunogier/received_events","type":"User","site_admin":false},"body":"> [EZP-24556](http://jira.ez.no/browse/EZP-24556)\r\n> Status: collaboration in progress\r\n\r\nThis is meant to establish the developer documentation for the Named Queries feature. Once complete, the technical specifications + development can be started.\r\n\r\n- [x] Integrate [conclusions from this PR](https://github.com/ezsystems/ezpublish-kernel/pull/1316)\r\n- [x] Update override rules doc + examples (separation of content & location)","created_at":"2015-06-25T14:47:43Z","updated_at":"2015-07-08T13:28:19Z","closed_at":null,"merged_at":null,"merge_commit_sha":"bb33a96d072e788fcd258657f65c284e5eaae6f5","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319/commits","review_comments_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319/comments","review_comment_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/1319/comments","statuses_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/statuses/f549b0f70fcc787a564b77df7df27b8a8dfe45e2","head":{"label":"ezsystems:ezp24556-named_queries_dev_requirements","ref":"ezp24556-named_queries_dev_requirements","sha":"f549b0f70fcc787a564b77df7df27b8a8dfe45e2","user":{"login":"ezsystems","id":295311,"avatar_url":"https://avatars.githubusercontent.com/u/295311?v=3","gravatar_id":"","url":"https://api.github.com/users/ezsystems","html_url":"https://github.com/ezsystems","followers_url":"https://api.github.com/users/ezsystems/followers","following_url":"https://api.github.com/users/ezsystems/following{/other_user}","gists_url":"https://api.github.com/users/ezsystems/gists{/gist_id}","starred_url":"https://api.github.com/users/ezsystems/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ezsystems/subscriptions","organizations_url":"https://api.github.com/users/ezsystems/orgs","repos_url":"https://api.github.com/users/ezsystems/repos","events_url":"https://api.github.com/users/ezsystems/events{/privacy}","received_events_url":"https://api.github.com/users/ezsystems/received_events","type":"Organization","site_admin":false},"repo":{"id":1663890,"name":"ezpublish-kernel","full_name":"ezsystems/ezpublish-kernel","owner":{"login":"ezsystems","id":295311,"avatar_url":"https://avatars.githubusercontent.com/u/295311?v=3","gravatar_id":"","url":"https://api.github.com/users/ezsystems","html_url":"https://github.com/ezsystems","followers_url":"https://api.github.com/users/ezsystems/followers","following_url":"https://api.github.com/users/ezsystems/following{/other_user}","gists_url":"https://api.github.com/users/ezsystems/gists{/gist_id}","starred_url":"https://api.github.com/users/ezsystems/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ezsystems/subscriptions","organizations_url":"https://api.github.com/users/ezsystems/orgs","repos_url":"https://api.github.com/users/ezsystems/repos","events_url":"https://api.github.com/users/ezsystems/events{/privacy}","received_events_url":"https://api.github.com/users/ezsystems/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ezsystems/ezpublish-kernel","description":"eZ Platform (aka eZ Publish 6.x) kernel","fork":false,"url":"https://api.github.com/repos/ezsystems/ezpublish-kernel","forks_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/forks","keys_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/teams","hooks_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/hooks","issue_events_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/events{/number}","events_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/events","assignees_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/assignees{/user}","branches_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/branches{/branch}","tags_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/tags","blobs_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/refs{/sha}","trees_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/statuses/{sha}","languages_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/languages","stargazers_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/stargazers","contributors_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/contributors","subscribers_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/subscribers","subscription_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/subscription","commits_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/commits{/sha}","git_commits_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/commits{/sha}","comments_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/comments{/number}","issue_comment_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/comments{/number}","contents_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/contents/{+path}","compare_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/merges","archive_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/downloads","issues_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues{/number}","pulls_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls{/number}","milestones_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/milestones{/number}","notifications_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/labels{/name}","releases_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/releases{/id}","created_at":"2011-04-26T08:54:24Z","updated_at":"2015-06-18T00:40:29Z","pushed_at":"2015-07-08T12:57:37Z","git_url":"git://github.com/ezsystems/ezpublish-kernel.git","ssh_url":"git@github.com:ezsystems/ezpublish-kernel.git","clone_url":"https://github.com/ezsystems/ezpublish-kernel.git","svn_url":"https://github.com/ezsystems/ezpublish-kernel","homepage":"http://ez.no","size":59000,"stargazers_count":100,"watchers_count":100,"language":"PHP","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":122,"mirror_url":null,"open_issues_count":55,"forks":122,"open_issues":55,"watchers":100,"default_branch":"master"}},"base":{"label":"ezsystems:master","ref":"master","sha":"8dee4f20a99aefdd01f2f04921abd4b45c8de1ed","user":{"login":"ezsystems","id":295311,"avatar_url":"https://avatars.githubusercontent.com/u/295311?v=3","gravatar_id":"","url":"https://api.github.com/users/ezsystems","html_url":"https://github.com/ezsystems","followers_url":"https://api.github.com/users/ezsystems/followers","following_url":"https://api.github.com/users/ezsystems/following{/other_user}","gists_url":"https://api.github.com/users/ezsystems/gists{/gist_id}","starred_url":"https://api.github.com/users/ezsystems/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ezsystems/subscriptions","organizations_url":"https://api.github.com/users/ezsystems/orgs","repos_url":"https://api.github.com/users/ezsystems/repos","events_url":"https://api.github.com/users/ezsystems/events{/privacy}","received_events_url":"https://api.github.com/users/ezsystems/received_events","type":"Organization","site_admin":false},"repo":{"id":1663890,"name":"ezpublish-kernel","full_name":"ezsystems/ezpublish-kernel","owner":{"login":"ezsystems","id":295311,"avatar_url":"https://avatars.githubusercontent.com/u/295311?v=3","gravatar_id":"","url":"https://api.github.com/users/ezsystems","html_url":"https://github.com/ezsystems","followers_url":"https://api.github.com/users/ezsystems/followers","following_url":"https://api.github.com/users/ezsystems/following{/other_user}","gists_url":"https://api.github.com/users/ezsystems/gists{/gist_id}","starred_url":"https://api.github.com/users/ezsystems/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ezsystems/subscriptions","organizations_url":"https://api.github.com/users/ezsystems/orgs","repos_url":"https://api.github.com/users/ezsystems/repos","events_url":"https://api.github.com/users/ezsystems/events{/privacy}","received_events_url":"https://api.github.com/users/ezsystems/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ezsystems/ezpublish-kernel","description":"eZ Platform (aka eZ Publish 6.x) kernel","fork":false,"url":"https://api.github.com/repos/ezsystems/ezpublish-kernel","forks_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/forks","keys_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/teams","hooks_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/hooks","issue_events_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/events{/number}","events_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/events","assignees_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/assignees{/user}","branches_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/branches{/branch}","tags_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/tags","blobs_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/refs{/sha}","trees_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/statuses/{sha}","languages_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/languages","stargazers_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/stargazers","contributors_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/contributors","subscribers_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/subscribers","subscription_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/subscription","commits_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/commits{/sha}","git_commits_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/git/commits{/sha}","comments_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/comments{/number}","issue_comment_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/comments{/number}","contents_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/contents/{+path}","compare_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/merges","archive_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/downloads","issues_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues{/number}","pulls_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls{/number}","milestones_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/milestones{/number}","notifications_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/labels{/name}","releases_url":"https://api.github.com/repos/ezsystems/ezpublish-kernel/releases{/id}","created_at":"2011-04-26T08:54:24Z","updated_at":"2015-06-18T00:40:29Z","pushed_at":"2015-07-08T12:57:37Z","git_url":"git://github.com/ezsystems/ezpublish-kernel.git","ssh_url":"git@github.com:ezsystems/ezpublish-kernel.git","clone_url":"https://github.com/ezsystems/ezpublish-kernel.git","svn_url":"https://github.com/ezsystems/ezpublish-kernel","homepage":"http://ez.no","size":59000,"stargazers_count":100,"watchers_count":100,"language":"PHP","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":122,"mirror_url":null,"open_issues_count":55,"forks":122,"open_issues":55,"watchers":100,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319"},"html":{"href":"https://github.com/ezsystems/ezpublish-kernel/pull/1319"},"issue":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/1319"},"comments":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/issues/1319/comments"},"review_comments":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319/comments"},"review_comment":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/pulls/1319/commits"},"statuses":{"href":"https://api.github.com/repos/ezsystems/ezpublish-kernel/statuses/f549b0f70fcc787a564b77df7df27b8a8dfe45e2"}}}}