doc/index.html in gqli-0.5.0 vs doc/index.html in gqli-0.6.0

- old
+ new

@@ -89,28 +89,38 @@ <h2 id="label-Usage">Usage</h2> <h3 id="label-Creating+a+GraphQL+Client">Creating a GraphQL Client</h3> <p>For the examples throughout this README, we&#39;ll be using the Contentful -and Github GraphQL APIs. Therefore, here&#39;s the initialization code -required for both of them:</p> +and Github GraphQL APIs, for which we have factory methods. Therefore, +here&#39;s the initialization code required for both of them:</p> <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>gqli</span><span class='tstring_end'>&#39;</span></span> <span class='comment'># Creating a Contentful GraphQL Client </span><span class='const'>SPACE_ID</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>cfexampleapi</span><span class='tstring_end'>&#39;</span></span> <span class='const'>CF_ACCESS_TOKEN</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>b4c0n73n7fu1</span><span class='tstring_end'>&#39;</span></span> -<span class='const'>CONTENTFUL_GQL</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/Client.html" title="GQLi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="GQLi/Client.html#initialize-instance_method" title="GQLi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span> - <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>https://graphql.contentful.com/content/v1/spaces/</span><span class='embexpr_beg'>#{</span><span class='const'>SPACE_ID</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> - <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Authorization</span><span class='tstring_end'>&quot;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Bearer </span><span class='embexpr_beg'>#{</span><span class='const'>CF_ACCESS_TOKEN</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span> -<span class='rparen'>)</span> +<span class='const'>CONTENTFUL_GQL</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/Contentful.html" title="GQLi::Contentful (module)">Contentful</a></span></span><span class='period'>.</span><span class='id identifier rubyid_create'><span class='object_link'><a href="GQLi/Contentful.html#create-class_method" title="GQLi::Contentful.create (method)">create</a></span></span><span class='lparen'>(</span><span class='const'>SPACE_ID</span><span class='comma'>,</span> <span class='const'>CF_ACCESS_TOKEN</span><span class='rparen'>)</span> <span class='comment'># Creating a Github GraphQL Client </span><span class='const'>GITHUB_ACCESS_TOKEN</span> <span class='op'>=</span> <span class='const'>ENV</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>GITHUB_TOKEN</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> -<span class='const'>GITHUB_GQL</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/Client.html" title="GQLi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="GQLi/Client.html#initialize-instance_method" title="GQLi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span> - <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>https://api.github.com/graphql</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> - <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Authorization</span><span class='tstring_end'>&quot;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Bearer </span><span class='embexpr_beg'>#{</span><span class='const'>GITHUB_ACCESS_TOKEN</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span> +<span class='const'>GITHUB_GQL</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/Github.html" title="GQLi::Github (module)">Github</a></span></span><span class='period'>.</span><span class='id identifier rubyid_create'><span class='object_link'><a href="GQLi/Github.html#create-class_method" title="GQLi::Github.create (method)">create</a></span></span><span class='lparen'>(</span><span class='const'>GITHUB_ACCESS_TOKEN</span><span class='rparen'>)</span> +</code></pre> + +<p><em>Note</em>: Please feel free to contribute factories for your favorite +GraphQL services.</p> + +<p>For creating a custom GraphQL client:</p> + +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>gqli</span><span class='tstring_end'>&#39;</span></span> + +<span class='comment'># Create a custom client +</span><span class='const'>GQL_CLIENT</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/Client.html" title="GQLi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="GQLi/Client.html#initialize-instance_method" title="GQLi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span> + <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>https://graphql.yourservice.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> + <span class='label'>headers:</span> <span class='lbrace'>{</span> + <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Authorization</span><span class='tstring_end'>&quot;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Bearer AUTH_TOKEN</span><span class='tstring_end'>&quot;</span></span> + <span class='rbrace'>}</span> <span class='rparen'>)</span> </code></pre> <h3 id="label-Creating+a+Query">Creating a Query</h3> @@ -392,10 +402,70 @@ <p>The difference is that by using the native implementation, in case of the condition not being met, the node will be completely not included in the outgoing query.</p> +<h3 id="label-Enums">Enums</h3> + +<p><a href="https://graphql.org/learn/schema/#enumeration-types">Enums</a> are +a list of predefined values that are defined on the type system level. +Since Ruby doesn&#39;t have built-in Enums that can be translated directly +into GraphQL Enums, we created the <code>__enum</code> helper that you can +use within your queries to transform your values into an Enum value.</p> + +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_query'>query</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/DSL.html" title="GQLi::DSL (module)">DSL</a></span></span><span class='period'>.</span><span class='id identifier rubyid_query'><span class='object_link'><a href="GQLi/DSL.html#query-class_method" title="GQLi::DSL.query (method)">query</a></span></span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_catCollection'>catCollection</span><span class='lparen'>(</span><span class='label'>order:</span> <span class='id identifier rubyid___enum'>__enum</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>lives_ASC</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='rparen'>)</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_items'>items</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_name'>name</span> + <span class='rbrace'>}</span> + <span class='rbrace'>}</span> +<span class='rbrace'>}</span> +</code></pre> + +<p>This will render to:</p> + +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_query'>query</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_catCollection'>catCollection</span><span class='lparen'>(</span><span class='label'>order:</span> <span class='id identifier rubyid_lives_ASC'>lives_ASC</span><span class='rparen'>)</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_items'>items</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_name'>name</span> + <span class='rbrace'>}</span> + <span class='rbrace'>}</span> +<span class='rbrace'>}</span> +</code></pre> + +<h3 id="label-Aliases">Aliases</h3> + +<p>There may be times where it is useful to have parts of the query aliased, +for example, when querying for <code>pinned</code> and +<code>unpinned</code> articles for a news site.</p> + +<p>This can be accomplished as follows:</p> + +<pre class="code ruby"><code class="ruby"><span class='const'>ArticleFragment</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/DSL.html" title="GQLi::DSL (module)">DSL</a></span></span><span class='period'>.</span><span class='id identifier rubyid_fragment'><span class='object_link'><a href="GQLi/DSL.html#fragment-class_method" title="GQLi::DSL.fragment (method)">fragment</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>ArticleFragment</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>ArticleCollection</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_items'>items</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_title'>title</span> + <span class='id identifier rubyid_description'>description</span> + <span class='id identifier rubyid_heroImage'>heroImage</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid_url'>url</span> + <span class='rbrace'>}</span> + <span class='rbrace'>}</span> +<span class='rbrace'>}</span> + +<span class='id identifier rubyid_query'>query</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="GQLi.html" title="GQLi (module)">GQLi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="GQLi/DSL.html" title="GQLi::DSL (module)">DSL</a></span></span><span class='period'>.</span><span class='id identifier rubyid_query'><span class='object_link'><a href="GQLi/DSL.html#query-class_method" title="GQLi::DSL.query (method)">query</a></span></span> <span class='lbrace'>{</span> + <span class='id identifier rubyid___node'>__node</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>pinned: articleCollection</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>where:</span> <span class='lbrace'>{</span> + <span class='label'>sys:</span> <span class='lbrace'>{</span> <span class='label'>id_in:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>articleID</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='rbrace'>}</span> + <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid____'>___</span> <span class='const'>ArticleFragment</span> + <span class='rbrace'>}</span> + <span class='id identifier rubyid___node'>__node</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>unpinned: articleCollection</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>where:</span> <span class='lbrace'>{</span> + <span class='label'>sys:</span> <span class='lbrace'>{</span> <span class='label'>id_not_in:</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>articleID</span><span class='tstring_end'>&#39;</span></span><span class='rbracket'>]</span> <span class='rbrace'>}</span> + <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='lbrace'>{</span> + <span class='id identifier rubyid____'>___</span> <span class='const'>ArticleFragment</span> + <span class='rbrace'>}</span> +<span class='rbrace'>}</span> +</code></pre> + <h2 id="label-Yet+to+be+implemented">Yet to be implemented</h2> <ul><li> <p>Mutation queries</p> </li><li> <p>Subscription queries</p> @@ -425,12 +495,12 @@ href="https://github.com/contentful-developer-relations/community-code-of-conduct">Read our full Code of Conduct</a>.</p> </div></div> <div id="footer"> - Generated on Fri Jan 25 13:36:03 2019 by + Generated on Sat Feb 16 22:53:59 2019 by <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a> - 0.9.16 (ruby-2.5.1). + 0.9.16 (ruby-2.5.3). </div> </div> </body> </html> \ No newline at end of file