# JSMedia

## Overview

`JSMedia` is a media wrapper designed for managing media content within solutions. It enables manipulation of media properties such as content bytes, MIME types, and metadata through a set of defined properties and methods.

The `bytes` property represents the content of the media as a byte array. This allows direct modification of the media content while retaining its original name. For example, users can read image files, replace their content, and verify changes programmatically. The `mimeType` property specifies the type of media, such as 'image/jpg' or 'image/png'. It can be updated alongside the content to reflect new media formats without altering the media’s name.

JSMedia provides several methods for interacting with media objects:

* **`getAsString()`**: Converts the byte content into a UTF-8 encoded string, returning `null` if the conversion fails or if the byte content is unavailable.
* **`getName()`**: Retrieves the name of the media object, ensuring that changes to content or MIME type do not affect the original name.
* **`getUUID()`**: Returns a unique identifier (UUID) for the media, allowing for precise identification.
* **`setAsString(string)`**: Updates the media’s byte content using a UTF-8 encoded string, enabling quick modifications with string inputs.

For more comprehensive information, refer to the [media](https://docs.servoy.com/reference/servoy-developer/solution-explorer/all-solutions/active-solution/media) section of this documentation.

## Properties Summarized

| Type                                                                         | Name                  | Summary                                               |
| ---------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------- |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)   | [bytes](#bytes)       | A byte array holding the content of the Media object. |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [mimeType](#mimetype) | The MIME type of the Media object.                    |

## Methods Summarized

| Type                                                                          | Name                                       | Summary                                                                                             |
| ----------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string)  | [getAsString()](#getasstring)              | Returns this media's bytes a a String converting it with the UTF-8 Charset.                         |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string)  | [getName()](#getname)                      | The name of the Media object.                                                                       |
| [UUID](https://docs.servoy.com/reference/servoycore/dev-api/application/uuid) | [getUUID()](#getuuid)                      | Returns the UUID of this media                                                                      |
| void                                                                          | [setAsString(string)](#setasstring-string) | Sets the bytes of this media to the give String that is converted to bytes using the UTF-8 Charset. |

## Properties Detailed

### bytes

A byte array holding the content of the Media object.

**Type**\
[Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) A byte array holding the content of the Media object.

**Sample**

```js
var ballBytes = plugins.file.readFile('d:/ball.jpg');
var mapBytes = plugins.file.readFile('d:/map.png');
var ballImage = solutionModel.newMedia('ball.jpg', ballBytes);
application.output('original image name: ' + ballImage.getName());
ballImage.bytes = mapBytes;
ballImage.mimeType = 'image/png';
application.output('image name after change: ' + ballImage.getName()); // The name remains unchanged. Only the content (bytes) are changed.
application.output('image mime type: ' + ballImage.mimeType);
application.output('image size: ' + ballImage.bytes.length);
```

### mimeType

The MIME type of the Media object.

Some examples are: 'image/jpg', 'image/png', etc.

**Type**\
[String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) The MIME type of this Media object.

**Sample**

```js
var ballBytes = plugins.file.readFile('d:/ball.jpg');
var mapBytes = plugins.file.readFile('d:/map.png');
var ballImage = solutionModel.newMedia('ball.jpg', ballBytes);
application.output('original image name: ' + ballImage.getName());
ballImage.bytes = mapBytes;
ballImage.mimeType = 'image/png';
application.output('image name after change: ' + ballImage.getName()); // The name remains unchanged. Only the content (bytes) are changed.
application.output('image mime type: ' + ballImage.mimeType);
application.output('image size: ' + ballImage.bytes.length);
```

## Methods Detailed

### getAsString()

Returns this media's bytes a a String converting it with the UTF-8 Charset.\
Returns null if it couldn't convert it or the bytes where null.

**Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) This media's bytes as a string converted with the UTF-8 charset, or null if conversion is not possible or bytes are null.

### getName()

The name of the Media object.

**Returns:** [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) A String holding the name of this Media object.

**Sample**

```js
var ballBytes = plugins.file.readFile('d:/ball.jpg');
var mapBytes = plugins.file.readFile('d:/map.png');
var ballImage = solutionModel.newMedia('ball.jpg', ballBytes);
application.output('original image name: ' + ballImage.getName());
ballImage.bytes = mapBytes;
ballImage.mimeType = 'image/png';
application.output('image name after change: ' + ballImage.getName()); // The name remains unchanged. Only the content (bytes) are changed.
application.output('image mime type: ' + ballImage.mimeType);
application.output('image size: ' + ballImage.bytes.length);
```

### getUUID()

Returns the UUID of this media

**Returns:** [UUID](https://docs.servoy.com/reference/servoycore/dev-api/application/uuid) The UUID of this Media object.

**Sample**

```js
var ballImg = plugins.file.readFile('d:/ball.jpg');
application.output(ballImg.getUUID().toString());
```

### setAsString(string)

Sets the bytes of this media to the give String that is converted to bytes using the UTF-8 Charset.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **string** ;

**Returns:** void

***