// Step 1: Make sure the Is SurvBee Package checkbox is checked (below editor window)
// Step 2: Create a Function

function wait_ms_1() {
    await(1000);
}

// You can now see this package in the list but it is empty and the function 
// wait_ms is not visible. You can of course use it elsewhere within this script.

// Step 3: 
// To turn an ordinary function into a SurvBee block you must do two things
//  - 3.a Rewrite the function definition to exports.wait_ms = function() { ... }
//    This is a format that can be imported. It is one of the international standards
//    for writing packages with functions that can be imported. 
//  - Add /* */ comments immediately above the function but have four stars instead
//    of just 1, as in /**** */ or /*****/. Now, SurvBee recognizes it as a SurvBee
//    block that can be dragged-and-dropped from the package.
//
// To stress this: THE SPECIAL COMMENT MUST COME IMMEDIATELY BEFORE THE FUNCTION

/*****/
exports.wait_ms_2 = function() {
    await(1000);
}

// Step 4: Adding an argument

/*****/
exports.wait_ms_3 = function(ms) {
    await(ms);
}

// The above works but (1) the label reads Ms (auto-capitalized) and the
// argument ms is interpreted as a string (check the JavaScript code under the
// Script tab on the right)

// Step 5: Adding an argument with a type.
// By using a more descriptive argument name 'milliseconds' the label becomes
// clearer to the user (experimenter). With the n_ prefix, SurvBee knows you 
// intend it to be a numeric argument. The n_ is removed in the label.

/*****/
exports.wait_ms_4 = function(n_milliseconds) {
    await(n_milliseconds);
}

/* There are several types of prefixes:

    richtext_: {type:'richtext', default: ''}
    text_: {type: 'textarea', default: ''}
    arr_: {type: [{option: ''}]} // Array of string  // TODO: (***) Simplify this to real array
    js_: {type: 'js', default: ''}
    var_: {type: 'varname', default: ''}
    obj_: {type: 'objectname', default: ''}
    n_: {type: 'number', default: 0}
    i_: {type: 'number', default: 0, decimals: 0}
    perc_: {type: 'number', default: 0, min: 0, max: 100}
    bool_: {type: 'checkbox', default: false}
    color_: {type: 'color', default: '#ffffff'}
    date_: {type: 'date', default: ''}
    time_: {type: 'time', default: ''}
    email_: {type: 'email', default: ''}
    url_: {type: 'url', default: ''}
    image_: {type: 'select_image', default: ''}
    audio_: {type: 'select_audio', default: ''}
    video_: {type: 'select_video', default: ''}
    txt_: {type: 'select_txt', default: ''}
    md_: {type: 'select_md', default: ''}
    csv_: {type: 'select_csv', default: ''}
    excel_: {type: 'select_excel', default: ''}
*/

// For example, it is possible a block that expects an image:

/*****/
exports.imageblock = function(image_an_image_file) {
    showimage(image_an_image_file);
}


// perc_ also allows min and max values e.g. 0 and 100
// A bug is that though they range works, 0 and 100 are shown in the label

/*****/
exports.padding = function(perc_0_100_padding) {
    await(perc_0_100_padding);
}


// Step 6: Adding properties with more details.
// Though the prefix-shorthand comes in handy for quick prototyping, more
// control can be obtained by adding details to the comments. This is done
// with YAML. See https://yaml.org/.

/****
description: wait ${ms} ms      # With ${ms} you can show the value of the function argument
data_object:
    - ms: 
        default: 1000
        label: Number of milliseconds to wait
        type: number
*/
exports.wait_ms_5 = function(ms) {
    await(ms);
}

// As we can see, there is a data_object that holds important information about
// each argument. In this case, there is only one, ms, and it has a default
// value of 1000, a label and a type. It is now no longer necessary to express
// the type and label in the name of the variable, which we can simplify to 'ms'.
// The description is the text shown on the block when it is closed. We can shown
// the contents of the variable ms with ${ms}. 
//
// The descriptions need show the function directly (here: wait_ms_5(${ms})) but
// should describe consisely what the block does. Ideally, someone who reads the
// descriptions on a SurvBee block construction should have a good impression of
// what the script does.


/****
name: waiting with cat
description_in_package: wait with cat ${ms} ms 
description: wait with cat ${ms} ms 
code: wait_ms_img
data_object:
    - ms: 
        default: 1000
        label: Number of milliseconds to wait
        type: number
*/
exports.wait_ms_img = function(ms) {
    await(ms);
}