¶ Exceptions and Results in Reservations
¶ Exceptions
Exceptions are the one way to abort a sneq script from anywhere within the script, including nested functions, and return some value.
For reservations and requests, the return value of the Exception determines how a script failure is reported to the user.
¶ As a string
If the Exception is a string, the conflict message will be set to that string.
return Exception("Hello world")
Tip: Avoid punctuating the last sentence of your exception with anything other than a period, because by default all conflicts will have a period appended to them if one is not present as the last character.
¶ As a dictionary
The dictionary form of an Exception is used to control behavior in the reservation/request modal. The dictionary should be in the following form:
{
'conflict'?: <str>,
'alert':? {
'title': <str>,
'text': <str>,
'confirmText'?: <str>,
'type'?: <str>, # 'error', 'info', 'question', 'success', or 'warning'
},
'times'?: {
'start': <datetime>,
'end': <datetime>,
'lockStart': <bool>,
'lockEnd': <bool>,
'lockStartPermanent': <bool>,
'lockEndPermanent': <bool>,
},
}
¶ conflict
If the conflict key is set and a string, the conflict will be set in the reservation/request modal.
¶ alert
If the alert key is set to a dictionary as above, an alert will be displayed to the user.
return Exception({
'conflict': 'foo',
'alert': {
'title': 'Title goes here',
'text': 'Text goes here',
'confirmText': 'confirmText',
'type': 'success',
},
})
¶ Date/time manipulation
Exceptions allow you to lock the date and time on your reservation. It also allows you to set them. Care must be taken when setting the start and end datetimes so that the reservation does not go into an infinite loop. For example, two scripts both setting start dates could easily send the booking modal into an infinite loop of conflict checks.
In the times value, start and end refer to datetime objects that are used to set the start and end date.
lockStart and lockEnd are used to lock the start and end times once, until the current conflict is cleared.
lockStartPermanent and lockEndPermanent are used to lock the start and end times indefinitely, and these locks will not change when another conflict check is made, for example, when a user changes the resource.
Below is an example that sets the start and end date to be January 1, 2021 at 12AM and February 1, 2021 at 12 AM, then locks the times to prevent the user from changing them.
start = datetime.from_date_and_time(
year=2021,
month=1,
day=1)
end = datetime.from_date_and_time(
year=2021,
month=2,
day=1)
# Do not infinite loop conflict checking if the start and end times
# are what they should be.
if reservation['start'] == start and \
reservation['end'] == end:
return True
# If they aren't what they should be, set them to what they should
# be and then lock them.
return Exception({
'times': {
'lockStartPermanent': True,
'lockEndPermanent': True,
'start': start,
'end': end,
},
})
Upon testing this script, you will see output like this:
Attach the script to a resource, then try on the calendar. You will see that the time has been fixed as per the script.
¶ Resource manipulation
The list of resources can be set by returning an Exception dict that contains the key "reservables".
return Exception({
'reservables': [
{
'reservable_id': <str>, # Required
'units'?: <dec> or <int>, # >= 1, default is 1
'rate_id'?: <dec> or <int>, # Integer for the rate ID of choice
},
...
],
})
¶ Note and purpose manipulation
You can set the value of the reservation's note and purpase by returning an Exception dict with "purpose" and "note" fields. Furthermore, you can lock the purpose or note from editing by also returning "lockPurpose" and "lockNote".
return Exception({
'lockNote': <bool>,
'lockPurpose': <bool>,
'note': <str>,
'purpose': <str>,
})
¶ Results
Results of a script may also modify the state of a reservation when no conflict exists. You can access these functions by returning a dictionary.
¶ disclaimer_resource
String with markdown syntax. Sets a disclaimer below the resource in the reservation booking modal. The first disclaimer found for the resource will be the one shown to the user in the case that there are multiple resource disclaimers present from multiple scripts.
What resource this disclaimer applies to is determined by which resource the script is attached to. For example, if the reservation is for two resources but the script is only attached to one of them, the disclaimer will only show for the one the script is attached to.
Example:
return { 'disclaimer_resource': '## foo' }
¶ disclaimer_top
String with markdown syntax. Sets a disclaimer above the list of resources in the reservation booking modal. The first script output with disclaimer_top set will be the one shown to the user in the case that there are multiple top-level disclaimers present from multiple scripts.
Example:
return { 'disclaimer_top': '## foo' }
¶ lockNote and lockPurpose
If you are setting the note or purpase with an exception it can be useful to always lock the value afterwards or when editing. This can be done without throwing an exception by returning an object with one or both of these keys set to true. Typically a reservation script would return an exception with a note or purpose value and a lock if the purpose needs to be set. If the purpose does not need to be changed, simply return the instruction to lock the fields so that no additional editing can take place.
return {
'lockNote': <bool>,
'lockPurpose': <bool>,
}