Developer Training:: Vinyl Advanced Training Manual

Developer Training:
Vinyl Advanced Training Manual
1
© 2018 Zudy Software - All material and information contained within this site confidential and proprietary.
No distribution, copying, or dissemination of the contents is allowed without prior written permission.
Last Modified 9/28/2018
ADVANCED VINYL 2.3
Table of Contents
Introduction .................................................................................................................................................. 5
What is Vinyl? ........................................................................................................................................... 5
Course Objective ....................................................................................................................................... 5
Vinyl Layers ................................................................................................................................................... 5
Data Storage Layer ................................................................................................................................ 5
Business Logic Layer .............................................................................................................................. 5
UI Layer ................................................................................................................................................. 5
Northwind Data Structure ........................................................................................................................ 6
Data Storage Layer ........................................................................................................................................ 7
Logical Data Types for Table Columns ...................................................................................................... 7
Unique ID .............................................................................................................................................. 7
String ..................................................................................................................................................... 8
Date, Date/Time, Time .......................................................................................................................... 9
Photo ................................................................................................................................................... 10
File ....................................................................................................................................................... 11
Number, Percent ................................................................................................................................. 11
Phone .................................................................................................................................................. 12
Currency .............................................................................................................................................. 13
Boolean ............................................................................................................................................... 13
Email.................................................................................................................................................... 14
Percent ................................................................................................................................................ 15
URL ...................................................................................................................................................... 15
Insert, Update and Delete....................................................................................................................... 16
Chapter Exercise: Modify the Product Table .......................................................................................... 17
Default Values ......................................................................................................................................... 17
Chapter Exercise: Set a Default on the Product Table ............................................................................ 18
Usage....................................................................................................................................................... 18
Other Common Usage Types .............................................................................................................. 19
Relationships ........................................................................................................................................... 19
Chapter Exercise: Create a Relationship on the Supplier Table.............................................................. 21
Relationships: Cascade............................................................................................................................ 21
Joins ............................................................................................................................................................ 22
2
ADVANCED VINYL 2.3
Union Joins .............................................................................................................................................. 23

CRUD ........................................................................................................................................................... 25
CRUD Update .......................................................................................................................................... 25
Chapter Exercise: Create a CRUD Update Rule ....................................................................................... 27
CRUD Delete............................................................................................................................................ 27
CRUD Rules with Events .......................................................................................................................... 27
Chapter Exercise: Create CRUDs and Custom Events ............................................................................. 30
Firing Events ............................................................................................................................................ 30
Chapter Exercise: CRUDs and Firing Events ............................................................................................ 32
Subquery Rules and CRUD Rules............................................................................................................. 32
Subqueries and CRUD Inserts ................................................................................................................. 33
Validations .................................................................................................................................................. 35
Chapter Exercise: Create a Validation..................................................................................................... 36
Validation Rules and Events .................................................................................................................... 36
Chapter Exercise: Attach a Validation Rule to an Event ......................................................................... 37
UI Layer ....................................................................................................................................................... 37
Board Panels ........................................................................................................................................... 37
Chart Panel .............................................................................................................................................. 39
Create a Business Object with an Aggregate Value ............................................................................ 39
Create a Chart ..................................................................................................................................... 40
Badging.................................................................................................................................................... 40
Reach....................................................................................................................................................... 41
Update the Customer (Source) Business Object ................................................................................. 42
Add Region List Control to the Customer Page................................................................................... 42
Reach and Subqueries ......................................................................................................................... 43
Join the Reach Subquery to a Business Object ................................................................................... 44
Add User List Control to the Employee Page ...................................................................................... 45
Bridge .......................................................................................................................................................... 46
Message Types ........................................................................................................................................ 47
Options .................................................................................................................................................... 47
Configuration ...................................................................................................................................... 47
Data Object Event Binding .................................................................................................................. 48
Bridge Registration.................................................................................................................................. 48
3
ADVANCED VINYL 2.3
Linking to a Bridge............................................................................................................................... 48
Message Creation ............................................................................................................................... 48
Translations ............................................................................................................................................. 48
Limitations .............................................................................................................................................. 49
Example Bridge Setup ............................................................................................................................. 49
Link Data Sources ................................................................................................................................ 49
Create a Bridge.................................................................................................................................... 49
Steps to Create Bridge ........................................................................................................................ 49
Register Bridge with Application......................................................................................................... 50
Define Bridge Options ......................................................................................................................... 51
Register Bridge as an Action with an Event ........................................................................................ 51
Vinyl Beyond the Class ................................................................................................................................ 52
4
ADVANCED VINYL 2.3
Introduction
What is Vinyl?
Vinyl is the first No-Code Enterprise Application Development Platform. Vinyl allows you to
create beautiful yet powerful applications and charts from multiple data sources, including
complex analytics all together on the same screen without writing a single line of code. Vinyl
is database agnostic, meaning it can work with any database type, and a key benefit of using
Vinyl is that the application turnaround time is a few weeks vs. a few years.
Course Objective
This course covers some of the more advanced skills used to develop in Vinyl, as well as the
methodology used at Zudy to develop applications. In this course we will take a deeper look
at the Data Storage Layer and review Logical Data Types, Union Joins, CRUD Rules,
Subqueries, Validations, Board and Chart Panels, Badging and Reach.
Vinyl Layers
Thes e are the t hree layer s of Vinyl: Data Stor age Layer , Business Logic Layer and the UI Layer.
Blue, Red, and Green ar e used to visu ally i dentify the 3 differ ent l ayers of Vinyl.
Data Storage Layer

Contains all the tables where the physical data is stored.
Business Logic Layer

Used to expose your data as well as allow you to manipulate and filter data from the tables in
the Data Storage Layer.
UI Layer
Where you build the actual application and customize the User Interface.
5
ADVANCED VINYL 2.3
Northwind Data Structure

Here are the data tables and corresponding columns which have been included in the
application. The first column is the Primary Key (abbreviated as PK):
The Tables and Prim ary Key’s (PK’s) i n the Northwi nd s Traini ng Appl icatio n
6
ADVANCED VINYL 2.3
Data Storage Layer

To start off, we will take a deeper look at the Data Storage Layer in Vinyl. In this chapter we
will review different data storage types for Columns, assigning Columns a default value, and
configuring relationships between tables to improve the quality of data in the application.
Data Storage Layer Link
Logical Data Types for Table Columns

A database is typically a large collection of data that is organized for rapid search and
retrieval. A database is comprised of Tables, which are in turn made up of various Columns.
Columns store a set of data values of a particular type, one value for each row of the
database. A column may contain text values, numbers, or even pointers to files in the
operating system.
In Vinyl, we leverage Logical Data Types to define the different type of data being stored in
the Column which can then be expressed in a manner that is unique to its data type. Logical
Data Types define the data type for the Column, while Physical Data Types determine how
the data in the Column is stored in the Data Storage Layer.
Unique ID
The first Logical Data Type we’ll review is Unique ID, which is used to store a unique identifier
value. Unique ID’s are used to uniquely identify each row or record in a Table in a database.
Primary Keys are examples of Columns which use a Unique ID Logical Data Type.
To View a Unique ID
1. Click the Action Drawer and select Vinyl IDE
2. Select Build your application from the Build menu
3. Click the Data Storage Layer button
4. Locate your application data source, and click the Tables gear icon
5. Expand the Category Table
6. Click the pop-up icon to view the Category ID Column information
7. Note that the Logical Data Type is Unique ID, the Physical Data Type is UUID, and the
Column Name ends in ‘ID’ which follows Vinyl naming methodology
8. Close this window, click the Results button and confirm you see UUID values being
stored for the CategoryID column
7
ADVANCED VINYL 2.3
PK Settings avai lable for a Column
Looking at the Column definition screen in Vinyl, there is a PK Settings Control Set which
contains three options which define the Primary Key Settings:
❖ Primary Key - Boolean flag that defines if a field is a Primary Key for a Table. Checking
this option indicates the Column is a Primary Key for the Table its associated with.
❖ Auto Gen – Boolean flag that determines whether you want the field to automatically be
generated upon new record creation (e.g., fill in the Unique ID field). Checking this causes
the Column to autogenerate its value as new records are created.
❖ Allow Nulls – determines whether a new record can be created which does not contain
any data (potentially creates bad data). Checking this indicates that nulls are allowed for
this Column, and having an X appear here indicates nulls are not allowed for this Column.
Physical Data Types available for Unique ID

❖ Char – Character data of fixed length.
❖ UUID – Universally unique identifier. 128-bit number used to uniquely identify
information.
String
The next Column Logical Data Type we will review is String. String is probably the most
frequently used Logical Data Type in Vinyl. String allows you to store an array of data in a
sequence of elements, typically characters, symbols and numbers. Let’s review the Employee
Table FirstName Column to review String. Note that we have Allow Nulls ticked off because
we want all Employees to have a First Name value:
8
ADVANCED VINYL 2.3
The Employee Tabl e, FirstName Co lumn uses Str ing Logical Data Type
Physical Data Types available for String

❖ Char - Character data of fixed length
❖ Encrypted – Encrypted data
❖ NChar – UNICODE character data of fix length
❖ NVarchar – UNICODE character data of indeterminate length. Typically, all Vinyl Strings
are stored as NVarchar so they can support Unicode and take up less space.
❖ Varchar – Character data of indeterminate length
Date, Date/Time, Time

Date is the Logical Data Type used to store date information in a Column, complete with day,
month and year and formatted as MM/DD/YYYY. If you try and edit a field set as Date, you’ll
see a calendar pop-up which allows you to choose a new date value.
If you are also looking to capture and store Time information along with Dates, Vinyl has a
separate Date/Time Logical Data Type for that purpose. Similarly, if you are only looking to
store and present Time information, Vinyl has a Time Logical Data Type designed for that
purpose.
To review the Date Logical Data Type, we will review the Employee Table, BirthDate Column.
9
ADVANCED VINYL 2.3
The Employee Tabl e, Birt hDate Colum n uses Date as its Logical Data Type
Physical Data Types available for Date

❖ Date - Date only
❖ Decimal – 10^38 + 1 – 10^38 - 1
❖ Integer – Int - -2,147,483,648 – 2,147,483,647
Photo
The next Logical Data Type we’ll review is for Photo. You might recall from the Intro Course
that we used the Photo Column in conjunction with a File Control to allow users to upload
new files and download existing files. Let’s look at the Employee Table’s Photo Column to
review an example of the Photo Logical Data Type.
The Employee Tabl e ’s Photo Column is an exampl e of the Pho to Logical Data Type
10
ADVANCED VINYL 2.3
Physical Data Types available for Photo

❖ Binary - Binary data is the only category of data that can be directly understood and
executed by a computer. It is numerically represented by a combination of zeros and
ones.
File
The File Logical Data Type stores a file, either as a Binary or NVarchar Physical Data Type.
From the UI Layer, File is often used in conjunction with a Photo Control to provide an end
user the ability to upload new files and replace existing ones with a data record. In the
example we will review, File is used for the Employee table’s Photo Column so that we can
upload, store and make available for download an Employee’s photo.
The Employee Tabl e’s Photo Column is an exampl e of a File Logical Data Type
Physical Data Types available for File

❖ Binary - Binary data is the only category of data that can be directly understood and
executed by a computer. It is numerically represented by a combination of zeros and
ones.
❖ NVarchar - UNICODE character data of indeterminate length.
Number, Percent
The Number Logical Data Type stores numeric data, and has many different Physical Data
Types available. If you want to store, present, and run calculations off of numbers as Percent
values Vinyl has a separate Percent Logical Data Type available for this purpose.
We can review an example of the Number Logical Data Type by looking at the Product
table’s UnitsInStock Column:
11
ADVANCED VINYL 2.3
The Pro duct Tabl e’s Uni ts InStock Column is an example of the Number Logi cal Data Type
Physical Data Types available for Number

❖ Decimal - 10^38 + 1 – 10^38 – 1. Used to store a number with a large decimal value.
❖ Float - -1.79E + 308 through -2.23E -308. Used to store smaller decimal values.
❖ Integer – BigInt - -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
❖ Integer – Int - 2,147,483,648 – 2,147,483,648
❖ Integer – SmallInt - -32,768 to 32,767
❖ Integer – TinyInt – 0 to 255
❖ Real - -3.40E + 38 through -1.18E - 38
Phone
The Phone Logical Data Type supports storing Phone number data, along with proper
formatting. As the corresponding Physical Data Type for Phone is Varchar, we can use this
field for International phone numbers as well as the United States. In this example we will
look at the Employee table’s HomePhone Column to see an example of the Phone Logical
Data Type:
12
ADVANCED VINYL 2.3
The Employee t abl e ’s Ho mePhone column is an ex ampl e of the Pho ne Logic al Data Type
Physical Data Types available for Phone

Currency
The Currency Logical Data Type supports numeric values with decimal places, and should be
used to store currency values. This data type only has one Physical Data Type available, which
is Decimal. In the UI Layer, a Control that makes use of a Currency Column will display a ‘$’
symbol next to the numeric value, to identify it as currency. We can review an example of the
Currency Logical Data Type by looking at the Product table’s UnitPrice Column:
The Pro duct Tabl e’s Uni t Price Column is an exam ple of the Currency Logic al Data Type
Physical Data Types available for Currency

❖ Decimal - 10^38 + 1 – 10^38 – 1. Used when you want to store a number with a large
decimal value.
Boolean
Boolean is a Logical Data Type that can only store one of two possible values, intended to
represent the two truth values of logic and Boolean algebra. Boolean values in Vinyl are most
often stored as Bit Physical Data Types. In the example we’ll review, we will look at the
Product table’s Discontinued Column:
13
ADVANCED VINYL 2.3
The Pro duct Tabl e’s Disco ntinu ed Co lumn is an example of a Boolean Logic al Data Type
Physical Data Types available for Boolean

❖ Bit – stores data as 0 or 1, with 0 meaning False and 1 meaning True. This is typically the
option used when you want to represent a checkbox on the UI Layer, where unchecked
means False and checked means True.
❖ Char – If you store Boolean with Char, from the UI Layer you will see a list that has True
and False values on it, instead of a checkbox.
❖ Decimal - 10^38 + 1 – 10^38 – 1. Used when you want to store a number with a large
decimal value.
Email
The Email Logical Data Type should be used for Columns where you want to capture, store
and display Email Address information. It is important to use this Logical Data Type for Email
Addresses, as it will ensure proper formatting. In this example we will review the Employee
table’s Email Column:
14
ADVANCED VINYL 2.3
The Employee Tabl e’s Em ail column is an example of an Email Logic al Data Type
Physical Data Types available for Email

❖ Char - Character data of fixed length
❖ NChar – UNICODE character data of fix length
❖ NVarchar - UNICODE character data of indeterminate length
Percent
The Percent Logical Data Type is available for capturing, storing and displaying percentage
data.
URL
The URL Logical Data Type is available for capturing, storing and displaying a URL value (the
address of a World Wide Web page). It is used to ensure the proper formatting is available for
this type information.
15
ADVANCED VINYL 2.3
The S hipper t abl e ’s Webs ite column is an exam ple of a URL Logic al Data Type
Physical Data Types available for URL

❖ NVarchar - UNICODE character data of indeterminate length.
Insert, Update and Delete

In Vinyl, each Table and Column can individually support Inserting, Updating and/or Deleting
data. Insert refers to creating new records, Update refers to modifying existing records, and
Delete refers to removing or deleting a record. Collectively these options control how a
Table’s data can be manipulated through the Vinyl Layers, so it is an important concept for a
Developer to understand when configuring these options.
Tables and Columns can have Insert, Update and Delete functionality enabled or turned off.
The settings here, to reiterate, control the behavior throughout the Vinyl Layers including the
Application Layer. In this example we will walk through changing the supported functionality
for the Employee table.
1. Click the Action Drawer icon, and select Vinyl IDE

2. Click the Build your application button on the Build menu
4. Click the Tables gear icon for your data source
5. Expand the Employee table to view the Table Definition
6. Click on Edge Case Settings at the bottom of the table panel o n the left
16
ADVANCED VINYL 2.3
Edge Cas e Settings optio ns avai lable for a Tabl e
7. The CRUD Support Control Set contains three options:

a. Insertable – allows new records to be added to this table
b. Updatable – allows records on this table to be modified
c. Deletable – allows records from this table to be deleted
8. Check that Insertable, Updatable, and Deletable are all checked (enabled) for the
Employee table and Save
Chapter Exercise: Modify the Product Table

In our Northwinds data source, when a Product sells out or is no longer being sold we want it
to be flagged as Discontinued, rather than being deleted as a record from the Table. This
being the case, there technically should not be a reason to need to Delete from the Product
table. Following the steps we reviewed for the Employee table, go review the Product table.
Expand the Product table to view the Table Definition, and click into the Edge Case Settings.
From there uncheck the Deletable option in CRUD Support.
Default Values
Columns in Vinyl can be created with default values. This can be useful when you have a field
that is usually the same value, or if you want to lock a field into a certain value by combining
a default with no support for Inserting and Updating.
To review a Default Value example, we’ll assign the Country Column of the Employee table a
default value of USA since the majority of Northwinds employees are based in the United
States.

5. Expand the Employee table to view the Table Definition
6. Click the pop-up icon to expand the Country column
17
ADVANCED VINYL 2.3
7. Click the Edit button and enter the value USA in the Default Value field
The Defau lt Valu e fiel d is where yo u can set defau l t informatio n for Columns
8. Click the Save button

9. Click the Results button and then click the Create button, confirm that the Country
field gets defaulted to USA
Chapter Exercise: Set a Default on the Product Table

Following the steps we reviewed for the Employee table, go review the Product table. Set a
default on the UnitsInStock Column for the Product Table, so that the default value is zero (0).
Test your results after setting the default value.
Usage
All Columns in Vinyl have a Usage field, and the purpose of the Usage field is to flag that
Column for a specific role within the database and application. It is important to note that
not all Columns have Usage values defined, in fact most do not.
Title is the most common Usage value defined for Columns, and is used to flag a Column as a
List Title which means that it will be added to a List Business Object if the List button is used
to create a List object. You will receive an error message clicking the List button to create a
List object if you are trying to use it on a Table without a Title Column defined. To correct this
issue, simply defined one of the Columns as your Title and then click the List button again.
In this example, we’ll look at defining a Usage for the Category table.

5. Expand the Category table to view the Table Definition
18
ADVANCED VINYL 2.3
6. Determine which Column makes the most sense to be used as a Title. If we made a
list object out of the Category table, we would assign the Category Column a usage of
Title.
The C at egory Colum n has Usage defi ned as Title
7. Now if we create a List Business Object for Employee table, Category will be used as
the Title field
Other Common Usage Types

❖ Subtitle – A Column that is designated as Subtitle will also be added automatically to a
List Business Object, as well as a List that is created in the application.
❖ Added By/Added On – Columns with this designation will automatically be filled in with
either the Added By/Added On information upon record creation, without having to
make a Default Rule to do so.
❖ Changed By/Changed On – Columns with this designation will automatically be filled in
with a record of who or when a record was modified, without having to make a Default
Rule to do so.
Relationships
Relationships in Vinyl are most useful for data integrity, by preventing users from entering
bad data and creating orphaned records (data which no longer has context). When creating
relationships between two tables, one table becomes the parent and the other becomes the
child. Each relationship is bound by a Primary Key which is common to both tables. By
creating the relationship, you ensure that information entered in the child table will match
information in the parent.
For example, if the Order table were the parent of the OrderDetail table, then it would ensure
that neither a user nor a developer could enter order details for an order that doesn’t yet
exist. Relationships constrain the developers of the application as well because they are
defined at the Data Storage Layer.
19
ADVANCED VINYL 2.3
To illustrate how relationships in Vinyl work, we will be making a relationship between the
Order table and the OrderDetail table, so that nobody can add an OrderDetail with an
OrderID that doesn’t exist in the Order table. Application users would typically be restricted
from doing so simply because they can only add order details on an order page, but adding
this relationship ensures that nobody can do so.

5. Expand the Order table to view the Table Definition
The Table Defini tion screen wher e you

view Primar y Key inform ation as well as Table Rel ationshi ps
6. In the Constraints Control Set, the Keys icon allows you to view Primary Key
information for the table
7. The Relationships Control Set area is where you can view information about table
parent and child relationships
8. Click the One to Many arrow icon, and click the Create button
9. Set the Primary Table value to Order, and the Secondary Table to OrderDetail
10. Check that the Binding Keys information is populated with OrderID for both
Columns. Here the Primary Column represents the Primary Key of the parent table,
and the Secondary Column refers to the Foreign Key from the child table that points
to the Primary Key.
20
ADVANCED VINYL 2.3
The Rel atio nshi p between the Or der parent and OrderDetail c hil d tables
With this relationship configured, it will be impossible to add to the OrderDetails table if
an order does not exist. This should already be impossible to do through the application’s
UI, but now it will also be impossible for a developer to make the same mistake or
accidentally allow users to do so.
Table Relationship Terminology

❖ Primary Table – the table which contains the Primary Key for the relationship
❖ Secondary Table – the table which contains the Foreign Key for the relationship
❖ Primary Columns – the Column in the Parent Table that is the Primary Key that will be
used to bind the relationship
❖ Secondary Columns – the Column in the Child Table that is the Foreign Key that points
to the Primary Column
Chapter Exercise: Create a Relationship on the Supplier Table

Following the steps we walked through with the Order and Order Detail table, create a
relationship where the Product table is the child of the Supplier table.
Relationships: Cascade
After you create a relationship you can change its On Delete and On Update options, which
cause certain behaviors when data is changed on the parent table. The On Update options
ensure that information that is updated in the parent table is reflected in the child table, and
On Delete ensures that data with no context (orphaned data) does not remain in the tables.
Both On Delete and On Update can either be set to Cascade, Null or Default, but we will only
review Cascade in this manual. Cascade means that child data will be updated at the same
time as its parent data.
To help illustrate how cascade works with relationships, we’ll configure a relationship
between the Order table and the OrderDetail table that is set to On Delete Cascade. Doing
21
ADVANCED VINYL 2.3
this will ensure that deleting an order will delete its order details as well. It is important to
note that selecting the correct parent to child relationship is critical to success. If we chose
the parent as OrderDetail in this example, deleting the details of an order would delete the
order itself. To create this relationship:

5. Expand the Order table to view the Table Definition
6. Click the One to Many arrow icon
7. Expand the Order relationship (created in the Relationships section of this manual)
8. Click the Edit button
9. Set On Delete to Cascade, which will cause a deleted order to cascade down and
delete any associated order details
Here w e added Cascade On Del ete to the Order to OrderDetail table Rel ati onship
10. Click Save
Joins
Up until this point we have spent a good amount of time in the Data Storage Layer. For the
rest of this training manual we will focus on the Business Logic Layer and the UI Layer. Up
next we will look at the Business Logic Layer, and review how SQL Union Joins work in Vinyl.
22
ADVANCED VINYL 2.3
Union Joins
In Vinyl, SQL Union Joins produce a combination of two select statements which target the
same Column. A Union Join combines the results of two different Columns (that have the
same name) from two different Tables into one unified Column. While most Joins utilize a
join column, the Union Join does not. This is because other Joins require shared context
between the two tables to function, but a Union Join only requires shared columns.
For example, an Inner Join between the Product and Supplier tables would show every
Product along with their Supplier, while a Union Join between Product and Supplier tables
would show you a list of all the different SupplierID fields. This is because the Union Join
essentially shows all the results from the same column in two different tables, and these two
tables only share the SupplierID. Remember with Joins that sharing context and having the
same Column are two different criteria.
Let’s review creating a Union Join to find all the countries that exist in the Northwinds data
source. The Union Join will allow us to take all the country fields from any table with country
data and combine them to make a collection of every country that belongs to each record:

3. Click the Business Logic Layer button
4. Click the BOBJ icon for your data source
5. Click the Create button under Rules
6. Assign the Name Supplier (Countries for Supplier and Customer)
7. Select the Purpose as Business Object
8. Set the Target to Supplier
The U nion Join Ru le Nam e, Purpos e and Targ et

10. Click the SQL gears icon
11. Add the Supplier and Customer Tables in the Tables panel. In the Northwinds data
source, these are the only tables containing country data.
12. In the Joins panel, click the Create button and set Left to S (for Supplier), Type to
Union, and Right to C (for Customer). Click the checkmark to save.
13. In the Columns panel click Create and add the Country column and assign no Target.
Click the checkmark to save.
23
ADVANCED VINYL 2.3
The Business SQL for the Union Join between Su pplier and Custom er tables
14. Click back to view details on this Rule and click the Edge Case Settings link
View Det ails inform ation o n the U nion Join Ru le
15. Click the Edit button and place a check in Select Distinct. We do this step in order to
not return duplicate values.
24
ADVANCED VINYL 2.3
Edge Cas e Settings for the Union Join Rule
16. Click Save, and click the X to close the Edge Case Settings window
17. Click the Results button to verify the results of the Business Object. This is the
completed Union Join, and it will list all countries appearing in both the Supplier and
Customer tables.
CRUD
One of the most important Business Object Rules in Vinyl is the CRUD Rule. CRUD stands for
Create, Read, Update, Delete. As a Vinyl developer you could not build a modern, intuitive
application without CRUD Rules. CRUD Rules are used to either insert, update or delete
records in a table. There are three different types of CRUD Rules in Vinyl:
❖ CRUD – used when you want to CRUD between two different databases
❖ CRUD Business Logic - will check and perform the different validations/actions as the
CRUD is executed
❖ CRUD XP – XP means cross platform and allows you to CRUD into different data sources
the application is linked to
CRUD Update
The first CRUD Rule to review is a CRUD Update, which has the action type Update and can
adjust existing records in a table. A CRUD Update can update an entire table’s records based
on a defined formula. It does this by adding numeric quantities or expressions against a
record, as well as changing a text entry from any existing value to a specified value.
In this chapter we will build a CRUD Rule since we want the Rule to run against the entire
database. The CRUD Rule we create will add 1 to the Quantity value.

25
ADVANCED VINYL 2.3
6. Assign the Name OrderDetail (Quantity +1), which follows Vinyl naming conventions
7. Set the Purpose value to CRUD
8. Set the Action to Update
9. Set and the Target to the OrderDetail table
11. Click the SQL icon to define the logic for the CRUD Update
12. Confirm the OrderDetail table appears in the Tables panel
13. Click the PK button to add in the Primary Keys as Columns
14. Click Create in the Columns panel and enter the expression Quantity+1, assign the
Alias as QuantityPlus, and Target as Quantity
The Business SQL for the CRUD Update Rul e
15. Although it is not necessary for the CRUD Update to function as expected, we will add
in the Quantity Column so we see that this works through the Results generated.
Click the Create button in Columns, and add in Quantity.
16. Click on the Results button, and confirm that the QuantityPlus column is adding 1 to
the Quantity column value.
The Resul ts of the CRU D Update Rule

26
ADVANCED VINYL 2.3
Chapter Exercise: Create a CRUD Update Rule

Following the steps we walked through to create a CRUD Update Rule, create a new CRUD
Update Rule with the purpose of it subtracting 1 from the OrderDetail table Quantity value.
CRUD Delete
In Vinyl, a CRUD Delete Rule is used to delete records from a table. Like other CRUD Rules,
they can be tied to a Control (like a button) to add functionality to an application. Since a user
can easily delete single records from the UI already, CRUD Delete Rules are mainly used to
delete many records at a time.
In this example, we will create a CRUD Delete Rule that will be applied to a button on the
Order panel of the Order page. The CRUD Delete Rule will delete all the Order Details
associated with an Order, as opposed to having a user delete each Order Detail record
manually one at a time.

6. Assign the Name OrderDetail (Delete OrderDetail for Order)
7. Assign the Purpose as CRUD
8. Select the Action Delete
9. Set the Target as the OrderDetail table
11. Click the SQL gears icon to define the Business SQL. Confirm that the OrderDetail
table has been added to the Tables panel.
12. Click the Create button in the Columns panel and add the OrderID column, and
Target OrderID. It is important to target the OrderID here, as you are stating that you
only want OrderDetail records with a specific OrderID value. Without this target you
would delete all OrderDetail records for all orders.
CRUD Rules with Events

In order for CRUD Rules to be used by the Application Layer, they must be attached to
Events. In Vinyl, Events are processes built into tables or Business Objects that get executed
in response to certain actions, such as saving a record. Each table and Business Object
intrinsically have Save, Update, Delete and Insert Events, which execute as you alter records
throughout Vinyl.
To activate the CRUD Rules we created, we will add them to an Event or create our own
Custom Event if the trigger is not one of the intrinsic ones. Unlike the intrinsic Events, a
Custom Event must be attached to a Control on the Application Layer to be executed. The
CRUD Rules we are creating will require Custom Events in order to execute when we want
them to in Vinyl.
The first Custom Event we will create with a CRUD Rule will use the CRUD Delete Rule, where
we want it to delete OrderDetail records associated with an Order, if an Order gets deleted.

27
ADVANCED VINYL 2.3

4. Click the BOBJ icon for the application data source
5. Click to select the Order table from the Tables panel, then click the Events icon for
the Order (Source) Business Object
6. We are creating a Custom Event, so click the Create button under All Events
7. Name the Event Delete Order Details
8. In the Messages section, enter the Confirmation text “Are you sure you want to
delete this Order’s Details?”
The C RUD Delete Custom Event
Event Details Terminology

❖ Active – this checkbox indicates if the Event is active or not
❖ Confirmation – this message is displayed to a user to confirm if they want to take an
action (such as submit a report)
❖ Success – this message is displayed to a user after a successful action has been
performed
❖ Failure – this message is displayed to a user after an action has failed

10. Confirm your Custom Event now appears in the All Events panel:
28
ADVANCED VINYL 2.3
The Cus tom Event now appears in All Events
Event Terminology
❖ Save Event – this Event runs every time a record is saved
❖ Delete Event – this Event runs every time a record is deleted
❖ Update Event – this event runs every time a record is updated
❖ Insert Event – this event runs every time a record is inserted
11. At this point we have created the event, but not attached the CRUD Rule to it. CRUD
Rules get attached as actions, as an Event may execute one or more CRUD Rules.
Click to select the Delete Order Details event from All Events, and then click the
Create button in the Actions panel.
12. Click the drop-down menu for Rule, and select the CRUD Delete Rule OrderDetail
(Delete OrderDetail for Order)
13. In the Technical Help section, write a brief description of the Action, such as “Deletes
all Order Details for an Order”
14. Click Save
15. Under Explicit Bindings, verify that OrderID is the Source column and OrderID is the
Rule column. If that entry wasn’t added automatically, add it now by clicking the
create button.
The Acti on detail information for the Del ete Order Details Custom Event
29
ADVANCED VINYL 2.3
16. The Custom Event is configured and ready to be implemented on the Application
Layer
Chapter Exercise: Create CRUDs and Custom Events

❖ Create an Event titled Quantity+1 on the OrderDetail (Source) Business Object, and add
the CRUD OrderDetail (Quantity +1) as an action
❖ Create the same Event in the location described above, except use the Quantity -1 CRUD
Rule we made
❖ Now we have finished configuring CRUD Rules and are ready to move onto the
Application Layer to implement the CRUD Rules in the application
Firing Events
After configuring the CRUD Rules, we attached them to Custom Events on a Business Object.
If we had attached them to intrinsic Events (Save, Insert, Update or Delete) instead of Custom
Events they would already be in effect. Because they are attached to Custom Events, we
need to add them to an application page via some type of Control. Events can be added to
text, image, list or button Controls. The CRUD Rules we defined are intended to be associated
with buttons.
Next, we will add the OrderDetail (Delete OrderDetail from Order) Rule to a button on the
Order panel of the Order page.
1. Navigate in the application to the Orders page

2. Click the chevron link from one of the Orders panel records to get to the Order page
3. Click on the Action Drawer, and select Design this page
4. Click to select the Order panel, and then click the Create button under Controls
5. Name the button Delete Order Details
6. Set the Control Type to Button. We don’t want a Data Column because this Control is
not trying to show any data.
7. Click Save
8. Click the Edit button in the Navigation and Actions panel
9. Select Delete Order Details as the Event
10. Click Save
30
ADVANCED VINYL 2.3
Addi ng the Del et e Order Details Event to a Butto n on the Order panel
11. Navigate back to the application Order page and refresh. Confirm that you now see
the Delete Order Details button on the Order panel.
The Del et e Order Details butto n added to the Order panel
31
ADVANCED VINYL 2.3
12. Test the button by clicking on it, clicking Proceed, and refreshing the page. If the Rule
was properly configured, only the details of the order will be deleted.
Chapter Exercise: CRUDs and Firing Events

❖ Create a button on the Order page, under the OrderDetails panel, which uses the
Quantity +1 Event we created.
❖ Create a button on the Order page, under the OrderDetails panel, which uses the
Quantity -1 Event we created.
Subquery Rules and CRUD Rules

Now that the CRUD Rules we created earlier have been implemented in the Application
Layer, we are going to take a step back to the Business Logic Layer and review a new Rule
that is available in Vinyl: the Subquery. Subquery Rules are used as an intermediary between
a table and its Business Objects/Rules. Subquery Rules are used to generate some sort of
calculation or make an adjustment to the data and pass that new information along to
whatever object it is placed in.
In this section, we will make a Subquery Rule and then attach it to a CRUD Insert. We will
make a Subquery used to find the maximum OrderID of the Order table, and then add one to
it. This will be used by a CRUD Insert Rule in the next chapter, whose functionality in turn will
be copying an order. Typically, the OrderID is autogenerated by Vinyl, but because we are
inserting a new record, we need to provide it with a new OrderID. In most cases we would
generate a new OrderID with the NewUUID() function, which generates a UUID, but the data
in this case won’t work with that method. Here the OrderID is not a UUID, rather, it is stored
as a numeric field.

6. Assign the Name Order (OrderID + 1)
7. Set the Purpose to Subquery
8. Set the Target to be the Order table
9. Click Save
10. Click the SQL gears icon to enter the Business SQL
11. Confirm that the Order table appears in the Tables panel
12. In the Columns panel, enter the expression Max(OrderID) + 1, and assign the Alias as
MaxOrderID. Here the MAX() function is used to search a column for its maximum
value.
32
ADVANCED VINYL 2.3
The Business SQL for the Subqu ery
13. Click on the Results button and confirm that you see one row with the MaxOrderID
column. The value should be the maximum OrderID value plus one.
Subqueries and CRUD Inserts

Now that we have a Subquery configured, we will build a CRUD Insert Rule to utilize the
Order (OrderID + 1) Subquery.

6. Assign the Name Order (Copy Previous Order)
7. Set the Purpose to be CRUD
8. Set the Action to be Insert
9. Set the Target to be the Order table
10. Click Save
11. Click the SQL gears icon to enter the Business SQL
12. Confirm that the Order table is added to the Tables panel
13. Click Create in Tables, and select Order (OrderID + 1) from the Subquery menu
14. Click the check mark to save the information
15. Click Create under Columns, and add in OrderID from the Order table with no Target.
We add this column because we need to bind to it.
16. Click Create under Columns and add the MaxOrderID column from the Subquery,
Target the OrderID column. We add this because we want the OrderID generated to
be used for the Order.
17. Click the All button for the Order table in the Tables panel to add in all remaining
columns from the table. These should target themselves because that is how the rule
copies the Order (taking all columns from the current Order and inserting their values
into a new Order).
33
ADVANCED VINYL 2.3
The Business SQL f or the Order (Co py Previous Order) CRUD Inser t
18. Now with the CRUD Insert Rule configured, we need to attach it to an Event. We want
this CRUD to be on the same Order panel that the CRUD Delete was put on, so
navigate to your application’s Order page, click the Action Drawer and select Design
this page.
19. Click the Business Logic icon for the Order panel
20. Click on the Events icon for the Order (Source) Business Object
21. Click the Create button under All Events
22. Name the Event Copy Order
23. Click Save, and close the pop-up
24. With the Copy Order Event selected in the All Events panel, click Create in the Actions
panel
25. Click the drop-down menu for Rule and select Order (Copy Previous Order)
26. Set the Binding Type to Explicit
27. Enter a short description on the Action into the Technical Help section, such as
“Copies Previous Order”. Click Save
28. In Explicit Bindings, Source should be OrderID and Rule Column should be OrderID
34
ADVANCED VINYL 2.3
The Event Action for the Order (Co py Previous Order) CR UD Inser t Rul e
29. Now that your Rule is configured, it can be added to a new button named Copy
Order. Follow the steps we took for the Delete Order Details button, but instead add a
Copy Order button instead.
Validations
Validation Rules are used to ensure that the data entered in Vinyl is valid or correct, and also
when you want to ensure that a user enters data if it is required. Validation Rules differ from
configuring your Data Storage Layer to not allow nulls because you can customize the error
message the user receives with Validation Rules. When developing applications for
companies, you are often working with existing data that has been imported into Vinyl. If you
were to set a Data Storage Layer field to not allow null values, you may result in errors if data
imported contains nulls. This is another reason to configure a Validation Rule at the Business
Logic Layer vs. change the Data Storage Layer.
In this example, we will create a Validation Rule to make the FirstName column of the
Employee table a required field. This Rule will only require one table, the Employee table, in
the Business SQL configuration.
1. Navigate to the Vinyl IDE, select Build your application from the Build menu
2. Click on the Business Logic Layer button
3. Click the BOBJ icon for your application data source
5. Assign a Name for this Validation Rule. For example: Employee (FirstName Required)
6. Select the Purpose as Validation
7. Set the Target as Employee (Source)
8. Click Save
9. Click the SQL cogs icon to define the Rule
10. Click Create under Tables, and select the Employee table. Click the checkmark icon to
add it.
11. Click the PK button to add in the Primary Key Column for EmployeeID
35
ADVANCED VINYL 2.3
12. Click Create under Columns, and then select the FirstName column. This is the
column we want to mark as required.
13. Click Create in the Where panel, and select E.FirstName as the Left value, set the
Operator value to IS NULL, and click the checkmark on the left to save the
information
The Business SQL for the Employee (Firs tName Required) Vali dation Ru le
At this point we have finished configuring the Validation Rule in the Business Logic Layer.
Like any other Rule we create in Vinyl, for this to work in the UI Layer, we need to attach it to
an Event in order for it to function. We’ll look at configuring this connection in the next
chapter.
Chapter Exercise: Create a Validation

❖ Follow the steps outlined to create a Validation Rule, and create a new Validation Rule
that makes the LastName column required for the Employee table.
Validation Rules and Events

Validation Rules must be added to the Events of a Business Object in order for it to function
or fire. The process to do this is similar to how we configured adding a CRUD Rule to an
Event, except that instead of adding the action in the Actions panel we will add the validation
in the Validation panel. The Validation Rule will get added to the existing Save Event, and
does not require a custom Event to be configured.
Next, we will step through configuring the Validation Rule we created for Employee
(FirstName Required) so that it is attached to an Event.
4. Click to select the Employee table, on the left Tables panel
5. Under the Rules panel, click to select the Events icon for the Employee (Source)
Business Object
6. Click to highlight the Save Event in the tables panel, and then click the Create button
in the Validations panel
36
ADVANCED VINYL 2.3
7. For Rule, select Employee (FirstName Required) from the list

8. Set the Type to Rule
9. Set the Severity to Error
10. In the Message field, enter First Name Required. This is the actual message that will
get displayed to a user when this Event gets triggered.
11. Set the Error Type to Fail on data returned
12. Set the Binding Type to Implicit
13. Use the Technical Help field to provide a brief description of the Validation, such as
“Employee’s First Name is Required”
Configuring t he Val idatio n Rule to be attac hed to the Save Event
15. Test that the Validation Rule is properly configured by navigating to the application’s
Employees page and creating a new Employee record with an empty or null
FirstName field. Make sure that the error message displays.
Chapter Exercise: Attach a Validation Rule to an Event
❖ Follow the steps outlined to attach the Employee (FirstName Required) Validation Rule to
the Save event, create a new Validation for the Employee (LastName Required) Validation
Rule. Attach this new Validation to the Employee (Source) Business Object.
UI Layer
Now that we’ve built out a good amount of Business Logic for our application, we’ll look at
the UI Layer and practice a few design elements we can add into the application that we
haven’t reviewed yet.
Board Panels
Board Panels function similar to Multi-row Panels in that they also allow multiple records of
data to be displayed, but different in that rather than showing all the records as rows on a
grid (MRP) they display as many Single-Row Panel looking boards on a page. Board Panels
37
ADVANCED VINYL 2.3
are mostly used for aesthetic reasons. Board Panels do not support inline Create, Edit or
Delete, but do support linking to another page where you can edit values.
Employee page with Board Panel Type
In this example we will convert the existing Employees page, which is currently a Multi-row
Panel Type, into a Board Panel Type.
1. Navigate to the Employees page in the application

2. Click on the Action Drawer, and select Design this page from the menu
3. Click the pop-up icon to expand the Employees Multi-row Panel
4. Click the Edit button, and change the Type value to Board Panel
5. In the Intrinsic Control Options area, change the Create Mode value to be Link to
Page
The Employees MRP converted to a Board P anel

7. Test the updates by Running the page or refreshing the application’s Employees
page.
38
ADVANCED VINYL 2.3
8. In the current state, the Employees page has too many Controls on it for an optimal
Board Panel Type page. Board Panels look best with just a few Controls. Go ahead and
remove all Controls except: Photo, Full Name, Title, and Email.
Chart Panel
Vinyl supports multiple Chart Types on Pages, using the Chart Panel Type. To use Charts in
Vinyl, you typically need to have an aggregate value defined in a Business Object. We don’t
yet have an aggregate value defined, so for this example we will first make a new Business
Object to use and then add a new page for a chart. Here we will be adding in a Column Chart
that will display Order Total by Employee.
Create a Business Object with an Aggregate Value

1. Navigate to the Vinyl IDE, and select Build your application
2. Click the Business Logic Layer button, and the BOBJ icon for your data source
4. Assign the Name OrderDetail (Total by Employee)
5. Set the Purpose as Business Object
6. Target the OrderDetail table
7. Click Save
8. Click the SQL cogs icon to define the Business SQL
9. Add the Order and OrderDetails tables
10. Inner Join the Order table to the OrderDetails table
11. Join Columns by OrderID = OrderID
12. Click Create under Columns and add in the syntax:
SUM(OD.Quantity*OD.UnitPrice*(1-OD.Discount))
13. Alias this Column as SumLineTotal
14. Click Create under Columns and add in the EmployeeID column
The Business SQL for the OrderDetail ( Total by Em ployee) Business Object
15. Click the Results button and check to see the results are as expected
39
ADVANCED VINYL 2.3
Create a Chart
Now that we have a Business Object with an aggregate value defined, we can add in a new
page to the application that will contain a Chart.
1. From the application, click the Action Drawer

2. Select Add a page
3. Assign the Name Order Total by Employee
5. Click Create under Panels, and select the Type Chart Panel
6. Select the Chart Type as Column
7. For the Source Rule, select the Business Object we just created, which is OrderDetail
(Total by Employee)
9. Click Create under Controls, and select EmployeeID as the Column
10. Select Category as the Control Type. Category represents the x axis for Charts in Vinyl.
11. Under List Control Properties, select Employee (Full Name List) for Data Object
12. Set the Key as EmployeeID
13. Set the Title as Employee
14. Click Save
15. Click Create to add another Control, for Column select SumLineTotal
16. Set Control Type to Value. Value represents the y axis for Charts in Vinyl.
17. Click Save
18. Run the page to confirm that the Chart looks as expected
The Co lumn Chart that r epresents Order Total by Employee
Badging
Badging allows you to apply a small badge to Buttons in Vinyl. Badges work similar to how
they do on smartphones, where they create small notifications in the top right corner of a
button that gives you a dynamic number representing something. For example, you might
have a badge notification of 20 next to an Orders button, indicating you have 20 new Orders.
40
ADVANCED VINYL 2.3
Badges in Vinyl are configured using information from a Column, such as an Order Count,
and put on a button to provide users with a view of their underlying data in a very convenient
way.
In this example we will apply a Badge to the Orders button on the Customers page. We are
going to use Badging to display the count of orders on the Orders button. If you do not have
an Orders button Control appearing on your Customers page, go ahead and add one in prior
to following these steps.
1. Navigate to the Customers page in the application

2. Click the Action Drawer, and select Design this page from the menu
3. Select the Customers panel, and click the pop-up icon to expand the Orders button
4. Click the Edit button under Miscellaneous, and select CountOrders as the Badge
Source
6. Test that the badging worked correctly by navigating back to the application
Customers page and refreshing. You should now see the badge and its corresponding
information appear on the Orders buttons.
The Or ders bu tton wi th Badging applied to it
Reach
Reach is a security feature in Vinyl that you can implement in applications. It allows you to
restrict the data that certain users have access to throughout the application. Users will still
be able to navigate to the same pages, but the data on each page will be customized to only
show the data that each individual employee should be seeing.
The Region table that we created earlier in the Vinyl Introduction Manual will be used to
restrict the Customers that an Employee User can view, based on the market they are
assigned to: East Coast or West Coast. We also added the RegionID column to the Employee
table as a foreign key, but now we will also have to add it to the Customer table.
41
ADVANCED VINYL 2.3
Add RegionID to the Customer table

2. Click on the Data Storage Layer button
3. Click the Tables cog icon for your application data source
4. Click the right chevron icon on the Customer table to expand it
5. Click the Create button in the Columns panel
6. Name the column RegionID
7. Set the Logical Data Type to Unique ID, and the Physical Data Type to UUID
8. Make sure the PK Settings are as follows:
PK Settings for the Regio nID Colum n

Add UserID to the Employee table
2. Click on the Data Storage Layer button
3. Click the Tables cog icon for your application data source
4. Click the right chevron icon on the Employee table
5. Click the Create button in the Columns panel
6. Name the column UserID
7. Set the Logical Data Type to Unique ID, and the Physical Data Type to UUID
8. Make sure the PK Settings are as follows:
PK Settings for the UserID Column

Update the Customer (Source) Business Object
If we want to use these columns in the application, we also need to update any Business
Objects we want to see them on. Here we will update the Customer (Source) Business
Object to include the RegionID column.
1. Navigate back to the Business Logic page, and make sure that the Customer table is
selected from the Tables panel
2. Click the SQL cog icon for the Customer (Source) Business Object, from the Rules panel
3. Click the Create button in the Columns panel and add the RegionID from the Customer
table
4. Repeat these steps to add the UserID column to the Employee (Source) Business Object
Add Region List Control to the Customer Page

In the Introduction Manual we added a Region List Object to the Employee Page and
associated some of our Employees with the available Regions from the Region table. Now
42
ADVANCED VINYL 2.3
that we have added RegionID to the Customer table and the Customer (Source) Business
Object, we can add a Region List Control to the Customer Single-Row Panel Pop-up page as
well.
1. Navigate to the Customers page, and click the Pop-up icon to view the Customer Single-
Row Panel page
2. Click the Action Drawer icon
3. Select Design this page from the menu
4. Click Create under Controls
5. For Column, select RegionID
6. Change the Name to be Region
7. Change the Control Type to List
8. Select Region (List) as the Data Object
9. Set the Key to RegionID
10. Set the Title to Region
11. Click Save
12. Close out of the Control window by clicking the X icon
13. Edit the Position value for the Region Control so that it appears before the Customer
location information.
14. Return to the app, refresh the page, and then open a dozen or so Customer records and
use the Region List Control we just created to select East Coast Region for half of them,
and West Coast Region for the other half.
The Cus tomer Po p-up page with Region List Control Added
Reach and Subqueries

Now that we have some Employees and Customers associated with Regions, and a UserID is
added to the Employee table, we are ready to move to the Business Logic Layer. Here we will
create a Subquery to check the User’s Reach, and then implement the Subquery on a
Business Object so that Pages built out of it filter the results they display based on a logged
in User’s Reach.
Subqueries are essentially a data object that completes a task or calculation, then passes
along the new information somewhere else where it can be used by the application. The
43
ADVANCED VINYL 2.3
Subquery we make here checks to see who is currently logged in as a User, and then checks
that User’s Reach information.
4. Select the Employee table from the Tables panel
5. Click the Create button under the Rules panel
6. Assign the Name Employee (Reach By UserID)
7. The Purpose will be Subquery
8. The Target should be set to the Employee table
9. Click Save
10. Click the SQL cogs icon to define the Business SQL for this Business Object
11. Click the Create button under Tables and add in the Employee and Region tables
12. Join the Employee table to the Region table with a Left Outer Join
13. In the Join Columns panel, join RegionID as Left to RegionID as Right
14. In the Columns panel, add the RegionID from the Employee table, and UserID from
the Employee table
15. In the Where panel, set the UserID from the Employee table equal to Who(‘UserID’).
The completed Subquery should look like this screenshot:
The complet ed Business SQL for Employee ( Reach By UserID) Subqu ery
Join the Reach Subquery to a Business Object

Before we can use the Reach Subquery on a page and see it in action, we need to Join it to
the Customer (Source) Business Object. Joining the Subquery to the Customer (Source)
Business Object will allow us to restrict the data being shown by the Business Object so that
it only shows data that is meant for the User viewing the page.
4. Select the Customer table
44
ADVANCED VINYL 2.3
5. Click the SQL cogs icon for the Customer (Source) Business Object
6. Next, we will add in the Subquery. Click Create in the Tables panel and select
Employee (Reach By UserID)
7. In the Joins panel, click Create and Join the Customer table to the Subquery with an
Inner Join
8. In the Join Columns panel, specify the RegionID as the Left value, equal to RegionID
as the Right value
The Business SQL jo ini ng the Reac h Subquer y to the Customer (So urce) Business Object
9. Click the Results button and test that the results look as expected and that there are
no errors
Add the Vinyl Data Source
For this example, we are going to need to attach another data source to our application in
order to retrieve User information. Specifically, we will add in the Vinyl Engine - Vinyl data
source.
1. Click the Action Drawer, and select the Vinyl IDE

2. Select Build your application, and click on the application logo for your application to
get to the Application Design screen
3. Under Data Sources, click on Create
4. Select the Vinyl Engine – Vinyl Relational Database as the Data Source
6. The newly added data source should now appear in the Data Source panel
7. Navigate back to the application
Add User List Control to the Employee Page
Now that we have added UserID to the Employee table and the Employee (Source) Business
Object, and connected the Vinyl Data Source, we can add a User List Control to the Employee
Pop-up page to associate an Employee’s record with their User Name.
45
ADVANCED VINYL 2.3
1. Navigate to the Employees page, and click on the Pop-up icon to view the Employee
pop-up page
2. Click the Action Drawer icon
3. Select Design this page from the menu
4. Click Create under Controls
5. For Column, select UserID
6. Change the Name to be User
7. Change the Control Type to List
8. Under List Control Properties, Select User_Read as the Business Object Set
9. Set the Key to UserID
10. Set the Title to UserName
11. Click Save
12. Close out of the Control window by clicking the X icon
13. Edit the Position value for the Region Control so that it appears just under the Photo
control.
14. Return to the app and refresh the page. Use the User List Control we just added to
associate your User Name with an Employee record. In my case I am logged into Vinyl as
Admin. Take note of the Region associated with this Employee record. You will now only
be able to see Customer records that are associated with that same Region.
The Employee Pop-u p page with User and Region List Controls Added
Bridge
Fundamentally, a Bridge in Vinyl can be thought of as a connection between a launching
page and a landing page. A Bridge is an application level concept which enables a designer
to send a message to a user. This message may have multiple options which define how the
46
ADVANCED VINYL 2.3
user can respond to the message. When options are present in a Bridge, the user's response
is automatically tracked by Vinyl.
Additional detail about Bridge is contained on the Zudy Knowledge Base, such as the public
data objects used as Bridge targets.
Message Types
Currently a Bridge can use one of the following message types:
• Email - Not surprisingly, an email.

• Vinyl Alert - A popup which shows up in the user's browser when they are logged into
Vinyl. Formerly called a Notification.
Both message types support adding options which are essentially URL links back to Vinyl.
Future releases of Vinyl will likely support sending messages to REST servers. This would
allow designers to interface with 3rd party services like Twilio for SMS.
Options
Bridges can have 0 or more options. When a Bridge contains no options, there is no expected
User response and consequently, no tracking of the User's response is provided. No links will
be added to the outgoing message. This is considered an Informational Bridge.
When a Bridge contains 1 or more options, a message is sent with URL links back into Vinyl
that allow the User to respond in some way. The User's response to the message (i.e. which
option they selected) is tracked by the Bridge.
Configuration
Bridge options can be configured in two ways:
1. Link to page - A link is provided which allows the user to navigate to a page.
Successfully navigating to the page is considering a complete response to the option.
2. Run page event - A link is provided which sends the User to a page and runs a
specified Event before the page is rendered. Again, the User's response is considered
complete once the Event is triggered.
For a page to be eligible for either option above, the page must be marked Shared.
As an example, an Admin may execute an Event that causes an email to be sent to an End
User. The email has some text and three buttons in it:
1. Review - Clicking Review can bring the User to a specific page in Vinyl
2. Approve - Clicking Approve can bring the User to a different page AND execute an
Event against some data objects in the page
3. Reject - Clicking Reject can bring the user to a different page AND execute an Event
against the same page or a different page's data objects
The Event must be executed before the page is rendered as it may affect data that is
contained in the panels on the page. To execute an Event, the designer must:
• Make the Link To page Shared.
47
ADVANCED VINYL 2.3
• Include the Event in either the Data Object for the page or as one of the Single-Row
Panel data sources on the page. Further illustration of this point is available in the
Data Object Event Binding section below.
Data Object Event Binding

Vinyl limits the Events that can be bound to a link. Specifically, this limitation only allows for
events that belong to a Data Object / Table that is bound to an unbound Single-Row Panel
on the target page. For example, let's consider a page that has 6 Single-Row Panels:
• Customer -> CustomerAddress -> CustomerMap

• Employee -> EmployeeAddress -> EmployeeMap
In this example, Customer and Employee panels are not bound to any other panels on the
page. Therefore, a designer can choose Events from those two panels data sources (along
with a page data object if one is specified).
Vinyl also limits the Events that can be bound to non-system events. For example, the
designer cannot link back to the Save, Insert, Update or Delete Events.
Bridge Registration
Linking to a Bridge
The Bridge Registration page in the Vinyl IDE allows the designer to link a Bridge to an
application. This is a 1 to 1 relationship. Additional information about the Bridge message can
be configured within the Bridge registration.
Message Creation
The Bridge message can be defined in the Template section of the Bridge Registration
page. This is the main content of the Bridge itself.
Substitutions are performed on the Template and use the {{fieldname}} syntax. Substitutions
may add an optional url flag to indicate the value is an url and requires url-encoding e.g.
{{fieldname|url}}.
In regards to substitution, the body may contain:
Hello {{CustomerName}},
In which case CustomerName must be contained in the Bridge rule's columns along with
the other required fields.
For emails, a Subject can be specified in the Bridge Registration page. The Subject field also
supports substitutions.
Bridges support rudimentary translations. There are three fields which are used for
translations:
Translations
1. Bridge Option Name

2. Bridge Registration Message
3. Bridge Registration Subject (for Emails)
48
ADVANCED VINYL 2.3
When creating the Bridge message, Vinyl will attempt to find translations for each of these
fields, assuming that their content specifies the corresponding translation key. The designer
also needs to add the keys to the translation bundle for the app manually (they are currently
not imported automatically for an app). Care must be taken with the Template field to add
the translation key as a raw string and not as HTML. There is a "code" icon at the bottom right
of the Bridge Registration Template field which allows you to directly edit the string.
Limitations
The Event executed in the option link belongs to the Page Data or a Single-Row Panel Data
Object. Currently, we do not display any validation results or post messages for page level
Events. In other words, the Event runs first, when it completes, the User is redirected their
page. By the time they arrive at their page, the Event results are lost.
Therefore, if the Event has a post message or fails validation, the system will not show those
results to the End User. The designer can easily workaround this by displaying data in their
panels that changes based on the successful execution of an Event.
Because of the above limitation, validation warnings will cause an Event to not execute. We
do not have a UI in place that allows for the User to accept or reject the warning.
Example Bridge Setup

Following are steps to setting up a Bridge. We'll assume that we're adding a Customer
Approval Bridge to the Northwinds Customers page in this example.
Link Data Sources

To create a Bridge, we will first need to link our data sources that the application currently
has added.
1. From the application, click on the Action Drawer

2. Select Design a data source
3. Double click on the entry for your Application Data Source
4. Click on the Link Sources icon
5. Click the Create button
6. For Linked Data Source, select Vinyl
Create a Bridge
Now that we have linked the data sources, we can create a Rule that targets a Bridge public
data object.
Steps to Create Bridge

4. Click Create under Rules
5. Assign a Name for the new Rule, for example CustomersRequestApprovalAlert
6. Select Bridge as the Purpose
7. Set the Target to Bridge_Vinyl_Alert_Send
49
ADVANCED VINYL 2.3
8. Click the SQL cog icon to enter the Business SQL

9. Add the Customer table, this table is our ‘select from’ table
10. Click Create and add a Column for CustomerID, and set the Target for it to Binding()
11. Click Create and add a Column for Customer
12. Click Create and add a Column for who(‘userID’), set the Alias and Target both to To
The Business SQL for Cus tomersRequ estApprovalA lert
Register Bridge with Application

2. Click the Bridges icon for your application
3. Click Create to add a new Bridge
4. Select the Bridge Rule we just created, CustomerRequestApprovalAlert
5. Enter the Message information you want to appear. For example:
Please review the following customer:
Customer: {{Customer}}
50
ADVANCED VINYL 2.3
6. Click Save
Define Bridge Options

Optionally define a landing page and prelaunch Event to run.
2. Click the Bridges icon for your application
3. Click the Pop-up icon to expand information on the Bridge we just created
4. Click Create under the Options panel
5. Set the Index value to 10
6. Set the Name to Review
7. Set Link To Page to Customer
8. Click the checkmark to save the information. Your Bridge information should look like
this:
The Bridg e Configur atio n I nformatio n
Register Bridge as an Action with an Event

In this case, we're assuming the Event is associated with a button on the launching page.
We'll also assume the Event is called 'Request Approval'. To achieve this, we will first add a
button named Request Approval to the Customer page, Customers panel.
1. Navigate in the application to the Customer page

2. Click the Action Drawer, and select Design this page
3. Click Create under Controls, and select Control Type as Button
4. Enter the Name as Request Approval
5. Edit the Index value so that the button shows up first on your Panel
6. Click Save and refresh your application Customer page. Confirm you now see a
button labeled Request Approval
7. Click the Action Drawer and select Design a data source
8. Click the Tables icon for your data source
9. Click to select the Customer table, and then click on the Events icon for the
Customer (Source) Business Object
10. Click Create under Events, and assign the Name as Request Approval
11. Click Save, and with the Request Approval Event selected, click Create under Actions
51
ADVANCED VINYL 2.3
12. Set Type to Bridge

13. Select the Bridge we created, CustomerRequestApprovalAlert
14. Enter a description for the action in the Technical Help field, such as “Customer
Approval Bridge”
15. Click Save and verify the Explicit Bindings are correct. For example: CustomerId –
CustomerId
The Bridg e Action config uration
16. Navigate back to the Customer page, and click the Action Drawer and Design this
page
17. Double click on the Request Approval button
18. Click Edit under Navigation and Actions
19. Select the Event as Request Approval
Test it out! You’ve now got the information configured for the Bridge in Vinyl and should
navigate to the Customer page and click on the Request Approval button. This should fire
the Event that prompts a notification to review a particular Customer, and if you click on
Review, you should be directed to the corresponding page with Customer information in the
application.
Vinyl Beyond the Class

This concludes the Vinyl Advanced Training Manual. If you’re looking for more information on
learning and working with Vinyl, please see the online Knowledge Base at
http://wiki.zudy.com
52

Developer Training:: Vinyl Advanced Training Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Developer Training:: Vinyl Advanced Training Manual

Uploaded by

Copyright:

Available Formats

Developer Training:

Vinyl Advanced Training Manual

Union Joins .............................................................................................................................................. 23

Data Storage Layer

Business Logic Layer

Northwind Data Structure

Data Storage Layer

Data Storage Layer Link

Logical Data Types for Table Columns

PK Settings avai lable for a Column

Physical Data Types available for Unique ID

Physical Data Types available for String

Date, Date/Time, Time

Physical Data Types available for Date

Physical Data Types available for Photo

Physical Data Types available for File

Physical Data Types available for Number

Physical Data Types available for Phone

Physical Data Types available for Currency

Physical Data Types available for Boolean

Physical Data Types available for Email

Physical Data Types available for URL

Insert, Update and Delete

1. Click the Action Drawer icon, and select Vinyl IDE

Edge Cas e Settings optio ns avai lable for a Tabl e

7. The CRUD Support Control Set contains three options:

Chapter Exercise: Modify the Product Table

1. Click the Action Drawer icon, and select Vinyl IDE

8. Click the Save button

Chapter Exercise: Set a Default on the Product Table

1. Click the Action Drawer icon, and select Vinyl IDE

The C at egory Colum n has Usage defi ned as Title

Other Common Usage Types

1. Click the Action Drawer icon, and select Vinyl IDE

The Table Defini tion screen wher e you

Table Relationship Terminology

Chapter Exercise: Create a Relationship on the Supplier Table

1. Click the Action Drawer icon, and select Vinyl IDE

10. Click Save

1. Click the Action Drawer icon, and select Vinyl IDE

The U nion Join Ru le Nam e, Purpos e and Targ et

9. Click the Save button

View Det ails inform ation o n the U nion Join Ru le

Edge Cas e Settings for the Union Join Rule

1. Click the Action Drawer icon, and select Vinyl IDE

The Business SQL for the CRUD Update Rul e

The Resul ts of the CRU D Update Rule

Chapter Exercise: Create a CRUD Update Rule

1. Click the Action Drawer icon, and select Vinyl IDE

CRUD Rules with Events

1. Click the Action Drawer icon, and select Vinyl IDE

2. Click the Build your application button on the Build menu

The C RUD Delete Custom Event

Event Details Terminology

9. Click the Save button

The Cus tom Event now appears in All Events

Chapter Exercise: Create CRUDs and Custom Events

1. Navigate in the application to the Orders page

The Del et e Order Details butto n added to the Order panel

Chapter Exercise: CRUDs and Firing Events

Subquery Rules and CRUD Rules

1. Click the Action Drawer icon, and select Vinyl IDE

The Business SQL for the Subqu ery