Joomla Vik Extensions by e4j Official Documentation

Vik Appointments Official Documentation

Vik Appointments - documentation

Version: 1.5

Dashboard

The dashboard page automatically refreshes the upcoming entities (orders, packages, customers and so on) and plays a notification sound every time a new entity is caught. The new entities will be highlighted with an orange background color.

Reservations

The Reservations entity contains the latest appointments booked and the closest incoming appointments.

In the Latest list are displayed the latest 10 placed orders. By clicking on the date of the checkin you will go to the details of the reservation. You can also print the order by clicking on the "Print" link. By Clicking on the customer name, you will be able to send an e-mail through the native Mail Processor installed on your computer.

Vik Appointments - reservation

In the Incoming list are displayed the 10 closest incoming appointments. By clicking on the date of the checkin you will go to the details of the reservation. By Clicking on the customer name, you will be able to send an e-mail through the native Mail Processor installed on your computer.

Vik Appointments - res incoming

Waiting List

The Waiting List entity contains the latest waiting customers registered and the closest customers to the expiration.

In the Latest list are displayed the latest 10 registrations. By hovering the mouse on the calendar icon, you will be able to see the chosen checkin day. By Clicking on the mail icon, you will be able to send an e-mail through the native Mail Processor installed on your computer. By hovering the mouse on the phone icon, you will see the phone number of the customer.

Vik Appointments - waiting list

In the Incoming list are displayed the 10 closest customers to the expiration. By Clicking on the mail icon, you will be able to send an e-mail through the native Mail Processor installed on your computer. By hovering the mouse on the phone icon, you will see the phone number of the customer.

Vik Appointments - waiting list 2

Customers

The Customers entity contains the latest registered customers and the currently logged in users.

In the Latest Registered list are displayed the latest 10 Joomla users registered. By clicking on the name of the user you will go to the details of the customer. By Clicking on the e-mail address, you will be able to send an e-mail through the native Mail Processor installed on your computer.

Vik Appointments - customers

In the Currently Logged list are displayed the latest 10 Joomla users temporarily logged-in. By clicking on the name of the user you will go to the details of the customer. By Clicking on the e-mail address, you will be able to send an e-mail through the native Mail Processor installed on your computer.

Vik Appointments - customers 2

Packages

The Packages entity contains the latest packages orders booked and the latest packages redeemed from the customers.

In the Latest Booked list are displayed the latest 10 placed packages orders. By Clicking on the customer name, you will be able to send an e-mail through the native Mail Processor installed on your computer.

Vik Appointments - packages

In the Latest Used list are displayed the latest 10 packages redeemed from the customers. By Clicking on the customer name, you will be able to send an e-mail through the native Mail Processor installed on your computer.

Vik Appointments - packages orders

ACL Options

It is possible to define the ACL (Access Control Level) rules by clicking on the "Options " button on the top right of the page.

The ACL is used to define the actions that certain user groups can perform inside the administrator section. This feature is useful when you want, in example, your secretary can access into the administrator and manage only certain tasks of VikAppointments.

Vik Appointments - acl options

  • Configure - the selected user-group can configure the ACL of all the user-groups and can edit the configuration of VikAppointments. Only the Super User should be allowed.
  • Access Administration Interface - the selected user-group can access in the back-end and can see VikAppointments in the Components list. This action is required if you want to login in the administrator.
  • Create - the selected user-group can create anything in VikAppointments.
  • Delete - the selected user-group can delete anything in VikAppointments.
  • Edit - the selected user-group can edit anything in VikAppointments.
  • Dashboard View - the selected user-group can see the Dashboard view. If not allowed, the Dashboard link on the menu will disappear.

  • Employees View - the selected user-group can see the Employees view. If not allowed, the Employees link on the menu will disappear.
  • Groups View - the selected user-group can see the Groups view. If not allowed, the Groups link on the menu will disappear.
  • Services View - the selected user-group can see the Service view. If not allowed, the Services link on the menu will disappear
  • Options View - the selected user-group can see the Options view. If not allowed, the Options link on the menu will disappear
  • Locations View - the selected user-group can see the Locations view. If not allowed, the Locations link on the menu will disappear.
  • Packages View - the selected user-group can see the Packages view. If not allowed, the Packages link on the menu will disappear. This section includes also the Packages Orders and the Packages Groups.

  • Reservations View - the selected user-group can see the Reservations view. If not allowed, the Reservations link on the menu will disappear.
  • Waiting List View - the selected user-group can see the Waiting List view. If not allowed, the Waiting List link on the menu will disappear.
  • Customers View - the selected user-group can see the Customers view. If not allowed, the Customers link on the menu will disappear.
  • Coupons View - the selected user-group can see the Coupons view. If not allowed, the Coupons link on the menu will disappear.
  • Calendar View - the selected user-group can see the Calendar view. If not allowed, the Calendar link on the menu will disappear.

  • Countries View - the selected user-group can see the Countries view. If not allowed, the Countries link on the menu will disappear.
  • Reviews View - the selected user-group can see the Reviews view. If not allowed, the Reviews link on the menu will disappear.
  • Subscriptions View - the selected user-group can see the Subscriptions view. If not allowed, the Subscriptions link on the menu will disappear. This section includes also the Subscription Orders.

  • Custom Fields View - the selected user-group can see the Custom Fields view. If not allowed, the Custom Fields link on the menu will disappear.
  • Payments View - the selected user-group can see the Payments view. If not allowed, the Payments link on the menu will disappear.
  • Invoices Archive View - the selected user-group can see the Archive view. If not allowed, the Archive link on the menu will disappear.
  • Media View - the selected user-group can see the Media view. If not allowed, the Media link on the menu will disappear.
Management

The Management section of VikAppointments contains the Groups, the Employees, the Services, the Options, the Locations and the Packages.

All the features contained in this section are used to build and to display the structure of your company.

Employees

The employees are used to define the availability system of your company. An employee can be represented as a person, a room, an object or anything else.

In the administrator section the employees can be filtered with the Keys Filter, which searches by first name and last name, and with the groups dropdown.

If you need to copy and paste an employee, you have to check the checkbox near its ID and click on the "Clone" button on the Joomla toolbar. In this way an exact copy of the selected employee will be created (details, working days, services assignments). The clone feature supports multiple employees at the same time.

The employees can be translated in different languages only from the edit employee page, by clicking on each flag on the top right side.

To receive online reservations you have to create at least one employee.

  • First Name - the first name of the employee.
  • Last Name - the last name of the employee.
  • Nominative - the nominative of the employee (i.e. Lastname, Firstname).
    This value can be translated in multiple languages.
  • E-Mail - the e-mail of the employee, useful for the administrator and required to receive Quick Contacts from the customers.
    This field is also used for the e-mail notifications sent from the system.
  • Notify Bookings - enable this value if you want to send an e-mail to the specified address every time a customer makes a booking with this employee.
  • Phone - the phone number of the employee, useful to the administrator.
    This field is also used for the sms notifications.
  • Show Phone - enable this value if you want to show the phone number of the employee in the Employees List / Employee Details view.
  • User ID - the existing Joomla User to allow the employee to access into the Employees Area in the front-end.
  • Group - the employees group relative to the employee.
  • Quick Contact - enable this value if you want to allow customers to ask info to the employee. The content is sent via e-mail.
  • Listable - enable this value if you want to show the employee in the Employees List page.
  • Active To - the current status of the employee. This value should be changed only when VikAppointments is configured as a portal of employees.
    The status can assume 3 different values:
    - Pending, the employee won't be listed
    - Date, the employee will be listed up to the selected date
    - Lifetime, the employee will be listed without expiration.
    The employees can renew the status of the account by purchasing a new subscription from the Employees Area.
  • Timezone - specify a value only if your employees come from different areas of the world. The dates and the times of the employee will be adapted to the specified timezone.
  • Sync Key - a secret key used to synchronize the appointments of the employee into a private Calendar Handler (like iCal, Google Calendar, Outlook Calendar and so on).
  • Sync URL - the URL to paste into your calendar handler to automatically synchronize the appointments. This field will be visible only for existing employees (it won't be visible during the creation).
  • Choose Image - you can choose an image for the employee to be displayed near its name. If you haven't uploaded yet, you can use the "Upload Image" field to upload an image via AJAX.
  • Description - The extended html description displayed in the Employees List page and in the Employee Details page.
    The html can contain the native Joomla features, like {load position} and it can be translated in multiple languages.
  • Payments - The employee can have different custom payment gateways instead than the global payments. By pressing the Payments button you can only see and remove the payments used from the employee. When an employee has no payments specified, will be automatically taken the global gateways configured. For security reasons, an employee can configure a custom payment only from the Payments section in the Employees Area.
Working Days

This section represents the complete table of the working days of the employees.
The employees must have at least one working day to be able to receive online reservations.

A working day can be split in different shifts (i.e. from 8 a.m. to 11:30 a.m. and from 14 p.m. to 17 p.m.) simply adding two different working days under the same day.
The days with no Working Times specified will be automatically considered as closed (in the example below Tue, Thu, Sat and Sun are closing days).
Vik Appointments - working days

You can also create one ore more Working Days in certain dates of the year (i.e. Thursday 21st April 2016), by selecting the "- Custom Day -" option from the dropdown and by picking a date from the calendar.

The Custom Working Days have more priority than the Week Working Days.

If you need to disable a certain day for a single employee (like 15th August or 25th december), you have to select the custom day and to check the Closed option.
Vik Appointments - working time

The created working days will be automatically assigned to all the services - employee relations.

Overrides

The overrides of the services should be used only when a service is shared from different employees and they doesn't have the same settings.

By clicking on the Overrides button from the Employees List page you will see the list of the settings to use/override for the selected employee-service relation.
Vik Appointments - overrides

From this page you can override the rate, the duration and the sleep values of the selected service by editing the amount inside the input. It is required to press the Save button to save the changes.

The Default is the amount specified from the details of the service and it is automatically assigned to each employee. The Min Over All indicates the minimum amount found between all the values for the current service. The Max Over All indicates the maximum amount found between all the values for the current service. 

Locations

The locations are used to display the working areas of the employees and to split the working days in different locations. If you own a portal of employees which work in different areas you should assign a location to each them to allow users to filter the employees by country and/or state/province and/or city.

You can access to the locations of a single employee by clicking on the Locations button in the Employees List page.

The Map button displays an overview of the working areas of the employee, while the Working Days Assignments button opens a form to split the available working days.

  • Name - the name of the location or the company name at this address.
  • Country - the country of the location. If you are not able to find your country, you have to add it from the Countries page.
  • State - the state/province of the location. If you are not able to find your state/province, you have to add it from the States page.
  • City - the city of the location. If you are not able to find your city, you have to add it from the Cities page.
  • Address - the street address of the location (street number included)
  • Zip Code - the zip code of the location.
  • Latitude - the latitude coordinate (in radiants) of the location. Required to be displayed on Google Maps.
  • Longitude - the longitude coordinate (in radiants) of the location. Required to be displayed on Google Maps.

By filling in the latitude and the longitude in the details page, you will see immediately an overview of the position in google maps. By filling in the address of the location, the system will find automatically the respective coordinates (only if the latitude and longitude fields are empty). You can refresh the latitude and longitude values by clicking on Get Coordinates From Address.

Vik Appointments - maps

The working days assignments are needed if you want to restrict the working days to certain locations, so that the customers are able to understand in which area the employee works for the selected date.
A working day can be assigned only to a single location or it can be left empty.
If you leave all the location field empty, the employee won't be displayed during a search through the Employees Filter module.

Vik Appointments - working days assignement

Reports

The reports page displays the main statistics of the selected employee(s): total earning and monthly earning.

The total earning is a cake graph which displays all the money earned for each service of the selected employee.

The monthly earning is a line graph which displays all the money earned from each service for each month. From the legend you can see the name of each service and the total CONFIRMED reservations received in the specified dates (number between parenthesis).

The reports can be filtered by 2 range dates, with a maximum distance of 3 years.
If you select more than one employee this page will display more graphics one below the other.

Vik Appointments - graph

Payments

The employees can receive payments directly through customized payment processors, so that the administrator won't have to transfer money from its account.

For security reasons the payment processors cannot be created from the administrator section, but it is possible to remove them instead. To create a new customized payment processor, the employees have to login into the Employees Area page.

The customized payment processors will be accessible only from their owners (employees).

Services

The services are the tasks the employees can perform, like Haircuts, Massages, Cleanings and so on. The services can be assigned to multiple employees.

In the administrator section the services can be filtered with the Keys Filter, which searches by name, and with the groups dropdown.

In the Services List page in the front-end, the services are displayed following the defined ordering values. The services can be categorized in groups, so that the services inside groups with lower ordering value will be displayed first.

To receive online reservations you have to create at least one service and it have to be assigned at least to one employee.

  • Name - the name of the service.
    This value can be translated in multiple languages.
  • Duration - the effective duration (in minutes) of the service. This value is used to calculate the checkout of the appointments. When you change this setting from a service, the durations of the assigned existing employees won't be affected.
  • Sleep Time - the sleep time (in minutes) of the service. The duration seen from the customers will be the same but the real duration of an appointment will be duration+sleep time. This option can assume negative values. This setting can be used, in example, when there is a required time to wait between 2 appointments. When you change this setting from a service, the sleep times of the assigned existing employees won't be affected.
  • Time Slots Length - the length (in minutes) of the time slots of the service. This option can be duration+time sleep or the minutes interval setting in the configuration. The time slots are the green/yellow/red block displayed when you click on a day from the calendar.
  • Price - the total cost of the service. Set this value to 0.00 to hide the price label and to skip the payment gateways step for this service. When you change this setting from a service, the rates of the assigned existing employees won't be affected.
  • Maximum Capacity - set this value greater than 1 if you want to have more than one appointment at the same date & time. The availability is given by the sum of all the people of each appointment at the choosen date and time and it cannot be higher than the Maximum Capacity specified. Use this option if you are using services like Yoga, Fitness, Sauna, etc...
  • Min People per App. - the minimum number of people allowed per appointment. When a customer chooses the number of people for this service, it can't be lower than this value. This option is considered only when the Maximum Capacity is greater than 1.
  • Max People per App. - the maximum number of people allowed per appointment. When a customer chooses the number of people for this service, it can't be higher than this value. This option is considered only when the Maximum Capacity is greater than 1.
  • Price per People - enable this option if you want to multiply the price of the service per the number of the people. This option is used only when the maximum capacity is greater than 1.
  • Published - the status of the service. An unpublished service can't be booked and it won't be displayed in the front-end.
  • Start Publishing - the service will become visible only starting from the selected date.
  • End Publishing - the service will be automatically disabled after the selected date. Notice that during the publishing period, reservations after the end publishing date are allowed.
  • Enable Quick Contact - enable this value if you want to allow customers to ask info about the service. The content will be sent via e-mail to the administrator.
  • Employee Choosable - enable this value if you want to allow customers to choose the employee in the Service Details page. When this option is not enabled the program will find automatically an employee related to the service. The assignment of the employee is not random, the system count the number of reservations of all the employees and chooses the employee with the lowest count.
  • Has Own Calendar - when this option is enabled, the reservations of this service won't affect the calendar of the other services. This setting should be used only if your service is self-managed and doesn't need a real employee.
  • Enable Zip Restrictions - enable this option if your employees perform this service in external areas and you want to restrict the available ZIP selection from the customers. You have to set the available ZIP codes from the configuration page.
  • Enable Recurrence - by enabling this option, the customers will be able to book an appointment with recurrence in the same order. All the appointments will be stored in the system as different reservations. The Recurrence options can be configured from the Configuration page. The recurrence will be available only if the SHOP is enabled.
  • Choose Image - you can choose an image for the service to be displayed near its name. If you haven't uploaded yet, you can use the "Upload Image" field to upload an image via AJAX.
  • Group - select the group to which the service belong. A service may not have an associated group.
  • Ordering - a number to display the services in ascending order, the services with the lowest ordering number will be displayed first. The ordering of the groups has more priority than the ordering of the services.
  • Description - the extended html description displayed in the Services List page and in the Service Details page.
    The html can contain the native Joomla features, like {load position} and it can be translated in multiple languages.

When you are editing a service and you have changed the price or the duration or the sleep time, you will be asked to update these values also to all the overrides of the employees assigned to that service.

Assignments

From the service details page, in the administrator section, you can create the service/employees and the service/options assignments.
The services have to be assigned at least to one employee, while it is not required an assignment with the options.

To create an assignment you have to choose an item from the dropdown and press the "Add Employee" or "Add Option" button.
Vik Appointments - employees

Working Days

The working days of a service are automatically extended from the working days of the employees. If you want to remove some working days for a certain service/employee assignment, you have to open the Service Working Days page (accessible from the services list page in the administrator section), pick an employee from the dropdown, remove the unused working days and press the Update button.

If you make something wrong during this step, you can press the Restore button to reset the working shifts of the service relative to the selected employee.
Vik Appointments - working days service

Options

The options can be selected from the customers as additional items or to improve the appointment experience.

The options can be assigned only to the services and they are displayed in the front-end after the selection of the date and time from the availability calendars.

Vik Appointments - options

  • Name - the name of the option.
    This value can be translated in multiple languages.
  • Description - a short description (html is not supported) of the option. The description is displayed as tooltip by hovering the mouse on the name of the option.
    This value can be translated in multiple languages.
  • Price - the price of the single option. The price will be multiplied for the quantity selected.
  • Selectable Quantity - enable this setting if you want to allow customers to select the option more than once.
  • Max Quantity - the maximum quantity selectable.
    This setting can be changed only when the Selectable Quantity option is enabled, otherwise it will be forced to 1.
  • Required - enable this setting if the selection of the option is mandatory. Customers won't proceed to the checkout until all the required options will be selected.
  • Display Image - it is possible to display the image of the option in 3 different ways:
    - hidden, the image won't be displayed
    - popup, the image will be displayed in a popup by clicking on the name of the option
    - left-side, the image will be displayed near the name of the option
  • Choose Image - you can choose an image for the option. If you haven't uploaded yet, you can use the "Upload Image" field to upload an image via AJAX.
Variations

If an option requires a selection between different values, you have just to add 2 or more variations to it.

To add a variation you have just to click the "Add New Variation" button and to fill in the name and the additional price of the variation. The specified price will be always summed to the base cost of the option.

It is possible to re-order the variations by dragging the field from the 3-dots icon. You are required to save the option once you have finished with the ordering.

When an option owns one ore more variations, it will be automatically displayed a dropdown near the name of the option (in the front-end) to allow customers to select the variation they need.

Locations

The locations are used to display the working areas of the employees. If you own a portal of employees which work in different areas you should assign a location to each them to allow users to filter the employees by country and/or state/province and/or city.

The global locations will be automatically assigned to all the employees and they will be visible from the details of the employees only if they are assigned at least to a working day.

The Map button displays an overview of all the working areas.

Vik Appointments - locations

  • Name - the name of the location or the company name at this address.
  • Country - the country of the location. If you are not able to find your country, you have to add it from the Countries page.
  • State - the state/province of the location. If you are not able to find your state/province, you have to add it from the States page.
  • City - the city of the location. If you are not able to find your city, you have to add it from the Cities page.
  • Address - the street address of the location (street number included)
  • Zip Code - the zip code of the location.
  • Latitude - the latitude coordinate (in radiants) of the location. Required to be displayed on Google Maps.
  • Longitude - the longitude coordinate (in radiants) of the location. Required to be displayed on Google Maps.
  • Employee - the employee owner of the location. If you leave this field empty, the location will be considered as global.

By filling in the latitude and the longitude in the details page, you will see immediately an overview of the position in google maps. By filling in the address of the location, the system will find automatically the respective coordinates (only if the latitude and longitude fields are empty). You can refresh the latitude and longitude values by clicking on Get Coordinates From Address.

Packages

The packages are used to pre-sell a defined number of services without the selection of the checkin date and time.

Once the payment of a package order is made, customers are able to specify the checkin date and time of one or more services simply by purchasing an appointment from the calendar. In this case, the cost of the services won't be considered.

To purchase the packages, the login is required to understand if a customer has already at least a package to redeem. To redeem a purchased package, customers require to login with the same account before to confirm the reservation of the appointment.

In the Packages page in the front-end, the packages are displayed following the defined ordering values. The packages can be categorized in groups, so that the packages inside groups with lower ordering value will be displayed first.

The packages can be translated in different languages only from the edit package page, by clicking on each flag on the top right side.

  • Name - the name of the package.
    This value can be translated in multiple languages.
  • Description - the extended html description displayed in the Packages page in the front-end.
    The final height of each package box depends on the description length. This value can be translated in multiple languages.
  • Price - the price of the package.
  • Num Appointments - the number of appointments that the customers can book after the purchase of this package.
  • Published - disable this option if you don't want to allow customers to see and purchase this package.
  • Start Date - the start publishing date allowed for the purchase. Customers can purchase this package only if this value is lower than the purchase date (today).
  • End Date - the end publishing date allowed for the purchase. Customers can purchase this package only if this value is higher than the purchase date (today).
  • Group - select the group to which the package belong. A package may not have an associated group.
  • Available Services - the available services that can be booked after the purchase of this package. If no service is specified, all the services can be booked.

To speed up the creation process of the packages you can clone one or more existing packages. The Clone functionality doesn't affect the translations of the packages.

Packages Groups

The packages groups are used as categories to filter the packages. The packages groups are not required, so if you don't want to categorize your package, you have just to leave this section empty.

The packages groups can be translated in different languages only from the edit group page, by clicking on each flag on the top right side.

The packages groups are used only in the Packages page in the front-end to categorize all your published packages. The packages without group will be displayed as last.

The Packages page can be published by filtering the packages assigned to the specified package group. Otherwise all the packages will be displayed.

  • Title - the title of the group to display.
    This value can be translated in multiple languages.
  • Description - a html description of the group to display in the Packages page.
    This value can be translated in multiple languages.
  • Ordering - a number to display the groups in ascending order, the group with the lowest ordering number will be displayed first.
Packages Orders

The packages orders contains the list of all the orders made from the customers and from the administrator. By editing an order it is also possible to redeem (or to add) manually an appointment.

It is possible to search the packages orders by customer name or by order key.

  • Order Number - an incremental identifier of the order (integer).
  • Order Key - an alphanumeric secret value used to search the order.
  • Customer - the customer assigned to the order. This value is required to assign the appointments to redeem to a Joomla user. By specifying this value, the nominative, the e-mail and the phone number will be automatically filled-in (only if they are empty). 
  • Nominative - the full name of the customer for this order.
  • E-Mail - the e-mail address of the customer for this order. This value will be used to send e-mail notifications to the customer.
  • Phone Number - the phone number of the customer for this order. The phone prefix have to be specified from the dropdown and not in the text input.
  • Payment - the payment gateway used (or to use) to pay the amount of the order.
  • Total Cost - the total cost of the order. The value is automatically updated every time you insert a package into the order. When someone pays the cost of the order through a payment gateway, you will be able to see the amount paid near the total cost. The total paid amount cannot be changed manually.
  • Status - the status of the order (for new order the CONFIRMED status will be used by default).
    There are 4 different possible statuses:
    CONFIRMED - the order is approved and the customers can book the appointment related to the packages in the order.
    PENDING - the order is stored in the database and the customers have to pay the amount of the order or have to wait for a manual approval.
    REMOVED or CANCELLED - the packages inside the order are no more accessible.
  • Notify Customer - check this option if you want to re-send a notification e-mail about the order only to the customer.
  • Custom Fields - the custom fields filled-in from the customer during the purchase. If you leave these fields blank, they will be auto filled-in with the customer details (only e-mail and phone number).

To insert a package into the order, you have just to pick an option from the apposite dropdown. You are able to change also all the values inside the input fields of the packages assigned to the order. The first input represents the number of appointments used, the second one represents the quantity of the packages and the third one is the price of the single package.

Every time an order is made from the front-end, the customer, the employee and the administrator(s) will be notified via e-mail.

Appointments

The Appointments section of VikAppointments contains the Reservations, the Waiting List, the Customers, the Coupons and the Calendars.

All the features contained in this section are used to manage the orders and the customers and to check the availability of your employees/services.

Reservations

All the orders/appointments stored are visible from this view. 
You can also create offline upcoming reservations (in example via telephone) with an intuitive calendar form.
The list of the reservations can be filtered by date, by order key, by customer and by employee/service.
You can print all the selected orders by clicking on the "Print" button in the Joomla Toolbar. 

  • Order Number - an incremental identifier of the orders (integer). By hovering the mouse on the ID you will see who (& when) created the order.
  • Order Key - an alphanumeric secret value used to search the orders from the customers (order number must be always specified).
  • Date - the day for the reservation that you want to create/edit.
  • Time - the time (hour, min) for the reservation that you want to create/edit.
  • Employee - the employee for the reservation that you want to create/edit.
  • Service - the service for the reservation that you want to create/edit.
  • People - the number of people for the selected date, time, employee and service. If your service doesn't host multiple people at the same date and time, it will be taken by default the "1" value.
  • User - select a user from the dropdown to assign a customer to the order and to auto fill-in all the details (nominative, mail and phone number). The fields will be filled-in after saving the changes and only if you leave them blank.
  • Nominative - the full name of the customer for this reservation.
  • Purchaser E-Mail - the e-mail address of the customer for this reservation. This value will be used to send e-mail notifications to the customer.
  • Purchaser Phone - the phone number of the customer for this reservation. This value will be used to send sms notifications to the customer. The phone prefix have to be specified from the dropdown and not in the text input.
  • Coupon - select a coupon from the dropdown if you want to assign it to the order. If an order has already a coupon code, it won't be possible to change it or to remove it. When you select a coupon code and save the changes, the new amount won't be automatically calculated, while the coupon details will be automatically updated (quantity used). From the dropdown will be visible only the VALID and NOT ACTIVE coupons (expired coupons are ignored).
  • Total Cost - the total cost of the appointment. The value will be automatically filled-in (for new reservations) with the cost of the service. When someone pays the cost of a reservation through a payment gateway, you will be able to see the amount paid near the total cost. The total paid amount cannot be changed manually.
  • Duration - the total duration of the appointment. The value will be automatically filled-in (for new reservations) with the duration of the service. Duration have to be specified in minutes.
  • Already Paid - enable this option if your customer has already paid the amount of the reservation. This value will be auto checked when the payment is made online. This value should be used only for offline payments, cash upon arrival or failed transactions.
  • Status - the status of the reservation (for new reservation the CONFIRMED status will be used by default).
    There are 4 different possible statuses:
    CONFIRMED - the order is approved and the customer can go to the appointment. The status CONFIRMED is set every time customers complete a payment successfully or when the total cost of the order is equals to 0.00 and the default status is CONFIRMED (config param).
    PENDING - the order is stored in the database and the customer have to pay the amount of the order or have to wait for a manual approval. An order remains as PENDING only for a limited period (the time is given from the "Keep App. Locked for" config param).
    REMOVED - an order become REMOVED when the customer doesn't pay the order and it passes too much time.
    CANCELLED - an order become CANCELLED when the customer cancel it from the Order page in the front-end. It is possible to disable the order cancellation from the configuration. When a customer cancels its order, it won't be refunded automatically from the system.

    When you change the status to CONFIRMED, the "Notify Customer" parameter will be automatically checked to notify it via e-mail. When you select the CANCELLED option, you will be asked to notify all the customers in the waiting list of that service and for that date.
  • Payment Gateway - the gateway used (or to use) to pay the amount of the reservation. If the selected employee won't have custom payments, it will be taken the default published gateways.
  • Notify Customer - check this option if you want to re-send a notification e-mail about the appointment only to the customer.
  • Notify Employee - check this option if you want to re-send a notification e-mail about the appointment only to the employee.
  • Custom Fields - the custom fields filled-in from the customer during the purchase. If you leave these fields blank, they will be auto filled-in with the customer details (only e-mail and phone number).
  • Additional Options - the additional options for this reservation. By selecting an option from the dropdown, it will be displayed the price and the quantity to choose. If the option has variations, you will be asked also to fill in the variation needed. You have to press the "Add Option" button to insert the selected option to this reservation.
  • Notes - if you need to insert some additional notes about the order, you can use this field. This value will be visible only from the administrator.

Every time an order is made front the front-end, the customer, the employee and the administrator(s) will be notified via e-mail.

Single & Multiple Appointments

If your system allows the creation of orders with multiple appointments (Enable Cart config param), near the ID cell of each reservation you can see a package icon or a chain icon.
The package icon represents the single orders (one order with one service).
By clicking on the button "Multiple Orders" you will see a chain icon near more than one order. The lines which display the "Multiple Orders" button are called PARENTS (one order with more than one service). When you change the Status from a PARENT, will be changed also the status of all the children. To change the total cost of a PARENT you have just to click on its "Total Cost" label.

Single Appointments have the package icon near the ID.
Vik Appointments - single appointment

Multiple Appointments have the chain icon near the ID (after clicking on the green button) and have the same Order Key.
If you don't click on the green button, the reservations won't display any icon.

Vik Appointments - multiple appointment

Make Recurrence

You can create a recurrence for an order by selecting it and clicking on the "Make Recurrence" button on the Joomla Toolbar.
It is possible to create a recurrence only for a reservation per time. It is not possible to create a recurrence for PARENT orders.

Before to create the recurrence you are asked to specify the time arguments:
Repeat Every [Day, Week or Month] For the Next [Amount][Days, Weeks or Months].

Vik Appointments - recurrence

You can get a preview of the available and occupied dates by clicking on the "Get Recurrence Preview" button, which will load asynchronously a list with the calculated dates and their statuses. A reservation results as not available when there is already an appointment stored for that date and time or if that date and time are not contained in the working days of the employee/service.

 Vik Appointments - recurrence dates

The reservations will be stored only after clicking on the "Create Recurring Reservations" button, which will display the number of reservations created. Notice that it will be created a reservation only for the available dates, while the occupied dates won't be considered.

Vik Appointments - reservations numb

Exporting

The reservations can be exported by pressing the "Export" button in the Joomla Toolbar.
By default there are 2 different ways to export the reservations: ICS and CSV.
The reservations to export can be filtered only by date and/or employee.

The dates filters will be automatically filled-in with the oldest checkin (start date) and with the furthest checkin (end date) to cover all the CONFIRMED reservations you have on your system.

ICS: the reservations will be exported in a file following the standard structure of the iCalendar format.
The exported file is compatible with all the most important calendar handler (iCal, Google Calendar, Outlook Calendar and so on), so that you can import it to synchronize your calendar with the appointments manually.

CSV: the reservations will be exported in a file following the standard structure of the comma-separated values format.
The exported file is compatible with all the most important spreadsheet applications (Open Office, Excel and so on).

SMS Notifications

If you have configured the SMS APIs in the configuration of the program, you will see the "Send SMS" button on the Joomla Toolbar.

This button is used to send SMS notifications to the customers about the details of its reservation. The content of the message can be specified only from the configuration.

To send a SMS you have to select at least a reservation and press the "Send SMS" button. The system will try to send a SMS to the phone number of each reservation specified. You will see a response about the status of the messages (success or failure).

Invoices

Pick one or more reservations from the list and press the "Invoice" button on the Joomla Toolbar to generate the relative invoices.

The generated invoices will be placed under the "Invoice" column of each reservation. By clicking on the icon you will see the .pdf on a different tab of your browser. You can also see and download all the generated invoices from the Archive view.

  • Unique Identifier - this is the unique code to identify the invoice. It consists of 2 different values: the first have to be a unique incremental integer number and the second can be a text or a number (like a code or a year). Each time you generate an invoice the unique number is incremented automatically. You should change this value only in the case you are going to overwrite an existing invoice.
  • Date - the date of the invoice can be equals to the Generation Day (today) or to the Booking Day (when the customer confirmed its order).
  • Taxes - the amount of the taxes used in your country (in percentage: 22% or 20.63%). The taxes in VikAppointments are always included in the total cost of the orders, so the invoice will separate the taxes from the total amount.
  • Legal Information - a short description about the legal information of your company.
  • Send Invoices - if you check this option, each customer will receive automatically the generated invoice via e-mail.

Vik Appointments - invoices

  • Page Orientation - the orientation of the page can be Landscape (horizontal) or Portrait (vertical).
  • Page Format - the format of the page can be A4, A5 or A6.
  • Unit - the unit length of the page can be specified in Points, Millimeters, Centimeters or Inches.
  • Scale - this option have to be specified in percentage and it is the scale ratio of the images.

Vik Appointments - generate invoices

Waiting List

The Waiting List is an automated system to notify the customers that are waiting for a service in a specified date. In fact, every time a customer or the administrator cancel an order, the system will automatically send a notification via e-mail (and via SMS if a gateway is configured) to all the customers interested in that service for that date.

The customers can register themselves in a Waiting List from the details page of a service and from the details page of an employee by clicking on the "Add Me in Waiting List" button. This button will be displayed only if the selected date contains at least a booked time.

When a row in the Waiting List becomes expired (the checkin day is in the past), it will be removed automatically from the system.

  • Service - the service in which the customer is interested. This field is mandatory.
  • Employee - the employee in which the customer is interested. This field is optional. When the employee is not specified, the customer will be notified for any cancellation related to the selected service.
  • Checkin Day - the checkin day in which the customer is interested. This field is mandatory.
  • User - the customer to assign in the waiting list. By specifying a user, the e-mail and the phone number will be automatically filled in (only if they are empty).
  • E-Mail - the e-mail address of the customer, used as recipient for the notification. This field is mandatory.
  • Phone Number - the phone number of the customer, used as destination for the notification via SMS. The phone number must contain the phone prefix before the address, by specifying the plus symbol and the prefix (+1). If the phone number is not specified or the SMS API gateway is not configured, the SMS won't be sent.
Customers

The customers view is used to collect all the details of your clients.

A customer will be created automatically every time a new logged-in client places a new order from the front-end.
Your users can edit their details by themselves from the "All Orders" view in the front-end, by clicking on the "My Details" button.

 All the details contained in the Customer object are used to generate the Invoices of the orders.

You can see the number of CONFIRMED appointments made from your customers and you can also ordering them to see a best-purchaser ranking.

  • User Account - the Joomla User assigned to this customer. If the customer doesn't have a Joomla User, you have to select the "Guest" option. By selecting the "Create New Account" option you will be asked to enter username, e-mail and password to create a new Joomla User. The Joomla User will be assigned automatically after saving.
  • Name - the billing full name of the customer.
  • E-mail - the billing e-mail address of the customer.
  • Phone - the billing phone number of the customer. The phone prefix (like +1) must not be specified if country is selected.
  • Country - the billing country of the customer.
  • State - the billing state of the customer.
  • City - the billing city of the customer.
  • Address - the billing address of the customer.
  • Address 2 - a secondary optional billing address of the customer.
  • Zip - the billing zip code of the customer.
  • Company Name - the billing company name of the customer.
  • Vat Number - the Vat Number of the customer.
  • SSN / Fiscal Code - the social security number / fiscal code of the customer.
  • Custom Fields - the custom fields filled-in during the purchase. You can leave these fields empty if you are creating a new customer from the back-end.
  • Notes - if you need to insert some additional notes about the customer, you can use this field. This value will be visible only from the administrator.
  • Avatar - the image of the customer can be changed only from the "All Orders" view.
SMS Notifications

From the customers page you are able to send custom SMS notifications by clicking on the "Comics" icon under the "Send SMS" column.
Only the green icons allow you to send a SMS. Gray icon means the customer doesn't own a phone number.

From the dialog you are asked to insert a short message (maximum 160 characters) to send to the customer.

If you check the "Remember" option (keep this text as default), the message will be stored and will be displayed as default every time you want to send a message.

Vik Appointments - sms

Coupons

The coupons are used to offer discounts to the customers during the purchase.

Coupons have to be applied before to save the order in the confirm appointment page and it is not possible to apply multiple coupons at the same time. If you try to enter 2 valid coupons, only the last one will be used.

There is no way to display coupons in the front-end, so you should promote them by yourself (in example through articles, modules, newsletters and so on).

  • Code - the coupon code to use to be applied. When you create a new coupon, a random code will be generated automatically. If you want you can change it to make it more human-readable.
  • Type - choose the type between Permanent option and Gift option. Permanent coupons remain on your system and it can be used from multiple customers. Gift coupons can be used only for the quantity amount specified, then they will be automatically expire.
  • Max Quantity - the max quantity of uses for this coupons. This value is considered only for Gift coupons.
  • Quantity Used - the number of times that this coupon has been used.
  • Auto Remove When Used - when this option is enabled and the Quantity Used parameter reaches the Maximum Quantity, this coupon will be automatically removed from the system. Even if this option is disabled and the coupon remains in your system, it won't be available. This option is considered only for Gift coupons.
  • Percent or Total - choose if the value of the coupon is a total amount (like 20.00 €) or a percentage amount to discount on the total order (like, 220.00 € - 15%).
  • Value - the amount of the coupon to discount.
  • Minimum Cost - this restriction applies the coupon only when the Total Cost of the order is equals or higher than this option.
  • Date Start - this restriction applies the coupon only when the booking date is equals or higher than this option. Leave it empty if you don't want to use this restriction. This restriction can be applied only if you specify also the Date End restriction.
  • Date End - this restriction applies the coupon only when the booking date is equals or lower than this option. Leave it empty if you don't want to use this restriction. This restriction can be applied only if you specify also the Date Start restriction.
  • Last Minute - enable this option if your coupon is "Last Minute". When you enable this option you will be asked to enter the "Checkin Within" value to determinate the maximum available date and time (by default 24 hours). In this way you can use the coupon only whether the checkin of the appointment is not after 24 hours from the current time.
  • Notes - a short description for this coupon, which can be seen only from the administrator.
  • Available Services - restrict the uses of this coupon only to the specified services. If no service is specified, it will result available for all the services in your system.
  • Available Employees - restrict the uses of this coupon only to the specified employees. If no employee is specified, it will result available for all the employees in your system.
  • Status - the status of a coupon is defined automatically evaluating the dates restrictions. The available statuses are:
    - Valid, the coupon code can be used from customers. The current date is between the dates restrictions or the restrictions are not specified and the quantity used is lower than the maximum quantity.
    Not Active, the coupon code cannot be used from customers. The current date is lower than the Date Start restriction.
    - Expired, the coupon code cannot be used from customers. The current date is higher than the Date End restriction or the quantity used is equals than the maximum quantity.
Calendar

From this page you can see the availability calendar overview of all your employees. The availability calendar is referred to only one employee per time. To change employee you have to switch value from the dropdown.

Below each month you will see a quick report about the earning of the selected employee. If you are not able to see this reports you should check the "Show Statistics" button.
Each month displays the total earning and the total number of appointments, the total earning of the selected employee and the total number of appointments of the selected employee. Then there are these last reports divided per services.

If you want to see a quick list of the reservations in a certain day, you have to pick a date from the calendar to display a list on the bottom of the page. It is possible to see all the details of a reservations by clicking on the pencil icon. If the list doesn't appear, there are no reservations on the selected date.

Reports

The reports page displays the main statistics of all the employees: total earning and monthly earning.

The total earning is a cake graph which displays all the money earned from each employee for all the services.

The monthly earning is a line graph which displays all the money earned from each employee for each month. From the legend you can see the name of each employee and the total CONFIRMED reservations received in the specified dates (number between parenthesis).

The reports can be filtered by 2 range dates (with a maximum distance of 3 years) and by employees.

Vik Appointments - reports

Portal

The Portal section of VikAppointments contains the Countries, the Reviews, the Subscriptions and the Subscription Orders.

Inside the Countries section can be managed also the States and the Cities.

In this section you will be able to configure the portal features of your website, like the reviews for your employees and/or services and the subscriptions purchased from the employees to be visible.

Countries

The countries are mainly used to build the locations of the employees and to setup the phone prefixes dropdown near the Phone Number custom field. By clicking on the name of the country you will see the assigned states. To edit a country you have to pick it from the list and to press the "Edit" button on the Joomla Toolbar.

All the countries are automatically created during the installation of the program.

If your business is located in only one country, you can remove or unpublish all the other countries.

  • Name - the name of the country. This value is by default in English.
  • Country 2 Code - the 2 letters code of the country. This value have to be a standard of ISO 3166.
  • Country 3 Code - the 3 letters code of the country. This value have to be a standard of ISO 3166.
  • Phone Prefix - the default phone prefix used from the country.
  • Published - disable this option if you don't want to show this country.
  • Flag - the image of the flag is automatically assigned using the 2 letters country code. The images of the flags are stored inside the directory: /components/com_vikappointments/assets/css/flags/
  • States - the number of the states inside the country. When this value is empty, the country has no state associated.
States

The states (or provinces) are mainly used to build the locations of the employees. By clicking on the name of the state you will see the assigned cities. To edit a state you have to pick it from the list and to press the "Edit" button on the Joomla Toolbar.

A lot of states are automatically created during the installation of the program. If your country doesn't have states, you can create them manually.

  • Name - the name of the state. This value is by default in English.
  • State 2 Code - the 2 letters code of the state.
  • State 3 Code - the 3 letters code of the state.
  • Published - disable this option if you don't want to show this state.
  • Cities - the number of the cities inside the state. When this value is empty, the state has no city associated.
Cities

The cities are mainly used to build the locations of the employees.

No city is created during the installation of the program.

  • Name - the name of the city.
  • City 2 Code - a 2 letters identifier.
  • City 3 Code - a 3 letters identifier.
  • Latitude - the latitude of the city (in radiants). This values is used only as reference of the location.
  • Longitude - the longitude of the city (in radiants). This values is used only as reference of the location.
  • Published - disable this option if you don't want to show this city.

By filling in the latitude and the longitude in the details page, you will see immediately an overview of the position in google maps. By filling in the name of the city, the system will find automatically the respective coordinates (only if the latitude and longitude fields are empty). You can refresh the latitude and longitude values by clicking on Get Coordinates From Address.

Reviews

If you want to receive reviews for your employees and/or services, you have to configure the Reviews section in the global configuration of VikAppointments.

Customers can leave reviews only if all the following conditions are verified:
- the customer is logged-in
- the customer hasn't rated yet the employee/service
- the customer has a confirmed appointment with the employee/service to rate
- the checkin of the appointment is in the past (this confirms the customer effectively met the employee or received the service)

The reviews have a mandatory stars rating (from 1 to 5), a mandatory title and an optional/mandatory description.

The reviews can be filtered by title, username, employee/service and rating.

  • Title - the title of the review (max 128 characters).
  • User - the existing Joomla account of the user.
  • Name - the name of the user. This value will be automatically filled-in by selecting the Joomla User.
  • E-mail - the e-mail address of the user. This value will be automatically filled-in by selecting the Joomla User.
  • Date - when the customer submitted the review from the front-end. This value can be changed from the back-end.
  • Rating - the number of stars that represent the rating of the employee/service.
  • Published - disable this option if you want to hide this review without deleting it. By default all the new submitted reviews are published automatically, but it is possible to disable this option to publish them manually.
  • Employee/Service - the employee or the service rated.
  • Language - the language tag of the review. When a customer submits a new review, the lang tag will be the same of the language set in the front-end. This option is used to filter the reviews by language.
  • Comment - the description of the review. The maximum characters length can be defined from the configuration.

Here is how the reviews look like in the services details pages and in the employees details pages.

Vik Appointments - reviews

While the customers can submit reviews through the form below.

Vik Appointments - reviews 2

Subscriptions

The subscriptions are located in the Employees Area and can be purchased from the employees to be listed on your website.
The employees will be visible in the Employees List page only when their subscription plan has not yet expired.
You should use the subscriptions only in the case you are hosting a portal of independent employees.

The subscriptions are exactly the items that your employees will purchase from the Employees Area.

  • Name - the name of the subscription plan.
  • Amount - an integer value of the subscription. This value is related to the Type option.
  • Type - the type of the subscription. The values allowed for the type are the followings: days, weeks, months, years, lifetime
  • Price - the total cost of the subscription plan.
  • Published - disabled this value if your employees cannot purchase this subscription.
  • Trial - enable this option if you want to offer this subscription as a trial for free. Only one subscription can have this option enabled. Employees can purchase a trial subscription only once.

The valid period of a subscription is given from the amount per the type (like, 6 months or 2 years). Lifetime subscriptions will have always the amount equals to 1 and they will never expire.

Subscription Orders

The Subscription Orders task in the administrator contains all the orders received from the employees.

The subscription orders can be filtered by Order Key or by the name of the employee.

  • Order Number - an incremental identifier of the subscription order (integer).
  • Order Key - an alphanumeric secret value.
  • Date - when the employee purchased the subscription plan.
  • Employee - the employee that purchased the subscription plan.
  • Subscription - the type of the subscription plan purchased.
  • Payment - the payment gateway used to transfer the money to the administrator.
  • Total Cost - the total amount of the order. This value is given from the cost of the subscription plan and the additional charge of the gateway.
  • Total Paid - the total amount paid from the employee.
  • Status - the status of the order. There are 3 possible statuses:
    CONFIRMED - the order is approved and the employee successfully paid the order. When the subscription plan has no cost, the order will be confirmed automatically.
    PENDING - the order is stored in the database and the employee have to pay the amount of the order or have to wait for a manual approval. An order remains as PENDING for an unlimited time.
    REMOVED - the order can be removed only from the administrator.

Every time a subscription order is successfully paid or manually confirmed, the expiration date of the employee is automatically renewed.

Employees Overview

The Employees Overview is used to see a quick list about the listing status of all the employees, so that you can see the active employees and the employees with an expired subscription.

By clicking on the Published/Unpublished icon of each employee, you can change immediately the listable status.

 Vik Appointments - employees sub

Global

The Global section of VikAppointments contains the Custom Fields, the Payment Gateways, the Invoices Archive, and the Media Manager.

Custom Fields

The custom fields are used to receive all the information you need about your customers.

They are displayed in the appointment confirmation page and in the packages confirmation page, before to store the order in the system.

  • Field Name - the text to display in the label near the input field (like, First Name).
    If you want to use multi language custom fields, you have to insert a code for this option (like MY_CUSTOMF_FIRST_NAME). Then you need to place the following code:
    ; this is equals to: LANG_KEY = "Translated value"
    MY_CUSTOMF_FIRST_NAME="First Name"
    
    into all your language files (admin & front):
    /administrator/language/en-GB/en-GB.com_vikappointments.ini
    /administrator/language/de-DE/de-DE.com_vikappointments.ini

    /language/en-GB/en-GB.com_vikappointments.ini
    /language/de-DE/de-DE.com_vikappointments.ini
  • Type - the type of the input to display. The values allowed for the type are the followings: Text, Textarea, Date, Select, Checkbox, File, Separator.
  • Required - enable this option if customers cannot leave this field blank. The order will be stored only when all the required custom fields will be filled-in. The label of the required options will contain the * symbol.
  • Is Nominative - enable this option if this field is used to collect a nominative (like First Name, Last Name or Full Name). All the nominative custom fields will be merged with a space in the middle. The resulting nominative will be assigned to the purchaser nominative field of the reservation.
  • Is e-Mail - enable this option if this field is used to collect an e-mail address. Only one field should have this option enabled, otherwise only the last e-mail address specified will be used. The resulting e-mail will be assigned to the purchaser mail field of the reservation.
  • Is Phone - enable this option if this field is used to collect a phone number. When this option is enabled you have to specify the 2 letters country code of your company, so that the system is able to specify a default phone prefix. Only one field should have this option enabled, otherwise only the last phone number specified will be used. The resulting phone number will be assigned to the purchaser phone field of the reservation.
  • Popup Link - the url of the page you want to show as popup. By clicking on the label of the field, it will be displayed a popup containing the url specified. It is suggested to use the tmpl=component attribute to ignore the template and to show only the content. This option is useful for the "Terms & Conditions" checkboxes.

Here you can see a detailed description about all the possible types of the custom fields.

Text Type

The text type displays a default html text input tag. It is used to receive short texts and numbers.

Vik Appointments - text field

Textarea Type

The textarea type displays a default html textarea tag. It is used to receive medium & long texts, thanks to the resizable right-bottom corner.

Vik Appointments - textarea field

Date Type

The date type displays a custom calendar field. By clicking on the calendar icon it will be opened a datepicker. It is used to pick formatted dates from a calendar.

Vik Appointments - date field

Select Type

The select type displays a default html select tag. The options of the dropdown can be defined from the details page of the custom field.

Vik Appointments - select field

Checkbox Type

The checkbox type displays a default html checkbox input tag. It is used to receive only true/false values (1/0 or yes/no).
The value of the required checkboxes, such as terms and conditions, is not stored because they can assume only the true value.

Vik Appointments - checkbox field

File Type

The file type displays a field to upload files into the server. The file extensions allowed can be defined from the details page of the custom field and must be separated by a comma (like png, jpg, pdf). The available extensions can be seen in the front-end between the parenthesis.
For security reasons the name of the images will be automatically changed in a secret code.

Vik Appointments - file field

This is how the file field works when customers have already uploaded a file.

Vik Appointments - file field 2

Separator Type

The separator type displays simply the name of the custom field. This custom field is not able to receive information from the customers.
It is possible to change the style of the separator by editing the CSS rules of the class .vapseparatorcf. When the separator has more than 30 characters, it will be used the classname .vapseparatofcflong instead than .vapseparatorcf.

Payments

The payment gateways are used to collect credit/debit cards payments from your website.

There are 2 different types of gateways: Seamless and Hosted.
With seamless payment gateways your customers won't leave your website because the credit card details will be filled through an apposite form. For this type of payment, the SSL certificate is required.
The hosted payment gateways will redirect the customers to a payment page hosted on your bank website. At the end of the transaction they will come back on your website and they will see the status of the order changed (only in case of success). For this type of payment, the SSL certificate is optional.

In the package you can find 3 pre-installed payment gateways: PayPal, Offline Credit Card, Bank Transfer.

The payment gateways will be used when the total cost of the order is higher than 0.00 and there will be at least a published gateway.

It is possible to make a payment only when the status of the order is PENDING.

  • Payment Name - the name of the payment to display in the front-end.
  • Notes - a html description for the selected payment. The notes are displayed only when the orders are confirmed. You can use this field to allow users to follow certain instructions after the payment.
  • File Class - the corresponding .php file of the gateway. The file is mandatory, otherwise the system won't be able to show the payment form and to process the transaction. When you change the value from the dropdown, it will be loaded a form with the details of the payment. All the loaded fields should be filled-in.
  • Published - disable this option if you don't want to allow customers to make payments through this gateway.
  • Allowed for Subscriptions & Packages - enable this option if you want to use this gateway also to receive payments for employee subscriptions and packages.
  • Cost - an additional charge/discount for this gateway. The selected amount will be displayed near the name of the payment (when it is different than 0.00). This value can be used to prevent fees or to make little discounts. When a gateway with additional cost is selected, the total cost of the order will be changed.
  • Auto-Set Order Confirmed - enable this value if you want to confirm the order by ignoring the payment transaction. This value should be enabled only for the pre-installed class "bank_transfer.php".
  • Output Position - you can specify where to print the payment form of this gateway. The possible values are: Ignore, Top-Left, Top-Center, Top-Right, Bottom-Left, Bottom-Center, Bottom-Right. By selecting the Ignore value, the payment form will be placed in a position similar to Bottom-Left
  • Always Show Note - enable this option if you want to display the Notes also before the payment transaction.
  • Ordering - a number to display the payments in ascending order, the payments with the lowest ordering number will be displayed first.
PayPal

The PayPal payment gateway (hosted) prints the standard orange PayPal button to start the transaction. The payment will come on PayPal website and, only after the transaction, the customers will be redirected to the order page on your website.

The parameters of PayPal require only the e-mail address assigned to your PayPal account.

To change any other parameter (like the accepted currencies) you have to do it directly from the merchant panel of your PayPal account.

If you want to test the PayPal gateway without transfer real cash, you should enable the "Sandbox" parameter.

Offline Credit Card

The Offline Credit Card payment gateway (seamless) is not a real method of payment. This gateway collects the credit card details of your customers and then send them via e-mail to the administrator, so that it is able to make the transaction with a virtual pos.

After the form submission the status of the order will be changed to CONFIRMED. If you want to leave the status to PENDING (and confirm it manually from the back-end) you have to change the default status setting from the parameters of your gateway.

For PCI compliance, this gateway doesn't store the credit card details on your database.

Bank Transfer

The Bank Transfer (or Pay upon Arrival) payment gateway is used to skip the payment method process when you have other gateways published. This gateway means you will receive the payment by cash when the customer will come to your company.

If you want to automatically confirm the order with this payment gateway, you have to enable the "Set-Auto Order Confirmed" option from the parameters of the gateway.

Invoices Archive

The invoices archive view contains all the generated invoices of your reservations.

The invoices are automatically categorized by years and months, depending on the booking date of the reservations.

The Others category contains all the reservations without a booking date. All the reservations placed before the 1.4 version of VikAppointments doesn't have a booking date.

The invoices can be filtered only by name. The search will be applied only to the invoices in the selected category. The name of the invoice is always [ordernumber]-[orderkey].pdf

By clicking on the name of the invoice it will be displayed the .pdf file in another tab of the browser. By clicking on the icon of the invoice you will select it. It is possible to select more than one invoice. If you want to select all the invoices you have to click on the "Select All" button.
The selected invoices can be downloaded or removed.

Vik Appointments - invoices archive

Download

If you download a single invoice, you will find the .pdf on your downloads folder.
While if you download multiple invoices, all the .pdf files will be zipped and you will find a .zip archive on your downloads folder.

Vik Appointments - pdf download
Vik Appointments - zip download
Media Manager

The Media Manager page contains all the uploaded images, which are used for services, employees, options and company logo.

A media is the representation of an image and its thumbnail. The original images are located in the folder:
/components/com_vikappointments/assets/media/
while the thumbnails are located in the folder:
/components/com_vikappointments/assets/media@small/

By hovering the mouse on the image, you will be able to see the date of the upload and the size (in kB) of the original image.

To rename a media file, you have to click on the image or on the edit icon, then the media will be flipped and you will be able to change the current name into a new one.

You can remove single media files by clicking on the trash button inside the box. The media will be removed via AJAX and the page won't be refreshed. To remove multiple media files you have to select them and click on the "Delete" button on the Joomla toolbar (the page will be refreshed).

The media files can be filtered by name.

Upload

To upload a media you have to press the "New" button on the Joomla toolbar, select an image from your file browser and press the "Save" button. All the medias will be uploaded with the last properties stored.

If you save a media without specifying a file, only the media properties will be changed. 

  • Image - the image file to upload, located on your computer. Only images are allowed for the upload.
  • Resize - enable this option if you want to resize the original image.
  • Original Size - crop the original image with the specified width and height. The crop is applied only if the Resize option is enabled.
  • Thumbnail Size - copy the image and crop it with the specified width and height.

When you upload a new image with the same name of an existing image, it will be concatenated a random number to the name of the new one.

Quick Upload

It is possible to upload multiple images in a quick way by using the Drag&Drop.

Vik Appointments - drag&drop

In the media creation page, you have to drag one or more files from your computer and drop them on the dashed gray box. All the images will be added in a queue and will be uploaded simultaneously. All the images will be uploaded following the last media properties used.

Vik Appointments - uploads

The images with 100% green status are successfully uploaded as media. The images with 100% blue status are completing the cropping of the thumbnail. The images with status lower than 100% are completing the upload of the original image. You can cancel the upload of an image by clicking on the "Abort" button. It is possible to abort an upload only when the original image hasn't been uploaded yet.

Analyze Media

The Analyze button in the Joomla toolbar is used to check which images are effectively used from the program.

Before to analyze your medias you have to select at least one image. If you want to analyze all your medias, you have to scroll down, press the "Load All Images" button, press the "Select All" button and analyze them.

When the analyzation will be completed all the selected images will be flipped and a response will be displayed.

Vik Appointments - analyze media

E-mail Custom Text

This section can be used to insert different contents in the e-mail for the customers depending on the status of the order.

In this way you can, in example, place details about the payment for PENDING orders or instructions to follow for CONFIRMED orders and so on.

To manage the e-mail custom text you have to open the global configuration of VikAppointments and click the "Manage Custom Text" button near the "E-Mail Template" setting.

  • Name - the name of the custom content of the e-mail. This is only a text identifier of the content.
  • Position - the position of the custom content in template of the e-mail. The possible values are: {custom_position_top} (below the company name), {custom_position_middle} (below the order total cost), {custom_position_bottom} (above the order link), {custom_position_footer} (bottom of the page). You can see where are exactly these codes by opening the template of the e-mail.
  • Status - you can display the custom content only when the status of the order is equals to this option (confirmed, pending, removed, cancelled).
  • File - you can display the custom content only when the e-mail template file used is equals to this option. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/
  • Language - you can display the custom content only when the language selected from the customer is equals to this option. To create multi language contents you have to duplicate a custom text and change the language tag and the content.
  • Content - insert here the html content you want to display in the e-mail template at the selected position.
Cron Jobs

The Cron is a time-based job scheduler which runs periodically a process at fixed times, dates, or intervals. It is possible to use cron jobs only if crontab is installed on your server.

You can check how to install a cron job on your server from here:
https://extensionsforjoomla.com/documentations/vik-appointments#configuration-cron-jobs

In the package you can find 5 pre-installed cron jobs: Appointment E-Mail Reminder, Appointment SMS Reminder, Employee Review Reminder, Service Review Reminder, Employee Subscription Reminder.

To manage the cron jobs you have to open the Cron Jobs configuration of VikAppointments and click the "See Cron Jobs List" button.

  • Name - the name of the cron job. This is only a text identifier of the element.
  • Class - the corresponding .php file of the cron job. The file is mandatory, otherwise the system won't be able to execute the process of the cron job. When you change the value from the dropdown, it will be loaded a form with the settings of the cron job to fill-in.
  • Published - disable this parameter if you don't want to execute the process of the cron job. If this job is correctly configured on your server, you should also stop it from your Control Panel, otherwise the cron will continue to be contacted and the error "cron not found" will be stored into the logs.

When you create a cron job the system will automatically launch the installation to adapt the database structure. It is possible to install more than one cron job of the same type, so that you can send (in example) the same reminder one day in advance and 2 hours in advance.

It is possible to launch manually a cron job by clicking on the apposite rocket icon. In this way the process of the cron will be executed immediately.

Cron Jobs Logs

Every time a cron is executed it will be stored a content message into the Logs section of that cron job. A log can have OK status or ERROR status.The error logs will be always stored in the system, while the successful logs will be logged depending on your Cron Job configuration. A cron job log contains the details of the last process executed, which could be the list of the appointments or the customers notified or the cause of the error found.

If the error is almost dangerous, the log is also sent via e-mail to the administrators addresses, so that they can immediately solve the problem. The logs sent via e-mail have a letter icon below the "Mailed" column.

Vik Appointments - cron job

Appointment E-Mail Reminder - Cron Job

This cron job is used to send a reminder via e-mail to all the customers which have an incoming appointment.

An appointment is considered incoming when its checkin time is included between the current time and TOT minutes in the future.

  • Send E-Mail in Advance - this setting is used to define the TOT minutes required for the notification.
  • E-Mail Subject - specify here the subject of the e-mail. You can specify this setting for each language installed on your website.
  • E-Mail Content - specify here the HTML content of the e-mail. This field accepts HTML tags and CSS tags. You can specify this setting for each language installed on your website.

Once a customer is notified from this cron job, it will no longer be contacted for the notification.

If you need to send 2 reminders in 2 different times, you have just to duplicate the cron job and change only the "Send E-Mail in Advance" setting.

Vik Appointments - settings

Appointment SMS Reminder - Cron Job

This cron job is used to send a reminder via SMS to all the customers which have an incoming appointment.

An appointment is considered incoming when its checkin time is included between the current time and TOT minutes in the future.

  • Send SMS in Advance - this setting is used to define the TOT minutes required for the notification.
  • SMS Content - specify here the plain text content of the SMS. This field should contain at most 160 characters. You can specify this setting for each language installed on your website.

Once a customer is notified from this cron job, it will no longer be contacted for the notification.

If you need to send 2 reminders in 2 different times, you have just to duplicate the cron job and change only the "Send SMS in Advance" setting.

Vik Appointments - settings 2

Employee Review Reminder - Cron Job

This cron job is used to remind to the customers to leave a review for the employees they met.

They will be contacted only the customers which had the checkin day, TOT days before the current day.

  • Send E-Mail Notification After - this setting is used to define the TOT days required for the notification.
  • E-Mail Subject - specify here the subject of the e-mail. You can specify this setting for each language installed on your website.
  • E-Mail Content - specify here the HTML content of the e-mail. This field accepts HTML tags and CSS tags. You can specify this setting for each language installed on your website.

Once a customer is notified from this cron job, it will no longer be contacted for the notification.

If you need to send 2 reminders in 2 different times, you have just to duplicate the cron job and change only the "Send E-Mail Notification After" setting.

Vik Appointments - settings 3

Service Review Reminder - Cron Job

This cron job is used to remind to the customers to leave a review for the services they received.

They will be contacted only the customers which had the checkin day, TOT days before the current day.

  • Send E-Mail Notification After - this setting is used to define the TOT days required for the notification.
  • E-Mail Subject - specify here the subject of the e-mail. You can specify this setting for each language installed on your website.
  • E-Mail Content - specify here the HTML content of the e-mail. This field accepts HTML tags and CSS tags. You can specify this setting for each language installed on your website.

Once a customer is notified from this cron job, it will no longer be contacted for the notification.

If you need to send 2 reminders in 2 different times, you have just to duplicate the cron job and change only the "Send E-Mail Notification After" setting.

Vik Appointments - settings 4

Employee Subscription Reminder - Cron Job

This cron job is used to remind to the employees that their subscription is going to expire.

They will be contacted only the employees with a subscription which will expire in TOT days.

  • Send E-Mail Notification Before - this setting is used to define the TOT days required for the notification.
  • E-Mail Subject - specify here the subject of the e-mail.
  • E-Mail Content - specify here the HTML content of the e-mail. This field accepts HTML tags and CSS tags.

Once an employee is notified from this cron job, it will no longer be contacted for the notification.

If you need to send 2 reminders in 2 different times, you have just to duplicate the cron job and change only the "Send E-Mail Notification Before" setting.

Vik Appointments - settings 5

Configuration

In the configuration there are located all the settings that will affect the flow of the program. From the configuration page can be changed the settings of the whole system, of the employees, of the closing days, of the SMS APIs and of the Cron Jobs.

The Renew Session button should be used (strongly recommended) every time you change something from the configuration to refresh the settings stored in the PHP session of the active users on your website. If you don't press this button, probably you won't see the changes in the front-end of your website.

The new settings will be immediately available for all the future users and will become available for the active users after 15 minutes of inactivity.

Global

In the global configuration of the program is possible to define all the generic parameters to fit the system to your needs.

System

Company Name
The real name of your company, displayed in the e-mail contents and subjects, in the sms and in the ICS sync.

Company Logo
The image logo of your company. To upload a new image you can use the Media Manager. The logo will be displayed only in the header of the e-mail for the customers. If you don't specify a logo image, it won't be used.

Enable Multilanguage
This option should be enabled when the contents of your website (services, employees, options, groups and so on) must be translated in different languages. When this option is enabled, you will find a toolbar with the available languages in the edit page of services, employees, options, groups, payments and packages. If you don't want to translate the contents, but only the text of the program, you can disable this option and simply use the translated language files of the extension.

Date Format
The format of the date to display in the back-end and in the front-end. The available formats are:
Y/m/d, m/d/Y, d/m/Y, Y-m-d, m-d-Y, d-m-Y, Y.m.d, m.d.Y, d.m.Y
where Y is the year, m is the month and d is the day.

Time Format
The format of the time to display in the back-end and in the front-end. The time can be formatted in 12 hours (am/pm) or 24 hours.

Format Service Duration
This option should be enabled when the duration of the services is higher then 60 minutes. The durations will be formatted as follows:
255 min. becomes 4 hours & 15 min.

Minutes Intervals
The default intervals (in minutes) of the selectable time slots. When this value is set to 15 min. customers will be able to select a time every 15 minutes, like 10:00, 10:15, 10:30 and so on. When this value is set to 60 min. customers will be able to select a time every hour, like 10:00, 11:00, 12:00 and so on. This setting can be overwritten from the details of each service.

Opening Time
The opening time of your company. This value is used to define the minimum time during the working days creation. If your company works 24 hours per day, set this option to 0:00.

Closing Time
The closing time of your company. This value is used to define the maximum time during the working days creation. If your company works 24 hours per day, set this option to 24:00.

Notice: when your business works 24 hours per day, you will be able to receive appointments during the whole day, but you won't be able to receive appointments between two different days: like 23:45 to 00:15.

Booking Minutes Restrictions
Use this option to define the minimum time for bookings from the current time (in minutes). In few words, when this values is set to 120, customers have to book an appointment 2 hours in advance.

Show Phones Prefix
Enable this option if you want to force your customer to select a phone prefix in the confirmation page. When this option is enabled, it will be displayed a dropdown with all the phone prefixes near the phone number custom field. This option is recommended if you have the SMS APIs framework configured. You can change the default prefix selected from the settings of your Phone Number custom field, where you have to edit the Default Country Code setting (by placing US it will be used the +1 prefix, while by placing FR it will be used +33).

Keep Appointments Locked For
This setting defines the number of minutes for which the system should keep the employee of a Pending Reservation, as "locked" so that nobody can choose an employee that is being reserved by another client. When a customer searches for an appointment, will be removed all the PENDING and EXPIRED reservations.
Set an high value to ignore this parameter (like 99999999), otherwise all the customers will be able to confirm an appointment only within X minutes.

Default View
The default view when you access in the administrator. The possible views are Dashboard and Calendars. By selecting the Calendars view, dashboard couldn't be accessed.

Dashboard Refresh Time
Set the seconds to auto-refresh the details in the dashboard view. In this way every X seconds, the system will be automatically refreshed. This value shouldn't be lower than 15 seconds.

Always Confirm On Delete
Disable this value if you don't want to confirm the dialog before to delete something from the system.

Enable Router
When this setting is enabled, the URLs of VikAppointments bill be routed in a different way. This option can work only when there is a .htaccess (on Apache) or a web.config file in the root of your server.

Load jQuery
jQuery is required to the system to perform certain actions via javascript. If your template already loads jQuery, you can disable this setting.

Show Footer
Disable this option if you don't want to show the e4j credits on the bottom of each page in the administrator.


Calendars

Number of Visible Months
Specify the number of calendars that you want to display in the employee/service details page. You can display 1, 2, 3, 6, or 12 months.

Selectable Months
Specify the number of the selectable months in the dropdown. By selecting 12 months, customers could check 11 months in advance (the first month is the current). By selecting 1 month, the dropdown won't be displayed.

Display Calendars From
If your business starts in a different month than the current, you can use this setting to specify the first available month of a certain year. This value will be considered only if it is not in the past, otherwise it will be used the current month.

Display Colors Legend
Enable this option if you want to display a legend about the colors of the day in the calendars. The legend will be displayed above the calendars.

First Week Day
Specify the first day of the week to display in your calendars. Usually this value is set to Monday, Saturday or Sunday.


Timezone

Enable Multiple Time Zones
Enable this value only if your employees come from different areas of the world. The administrator will use the timezone set on your server. In the front-end the system will automatically switch the timezone depending on the employee selected. The time blocks will be the same, but it will be possible to adapt the times to the local area of the employee, so that customers can book for the current day.

Current Default Time Zone
The default timezone set on the php.ini configuration of your server. If this value doesn't correspond to the local area of your business, you should contact your hosting provider.


Appointments Sync

Sync URL
You can use this link to automatically synchronize the appointments on VikAppointments into your favourite calendar provider. You have only to specify this link into the apposite page of your provider and it will download automatically an ICS file to sync each day the appointments stored.
You can also filter the appointments to export by employee simply adding the &employee=[EMP_ID] parameter in the query string of the url.

Sync Password
Specify a password to make sure someone else won't be able to download the appointments from the Sync URL. When you change the password, the Sync URL will change too.


ZIP Restrictions

Zip Code Field
If your services are performed out of your business base and you want to restrict the available areas, you have to select the ZIP field from the custom fields created. This field will be used to validate the entered zip with all the available zip codes.

Zip Codes
Put here all the available zip codes for your services. You can put intervals of zip (like EG34X - EH67F or 68000 - 68999) or unique ZIP (98700-98700).

Try Zip Code Validation
Try to test if a zip code is able to receive your services. Before to test, save the configuration, otherwise the new zip codes won't be found.

Load Zips From File
You can insert all the available zip codes by uploading file containing all the available zip codes. The structure of the file must contain one zip code per line and it is not necessary they are ordered. You should use the .txt file extension. Before to use this tool you should save the configuration to don't lose your changes.


Reservations List Columns

You can specify from this setting all the columns that you want to display/hide in the reservations list page in the administrator. The available columns are: Order Number, Order Key, Payment, Begin, End, Employee, Service, People, Info, Coupon, Nominative, Purchaser E-mail, Purchaser Phone, Total Cost, Already Paid, Invoice, Status.


E-Mail

Admin e-Mail
The e-mail addresses of the administrator(s). All the notifications, including the reservations received, will be sent to these addresses.
If you want to notify multiple addresses, you have just to specify the e-mails separated by a comma: This email address is being protected from spambots. You need JavaScript enabled to view it., This email address is being protected from spambots. You need JavaScript enabled to view it., This email address is being protected from spambots. You need JavaScript enabled to view it..

Sender e-Mail
The e-mail address used to send all the notifications via mail. If you don't specify this e-mail address, will be used the first address specified in the Admin e-Mail parameter.

Mail Attachment
If you want to include an attachment (like a .pdf or a .doc) in the confirmation e-mail for the customers, you can upload a file from this setting.

Send to Customers with Order
Set the value to "Only Confirmed" if you want to send the confirmation e-mail to customers only when the status of the order is confirmed.

Send to Employees with Order
Set the value to "Only Confirmed" if you want to send the notification e-mail to the employees only when the status of the order is confirmed.

Send to Admin with Order
Set the value to "Only Confirmed" if you want to send the notification e-mail to the administrator(s) only when the status of the order is confirmed.

Customer E-Mail Template
You can change the HTML content of the e-mail of the purchase for the customers by clicking on the "Edit" button near the dropdown. It is possible to use only one template per time. You can save the template as copy to don't lose the original code. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/

The Manage Custom Text button is used to insert dynamic content on the e-mail depending on the status of the order.

Admin E-Mail Template
You can change the HTML content of the e-mail of the purchase for the administrators by clicking on the "Edit" button near the dropdown. It is possible to use only one template per time. You can save the template as copy to don't lose the original code. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/

Employee E-Mail Template
You can change the HTML content of the e-mail of the purchase for the employees by clicking on the "Edit" button near the dropdown. It is possible to use only one template per time. You can save the template as copy to don't lose the original code. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/

Cancellation E-Mail Template
You can change the HTML content of the e-mail of the cancellation for the employees and the administrators by clicking on the "Edit" button near the dropdown. It is possible to use only one template per time. You can save the template as copy to don't lose the original code. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/

Attach ICS to
From this setting you can automatically include the .ics file of the appointment in the attachments of the e-mail for customers and/or employees and/or administrator(s).

Attach CSV to
From this setting you can automatically include the .csv file of the appointment in the attachments of the e-mail for customers and/or employees and/or administrator(s).


Currency

Currency Symbol
Insert here the symbol (or some characters) of the currency used in your system (like €, $, £ and so on). This value will be displayed near each price on your website.

Currency Name
Insert here the standard 3 letters code of the currency used in your system (like EUR, USD, GBP and so on). The value specified must be a standard of the ISO 4217. When a payment gateway doesn't have the currency selection, it will be used this value as currency of the transaction.

Symb Position
Choose from this setting the position of your currency symbol: after the price (12.50 €) or before the price (€ 12.50).

Decimal Separator
The symbol used to separate the integer part from the fractional part of a price, like € 120.00 or € 120,00.

Thousands Separator
The symbol used for the digit grouping, like € 1.000,00 or € 1,000.00.

Number of Decimals
The number of decimals to display for the fractional part of a price, like € 280.0 or € 280.00.


Shop

Default Status
The default status for the appointments without payment gateway. If your services are free or you don't want to collect payments online, you can set this value to PENDING to confirm the orders manually from the back-end or from the notification e-mail.

Enable Cart
This option must be enabled it you want to receive multiple appointments in the same order.

Maximum Cart Appointments
The maximum number of appointments that customers can book in a single order. If you don't want to use this restriction, you have to check the "Unlimited" checkbox. This value is 1 by default when the "Enable Cart" setting is disabled.

Same Checkin in Cart
When this setting is enabled, the customers will be able to add into the cart different services at the same date and time.

Cart Auto Expanded
Enable this option if you want to automatically collapse the summary order in the confirmation page.

Shop Button Filter
The default link to use when customers click on the "Continue Shopping" button below the summary order in the confirmation page. You can disable this button by selecting the "Hide Button" option. With the "Custom Link" option you are able to specify the direct link to use.

Use Deposit After
When the total cost of an order is higher than the value specified for this setting, customers have to pay online a "Deposit Amount" instead the total cost of the order. If you don't want to use the deposit feature, you have just to insert an unreachable value (like 9999999).

Deposit Amount
The deposit amount to use can be a fixed value (like 100 €) or a percentage value of the total cost (like 20% of the order). This value is considered only when the total cost of the order is higher than the "Use Deposit After" option.

Login Requirements
Set this value to "Required" if you want to force your customers to login/register before to proceed with the checkout. The custom fields of customers will be stored (only when logged-in) and automatically filled-in starting from the second purchase. The information specified in the registration fields won't be used for custom fields. This setting accepts the following options: OptionalRequired on Confirmation PageRequired on Service/Employee Details.

By Selecting the Required on Service/Employee Details value, customers won't be able to see the availability calendars as guest users. While, by selecting the Required on Confirmation Page value, the customers won't be able to proceed with the purchase as guest users.

Enable Order Cancellation
Enable this value if you want to allow your customers to cancel their CONFIRMED orders by themselves from the order details page. When a customer cancels an order, the administrator, the employee and the customer will receive a notification e-mail.

Accept Cancellation Before
Restrict the order cancellation by setting a minimum number of days. In this way customers can cancel their orders only X days in advance.

Printable Orders
When this option is enabled, customers will be able to print their orders from the order details view.

Auto Generate Invoice
Enable this option to automatically generate the Invoice of an order after a successful payment transaction. The customers can download the invoice PDF file from the order details view.

Notice: even if this setting is disabled, customers will be able to download the invoice from the order details view (only if the pdf has already been generated from the administrator).


Waiting List

Enable Waiting List
Enable this option if you want to allow customers to register into a waiting list of a certain service and with a certain employee. If you don't want to use the waiting list features, you can skip the following parameters.

E-Mail Template
You can change the HTML content of the e-mail of the waiting list notification for the customers by clicking on the "Edit" button near the dropdown. It is possible to use only one template per time. You can save the template as copy to don't lose the original code. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/

Every time a customer cancels an appointment, all the customers registered for that service and/or employee, will receive a notification e-mail about one or more free slots.

SMS Content
You can change the plain text content of the SMS of the waiting list notification for the customers from the apposite textarea. It is possible to specify a different text for each language in your system and also for single orders (the cancellation affected a single service) and multiple order (the cancellation affected multiple services).

Every time a customer cancels an appointment, all the customers registered for that service and/or employee, will receive a notification SMS about one or more new free slots.


Recurring Appointments

Enable Recurrence
Enable this option if you want to allow customers to book an appointment with recurrence through an apposite form. If you don't want to use the recurrence, you can skip the following parameters.

This feature can work only when the cart setting is enabled.

Repeat Every
The appointments can be repeated every day, week or month. From this setting you can set the available values to insert in the first dropdown of the form.

For the next
The appointments can be repeated for the next TOT days, weeks or months. From this setting you can set the available values to insert in the third dropdown of the form.

Min. Amount
The minimum amount to use for the setting "For the next". It will be the minimum selectable value in the second dropdown.

Max. Amount
The maximum amount to use for the setting "For the next". It will be the maximum selectable value in the second dropdown.

By changing something from these parameters you will see a preview of the recurrence form displayed in the front-end.


Reviews

Enable Reviews
Enable this option if you want to use the reviews framework. If you disable this option you can skip the following parameters.

Services Reviews
Enable this option if you want to receive reviews for your services.

Employees Reviews
Enable this option if you want to receive reviews for your employees.

Comment Required
Enable this option if you want to force your customers to submit reviews with comments. Otherwise only the rating and the title will be required.

Comment Min. Length
The minimum characters allowed for the comments of the reviews during the submission.

Comment Max. Length
The maximum characters allowed for the comments of the reviews during the submission.

List Limit
The maximum number of reviews to display in the list.

Reviews Load Mode
When the total number of reviews exceeds the list limit, it will be used one of the following ways to load the next reviews: on scroll down (when the page scroll reaches the last loaded review) or on button press (when customers click on the load button below the last loaded review).

New Auto-Published
Disable this option if you want to approve manually the reviews from the back-end.

Filter By Language
When this option is enabled, a review will be displayed only if its language tag is the same of the language selected from the customer.


Packages

Enable Packages
Enable this option if you want to sell packages on your system. If you don't want to use the packages, you can skip the following parameters.

Packages per Row
The number of packages to display in a single row of your marketplace. It i possible to display 1, 2, 3, 4, 5 or 6 packages per row.

Max Packages in Cart
The maximum number of packages that can be purchased in a single order. If you don't want to limit this feature, you have just to select the Unlimited option from the dropdown.

Allow User Registration
Enable this setting to allow customers to create a new account directly from the confirmation page during the purchase. If this setting is disabled, customers will be able to register an account only through the Login Joomla module or from the back-end.

E-Mail Template
You can change the HTML content of the e-mail of the packages purchase for the customers the employees and the administrators by clicking on the "Edit" button near the dropdown. It is possible to use only one template per time. You can save the template as copy to don't lose the original code. The e-mail template files are located in the folder /components/com_vikappointments/helpers/mail_tmpls/


Employees Listings

Employees Listing Mode
The first published type of ordering found in the list of this setting will be used as default ordering for the employees list page. These are the possible types of ordering: Alphabetically a..Z (ascending), Alphabetically Z..a (descending), Newest Employees (descending creation), Oldest Employees (ascending creation), Most Popular (descending number of confirmed appointments) and Highest Rating (descending average value of the reviews).

You can change the ordering of this options by dragging the 3-dots icon. You can disable an option by selecting the "NO" value from the dropdown.

In the front-end, the ordering can be changed from the apposite "Ordering Filter" tool.

List Limit
Set the maximum number of employees to display in the employees list page. When the number of total employees exceeds this value, it will be used a pagination.

Description Length
The maximum number of characters of the employees description to display in the employees list page.

Image Link Action
Define the action to perform when customers click on the image of the employees. by clicking on the image customers can enter directly on the details of the employee or can see a popup with the original image.

Enable Groups Filter
Disable this option if you are not categorizing your employees or if you don't want to allow your customers to filter them by group.

Enable Ordering Filter
Disable this option if don't want to allow customers to change the default ordering of the employees. When this option is disabled, the default ordering used will be the first published value found in the Employees Listing Mode setting.


Services Listings

Description Length
The maximum number of characters of the services description to display in the services list page.

Image Link Action
Define the action to perform when customers click on the image of the services. by clicking on the image customers can enter directly on the details of the service or can see a popup with the original image. It is also possible to display the description of the service by hovering the mouse on the image. In this case, the image cannot be clicked.


Employees

The employees configuration is used to define the actions the employees can perform in the Employees Area page in the front-end.

This section of the configuration is required if you want to build a portal of employees.

Registration

Enable Employee SignUp
Enable this option if you want to allow new users to create a new employee account through the Employees Area page. This option should be disabled if your website doesn't host a portal of employees.

Default Status
The status of the account after the registration. The possible values are: PENDING (the employee must be approved from the back-end or need to purchase a subscription) or CONFIRMED (the employee is ready to work on your website).

Default User Group
The user group of the Joomla user account assigned to the employee after the registration (Author by default).

Services Auto-Assignment
In this field you can insert one or more services so that employees will have them already assigned to their accounts.


Authorise

Create Services
Enable this option if you want to allow the employees to create new services in the Employees Area.

Max Number of Services
The maximum number of services that an employee can host. This value won't be considered when employees are not allowed to create services.

Manage Services
Enable this option if you want to allow the employees to edit their services in the Employees Area. The default price, duration and sleep time of the service will never change.

Manage Services Overrides
Enable this option if you want to allow the employees to update only the price, the duration and the sleep time of their services in the Employees Area. This option is selectable only when the employees are not able to manage their services.

Remove Services
Enable this option if you want to allow the employees to remove their services in the Employees Area.

Manage Profile
Enable this option if you want to allow the employees to change their details.

Manage Working Days
Enable this option if you want to allow the employees to create and remove their working days and closing days.

Manage Coupons
Enable this option if you want to allow the employees to manage their coupons. A coupon created from the Employees Area will be available only for the services of its owner.

Manage Payments
Enable this option if you want to allow the employees to use customized payment processors to receive money directly on their accounts.

Manage Custom Fields
Enable this option if you want to allow the employees to manage their custom fields. The custom fields of an employee will be used with the global custom fields. This fields are selectable only when the customer is going to purchase an appointment with that employee.

Manage Locations
Enable this option if you want to allow the employees to create, edit and remove their locations.


Reservations

Create
Enable this option if you want to allow the employees to create new reservations in the Employees Area.

Manage
Enable this option if you want to allow the employees to edit their existing reservations in the Employees Area.

Remove
Enable this option if you want to allow the employees to remove their existing reservations in the Employees Area.

Notify Admin
Enable this option if you want to send a notification e-mail to the administrator(s) every time an employee removes a reservation. This option can be selected only when the employees can remove reservations.


Closing Days

Define the days in which your Company is closed. These dates won't be available for the creation of new reservations and they will affect all the working days of the employees. You can define, in example, to close your company every Monday, on Christmas, the first day of all months and so on.

A closing day can be defined as Single Day or can be repeated Weekly, Monthly or Yearly.


Closing Periods

Define the periods in which your Company is closed. These dates won't be available for the creation of new reservations and they will affect all the working days of the employees. You can define, in example, to close your company the whole month of August, the first week of January and so on.

A closing period must be defined within a range of 2 dates.


SMS APIs

The SMS APIs configuration is used to configure the APIs settings of your provider to be able to send SMS manually and/or automatically through your system.

SMS API File
Select the .php file of the SMS provider you want to use. When you change a file will be loaded some parameters to set up the gateway. All the loaded parameters should be filled in.

Enable Auto-Send
Enable this option if you want to send automatically a SMS when an appointment becomes CONFIRMED. You can also send SMS manually from the reservations and customers pages in the administrator.

Send SMS to
The program can send automatically the SMS to the customer and/or to the administrator and/or to the employee of the appointment.

Phone Number
Specify here the phone number of the administrator to receive the SMS. Remember to include the phone prefix before the phone number (like +1).


SMS Customer Template

From this form you can compose the content of the SMS to send to the customers. If you want to insert some details about the appointment you can click on the buttons above the textarea (it will be inserted a code which will be replaced with the relative value of the appointment).

It is possible to create a content for the SMS relative to the orders with multiple appointments and for orders with single appointments. The orders with multiple appointments shouldn't contain {service}, {employee} and {checkin} codes. To switch the content of the sms you have to press the button on the left side below the textarea.

All the SMS contents can be translated in different languages by clicking on the apposite language buttons on the right side below the textarea. These buttons will be available only when the "Multilanguage" option is enabled. The available languages will be retrieved from the Language Manager of your Joomla.


SMS Administrator Template

From this form you can compose the content of the SMS to send to the administrator and to the employees. If you want to insert some details about the appointment you can click on the buttons above the textarea (it will be inserted a code which will be replaced with the relative value of the appointment).

It is possible to create a content for the SMS relative to the orders with multiple appointments and for orders with single appointments. The orders with multiple appointments shouldn't contain {service}, {employee} and {checkin} codes. To switch the content of the sms you have to press the button on the left side below the textarea.


Cron Jobs

In the cron job configuration of the program is possible to setup the automated processes of VikAppointments which have to be executed periodically.

Settings

Secure Key
Specify a secure key to make sure someone else won't be able to execute the cron jobs manually. When you change this secure key, the code of all the running cron jobs files must be updated.

It is suggested to specify a secure key (or to leave the random generated one) only once, before the installation of the cron job files.

Register Log
It is possible to register the log of the cron jobs always or only in case of errors.
The logs are accessible from the Logs section into the list of the Cron Jobs.

Installed Cron
Click on the See Cron Jobs List button to see the list of the installed cron jobs and also to manage them.


Installation

To configure properly a cron job you have to follow the instructions below:

  • 1. Create a cron job from the "Cron Jobs List" in the settings tab.
  • 2. Pick the right cron job from the apposite dropdown and click on the "cron_runnable.php" link.
  • 3. Rename the downloaded file with a unique name. The name of the file should be a short description of the cron job used, like sms_reminder_2_hours_cronjob.php.
  • 4. Upload the downloaded file into the root of your server and make sure you are not overwriting an existing file.
  • 5. Identify the absolute path of the root of your server to specify the source location of the script to execute. You can identify this path from the configuration of your Joomla, by clicking on the System Tab, where is located the "Path to Log Folder". The root should look like /www/home/e4j.com/html/.
  • 6. Create a new cron job from the control panel of your server and assign the downloaded file as script, like /www/home/e4j.com/html/sms_reminder_2_hours_cronjob.php.

The steps to create a Cron Job are strictly related to the control panel of your hosting provider and may not match the steps above.

If you have no idea how to create a new cron job from your control panel, you should contact your hosting provider.

Development APIs

Here you can understand how to integrate a customized payment gateway or a SMS provider for VikAppointments.

How to develop a payment processor

The payment framework of VikAppointments can be extended by creating a PHP file declaring the VikAppointmentsPayment class.
The created file must be placed via FTP onto the directory: /administrator/components/com_vikappointments/payments/
In order to develop the class VikAppointmentsPayment please follow the code example below.

<?php

defined('_JEXEC') OR die('Restricted Area');

class VikAppointmentsPayment {
	
	private $order_info;
	private $params;
	
	public static function getAdminParameters() {
		return array();
	}
	
	public function __construct($order, $params=array()) {
		$this->order_info = $order;
		$this->params = $params;
	}
	
	public function showPayment() {
		/** See the code below to build this method */
	}
	
	public function validatePayment() {
		/** See the code below to build this method */
		return array();

	}

	public function afterValidation($esit = 0) {
		/** See the code below to build this method */
	}
}
?>
Parameters Building

The parameters form for the administrator section can be built through the getAdminParameters() static method. This is useful to fill in private data or credentials, required for the creation and the validation of the payment/transaction. A Merchant ID and a Signature Key are an example of parameters that should be visible as well as editable in the back-end.
The parameters of the form are returned as an array with the following structure:

[
	"param_1" : [
		"label" : "Label 1",
		"type" 	: "text",
	],
	"param_2" : [
		"label" : "Label 2",
		"type" 	: "select",
	],
]
  • param_1 - is one key of the array that must be unique (required).
    It represents the name of the parameter to use.

  • label - indicates the text to assign for the parameter in the administrator section (optional).
    By placing a double slash (//) after the label, the text after will be displayed as a tip next to the field of the parameter (like "Merchant ID//this is a tip to display...").
  • type - is used to render the right type of input field in the administrator section (required).
    The values allowed for the type are the followings: custom, select, text.
  • html - will be used only when the type of the parameter is custom (optional).
  • options - is an array containing all the possible values to use in the dropdown (required only when the type is select).
public static function getAdminParameters() {
	$logo_img = JURI::root().'administrator/components/com_vikappointments/payments/mypay/mypay-logo.jpg';
	return array(	
		'logo' => array(
			'label' => '',
			'type' => 'custom',
			'html' => '<img src="'.$logo_img.'"/>'
		),
		'merchantid' => array(
			'label' => 'Merchant ID',
			'type' => 'text'
		),
		'testmode' => array(
			'label' => 'Test Mode',
			'type' => 'select',
			'options' => array('Yes', 'No'),
		),
	);
}

The code above will generate a parameters form in the administrator section as follows.
Vik Appointments - payment processor
If your form doesn't come up, probably there is a syntax error on your file.
When you fill in the admin form, the parameters are stored in the array $params and you are able to get the values with the instructions below:

$merchant_id = $this->params['merchantid']; /* returns "539264823539" */
$test = $this->params['testmode']; /* returns "Yes" */
Order Info Object

The $order_info object is a mapped key/val array with the order information needed to complete the payment process. You can see below all the available keys of the array.

ParamTypeDescription
oid integer Is the unique ID of the reservation.
sid alphanumeric(16) Is the Order Key of the reservation.
transaction_currency char(3) The currency of the amount (3-letter ISO 4217 code). The default is EUR.
return_url string The return url to come back to your shop from the bank on successful transactions.
error_url string The error url to come back to your shop from the bank on failed transactions.
notify_url string The notification url to validate the transaction data sent from the bank. This URL invokes the validatePayment method of your gateway.
total_to_pay decimal The total amount to pay as decimal (ex. 135.50).
details array The customer details stored in the order. The available fields are purchaser_mail, purchaser_phone, purchaser_nominative.

You can retrieve the information of the $order_info array with the example below.

$uniq_id = $this->order_info['oid']."-".$this->order_info['sid'];
Show Payment

The method showPayment() of the object VikAppointmentsPayment is invoked every time a user visits the page of a reservation with PENDING Status. Here you need to echo the HTML form that points to the payment creation url of your bank gateway.
In this method it is possible also to make calls via cURL to retrieve tokens or to self submit the form to receive additional info to send to the bank.

public function showPayment() {
	
	$merchant_id = $this->params['merchantid'];
	
	$action_url = "https://yourbankgateway.com/";
	if( $this->params['testmode'] == 'Yes' ) {
		$action_url = "https://test.yourbankgateway.com/";
	}

	$form='<form action="'.$action_url.'" method="post">';
	// put here all the required fields of your gateway
	$form.='<input type="hidden" name="your_post_data_merchantid" value="'.$merchant_id.'"/>';
	$form.='<input type="hidden" name="your_post_data_amount" value="'.$this->order_info['total_to_pay'].'"/>';
	$form.='<input type="hidden" name="your_post_data_notifyurl" value="'.$this->order_info['notify_url'].'"/>';
	$form.='<input type="hidden" name="your_post_data_description" value="'.$this->order_info['transaction_name'].'"/>';
	// print a button to submit the payment form
	$form.='<input type="submit" name="_submit" value="Pay Now!" />';
	$form.='</form>';
	
	echo $form;

}
Validate Payment

The validatePayment() method is used to validate the transaction details sent from the bank. This method is invoked by the system every time the Notify URL is visited (the one described in the showPayment() method). Usually data are sent via POST method, and you can access them by simply using the $_POST super-global variable. Some gateways require a signature validation to make sure the transaction wasn't corrupted. The signature validation can be created only following the instructions on the official documentation of your bank.

This method must return a key/value array with the status of the transaction. The possible keys of the array are the followings.

ParamTypeDescription
verified boolean The status of the transaction. 1/true in case of success, otherwise 0/false.
tot_paid decimal The real amount paid from the customer (ex, 102.75).
log string A log message sent to the administrator in case of transaction failed. The log can contain any value returned from the Bank and it should be as specific as possible.

You can pass any other value in the array, but they will be completely ignored during the validation of the transaction.

public function validatePayment() {
	$array_result = array();
	$array_result['verified'] = 0;
	$array_result['tot_paid'] = ''; /** This value will be stored in the DB */
	
	/** In case of error the log will be sent via email to the admin */
	
	$status = $_POST['status'];
	/** Process your gateway response here */
	if($status == 'success') {
		$array_result['verified'] = 1;
		/** Set a value for $array_result['tot_paid'] */
		$array_result['tot_paid'] = $_POST['amount'];
	} else {
		$array_result['log'] = "Transaction Error!\n".$_POST['error_msg'];
	}
	
	/** Return the array to VikAppointments */
	return $array_result;
}
After Validation

The afterValidation($esit) method is generally used to display a message and to redirect the gateway to the order summary view in case of success or failure. Notice that this method should be in your Class only in case the Bank Gateway will not redirect the user to the ReturnURL. Also, this method, if exists in the Class, will be invoked by the system after the validatePayment(). The $esit argument is a boolean value that represents the status of the transaction. In case of success (1/true) you should print a positive message and redirect the gateway to the return_url address, otherwise (0/false) you should print an error message and redirect the gateway to the error_url address. Remember also to put an exit or die rule at the end of the method to completely stop the flow.

public function afterValidation($esit = 0) {
	
	$mainframe = JFactory::getApplication();
	
	if($esit < 1) {
		JError::raiseWarning('', 'The payment was not verified, please try again.');
		$mainframe->redirect($this->order_info['error_url']);
	} else {
		$mainframe->enqueueMessage('Thank you! The payment was verified successfully.');
		$mainframe->redirect($this->order_info['return_url']);
	}
	
	exit;
	//
}

You can get HERE the complete code of this example gateway.

How to develop a SMS gateway

 

The SMS gateways for VikAppointments can be extended by creating a PHP file containing the VikSmsApi class.
The created file have to be placed via FTP in the directory: /administrator/components/com_vikappointments/smsapi/
To develop the class VikSmsApi you need to follow the code below.

<?php

defined('_JEXEC') OR die('Restricted Area');

class VikSmsApi {
	
	private $order_info;
	private $params;
	private $log = '';
	
	public static function getAdminParameters() {
		return array();
	}
	
	public function __construct($order, $params=array()) {
		$this->order_info=$order;
		$this->params = ( !empty($params) ) ? $params : $this->params;
	}

	public function sendMessage( $phone_number, $msg_text ) {
		/** See the code below to build this method */
		return new stdClass;
	}
	
	public function estimate( $phone_number, $msg_text ) {
		/** See the code below to build this method */
		return new stdClass;
	}
	
	public function validateResponse($response_obj) {
		/** See the code below to build this method */
		return true;
	}
	
	public function getLog() {
		return $this->log;
	}
		
}


?>
Parameters Building

The parameters form for the administrator can be built through the getAdminParameters() static method, to fill in private data required to the creation and validation of the payment, like API Key and API Secret.
The parameters of the form are returned as an array with the following structure:

[
	"param_1" : [
		"label" : "Label 1",
		"type" 	: "text",
	],
	"param_2" : [
		"label" : "Label 2",
		"type" 	: "select",
	],
]
  • param_1 is the key of the array and have to be unique (required).
    It represents the name of the parameter to use.

  • label indicates the text to assign for the parameter in the administrator section (optional).
    By placing a double slash (//) after the label, the next text will be displayed as a tip near the field of the parameter (like "Sender//max 11 characters").
  • type is used to render the right type of input in the administrator section (required).
    The assumed value can be only one of the followings: custom, select, text.
  • html will be used only when the type of the parameter is custom (optional).
  • options is an array containing all the possible values to use in the dropdown (required only when the type is select).
public static function getAdminParameters() {
	return array(	
		'apikey' => array(
			'label' => 'API Key',
			'type' => 'text'
		),
			
		'apisecret' => array(
			'label' => 'API Secret',
			'type' => 'text'
		),
		
		'sender' => array(
			'label' => 'Sender Name//max 11 characters',
			'type' => 'text'
		),
		
		'sandbox' => array(
			'label' => 'Sandbox',
			'type' => 'select',
			'options' => array('NO', 'YES')
		)
	);
}

The code above will generate a parameters form in the administrator section as follows.

If your form doesn't come up, probably there is a syntax error on your file.
When you fill in the admin form, the parameters are stored in the array $params and you are able to get the values with the instructions below:

$api_key = $this->params['apikey']; /* returns "TS8KJSGV20E7SG2K" */
$api_secret = $this->params['apisecret']; /* returns "ks03bsoaqsdlew83hdswlsn2ie7d2hndmwq" */
$sender_name = $this->params['sender']; /* returns "e4j.com" */
$sandbox = $this->params['sandbox']; /* returns "NO" */
Send Message

The method sendMessage($phone_number, $msg_text) of the object VikSmsApi is invoked every time an order becomes CONFIRMED, like after a payment. Here you have to post the details of your account, the phone number of the customer and the message to send through the gateway of your provider. Generally you need to post these fields via cURL to a certain end-point provided from your gateway.

The sendMessage function requires 2 arguments:

  • $phone_number - (string) the phone number of the customer. This value have to be validate before to send the message, because it could not contain the prefix or could contain unrecognized characters (like @ or / and so on) 
  • $msg_text - (string) the full text to send to the customer. A lot of providers allow to send only 160 characters per message, so you should consider this limitation.

The code below is only an example how it should work a cURL connection to the gateway of the provider.

public function sendMessage($phone_number, $msg_text) {
	$phone_number = $this->sanitizePhoneNumber($phone_number);
	
	if( $this->params['sandbox'] == "NO" ) {
		$this->params['sandbox'] = 0;
	} else {
		$this->params['sandbox'] = 1;
	}
	
	$request = array(
		"apikey" => $this->params['apikey'],
		"apisecret" => $this->params['apisecret'],
		"from" => $this->params['sender'],
		"to" => $phone_number,
		"msg" => $msg_text,
		"sandbox" => $this->params['sandbox']
	);
	
	$json = json_encode($request);

	$curl_opts = array(
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => $json,
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_HTTPHEADER => array(
                        'Accept: application/json',
                        'Content-Type: application/json;charset=UTF-8',
                        'Content-Length: '.strlen($json)
                ),
                CURLOPT_VERBOSE => true,
        );
 
	$ch = curl_init('https://secure.sms.fakeprovider.com/send');
	curl_setopt_array($ch, $curl_opts);
	$response = curl_exec($ch);

	return json_decode($response);
}
Sanitize Phone Number

The sanitizePhoneNumber function used above is not a native function of the VikSmsApi class, so you have to write this method on your code.

Here you can find a simple code to sanitize a phone number.

protected function sanitizePhoneNumber($phone_number) {
	$str = '';
	for( $i = 0; $i < strlen($phone_number); $i++ ) {
		if( ($phone_number[$i] >= '0' && $phone_number[$i] <= '9') || $phone_number[$i] == '+' ) {
			$str .= $phone_number[$i]; // copy only numbers and plus character
		}
	}
	
	$default_prefix = '+1'; // US, Canada phone prefix
	
	if( $phone_number[0] != '+' ) { 
		// $phone_number doesn't contain the phone prefix 
		$str = $default_prefix.$str;
	}
	
	return $str;
}
Validate Response

The validateResponse($response_obj) method is used to validate the object returned from the gateway during the sending of the message. Some gateways return an object containing a short error message and the http status code.

{
	"httpcode" : 200,
	"errmsg" : "",
}
{
	"httpcode" : 401,
	"errmsg" : "BAD_CREDENTIALS",
}
{
	"httpcode" : 402,
	"errmsg" : "BAD_CREDIT",
}

While, sometimes, the object returned is a simple boolean value (true/false).

In this method you have to return only a boolean value to communicate to the program the status of the message. With TRUE status, nothing will be notified, otherwise an error e-mail will be sent to the administrator containing the text in the $log attribute.

public function validateResponse($response_obj) {
	if( $response_obj->httpcode == 200 ) {
		return true;
	}
	$this->log .= $response_obj->errmsg;
	return false;
}
Estimate Credit

The estimate($phone_number, $msg_text) is an optional method used to retrieve the remaining credit from the back-end of the program. A lot of providers don't have an API call to retrieve the credit of a certain account, so you can decide to skip this method.
$phone_number and $msg_text are only used as example from the gateway.

The returned value from this function have to be an object containing the errCode and userCredit attributes:

{
	"errCode" : 0, // no error
	"userCredit" : 85.47, // in decimals
}

Generally the estimate function is similar to the sendMessage function, but it makes a call to a different gateway of the provider.

public function estimate($phone_number, $msg_text) {
	$phone_number = $this->sanitizePhoneNumber($phone_number);
	
	$request = array(
		"apikey" => $this->params['apikey'],
		"apisecret" => $this->params['apisecret'],
		"from" => $this->params['sender'],
		"to" => $phone_number,
		"msg" => $msg_text,
	);
	
	$json = json_encode($request);

	$curl_opts = array(
		CURLOPT_POST => true,
		CURLOPT_POSTFIELDS => $json,
		CURLOPT_RETURNTRANSFER => true,
		CURLOPT_HTTPHEADER => array(
			'Accept: application/json',
			'Content-Type: application/json;charset=UTF-8',
			'Content-Length: '.strlen($json)
		),
		CURLOPT_VERBOSE => true,
	);
 
	$ch = curl_init('https://secure.sms.fakeprovider.com/estimate');
	curl_setopt_array($ch, $curl_opts);
	$response = curl_exec($ch);
	$response = json_decode($response);

	$fixedResponse = new stdClass;
	$fixedResponse->errCode = $response->httpcode; 
	$fixedResponse->userCredit = 0.0;
	if( $fixedResponse->errCode == 200 ) {
		$fixedResponse->errCode = 0;
		$fixedResponse->userCredit = $response->credit;
	}

	return $fixedResponse;
}

The code above will generate automatically a button in the configuration of the program to estimate the remaining credit.
Vik Appointments - estimate credit

You can get HERE the complete code of this example gateway.

Tutorials

Extensionsforjoomla.com is not affiliated with or endorsed by the Joomla! Project or Open Source Matters.
The Joomla! name and logo is used under a limited license granted by Open Source Matters the trademark holder in the United States and other countries.
e4j - Extensionsforjoomla.com - VAT N. 02196010975