Example: Adding a new Database Category
In the following example we want to add a new category to the editor’s database. To do that, we will first open the Extension Editor through the Menu under View > Extension.
Next we will make a right-click on the"Data Record Views " folder and select New > Data Record View to create a new view for our new category. We will call it"Cards " since we want to create cards for a simple card game in our VN. It already contains some basic JSON which looks like this:
{
"category": "cards",
"descriptor": {
"name": "Cards",
"attribute": "cards",
"sections": []
}
}
Lets go through the different fields step by step.
category
The backend field name of the category. It should be a unique name in camel-case notation.
descriptor
Contains the details about the view used for each single record of the category.
descriptor.name
The name displayed in the category list in database.
descriptor.attribute
The backend attribute name used to store the records. That name is used to access the data records through script. The name should be a unique name in camel-case. In most cases it is the same like category-field.
descriptor.sections
Contains all the sections used for the UI.
Lets first think about what kind of data we need to store to describe a card in our game. We will keep it simple so a card has a name, a description and an image and that's it. Now lets design the UI for that.
We will create two sections. One for the general data like the name and the description and one section for the image. So our JSON will look like this now:
{
"category": "cards",
"descriptor": {
"name": "Cards",
"attribute": "cards",
"sections": [
{
"name": "General",
"items": [
]
},
{
"name": "Graphic",
"items": [
]
}
]
}
}
As we can see here, we added the two sections described above. Each section has a name which is displayed to the user and a list of items to let the user interact with the view.
Lets start with the first section"General ". In our example we just need to add one text field for the card name and one multiline text-area for the card’s description plus two labels to describe that fields for the user. So our section will look like this now:
{
"name": "General",
"items": [
{
"type": "GSLabel",
"text": "Name:",
"group": "labels",
"frame": [0, 0]
},
{
"type": "GSTextField",
"attribute": "name",
"frame": [1, 0]
},
{
"type": "GSLabel",
"text": "Description:",
"frame": [0, 1]
},
{
"type": "GSTextField",
"multiline": true,
"attribute": "description",
"defaultValue": "Enter description here...",
"frame": [0, 2, -1, 100]
}
]
}
We added 4 items to our section. Lets take a deeper look to the fields of each item. Each item can have a few general fields which are available for each type of item but also some type specific fields. Lets start with the general fields used in that example:
type (Required)
Indicates the type of the item like if its a label, a text field, a check box, etc. The type must be present.
attribute
The backend JavaScript attribute name where the item will store its data. You can access the data via script using that name. The name should be unique for the view to avoid collisions.
frame (Required)
The first two values are the position and the other two are the size of the item. For most items, the size is calculated automatically but for some items it is necessary to specify at least the height like for multiline text-fields, tables, etc. You can also use -1 for size-values to indicate that the value should be calculated automatically. The frame must be present for each item and must have at least and x and y value.
defaultValue
You can define a default value here used if a new record is created and there is no existing data to read from.
Now lets take a look at item specific fields used in that example.
group
Assigns the label to a label group which automatically resizes the label to fit correctly depending on its text and the text of other labels in the same group. Like if you have multiple labels below each other like this:
Label 1: <Text-Field>
Other Label 2: <Text-Field>
Another Label 3: <Text-Field>
You probably want that the labels all have the same width depending on the label with the highest width value to avoid that your layout looks like this:
Label 1: <Text-Field>
Other Label 2: <Text-Field>
Another Label 3: <Text-Field>
However, that can also be solved using different types of layouts but that is not covered by this tutorial. Take a look at the Plugin API Reference to learn more about different types of layouts.
multiline
Indicates that we want to have a multiline text-field. In that case we have to specify a height value for our text-field. We made it 100px in height in our example. After we are done setting up our first section we can click on the"Preview " button to see an interactive preview of our view so we can check if our elements look right. To close the preview for DataRecordViews, we just click on the"Preview " button again.
Ok, lets move forward and implement the section for the card’s image.
{
"name": "Graphic",
"items": [
{
"type": "GSImageView",
"attribute": "graphic",
"folder": "Graphics/Pictures",
"frame": [0, 0, 300, 450]
}
]
}
We are using a"GSImageView " which allows the user to select a graphic and shows a preview at the same time. We are using a size of 300x450 since our card images have exactly that size. Lets take look at the fields:
folder
The folder to select an image from. In our case we will use the picture folder"Graphics/Pictures ".
That’s it! We are done! Lets now save our project and restart Visual Novel Maker to see our changes. If we go now to database we will see our new category"Cards " there. We can now use that category to create different types of cards for our game.
Accessing Data via Script
In script we can use RecordManager class to access the database. The RecordManager automatically has a property with the name we specified for category/attribute field of our Data Record View. To access our cards in way like this:
cards = RecordManager.cards
for card in cards
if card?
console.log("Name: #{card.name}")
console.log("Description: #{card.description}")
console.log("Image: #{card.graphic?.name}")