Layouts

Layout resources encompass all liquid templates that make up the bulk of an Voog site's HTML.

Summary of layout endpoints

• GET /admin/api/layouts - list all available layouts for the current site.
• POST /admin/api/layouts - create a new layout for the current site.
• GET /admin/api/layouts/1 - get data for a single layout.
• PUT /admin/api/layouts/1 - update attributes of a single layout.
• DELETE /admin/api/layouts/1 - remove a layout.

List all available layouts for the current site

Get list of layouts and layout components of current site for active design.

Depending on the site design setup, the response may include both design-specific layouts and global layouts (e.g. "Blank layout"). Use mime_type to distinguish custom and stock layouts.

Kind of layout design (custom/stock/global) is presented using mime_type attribute where possible values are:

• application/vnd.voog.design.custom+liquid - custom design.
• application/vnd.voog.design.stock+liquid - stock design.
• application/vnd.voog.design.global+liquid - global design.

GET /admin/api/layouts

Example response:

Status: 200 OK

[
  {
    "id": 1,
    "parent_id": null,
    "title": "Common page",
    "layout_name": "common_page",
    "content_type": "page",
    "mime_type": "application/vnd.voog.design.custom+liquid",
    "component": false,
    "url": "http://helloworld.voog.co/admin/api/layouts/1",
    "created_at": "2008-06-18T14:41:12.000Z",
    "updated_at": "2012-01-26T11:14:53.000Z",
    "updater": {
      "id": 1,
      "email": "user@example.com",
      "firstname": "John",
      "lastname": "Smith",
      "name": "John Smith",
      "url": "http://helloworld.voog.co/admin/api/people/1
    }
  },
  {
    "id": 2,
    "parent_id": null,
    "title": "Blog & News",
    "layout_name": "blog",
    "content_type": "blog",
    "mime_type": "application/vnd.voog.design.custom+liquid",
    "component": false,
    "url": "http://helloworld.voog.co/admin/api/layouts/2",
    "created_at": "2008-06-18T14:42:09.000Z",
    "updated_at": "2013-06-06T12:00:25.000Z",
    "updater": {
      "id": 1,
      "email": "user@example.com",
      "firstname": "John",
      "lastname": "Smith",
      "name": "John Smith",
      "url": "http://helloworld.voog.co/admin/api/people/1
    }
  }
]

Parameters

• per_page - elements per response (default: 50; maximum: 250).
• page - requested page (default: 1).
• content_type - filter by layout content type (e.g. ?content_type=page). Accepted values are: page, blog, blog_article, elements, element, product, error_401, error_404.
• include_body - if present, the listing includes body in each returned layout, as in the single layout endpoint.

Filter attributes

Read more about filters.

• Object layout attributes: id, parent_id, title, content_type, component, layout_name, body, updater_id, created_at, updated_at.
• Object updater attributes: id, email, firstname, lastname. Applies only for custom design layouts.

Create a new layout for the current site

POST /admin/api/layouts

Creating a new layout is allowed only when current site is using custom design. See site site.custom_design attribute.

Example data:

{
  "title": "Blog article",
  "component": false,
  "created_at": "2008-06-18T14:42:09.000Z",
  "updated_at": "2013-06-06T12:00:25.000Z",
  "content_type": "blog_article",
  "parent_id": 2,
  "body": "asdf"
}

Example response:

Status: 201 Created

{
  "id": 3,
  "parent_id": 2,
  "title": "Blog article",
  "layout_name": "blog_article",
  "content_type": "blog_article",
  "mime_type": "application/vnd.voog.design.custom+liquid",
  "body": "asdf",
  "component": false,
  "url": "http://helloworld.voog.co/admin/api/layouts/3",
  "created_at": "2008-06-18T14:43:10.000Z",
  "updated_at": "2013-06-06T12:00:08.000Z",
  "updater": {
    "id": 1,
    "email": "user@example.com",
    "firstname": "John",
    "lastname": "Smith",
    "name": "John Smith",
    "url": "http://helloworld.voog.co/admin/api/people/1
  }
}

Parameters

Required minimum set of parameters are:

• title - human readable layout name. (NB! Should be unique in case of components.)
• content_type - content type. Accepted values for layouts:
  • page – the most basic type used in most pages.
  • blog – for blog article listings pages.
  • blog_article – for blog article pages.
  • elements – for element listings pages.
  • element – for element pages.
  • product – for canonical product pages (one layout per site).
  • error_401 for password protected pages (one layout per site).
  • error_404 not found error page (one layout per site).
• body - layout body (can be empty string).
• parent_id - required only for layouts where content_type is blog_article or element.

Optional parameters:

• component - boolean value that detects kind of layout (layout or component). Default is false.
• layout_name - internal layout name. Default is unified value from title.
• parent_title - parent layout title. Required only for layouts where content_type is blog_article or element. It's ignored when parent_id is presented in request.

Get data for a single layout

GET /admin/api/layouts/1

Example request:

GET http://helloworld.voog.co/admin/api/layouts/3

Example response:

Status: 200 OK

{
  "id": 3,
  "parent_id": 2,
  "title": "Blog article",
  "layout_name": "blog_article",
  "content_type": "blog_article",
  "mime_type": "application/vnd.voog.design.custom+liquid",
  "body": "asdf",
  "component": false,
  "url": "http://helloworld.voog.co/admin/api/layouts/3",
  "created_at": "2008-06-18T14:43:10.000Z",
  "updated_at": "2013-06-06T12:00:08.000Z",
  "updater": {
    "id": 1,
    "email": "user@example.com",
    "firstname": "John",
    "lastname": "Smith",
    "name": "John Smith",
    "url": "http://helloworld.voog.co/admin/api/people/1
  }
}

Update attributes of a single layout

PUT /admin/api/layouts/1

This request updates the layout with provided attributes.

Update request is allowed only when current site is using custom design and layout mime_type value is application/vnd.voog.design.custom+liquid.

Example request:

PUT http://helloworld.voog.co/admin/api/layouts/1

Example data:

{
  "title": "new layout title"
}

Example response:

Status: 200 OK

{
  "id": 3,
  "parent_id": 2,
  "title": "new layout title",
  "layout_name": "blog_article",
  "content_type": "blog_article",
  "mime_type": "application/vnd.voog.design.custom+liquid",
  "body": "asdf",
  "component": false,
  "url": "http://helloworld.voog.co/admin/api/layouts/3",
  "created_at": "2008-06-18T14:43:10.000Z",
  "updated_at": "2013-06-06T12:00:08.000Z",
  "updater": {
    "id": 1,
    "email": "user@example.com",
    "firstname": "John",
    "lastname": "Smith",
    "name": "John Smith",
    "url": "http://helloworld.voog.co/admin/api/people/1
  }
}

Parameters

Optional parameters:

• title - human readable layout name. (NB! Should be unique in case of components.)
• content_type - content type. Accepted values for layouts:
  • page – the most basic type used in most pages.
  • blog – for blog article listings pages.
  • blog_article – for blog article pages.
  • elements – for element listings pages.
  • element – for element pages.
  • product – for canonical product pages (one layout per site).
  • error_401 for password protected pages (one layout per site).
  • error_404 not found error page (one layout per site).
• body - layout body (can be empty string).
• parent_id - required only for layouts where content_type is blog_article or element.
• component - boolean value that detects kind of layout (layout or component). Default is false.
• layout_name - internal layout name. Default is unified value from title.

Remove a layout

DELETE /admin/api/layouts/1

This request deletes the layout from the database.

Delete request is allowed only when current site is using custom design and layout mime_type value is application/vnd.voog.design.custom+liquid.

Example request:

DELETE http://helloworld.voog.co/admin/api/layouts/1

Example response:

Status: 204 No Content

Limits:

• If layout is assigned to at least one page, it will not be deleted.