bitmark Resources
A quiz Bit often refers to a text to read, like a news article, an extract from a book or magazine or to a video to watch, an audio file to listen to or an image to describe.
With bitmark, it is possible to attach such a resource to any Bit.
By design, a Bit contains one single, optional resource. This allows us to keep the standard and implementations of the standard in the clients simple but still very powerful ("KISS").
The vast majority of real world learning material, be it in text books, online or in LMS's, only use one single resource anyway. One picture to describe, one audio to listen to, one video to watch, ...
However, some specialized Bits allow for several resources like media files.
If one specific resource is not sufficient for your needs, you can always choose to use bitmark++ as the text format for a Bit or attach a full featured bitmark++ article. An article in bitmark++ text format can contain text and an unlimited number of images and many more advanced features.
Common Properties
A resource contains several standard properties which are shared among all types of resources. In addition, it contains a property with the name of its type (video in the example below) to contain all resource specific information.
...
"resource": {
"type": "video",
"preview": ...,
"search": ...,
"private": ...,
"video": {
...
}
},
...
A resource of type video with its video property.
Resource Type
Status: Release Candidate v1
The type of the resource is defined by the type property. A resource contains a property with the name of its type that holds all resource specific information. All other properties are shared among all different types of resources.
Resource types can also be used for filtering at API level. See Full Text Search and Filter
bit | Data Type, Description |
---|---|
resource.type | "image", "image-online", "image-zoom", "audio", "audio-online", "video", "video-online", "article", "article-online", "document, "document-online", "app" |
Resource Preview
Status: Release Candidate v1
Resources have an optional preview.
If the preview is available, the clients must show this preview instead of the resource itself.
If there is no explicit preview, a client might still choose to display a preview only of a certain resource. Be it because of the length of a resource (e.g. very long news article) or be it because the client does not support a certain resource natively and needs an external helper application to do so.
All of the preview properties are optional.
"resource": {
"preview": {
"title": "Cat",
"description": "Cat",
"icon": null,
"image": {
"src1x": "http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64.jpg",
"src2x": "http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64@2x.jpg",
"src3x": null,
"format": "basic",
"size": "64x64",
...
}
}
...
},
resource | Data Type, Description |
---|---|
title | String, bitmark--, if declared by the bit type (not the resource type!), optional |
Please use short titles only. | |
description | String, bitmark--, if declared by the bit type (not the resource type!), optional |
A description like a summary or the first few lines of the resource, if appropriate. Long text might be truncated by the clients. Clients typically show max. 2 to 3 lines. | |
image | Image, optional |
The preview image is used to show a preview of the resource. Often in combination with the preview title and description. | |
icon | Icon, optional |
The preview icon is often used in combination with the preview title and description and as a fallback of a missing preview image. |
Resource Icon
Status: Release Candidate v1
The icon property of the resource comes in two flavors. As an svg string or as a Material Design, Octicons or Font Awsome icon.
...
"resource": {
"preview": {
"icon": {
"svg": "<svg aria-hidden=\"true\" focusable=\"false\" data-prefix=\"fas\" data-icon=\"file-word\" class=\"svg-inline--fa fa-file-word fa-w-12\" role=\"img\" xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 384 512\"><path fill=\"currentColor\" d=\"M224 136V0H24C10.7 0 0 10.7 0 24v464c0 13.3 10.7 24 24 24h336c13.3 0 24-10.7 24-24V160H248c-13.2 0-24-10.8-24-24zm57.1 120H305c7.7 0 13.4 7.1 11.7 14.7l-38 168c-1.2 5.5-6.1 9.3-11.7 9.3h-38c-5.5 0-10.3-3.8-11.6-9.1-25.8-103.5-20.8-81.2-25.6-110.5h-.5c-1.1 14.3-2.4 17.4-25.6 110.5-1.3 5.3-6.1 9.1-11.6 9.1H117c-5.6 0-10.5-3.9-11.7-9.4l-37.8-168c-1.7-7.5 4-14.6 11.7-14.6h24.5c5.7 0 10.7 4 11.8 9.7 15.6 78 20.1 109.5 21 122.2 1.6-10.2 7.3-32.7 29.4-122.7 1.3-5.4 6.1-9.1 11.7-9.1h29.1c5.6 0 10.4 3.8 11.7 9.2 24 100.4 28.8 124 29.6 129.4-.2-11.2-2.6-17.8 21.6-129.2 1-5.6 5.9-9.5 11.5-9.5zM384 121.9v6.1H256V0h6.1c6.4 0 12.5 2.5 17 7l97.9 98c4.5 4.5 7 10.6 7 16.9z\"></path></svg>",
"license": "https://fontawesome.com/license"
},
...
}
...
},
...
...
"resource": {
"preview": {
"icon": {
"code": ":material-file-excel-outline:",
"tint": "#1da1f2",
"license": "https://github.com/Templarian/MaterialDesign/blob/master/LICENSE"
},
...
}
...
},
...
Note
Be aware, you need to add the license of the respective library/font.
The following icon sets are supported. You need to add the library id as a prefix to the icon name and surround it :
Icon Library | |
---|---|
Material Design | https://materialdesignicons.com/ |
Prefix: material- | |
Example: :material-file-excel-outline: | |
License: https://github.com/Templarian/MaterialDesign/blob/master/LICENSE | |
Octicons | https://primer.style/octicons/ |
Prefix: octicons- | |
Example: :octicons-file-media-24: | |
Tip: Don't forget to add the size of the icon "-24" in the example above | |
License: https://github.com/primer/octicons/blob/master/LICENSE | |
FontAwesome | https://fontawesome.com/icons |
Prefix: fontawesome- | |
Example: .fontawesome-solid-brain: | |
Example: .fontawesome-brands-twitter: | |
Tip: solid and brands icons are free. Add -solid or -brands infront of the icon name. | |
License: https://fontawesome.com/license |
Icon Tint Color
Icons can be tinted by the color in the tint property.
...
"icon": {
"code": ":fontawesome-brands-twitter:",
"tint": "#1da1f2",
"license": "https://fontawesome.com/license"
}
...
Search
Status: Release Candidate v1
For resources to be found, please include some text that describes the image or text that is part of the image.
"resource": {
...
"search": "Black cat playing with a toy.",
...
},
The information from this field is never shown to the user, so, you don't have to care about its format at all (from full sentences to comma separated keywords). Just add anything that makes sense to describe the picture. The bitmark API itself might add information to this field on request.
Please don't repeat the alt text of images here to be found.
Note
You might want to extract all text information from images and store it in the search field.
Private
"resource": {
"type": "image",
"image": {
...
},
...
"private": {
"uploadDetails": {
"displayHeight": 115.60000000000001,
"displayWidth": 200,
"filename": "asus7.jpg",
"height": 287,
"width": 500,
"orientation": 1,
"xRes": 180,
"yRes": 180
},
"printImage" : "http://intranet/images/print/cat3_highres.tiff",
...
}
}
},
The private node is used for private meta data for this resource. This property can be freely used by the publisher for any internal use. There are no restrictions (besides being 100% valid JSON, of course).
Resouces
Image
Status: Release Candidate v1
"resource": {
"type": "image",
"image": {
"src1x":"http://cdn.bitmark.cloud/images/cat3_big_image.jpg",
"src2x":"http://cdn.bitmark.cloud/images/cat3_big_image@2x.jpg",
"src3x":"http://cdn.bitmark.cloud/images/cat3_big_image@3x.jpg",
"showInIndex": true,
"format": "basic",
"size": "640x480",
"alt": "Black cat playing with a toy.",
"caption": "Cat playing",
"license": "https://www.istockphoto.com/en/legal/license-agreement",
"copyright": "© iStockphoto.com"
},
"private": {
"uploadDetails": {
"displayHeight": 115,
"displayWidth": 200,
...
}
}
},
bitmark | Description, Example |
---|---|
[&image::...] |
Image URL (Resolution @1x) |
[&image:...][@src2x:...] |
Image URL, Resolution @2x |
... | Same pattern for all resource types. |
[&image:jpg:...] |
Image URL, image format "jpg" |
[&image:basic:...] |
Image URL, image format "basic (default)" |
"basic" stands for "gif", "jpg", "png" and "svg" | |
The type must macht the file extension (or in case of "basic", match one of the basic file extensions). The main application for setting the type of an image, is, if there is no extension in the url. So, usually, this is not used. | |
Resource tags are block tags and therefore must start at the beginning of a line. | |
[&image:...][@showInIndex] |
Image is listed in the image index of the book, default is false |
[&image:...][@alt:...] |
Alternative Text for this image |
[&image:...][@alt:Black cat playing with a toy.] |
|
[&image:...][@caption:...] |
Caption of this image |
The size of an image should not be described by bitmark. Size is set to the real size by the API call when creating a Bit from bitmark.
SVG
In case, the svg contains bitmap data, please use the @src1x, @src2x, ... properties to store the url of the corresponding svg. In case the svg contains vector graphics only, please repeat the same url for all properties
For svg images, the aspect ratio must match, in case a certain size is expected from the API.
Note
We highly recommend using svg as your preferred format, if applicable. Due to some short-comings in handling text, we recommend that all text in your svgs are rendered as paths. Please consider adding the text from the original svg to the resource.search field. See above.
Image-Online
Status: Release Candidate v1
"resource": {
"type": "image-online",
"imageOnline": {
"provider": "dribble.com",
"url": "https://dribbble.com/shots/5729146-Home-30",
},
},
bitmark | Description, Example |
---|---|
[&image-online::...] |
Image Viewer/App URL |
Resource tags must start at the beginning of a new line. |
Zoom-Image
Status: Draft
"resource": {
"type": "image-zoom",
"preview": {
"image": {
"src1x":"http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64.jpg",
"src2x":"http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64@2x.jpg",
"src3x":"http://cdn.bitmark.cloud/books/com.firstpub.book98789/cat3_64x64@3x.jpg",
"format": "jpg",
"size": "64x48",
}
},
"imageZoom": {
"src1x":"http://cdn.bitmark.cloud/images/cat3_big_image.jpg",
"src2x":"http://cdn.bitmark.cloud/images/cat3_big_image@2x.jpg",
"src3x":"http://cdn.bitmark.cloud/images/cat3_big_image@3x.jpg",
"format": "basic",
"size": "640x480",
"alt": "Black cat playing with a toy.",
...
},
...
},
See Image for details.
The preview image is optional. In case of no preview, the app needs to create one form the main image.
Audio
Status: Release Candidate v1
"resource": {
"type": "audio",
"audio": {
"format": "mp3",
"src": "http://cdn.bitmark.cloud/publishers/3/books/26363/sports.mp3",
"duration": "PT12M31S",
"autoplay": true
}
},
bitmark | Description, Example |
---|---|
[&audio::...] |
Audio File URL |
[&audio:mp3:...] |
Audio File URL, Audio Format mp3 |
Only "mp3" is supported for now. Please let us know, if you need support for other formats. Please be aware, that you can always use audio-online. |
Duration in ISO_8601
Autoplay might not be supported (or intenionally disallowed) in certain environments.
Audio-Online
Status: Draft
"resource": {
"type": "audio-online",
"audioOnline": {
"provider": "soundcloud.com",
"url": "https://soundcloud.com/kodak-black/zeze-feat-travis-scott-offset-1",
"duration": "PT12M31S",
"autoplay": true
}
},
bitmark | Description, Example |
---|---|
[&audio-online::...] |
Audio Player/App URL |
Resource tags must start at the beginning of a new line. |
Duration in ISO_8601
Autoplay might not be supported (or intenionally disallowed) in certain environments.
Video
Status: Release Candidate v1
"resource": {
"type": "video",
"video":{
"format": "mp4",
"src": "http://cdn.bitmark.cloud/publishers/3/books/26363/news.mp4",
"size": "640x480",
"duration": "PT12M31S",
"mute": true,
"autoplay": true,
"allowSubtitles": true,
"showSubtitles": true,
"alt": "Today's News",
"license": "https://www.gnu.org/licenses/gpl-3.0-standalone.html",
"copyright": "© iStockphoto.com"
}
},
Autoplay might not be supported (or intenionally disallowed) in certain environments.
Subtitles must be embedded in the video file.
bitmark | Description, Example |
---|---|
[&video::...] |
Video File URL |
[&video:mp4:...] |
Video File URL, Video Format mp4 |
Only "mp4" is supported for now. Please let us know, if you need support for other formats. Please be aware, that you can always use video-online. |
Video-Online
Status: Draft
"resource": {
"type": "video-online",
"videoOnline": {
"provider": "youtube",
"url": "https://www.youtube.com/watch?v=RecY5iZn6B0",
"size": "640x480",
"duration": "PT12M31S",
"thumbnails": [
{
"src1x": "www.youtube.com/tumb_201809210816.png",
"format": "png",
"size": "640x480"
}
]
}
},
bitmark | Description, Example |
---|---|
[&video-online::...] |
Video Player/App URL |
Resource tags must start at the beginning of a new line. |
Duration in ISO_8601
ImageWithAudio
"resource": {
"type": "imageWithAudio",
"image": {
"src1x":"http://cdn.bitmark.cloud/images/cat4.jpg",
"src2x":"http://cdn.bitmark.cloud/images/cat4@2x.jpg",
"src3x":"http://cdn.bitmark.cloud/images/cat4@3x.jpg",
"showInIndex": true,
"format": "basic",
"size": "640x480",
"alt": "Hungry black cat."
},
"audio": {
"format": "mp3",
"src": "http://cdn.bitmark.cloud/publishers/3/books/26363/miau.mp3"
}
},
bitmark | Description, Example |
---|---|
[&imageWithAudio::...] |
See image resource |
[&imageWithAudio:mp3:...] |
See audio resource |
Article
{
"type": "match",
"format": "text",
"resource": {
"type": "article",
"article": {
"format": "bitmark--",
"content": "**Nice!**\nFinally I get proper new line support."
}
},
...
}
[.match&article:bitmark--]
...
[&article:
**Nice!**
Finally I get proper new line support.
]
Article-Online
"resource": {
"type": "article-online",
"articleOnline": {
"url" : "https://www.nytimes.com/2018/12/11/opinion/letters/cats.html"
}
},
bitmark | Description, Example |
---|---|
[&article-online::...] |
bitmark or other Article Reader URL |
Mainly just a link to a website. | |
Resource tags must start at the beginning of a new line. |
Website
"resource": {
"type": "website",
"preview": {
"title": "Apple",
"description": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, and expert device support.",
"image": {
"src1x": "https://www.apple.com/ac/structured-data/images/open_graph_logo.png?201809210816",
"format": "png",
"size": "1200×630",
}
},
"website": {
"siteName": "Apple",
"url":"https://www.apple.com/"
}
},
bitmark | Description, Example |
---|---|
[&website::...] |
bitmark or other Article Reader URL |
Link to a website including preview data. | |
Resource tags must start at the beginning of a new line. |
This resource is heavily inspired by https://ogp.me and often used in .message bits.
Document
"resource": {
"type": "document",
"document": {
"type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"url": "https://cdn.bitbooks.com/animals/cat.docx"
}
},
bitmark | Description, Example |
---|---|
[&document::...] |
Document File URL |
[&document:application/vnd.openxmlformats-officedocument.wordprocessingml.document:...] |
Document File URL, Microsoft Word Document (docx) |
Format must match file extension. | |
Format is used to show a suitable icon. Icon must be shown together with the optional preview. |
Document-Online
"resource": {
"type": "document-online",
"documentOnline": {
"provider": "docs.google.com",
"url": "https://docs.google.com/document/d/5678"
}
},
bitmark | Description, Example |
---|---|
[&document-online::...] |
Document App URL |
Resource tags must start at the beginning of a new line. |
App
"resource": {
"type": "app",
"app": {
"url" : "https://itunes.apple.com/ch/album/like-sugar-single/1392081432?l=en"
}
},
"resource": {
"type": "app",
"app": {
"url" : "tel:+1987987987987"
}
},
bitmark | Description, Example |
---|---|
[&app::...] |
Deep Link App URL |
Please use Universal Links (Apple), Android App Links or custom protocol URLs. | |
[&app::https://itunes.apple.com/ch/album/like-sugar-single/1392081432?l=en] |
|
[&app::tel:+1987987987987] |
|
Resource tags must start at the beginning of a new line. |