virtuslab / beholder

Small slick lib for create views on on database

Beholder: Play-Slick library for data presentation

Standard part of many application are list of data that is not a effect of simple query from one table but junction and aggregation of data from many tables. Beholder provides support for such elemets.

Features:

• views as table
• declaring filters for data
• support for sorting, filtering on multiple (custom) datatypes

Contributors

Authors:

• Krzysztof Romanowski
• Jerzy Müller
• Mikołaj Jakubowski
• Krzysztof Borowski

Feel free to use it, test it and to contribute!

Getting beholder

For latest version (Scala 2.11.7 compatible) use:

// https://mvnrepository.com/artifact/org.virtuslab/beholder
libraryDependencies += "org.virtuslab" %% "beholder" % "1.1.0"

Or see Maven repository for 2.10 and 2.11.

Examples

Lets assume that we created simple entries

case class MachineId(id: Long) extends AnyVal with BaseId

case class UserId(id: Long) extends AnyVal with BaseId

and junction table joined them by ids.

Defining view

Usually for data in view does not came form single table so we have to create view that is materialisation of some query. Beholder provides such utility. We can create Slick's table that operate on view (it is read only).

case class UserMachineView(email: String, system: String, cores: Int)

val usersMachinesQuery = for {
  user <- Users
  userMachine <- UserMachines if user.id === userMachine.userId
  machine <- Machines if machine.id === userMachine.machineId
} yield (user, machine)


val UsersMachineView = FilterableViews.createView(name = "USERS_MACHINE_VIEW",
  apply = UserMachineView.apply _,
  unapply = UserMachineView.unapply _,
  baseQuery = usersMachinesQuery) {
  case (user, machine) =>
    //naming the fields
    ("email" -> user.email,
      "system" -> machine.system,
      "cores" -> machine.cores)
}

UsersMachineView.viewDDL.create

Defining filter

We create a filter by specify table query (view or normal table) and mapping for field

val UsersMachineFilter = new FiltersGenerator[UserMachineView].create(view,
  inText,
  inText,
  inIntField
)

Do the filtering from request

UsersMachineFilter.filterForm.bindFromRequest().fold(
  errors => handleError(),
  filterData => showResult(UsersMachineFilter.filter(filterData))
)

beholder's Issues

Filtering by ignored json field

When filtering by json field that is ignored doFilter endpoint returns null instead of list of entities not filtered by this value.

View are still in Beholder 1.0

Views are written still in spirit of 1.0 beholder.

We need to make them more DBIO-like, and remove unicorn dependencies (or extract to one place)

Crating more lightway dsl will be also benefical.

Create more tests for json filters

We need to create tests for (see ForamtterTestSuire.scala)

• ranges, and alternatives for all fields
• nested filters
• definition tests
• create tests for json controllers

Create function based dsl

Enrich existing filter dsl to accept one function style dsl e.g.:

fromQuery(myQuery){
  case (a, b) => "ala" from a.ala and "ola" from o.ola
}

Beholder keys (strings) cleanup

Move all beholder specific keys into dedicated object and use it in tests

Collectors dsl

Currently we have only one poor collector. We need to create dsl for creating and chaining collectors.

Migrate to Play 2.4

Migrate to Play 2.4
Fix tests
Add scoverage plugin
Write tests to achieve high coverage

Create legacy fully typesafe dsl

Utils for enum fields

Create utils for making enum fields working with both databse and json

Dsl should allows to configure name for filter

Filter should be named. We need to create DSL for naming filter (it is required for errors messages for nested filters).

Create aggregation collector

Create aggregation collector including tests

Create more tests tests for Filters

We need to create tests for:

• table based filers
• another dsl forms
• test deeper nested joins with name clashes, alternatives and ranges
• enums
• negative tests

All should be done as extensions to exisiting tests (enums will be tested for all dsl etc.)

[feature update]

could you add the title when scan the web?

Add new filter method to return total entities number

I am writing table with pagination. For best possible performance I am taking only some records from database using FilterDefinition.take and FilterDefinition.skip fields. But I need also total entities number on particular filter query (without taking FilterDefinition.take and FilterDefinition.skip in account) to compute proper number of pages in my table. I need method like that (pseudo code):

type TotalEntitiesNumber = Int
def filterWithTotalEntitiesNumber(data: FilterDefinition[FilteredData]): (Seq[Entity], TotalEntitiesNumber)

Date range filtering

Date range should be closed [a,b] not open (a,b). Now for range (a,a) result is empty even if there is a row with a date.

DSL for joins

We need better dsl for filter joins

Migrate tests to slick 3.0 approach

Tests are currently strongly dependes on session and unicorn. We need rewrite them into slick 3.0 approach.

Create beholder specific exceptions

Test are failing

Currently on master branch tests are failing.

Disjunction filtering based on enum values

Is it possible to filter data using many enum values ? E. g. I have enum:

Currency {
 PLN, 
 USD,
 EUR
}

And I want to have all unique results which have type PLN or USD. This feature could be also added to others filterable fields.

FilterControllerComponent method with action performed on filtered data

Often, after you filtered desired items, you want to perform some action on them. There should be method which will make it easier.

Split beholder into smaller projects

Beholder is now single jar. We need to split it into set of smaller ones with different dependencies. My proposal:

beholder-core - depends only on slick
beholder-json (beholder-play) - depends on core and play
beholder-unicorn - all unicorn-ed end points

Update readme.md and create user documentation