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.

Kind of layout design (custom/stock) 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.

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.

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.