# ViewsBuilder

Factory for the View objects a controller returns to render a response, plus helpers for building JsonResult objects and throwing common HTTP error
responses.

A single shared instance is bound into server-side JS as the "views" global, so app code builds responses with calls like views.templateView(...),
views.jsonView(...), views.csvView(...) and returns the result from a controller function. Each factory method wraps a matching View implementation
constructor.

Package: `io.milton.cloud.server.repoapps.views`  
Group: Views  

## Methods

### `templateView(String template)`

Returns: [TemplateView](TemplateView.md)

Creates a view that renders the given HTML template path against the current resource.

| Parameter | Description |
|---|---|
| `template` | the path of the template to render |

### `jsonView(String attribute)`

Returns: [JsonView](JsonView.md)

Creates a view that renders the named page attribute as JSON.

| Parameter | Description |
|---|---|
| `attribute` | the name of the page attribute holding the object to render as JSON |

### `jsonView(boolean status, String message)`

Returns: [JsonView](JsonView.md)

Creates a view that renders a simple success/failure JsonResult as JSON.

| Parameter | Description |
|---|---|
| `status` | the result's success flag |
| `message` | the result's message text |

### `jsonObjectView(Object o)`

Returns: [JsonView](JsonView.md)

Creates a view that renders the given object as JSON.

| Parameter | Description |
|---|---|
| `o` | the object to render as JSON |

### `redirectView(String uri)`

Returns: [RedirectView](RedirectView.md)

Creates a view that issues a temporary redirect to the given URI.

| Parameter | Description |
|---|---|
| `uri` | the URI to redirect to |

### `redirectView(String uri, boolean permanent)`

Returns: [RedirectView](RedirectView.md)

Creates a view that redirects to the given URI, as a permanent redirect if requested.

| Parameter | Description |
|---|---|
| `uri` | the URI to redirect to |
| `permanent` | true to issue a permanent redirect rather than a temporary one |

### `textTemplateView(String template, String contentType)`

Returns: [TextTemplateView](TextTemplateView.md)

Creates a view that renders the given text template path with the given response content type.

| Parameter | Description |
|---|---|
| `template` | the path of the text template to render |
| `contentType` | the content type to send with the response |

### `fileView(String hash, String contentType)`

Returns: [FileHashView](FileHashView.md)

Creates a view that streams a stored file, looked up by its content hash from the server-wide blob store.

| Parameter | Description |
|---|---|
| `hash` | the file's content hash |
| `contentType` | the content type to send with the response |

### `fileView(String hash, String contentType, boolean isPerTenant)`

Returns: [FileHashView](FileHashView.md)

Creates a view that streams a stored file, looked up by its content hash. If isPerTenant is true, the content is retrieved from the current
tenant's own blob store rather than the server-wide one.

| Parameter | Description |
|---|---|
| `hash` | the file's content hash |
| `contentType` | the content type to send with the response |
| `isPerTenant` | true to read from the current tenant's own blob store |

### `contentFileView(String contentName, String contentType)`

Returns: [ContentFileView](ContentFileView.md)

Creates a view that streams stored content looked up by content name, from the top level of tenant storage.

| Parameter | Description |
|---|---|
| `contentName` | the stored content's name, used as the lookup key |
| `contentType` | the content type to send with the response |

### `contentFileView(String dir, String contentName, String contentType)`

Returns: [ContentFileView](ContentFileView.md)

Creates a view that streams stored content looked up by directory and content name.

| Parameter | Description |
|---|---|
| `dir` | the storage directory the content was stored under |
| `contentName` | the stored content's name, used as the lookup key within the directory |
| `contentType` | the content type to send with the response |

### `binaryView(byte[] fileContent, String contentTpe)`

Returns: [BinaryView](BinaryView.md)

Creates a view that streams the given byte array as binary content, with the given content type.

| Parameter | Description |
|---|---|
| `fileContent` | the bytes to render |
| `contentTpe` | the content type to send with the response |

### `binaryView(InputStream fileContent, String contentTpe)`

Returns: [BinaryView](BinaryView.md)

Creates a view that streams the given input stream as binary content, with the given content type.

| Parameter | Description |
|---|---|
| `fileContent` | the stream to copy the response bytes from |
| `contentTpe` | the content type to send with the response |

### `textView(String text)`

Returns: [TextView](TextView.md)

Creates a view that renders the given fixed text as text/plain.

| Parameter | Description |
|---|---|
| `text` | the text to render as the response body |

### `textView(String text, String contentType)`

Returns: [TextView](TextView.md)

Creates a view that renders the given fixed text with the given content type.

| Parameter | Description |
|---|---|
| `text` | the text to render as the response body |
| `contentType` | the content type to send with the response |

### `jsonResult(boolean result)`

Returns: [JsonResult](JsonResult.md)

Creates a JsonResult with the given success flag and no message.

| Parameter | Description |
|---|---|
| `result` | the result's success flag |

### `jsonResult(boolean result, String message)`

Returns: [JsonResult](JsonResult.md)

Creates a JsonResult with the given success flag and message.

| Parameter | Description |
|---|---|
| `result` | the result's success flag |
| `message` | the result's message text |

### `jsonResult(boolean result, List<String> messages)`

Returns: [JsonResult](JsonResult.md)

Creates a JsonResult with the given success flag and a list of messages.

| Parameter | Description |
|---|---|
| `result` | the result's success flag |
| `messages` | the result's message texts |

### `jsonResult(boolean result, String[] messages)`

Returns: [JsonResult](JsonResult.md)

Creates a JsonResult with the given success flag and a list of messages given as an array.

| Parameter | Description |
|---|---|
| `result` | the result's success flag |
| `messages` | the result's message texts |

### `jsonResult(boolean result, String message, String nextHref)`

Returns: [JsonResult](JsonResult.md)

Creates a JsonResult with the given success flag, message and a URL for the client to navigate to next.

| Parameter | Description |
|---|---|
| `result` | the result's success flag |
| `message` | the result's message text |
| `nextHref` | the URL the client should navigate to next |

### `jsonDataResult(Object data, String message)`

Returns: [JsonResult](JsonResult.md)

Creates a successful JsonResult carrying the given data and an optional message.

| Parameter | Description |
|---|---|
| `data` | the data to attach to the result |
| `message` | the result's message text, or null for none |

### `jsonDataResult(Object data)`

Returns: [JsonResult](JsonResult.md)

Creates a successful JsonResult carrying the given data and no message.

| Parameter | Description |
|---|---|
| `data` | the data to attach to the result |

### `searchResponseView(KSearchResponse r)`

Returns: [SearchResponseView](SearchResponseView.md)

Creates a view that writes an Elasticsearch search response directly to the response as JSON.

| Parameter | Description |
|---|---|
| `r` | the search response to write |

### `contentEditorView()`

Returns: [ContentEditorView](ContentEditorView.md)

Creates a view that renders the built-in rich content editor page.

### `csvView(List<List> rows)`

Returns: [CsvView](CsvView.md)

Creates a view that renders the given rows as CSV.

| Parameter | Description |
|---|---|
| `rows` | the rows to render, each entry a row of column values |

### `rowsResultCsvView(RowsResult rowsResult)`

Returns: [RowsResultCsvView](RowsResultCsvView.md)

Creates a view that renders a table query result as CSV, with no explicit column headers.

| Parameter | Description |
|---|---|
| `rowsResult` | the query result to render as CSV |

### `rowsResultCsvView(String[] headers, RowsResult rowsResult)`

Returns: [RowsResultCsvView](RowsResultCsvView.md)

Creates a view that renders a table query result as CSV, using the given column headers.

| Parameter | Description |
|---|---|
| `headers` | the column header row to write |
| `rowsResult` | the query result to render as CSV |

### `throwNotAuthorizedException(String message, Resource page)`

Returns: `void`

Logs a warning and throws a NotAuthorizedException with the given message, for a controller to reject an unauthorised request.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |

### `throwNotAuthorizedException(String message, Resource page, String body)`

Returns: `void`

As throwNotAuthorizedException(message, page), but sends the given body instead of the usual error page, so an API
can answer a 401 in its own format.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |
| `body` | the response body to send, already serialised, sent as application/json, or null for no body |

### `throwNotAuthorizedException(String message, Resource page, String body, Map<String,Object> headers)`

Returns: `void`

As throwNotAuthorizedException(message, page, body), and sets the given response headers, for example
WWW-Authenticate on an OAuth2 401.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |
| `body` | the response body to send, already serialised, sent as application/json, or null for no body |
| `headers` | response headers to set, may be null |

### `throwForbiddenException(String message, Resource page, String body)`

Returns: `void`

As throwNotAuthorizedException(message, page, body), but answers 403 instead of 401. Use it when the caller is
known and simply not allowed: a 401 tells a client its credentials were rejected, so it will try to authenticate
again, which is pointless when no credentials would help.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |
| `body` | the response body to send, already serialised, sent as application/json, or null for no body |

### `throwForbiddenException(String message, Resource page, String body, Map<String,Object> headers)`

Returns: `void`

As throwForbiddenException(message, page, body), and sets the given response headers.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |
| `body` | the response body to send, already serialised, sent as application/json, or null for no body |
| `headers` | response headers to set, may be null |

### `throwBadRequestException(String message, Resource page)`

Returns: `void`

Logs a warning and throws a BadRequestException with the given message, for a controller to reject a malformed request.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |

### `throwBadRequestException(String message, Resource page, String body)`

Returns: `void`

As throwBadRequestException(message, page), but sends the given body instead of the usual error page, so an API can
answer a 400 in its own format.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |
| `body` | the response body to send, already serialised, sent as application/json, or null for no body |

### `throwBadRequestException(String message, Resource page, String body, Map<String,Object> headers)`

Returns: `void`

As throwBadRequestException(message, page, body), and sets the given response headers.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |
| `page` | the resource the request was for |
| `body` | the response body to send, already serialised, sent as application/json, or null for no body |
| `headers` | response headers to set, may be null |

### `throwNotFoundException(String message)`

Returns: `void`

Logs a warning and throws a NotFoundException with the given message, for a controller to signal a missing resource.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |

### `throwServerException(String message)`

Returns: `void`

Logs a warning and throws a ServerErrorException with the given message, for a controller to signal an unrecoverable server error. The request
is answered with a 500; every other script failure is a 400.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |

### `throwPasswordInvalidException(String message)`

Returns: `void`

Logs a warning and throws a PasswordInvalidException with the given message, for a controller to reject an invalid password.

| Parameter | Description |
|---|---|
| `message` | the message to log and attach to the exception |