How to create your own craftform ?

Let's have a look at a use case based on a genuine document (the document used here is an examination certificate)

1. List all the information in the document
2. Keep all useful data and create the skeleton / structure of the document
3. Create the form using YAML language

Let's get into the details

The writer of the examination certificate wants to be able to create his document via paxpar.tech

Advantages

Here are a number of advantages when generating your document via the platform, rather than using a common text editor.

One can :

• Resubmit the generated document to quickly and efficiently edit it again
• Deal with a document no matter how overloaded it may be with metadata, photos or even PDFs
• benefit from the automatic completion of the form, simply by dropping in a document which has formerly been generated via the platform

The desired craftform

Procedure

To create the craftform, we need to create several files:

• base.craftform.yaml: .yaml file used to name and identify the craftform
• schema.yaml: a .yaml file used to define the form

base.craftform.yaml file

This file is used to identify and display the craftform in the crafts' gallery.

The minimum configuration of this file is:

$schema: https://paxpar.tech/schema/common.tutorial_demo_attest_exam.craftforms.attest_exam.base.craftform/1
name: Examination Certificate
version: "1"
desc: I craft an examination certificate

The information listed in this file are :

• name: which is used to specify the name displayed
• version: which is used to specify the version number for this document
• desc: which is used to specify the description displayed in the gallery

There are other settings available, which allow you to add more details to your form, so we can end up with a file like this:

# yaml-language-server: $schema=https://paxpar.gitlab.io/schemas/craftform-1.0.schema.json
$schema: https://paxpar.tech/schema/common.tutorial_demo_attest_exam.craftforms.attest_exam.base.craftform/1
name: examination certificate
version: "1"
desc: |
  I craft an examination certificate
image: mdi:wrench
gallery:
  published: true
tags:
  - test

Thanks to this file, our form is displayed in the list of craftforms:

schema.yaml file

This file, written in YAML but using the JSON Schema standard, is used to create and set up your document creation form.

List of key information

Before you start creating the document, you first need to note down the information it contains. In our example, we have the document of an examination certificate, which proves and validates that a learner has passed or failed a test.

We therefore have the following information

• the full name of the organisation or school
• the organisation or school's address
• the organisation or school's telephone number
• the learner's name
• the learner's date of birth
• the learner's address
• the examination date
• the examination subject
• the final score

We have chosen to keep only the key information, which will be checked using the checklist.

These key information must appear in the metadata linked to the document. Thus, we have the following key points

• the learner's first and last name
• the learner's date of birth
• the learner's address
• the examination date
• the examination subject
• the final score

'Types' of key information

Now that we have picked required information, half the job is done. All you need to do now is to specify the types of information you've just selected.

In our case, all the strings are words. regarding certain pieces of information, such as the date, you can add more details, and specify, for example, that the format of the string is a date.

And so, you end up having :

Defining the form

Only two lines are needed to create the form:

title: Exam certificate
type: object

However you then need to define the fields in the form, and to do this you add the line properties:, which will contain all the fields in the form.

In order to do so, now that you're done with the rough work, you can simply do as for the learner's name in the yaml example hereafter

  nom:
    title: Learner's first name and last name # title: it is used to specify the title displayed on the craft
    type: string # type: it is used to specify the type of field, in this case plain text.

In the case of a field with a specific format, such as dates, we need to add a format:

  date_naissance:
    title: Learner's date of birth
    type: string
    format: date # Here, we specify that the field has a date format (YYYY-MM-DD)

We can then repeat these steps to complete the form in order to craft the examination certificate:

title: Exam certificate
type: object
properties:
  nom:
    title: Learner's first and last name
    type: string
  date_naissance:
    title: Learner's date of birth
    type: string
    format: date
  adresse:
    title: Learner's address
    type: string
  date_examen:
    title: Examination date
    type: string
    format: date
  matiere:
    title: Examination subject
    type: string
  note:
    title: Final score out of 20
    type: string

However, there is an issue with the current configuration: the score can be any word. But word/20 is not a proper score. And 100/20 is not a proper score either. So we need to adapt, and set more details to the craftform.

title: Exam certificate
type: object
properties:
  nom:
    title: Learner's first and last name
    type: string
  date_naissance:
    title: Learner's date of birth
    type: string
    format: date
  adresse:
    title: Learner's address
    type: string
  date_examen:
    title: Examination date
    type: string
    format: date
  matiere:
    title: Examination subject
    type: string

  note:
    title: Final score out of 20
    type: number # because the score is a figure composed of a single digit or of multiple digits
    minimum: 0 # because the score cannot be less than 0
    maximum: 20 # because the score cannot be more than 20

And so we have our document craftform.

The document's template is as important as the document's craftform. To find out more about the template, please clic here

Appendix

https://json-schema.org/understanding-json-schema/reference/string#built-in-formats