ditkrg/active_model_serializers
4
0
Fork 0
mirror of https://github.com/ditkrg/active_model_serializers.git synced 2026-01-22 22:06:50 +00:00
Code Issues Packages Projects Releases Wiki Activity
gh-pages
active_model_serializers/index.html
Benjamin Fleischer e4258b6db9 Generating docs for version 0.10.0 at ref 0e46d20.
2016-06-16 09:05:14 -05:00

262 lines
13 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
File: README
&mdash; Documentation by YARD 0.8.7.6
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
hasFrames = window.top.frames.main ? true : false;
relpath = '';
framesUrl = "frames.html#!file.README.html";
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> &raquo;
<span class="title">File: README</span>
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
Class List
</a>
<a class="full_list_link" id="method_list_link"
href="method_list.html">
Method List
</a>
<a class="full_list_link" id="file_list_link"
href="file_list.html">
File List
</a>
</div>
<div class="clear"></div>
</div>
<iframe id="search_frame"></iframe>
<div id="content"><div id='filecontents'>
<h1 id="label-ActiveModelSerializers">ActiveModelSerializers</h1>
<table>
<tr>
<td>Build Status</td>
<td>
<a href="https://travis-ci.org/rails-api/active_model_serializers"><img src="https://travis-ci.org/rails-api/active_model_serializers.svg?branch=master" alt="Build Status" ></a>
<a href="https://ci.appveyor.com/project/joaomdmoura/active-model-serializers/branch/master"><img src="https://ci.appveyor.com/api/projects/status/x6xdjydutm54gvyt/branch/master?svg=true" alt="Build status"></a>
</td>
</tr>
<tr>
<td>Code Quality</td>
<td>
<a href="https://codeclimate.com/github/rails-api/active_model_serializers"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/gpa.svg" alt="Code Quality"></a>
<a href="https://codebeat.co/projects/github-com-rails-api-active_model_serializers"><img src="https://codebeat.co/badges/a9ab35fa-8b5a-4680-9d4e-a81f9a55ebcd" alt="codebeat" ></a>
<a href="https://codeclimate.com/github/rails-api/active_model_serializers/coverage"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/coverage.svg" alt="Test Coverage"></a>
</td>
</tr>
<tr>
<td>Issue Stats</td>
<td>
<a href="https://github.com/rails-api/active_model_serializers/pulse/monthly">Pulse</a>
</td>
</tr>
</table>
<h2 id="label-About">About</h2>
<p>ActiveModelSerializers brings convention over configuration to your JSON
generation.</p>
<p>ActiveModelSerializers works through two components:
<strong>serializers</strong> and <strong>adapters</strong>.</p>
<p>Serializers describe <em>which</em> attributes and relationships should be
serialized.</p>
<p>Adapters describe <em>how</em> attributes and relationships should be
serialized.</p>
<p>SerializableResource co-ordinates the resource, Adapter and Serializer to
produce the resource serialization. The serialization has the
<code>#as_json</code>, <code>#to_json</code> and
<code>#serializable_hash</code> methods used by the Rails JSON Renderer.
(SerializableResource actually delegates these methods to the adapter.)</p>
<p>By default ActiveModelSerializers will use the <strong>Attributes
Adapter</strong> (no JSON root). But we strongly advise you to use
<strong>JsonApi Adapter</strong>, which follows 1.0 of the format specified
in <a href="http://jsonapi.org/format">jsonapi.org/format</a>. Check how to
change the adapter in the sections below.</p>
<p><code>0.10.x</code> is <strong>not</strong> backward compatible with
<code>0.9.x</code> nor <code>0.8.x</code>.</p>
<p><code>0.10.x</code> is based on the <code>0.8.0</code> code, but with a
more flexible architecture. We&#39;d love your help. <a
href="CONTRIBUTING.md">Learn how you can help here.</a></p>
<p>It is generally safe and recommended to use the master branch.</p>
<h2 id="label-Installation">Installation</h2>
<p>Add this line to your application&#39;s Gemfile:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>active_model_serializers</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'>~&gt; 0.10.0</span><span class='tstring_end'>&#39;</span></span>
</code></pre>
<p>And then execute:</p>
<pre class="code ruby"><code class="ruby">$ bundle</code></pre>
<h2 id="label-Getting+Started">Getting Started</h2>
<p>See <a href="docs/general/getting_started.md">Getting Started</a> for the
nuts and bolts.</p>
<p>More information is available in the <a href="docs">Guides</a> and <a
href="README.md#high-level-behavior">High-level behavior</a>.</p>
<h2 id="label-Getting+Help">Getting Help</h2>
<p>If you find a bug, please report an <a
href="https://github.com/rails-api/active_model_serializers/issues/new">Issue</a>
and see our <a href="CONTRIBUTING.md">contributing guide</a>.</p>
<p>If you have a question, please <a
href="http://stackoverflow.com/questions/tagged/active-model-serializers">post
to Stack Overflow</a>.</p>
<p>If you&#39;d like to chat, we have a <a
href="http://amserializers.herokuapp.com">community slack</a>.</p>
<p>Thanks!</p>
<h2 id="label-Documentation">Documentation</h2>
<ul><li>
<p><a
href="https://github.com/rails-api/active_model_serializers/tree/master">0.10
(master) Documentation</a></p>
</li><li>
<p><a
href="http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0"><img
src="http://img.shields.io/badge/yard-docs-blue.svg"></a></p>
</li><li>
<p><a href="docs">Guides</a></p>
</li><li>
<p><a
href="https://github.com/rails-api/active_model_serializers/tree/0-9-stable">0.9
(0-9-stable) Documentation</a></p>
</li><li>
<p><a
href="http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable"><img
src="http://img.shields.io/badge/yard-docs-blue.svg"></a></p>
</li><li>
<p><a
href="https://github.com/rails-api/active_model_serializers/tree/0-8-stable">0.8
(0-8-stable) Documentation</a></p>
</li><li>
<p><a
href="http://www.rubydoc.info/github/rails-api/active_model_serializers/0-8-stable"><img
src="http://img.shields.io/badge/yard-docs-blue.svg"></a></p>
</li></ul>
<h2 id="label-High-level+behavior">High-level behavior</h2>
<p>Choose an adapter from <a
href="lib/active_model_serializers/adapter">adapters</a>:</p>
<pre class="code ruby"><code class="ruby"><span class='const'>ActiveModelSerializers</span><span class='period'>.</span><span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_adapter'>adapter</span> <span class='op'>=</span> <span class='symbol'>:json_api</span> <span class='comment'># Default: `:attributes`
</span></code></pre>
<p>Given a <a href="lib/active_model/serializer/lint.rb">serializable
model</a>:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># either
</span><span class='kw'>class</span> <span class='const'>SomeResource</span> <span class='op'>&lt;</span> <span class='const'>ActiveRecord</span><span class='op'>::</span><span class='const'>Base</span>
<span class='comment'># columns: title, body
</span><span class='kw'>end</span>
<span class='comment'># or
</span><span class='kw'>class</span> <span class='const'>SomeResource</span> <span class='op'>&lt;</span> <span class='const'>ActiveModelSerializers</span><span class='op'>::</span><span class='const'>Model</span>
<span class='id identifier rubyid_attr_accessor'>attr_accessor</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='symbol'>:body</span>
<span class='kw'>end</span>
</code></pre>
<p>And initialized as:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_resource'>resource</span> <span class='op'>=</span> <span class='const'>SomeResource</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='label'>title:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>ActiveModelSerializers</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>body:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Convention over configuration</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
</code></pre>
<p>Given a serializer for the serializable model:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>SomeSerializer</span> <span class='op'>&lt;</span> <span class='const'>ActiveModel</span><span class='op'>::</span><span class='const'>Serializer</span>
<span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='label'>key:</span> <span class='symbol'>:name</span>
<span class='id identifier rubyid_attributes'>attributes</span> <span class='symbol'>:body</span>
<span class='kw'>end</span>
</code></pre>
<p>The model can be serialized as:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
<span class='id identifier rubyid_serialization'>serialization</span> <span class='op'>=</span> <span class='const'>ActiveModelSerializers</span><span class='op'>::</span><span class='const'>SerializableResource</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_resource'>resource</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span><span class='rparen'>)</span>
<span class='id identifier rubyid_serialization'>serialization</span><span class='period'>.</span><span class='id identifier rubyid_to_json'>to_json</span>
<span class='id identifier rubyid_serialization'>serialization</span><span class='period'>.</span><span class='id identifier rubyid_as_json'>as_json</span>
</code></pre>
<p>SerializableResource delegates to the adapter, which it builds as:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_adapter_options'>adapter_options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
<span class='id identifier rubyid_adapter'>adapter</span> <span class='op'>=</span> <span class='const'>ActiveModelSerializers</span><span class='op'>::</span><span class='const'>Adapter</span><span class='period'>.</span><span class='id identifier rubyid_create'>create</span><span class='lparen'>(</span><span class='id identifier rubyid_serializer'>serializer</span><span class='comma'>,</span> <span class='id identifier rubyid_adapter_options'>adapter_options</span><span class='rparen'>)</span>
<span class='id identifier rubyid_adapter'>adapter</span><span class='period'>.</span><span class='id identifier rubyid_to_json'>to_json</span>
<span class='id identifier rubyid_adapter'>adapter</span><span class='period'>.</span><span class='id identifier rubyid_as_json'>as_json</span>
<span class='id identifier rubyid_adapter'>adapter</span><span class='period'>.</span><span class='id identifier rubyid_serializable_hash'>serializable_hash</span>
</code></pre>
<p>The adapter formats the serializer&#39;s attributes and associations
(a.k.a. includes):</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_serializer_options'>serializer_options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
<span class='id identifier rubyid_serializer'>serializer</span> <span class='op'>=</span> <span class='const'>SomeSerializer</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_resource'>resource</span><span class='comma'>,</span> <span class='id identifier rubyid_serializer_options'>serializer_options</span><span class='rparen'>)</span>
<span class='id identifier rubyid_serializer'>serializer</span><span class='period'>.</span><span class='id identifier rubyid_attributes'>attributes</span>
<span class='id identifier rubyid_serializer'>serializer</span><span class='period'>.</span><span class='id identifier rubyid_associations'>associations</span>
</code></pre>
<p>See <a href="docs/ARCHITECTURE.md">ARCHITECTURE.md</a> for more
information.</p>
<h2 id="label-Contributing">Contributing</h2>
<p>See <a href="CONTRIBUTING.md">CONTRIBUTING.md</a></p>
</div></div>
<div id="footer">
Generated on Thu Jun 16 09:05:02 2016 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.6 (ruby-2.2.4).
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink