[[people-custom-field-sections]]
== PEOPLE: CUSTOM FIELD SECTIONS

=== Introduction

OpenCBS has a couple of concepts that greatly increase its flexibility and the ability to be adjusted
to different practices and contexts. They are _custom fields_ and _custom field sections_.

_Custom fields_ is a way to enhance the default set of attributes of certain resources by your own attributes.
For example, when you create personal profiles OpenCBS allows you to capture the first name, the last name, and
the birth date. But what if you need to collect more data points about each prospective client than what's
available by default? What if you want to record information about their professional or educational background?
Custom fields is the answer to those questions, it is a way for you to define additional attributes and let
OpenCBS manage them for you.

Custom fields are grouped into clusters called _custom field sections_. This is just logical grouping of
custom fields. It does not give you much more flexibility than what you already have with custom fields,
however, they allow for building more convenient input forms inside of client applications whereas bunches
of input elements are grouped together. Think of them as containers where you add your custom fields and
then the input elements for each custom field are placed into the corresponding container when being
displayed in the form.

Both custom fields and custom field sections do not exist on their own. Rather, they have to be
defined within and for a certain resource. This chapter, for example, deals with custom field sections
for personal profiles. Further down below you will find similar chapters for other resources like
company profiles, loans, savings, etc.

[[people-custom-field-sections-list]]
=== List sections

A `GET` request will list all custom field sections linked to the personal profile.

[[people-custom-field-sections-list-response]]
==== Response structure

As you see in the table below, each section contains a list of custom fields linked to it. This might
look like a lot of extra data when fetching this resource, but it turns out to be quite handy in practice
when you build the form in your client application for capturing personal profile data: there is no
need to send separate requests to the backend to fetch custom fields for each section, because all the data is
already there.

include::{snippets}/people-custom-field-sections-get-all-example/response-fields.adoc[]

==== Example request

include::{snippets}/people-custom-field-sections-get-all-example/http-request.adoc[]

==== Example response

include::{snippets}/people-custom-field-sections-get-all-example/http-response.adoc[]


=== Retrieve a section

A `GET` request will retrieve the details of a custom field section.

[[people-custom-field-sections-get-response]]
==== Response structure

include::{snippets}/people-custom-field-sections-get-example/response-fields.adoc[]

==== Example request

include::{snippets}/people-custom-field-sections-get-example/http-request.adoc[]

==== Example response

include::{snippets}/people-custom-field-sections-get-example/http-response.adoc[]

=== Create a section

A `POST` request will create a new custom field section.

[[people-custom-field-sections-create-request]]
==== Request structure

include::{snippets}/people-custom-field-sections-create-example/request-fields.adoc[]

[[people-custom-field-sections-create-response]]
==== Response structure

A new section is assigned the order of the last existing section plus 1. Thus, it is placed at the
end of the collection. As you see from the table below, the whole collection is returned to the client.
This might look like a lot of extra data, but it turns out to be pretty handy, especially if you are
developing a web application in a framework with some form of state management in it (read React+Redux/MobX,
or Angular2+Redux, and so on.). This way you fire just one `POST` request, read in the response, and
update the store with the updated list of sections.

include::{snippets}/people-custom-field-sections-create-example/response-fields.adoc[]

==== Example request

include::{snippets}/people-custom-field-sections-create-example/http-request.adoc[]

==== Example response

include::{snippets}/people-custom-field-sections-create-example/http-response.adoc[]

=== Update a section

A `PUT` request will update the details of a custom field section.

[[people-custom-field-sections-update-request]]
==== Request structure

include::{snippets}/people-custom-field-sections-update-example/request-fields.adoc[]

[[people-custom-field-sections-update-response]]
==== Response structure

include::{snippets}/people-custom-field-sections-update-example/response-fields.adoc[]

==== Example request

include::{snippets}/people-custom-field-sections-update-example/http-request.adoc[]

==== Example response

As you can tell from the example response, by assigning the value of `1` to `order` we have effectively
rearranged the sections and this section has bubbled up to the top.

include::{snippets}/people-custom-field-sections-update-example/http-response.adoc[]
