How to integrate “My Queries”

“My Queries” is a Jspresso feature for “filter modules” and “pivot modules” that will add to your application the capability to manage combination of queries. This will help your application to become more “business” oriented instead of “data oriented”. Users will appreciate it.

 

What will “My Queries” help me to do ?

  • Naming and saving criteria combination… managing a summary of all saved criteria… loading criteria quickly by a single click.
  • Defining a “Default” criteria, so that as soon as you move to the filter module the criteria is applied and the result list is loaded and displayed.
  • Sharing criteria with other users from the same organisation, the same customer or whatever you want (See chapter II)
  • Managing “shared” queries, so that backend users will provide useful criteria to other users (See chapter III)

 

I. My Queries user guide

 

“My Queries” is made up of 3 simple elements,

  • A “My Queries” filter tab to browse queries and select the one you need.
  • A “My Queries” action button to open ” My Queries” popup.
  • A “My Queries” popup to save criteria combination and to manage them.

… and 1 advanced element :

  • An administration module to manage “shared” queries.

 

“My Queries” filter tab

  • Review all queries you saved.
  • Apply any query by a simple click. The selected query name will turn to bold characters.
  • Browse more than 6 queries by selecting previous (“<“) and next (“>”) buttons on each side.
  • TIP : You can display query tooltip for some information : who shared this query ? how many time it was used ? etc.

  MyRequests-Tab-tooltip

“My Queries” button

MyRequests-Button

  • Just click to open “My Queries” popup

 

“My Queries” popup

  • Review all queries you saved. TIP : your own queries are blue, queries shared by other people are gray.
  • Apply any query by a simple click.  Criteria will be applied and the result list will be loaded and displayed. The selected query name will turn to bold characters into “My Queries” filter tab.
  • Save, Rename, Delete criteria :
    MyRequests-Save
    TIP : You can’t delete or renames queries shared by other users.
  • Reorder queries using up and down arrow on bottom left.
  • Share your queries by checking the “shared” box. See next chapter for more information.
  • Setup your default criteria, so that as soon as you move to the filter module the criteria is applied and the result list is loaded and displayed. Simply check the “Shared” box.

 

II. Criteria sharing mechanism

 

Here is how My Queries deals with criteria sharing :

  • Each application’s user belongs to one or more “groups”.
  • When a user shares a query, the query is tagged with all user’s groups.
  • The “My Queries” tab will display all queries tagged with one or more user’s group.

Here is a chart to understand better which user will see which queries :

MyRequests-Sharing

See chapter IV to deal about how to define user’s groups.

 

III. Managing “shared” queries

 

“My Queries” also provides a dedicated Jspresso module to manage all user’s shared queries.

MyRequests-Admin

 

The UI consists of (left to right, top to bottom) :

  • Modules : the list of modules having at least one shared query. The right side is synchronized with the selected module in this list.
  • Identification : the selected module’s id and it’s name. The toolbar above allow to Save and Cancel changes. You can also move to the module using the “Navigate to module” button.
  • Filter : a form to filter queries displayed bellow by query name, shared group, and owner.
  • Queries : the queries lists …
    • A table of query names, “shared with” lists, owner’s names
    • A top toolbar to add and remove sharing, changing queries owners.
    • A bottom toolbar to check / uncheck all queries and duplicate or delete queries
  • Criteria and Extra criteria : technical stuff to check what the query is about.
  • Tracing : query tracking informations such as the query created date, the last use date, the number of uses, etc.

 

This module main purpose is to allow administrators to dispatch queries to the appropriate groups by adding or removing groups :

  • Select one or more queries.
  • Press “Add sharing” or “Remove sharing” to open the groups selection popup.
  • Select one or more groups and press “Ok”
    MyRequests-Admin-AddSharing
    NB : groups displayed with blue characters are already part of the selected queries sharing groups.

TIP : you can also enter group names directly in the table… pay attention to spelling mistakes !

 

IV. Technical information

 

Adding “My Queries” action

Simply add the “chooseQueryCriteriasFrontAction” action to the module view of your filter module or pivot module, that’s it !

Adding “My Queries” filter tab

You can turn all your application to use “My queries” filter tab every where by overriding the “abstractFilterableBeanCollectionModule” bean :

bean('abstractFilterableBeanCollectionModule',
  parent: 'abstractFilterableBeanCollectionModuleBase',
  custom:[queryComponentDescriptorFactory_ref:'extendedQueryComponentDescriptorFactory',
          queryExtraViewDescriptorFactory_ref:'queryExtraViewDescriptorFactory'])
}

If you want to use “My queries” only for some of your modules, then use the « custom » attribut to setup parameters :

pivotModule('EmployeeModule’,
   ... 
   component:'Employee',
   custom:[queryComponentDescriptorFactory_ref:'extendedQueryComponentDescriptorFactory',
           queryExtraViewDescriptorFactory_ref:'queryExtraViewDescriptorFactory'])

 

Adding “My Queries” administration module

Add “userqueries.admin.module” module to any workspace, for example :

workspace('administration.workspace') {
 module ('userqueries.admin.module', parent:'userqueries.admin.module')
 ...
}}

 

 

Criteria sharing implementation

You have to override the the “userQueriesHelper” bean to use your own implementation :

bean('userQueriesHelper',
   parent:'userQueriesHelperBase',
   class:'org.jspresso.hrsample.ext.backend.UserQueriesHelper')

The class should inherit from “org.jspresso.contrib.backend.query.AbstractUserQueriesMatchingGroupsHelper“.
You should implement at least 2 methods :

•   public List<String> getAllGroups(Map<String, Object> context)

•   public List<String> getMySharedGroups(Subject subject)

The first one should return the list of all possible group names, the second one the user’s group names.

Here is an example from HR-Sample EE :

/**
 * User query helper implementation.
 * Uses companies and organisation units.
 * 
 * @author Maxime HAMM
 */
public class UserQueriesHelper extends AbstractUserQueriesMatchingGroupsHelper {

  /**
   * {@inheritDoc}
   * 
   * Gets Employee's company, department and team names.
   */
  @Override
  public List getMySharedGroups(Subject subject) {
    
    // get user instance
    HibernateBackendController controller = (HibernateBackendController) BackendControllerHolder.getCurrentBackendController();
    DetachedCriteria criteria = DetachedCriteria.forClass(Employee.class);
    criteria.add(Restrictions.eq(Employee.SSN, getLogin(subject)));
    Employee employee = controller.findFirstByCriteria(criteria, EMergeMode.MERGE_KEEP, Employee.class);
    if (employee == null || employee.getCompany() == null)
      return Collections.emptyList();
    
    // build shared groups, with company and organisation units
    List groups = new ArrayList<>();
    String company = employee.getCompany().getNameRaw();
    groups.add(company);
    
    for (Team t : employee.getTeams()) {
      groups.add(company + '/' + t.getDepartment().getOuId());
    }
    
    return groups;
  }
  
  /**
   * {@inheritDoc}
   * 
   * Get all company names and organisation unit names.
   */
  @Override
  public List getAllGroups(Map context) {
    List groups = new ArrayList<>();
    HibernateBackendController controller = (HibernateBackendController) BackendControllerHolder.getCurrentBackendController();
    
    DetachedCriteria criteria = DetachedCriteria.forClass(Company.class);
    criteria.addOrder(Order.asc(Company.NAME_RAW));
    List companies = controller.findByCriteria(criteria, EMergeMode.MERGE_KEEP, Company.class);
    for (Company c : companies) {
      String company = c.getNameRaw();
      groups.add(company);
      
      for (Department d : c.getDepartments()) {
        groups.add(company + '/' + d.getOuId());
      }
    }
   
    return groups;
  }
}


Categories: User Interface

Leave a Reply