Developers

Layouts

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

Summary of layout endpoints

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"
  },
  {
    "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"
  }
]

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, error_401, error_404.

Filter attributes

Read more about filters.

  • Object layout attributes: id, parent_id, title, content_type, component, layout_name, body, created_at, updated_at.

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"
}

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, blog, blog_article, elements, element. There are also special layout types for error pages: error_401 (for password protected pages), error_404 (not found error). There can be only one layout per error type.
  • 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"
}

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"
}

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, blog, blog_article, elements, element. There are also special layout types for error pages: error_401 (for password protected pages), error_404 (not found error). There can be only one layout per error type.
  • 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.