Kotlin
How to getting started with Joyfill in a Kotlin cross-platform project.
We offer four libraries entirely build in kotlin multiplatform
io.joyfill:joyfill-compose
: The main library for integrating Joyfill into your Compose app. This library includes all the necessary UI components for displaying and interacting with Joyfill documents.
io.joyfill:joyfill-models
: A library for integrating Joyfill models into your Kotlin app.
io.joyfill:joyfill-builder
: A library for creating documents programmatically in kotlin
io.joyfill:joyfill-api
: A library for all the network interactions with the Joyfill API.
Project Requirements
Note: userAccessTokens & identifiers will need to be stored on your end (usually on a user and set of existing form field-based data) in order to interact with our API and UI Components effectively
See our API Documentation for more information on how to interact with our API.
Install Dependency
Add the following maven coordinates to your dependencies in your build.gradle.kts
file.
implementation("io.joyfill:compose:<version>")
Select the SDK version that you want to use.
Note: We recommend using the default (latest) SDK version, but you can choose an older version if needed.
Choose the Joyfill libraries you want to use.
Getting Started
Show a Joyfill Document with the Form
Composable
Form
Composableimport joyfill.Form
Form(
document = getJoyDoc(),
mode = JoyMode.readonly, // or JoyMode.fill,
onChange = { event ->
// handle your events here
}
)
See our example project for more details.
Form
Params
Form
Params-
mode: 'Mode.fill' | 'Mode.readonly'
- Enables and disables certain JoyDoc functionality and features.
- Default is
Mode.fill
. - Options
fill
is the mode where you simply input the field data into the formreadonly
is the mode where everything in the form is set to read-only.
-
document: Document
- The JoyDoc JSON object to load into the SDK. Must be in the JoyDoc JSON data structure.
- The SDK uses object reference equality checks to determine if the
doc
or any of its internalpages
orfields
have changed in the JSON. Ensure you’re creating new object instances when updating the document, pages, or fields before passing the updateddoc
JSON back to the SDK. This will ensure your changes are properly detected and reflected in the SDK.
-
pageID: String
- Specify the page to display in the form.
- Utilize the
_id
property of a Page object. For instance,page._id
. - If page is not found within the
doc
it will fallback to displaying the first page in thepages
array. - You can use this property to navigate to a specific page in the form.
-
onChange: (event: ChangeEvent) -> Unit
- Used to listen to any field change events.
event.changelogs: List<ChangeLog>
- Can contain one or more of the changelog object types supported. Learn more about changelogs
event.document: Document
- Fully updated JoyDoc JSON structure with changes applied.
-
onUpload: suspend (event: FieldEvent) -> List<String>
- Used to listen to file upload events.
- Specifies information about the uploaded file.
-
onFocus: (event: FieldEvent) -> Unit
- Used to listen to field focus events.
event
Specifies information about the focused field.blur: Function
- Triggers the field blur event for the focused field.
- If there are pending changes in the field that have not triggered the
onChange
event yet then thee.blur()
function will trigger both the change and blur events in the following order: 1)onChange
2)onBlur
. - If the focused field utilizes a modal for field modification, ie. signature, image, tables, etc. the
e.blur()
will close the modal.
-
onBlur: (event: FieldEvent) -> Unit
- Used to listen to field focus events.
event
Specifies information about the blurred field.
-
onFieldChange: (event: FieldEvent) -> Unit
- Used to listen to individual micro field change events.
event
Specifies information about the field change.
ChangeEvent Properties
Field Events
- Text, Textarea, Number
onFocus(params: object, e: object)
is fired when the field is focused.onChange
is fired when the field value is modified.onBlur
is fired when the field is blurred.
- Date, Dropdown
onFocus
is fired when the field is pressed and selection modal is displayed.onChange
is fired when the field value is modified.onBlur
is fired when the field is blurred and the selection modal is closed.
- Multiselect
onFocus
is fired when an option is selected or unselected for the first time on the field.onChange
is fired when an option is selected or unselected in the field.
- Chart
onFocus
is fired when “view” button is pressed and modal is displayed.onChange
is fired when the field value is modified.onBlur
is fired when modal is closed.
- Image
onFocus
is fired when “view” button is pressed and modal is displayed.- An empty image field that is focused will also trigger the
onUploadAsync
request. - A populated image field that is focused will trigger the image modal to open.
- An empty image field that is focused will also trigger the
onChange
is fired when the field images are uploaded or removed.onBlur
is fired when modal is closed.
- Signature
onFocus
is fired when open modal button is pressed and modal is displayed.onChange
is fired when the field value is modified.onBlur
is fired when the modal is closed.
- Table
onFocus
is fired when “view” button is pressed and modal is displayed.onBlur
is fired when modal is closed.- Table Cells
- Text Cell
onFocus
is fired when the cell is focused.onChange
is fired when the cell value is modified.onBlur
is fired when the cell is blurred
- Dropdown Cell
onFocus
is fired when the cell is pressed and selection modal is displayed.onChange
is fired when the field value is modified.onBlur
is fired when the cell is blurred and the selection modal is closed.
- Image Cell
onFocus
is fired cell is pressed and modal is displayed.- An empty image cell that is focused will also trigger the
onUploadAsync
request. - A populated image cell that is focused will trigger the image modal to open.
- An empty image cell that is focused will also trigger the
onChange
is fired when the cell images are uploaded or removed.onBlur
is fired when modal is closed.
- Text Cell
IMPORTANT NOTE: JoyDoc SDK onFocus
, onChange
and onBlur
events are not always called in the same order. Two different fields can be triggering events at the same time. For instance, if you have Field A focused and then focus on Field B, the Field B onFocus event could be fired before the Field A onBlur event. Always check the event params object ids to match up the associated field events.
Other Artifacts
Samples
Checkout our samples app that uses the Kotlin Joyfill API to fill and update documents
Kotlin Api
You can check the Kotlin Joyfill API and see it's progress there as well
Updated 8 months ago