Creating a Multi-Row Agent

In this Lesson

You will learn how to create a multi-row agent that uses a datasource to display and delete information from a database table.


Agents, like other Soiree items, are created using a Soiree wizard. All agents are grouped into two categories.

  • Multi-Row
    These are agents whose primary purpose is to contain a list of information – such as a list of parties.
  • Single-Row
    These are agents whose primary purpose is not to display a list of information. Single-Row agents may be agents that contain a discrete set of data – or no data at all.

The Soiree wizard can be used to create an agent that uses a Soiree datasource as its source of information. This is very convenient for creating agents that view or modify rows in a database table.

The Soiree wizard can also be used to create an agent that does not use a datasource. You are then responsible for manually adding the data or processing to be provided by the agent.

Node Types

All agents use nodes to contain the data they provide to scenes. Each node has a type describing the type of information it contains.

There are node types for all the usual suspects you would expect to find at a Java themed party

  • Boolean
  • String
  • Short
  • Integer
  • Long
  • Float
  • Double
  • Decimal
  • Date
  • Time
  • Timestamp

There are also a few node types that provide special capabilities

  • Grid
    This node contains multiple rows each of which may contain other nodes. [ much like a table contains rows and columns ]
  • Tree
    This node is used to display a tree of information [ such as the folders and files contained in a filesystem ]
  • Image
    This is used to display an image from the Soiree Image Repository
  • Entity
    This is a reference to a Soiree entity. This node supports the ability to represent an entity in a scene. These are also eligible to be dragged onto an agent conduit.
  • File Upload
    This node supports the ability to upload files from a Soiree client to the server.

Each agent may contain zero or more nodes of each type.

Grid Node and Agent Type
Both multi-row and single-row agents may contain grid nodes. The difference between a multi-row agent and a single-row agent is its primary purpose.

  • A multi-row agent is primarily designed to provide a list of information. Each multi-row agent always has a grid node named list which contains the list of information being provided. It may also contain other nodes, including other grid nodes.
  • A single-row agent is primarily designed to display non-list information or no information at all. A single-row agent may also contain a grid node if the design calls for it but the grid would only contain supporting information about the primary purpose of the agent.
Keep it simple
If you are tempted to add a grid to a single-row agent ( or a second grid to a multi-row agent ) you may be asking the agent to do too much. Consider making a second agent to contain the desired list.
Keep each agent highly cohesive – each agent should serve a single purpose.

Create a multi-row agent

You will now create a multi-row agent to provide a list of all parties in the party table. When we say all parties what we mean, of course, is all the parties for a single tenant because the party table is designed for multi-tenancy.

  1. Select the package and then open the Soiree Agent Wizard

  2. Create a multi-row agent named PartyList as shown here

  3. Add all the datasource values to the agent

  4. Select the datasource queries for View and Delete.
    The PartyPaging

    You may have noticed there are two datasource queries available for the View mode: one called Party and one called PartyPaging. These were created when you requested a ‘full access’ datasource to be created. These are both browse cursors which return all the rows in the table for a single entity. The Party query returns all rows – starting with the first row – each time it is called. The PartyPaging has the option of returning the query result set as a series of pages much like an internet search. The results are returned a page at a time and the user can request a ‘next page’ of information. It is a good idea to use a paging cursor for multi-row agents so you have the option of controlling how many rows are returned to the scene at one time.
  5. Click on the Nodes tab. Notice this multi-row agent’s scheme has a single Grid node named list. It is used to contain all the rows offered by this agent.

  6. Click on the list tab. Each grid node receives its own tab for defining the nodes, events, and conduits in each row.

  7. Add an event named select to the list grid.

    Your agent should now look like this

  8. Build the agent

  9. The Agent view should indicate the build was successful

  10. Notice the Java classes that were created

You have reached the end of this lesson.