doc/book/en/development/vreg.rst
branchstable
changeset 5394 105011657405
parent 5393 875bdc0fe8ce
child 5395 e0ab7433e640
equal deleted inserted replaced
5393:875bdc0fe8ce 5394:105011657405
     1 The VRegistry, selectors and application objects
       
     2 ================================================
       
     3 
       
     4 This chapter talks about core concepts of the |cubicweb| framework,
       
     5 that make it different from other frameworks (and maybe not easy to
       
     6 grasp at a first glance). To be able to do advanced development with
       
     7 |cubicweb| you need a good understanding of what is explained below.
       
     8 
       
     9 This chapter goes deep into details. You don't have to remember them
       
    10 all but keep it in mind so you can go back there later.
       
    11 
       
    12 An overview of AppObjects, the VRegistry and Selectors is given in the
       
    13 :ref:`VRegistryIntro` chapter.
       
    14 
       
    15 .. autodocstring:: cubicweb.cwvreg
       
    16 .. autodocstring:: cubicweb.selectors
       
    17 .. automodule:: cubicweb.appobject
       
    18 
       
    19 Base selectors
       
    20 --------------
       
    21 
       
    22 Selectors are scoring functions that are called by the registry to tell whenever
       
    23 an appobject can be selected in a given context. Selector sets are for instance
       
    24 the glue that tie views to the data model. Using them appropriately is an
       
    25 essential part of the construction of well behaved cubes.
       
    26 
       
    27 Of course you may have to write your own set of selectors as your needs grows and
       
    28 you get familiar with the framework (see :ref:`CustomSelectors`).
       
    29 
       
    30 Here is a description of generic selectors provided by CubicWeb that should suit
       
    31 most of your needs.
       
    32 
       
    33 Bare selectors
       
    34 ~~~~~~~~~~~~~~
       
    35 Those selectors are somewhat dumb, which doesn't mean they're not (very) useful.
       
    36 
       
    37 .. autoclass:: cubicweb.appobject.yes
       
    38 .. autoclass:: cubicweb.selectors.match_kwargs
       
    39 .. autoclass:: cubicweb.selectors.appobject_selectable
       
    40 
       
    41 
       
    42 Result set selectors
       
    43 ~~~~~~~~~~~~~~~~~~~~~
       
    44 Those selectors are looking for a result set in the context ('rset' argument or
       
    45 the input context) and match or not according to its shape. Some of these
       
    46 selectors have different behaviour if a particular cell of the result set is
       
    47 specified using 'row' and 'col' arguments of the input context or not.
       
    48 
       
    49 .. autoclass:: cubicweb.selectors.none_rset
       
    50 .. autoclass:: cubicweb.selectors.any_rset
       
    51 .. autoclass:: cubicweb.selectors.nonempty_rset
       
    52 .. autoclass:: cubicweb.selectors.empty_rset
       
    53 .. autoclass:: cubicweb.selectors.one_line_rset
       
    54 .. autoclass:: cubicweb.selectors.multi_lines_rset
       
    55 .. autoclass:: cubicweb.selectors.multi_columns_rset
       
    56 .. autoclass:: cubicweb.selectors.paginated_rset
       
    57 .. autoclass:: cubicweb.selectors.sorted_rset
       
    58 .. autoclass:: cubicweb.selectors.one_etype_rset
       
    59 .. autoclass:: cubicweb.selectors.multi_etypes_rset
       
    60 
       
    61 
       
    62 Entity selectors
       
    63 ~~~~~~~~~~~~~~~~
       
    64 Those selectors are looking for either an `entity` argument in the input context,
       
    65 or entity found in the result set ('rset' argument or the input context) and
       
    66 match or not according to entity's (instance or class) properties.
       
    67 
       
    68 .. autoclass:: cubicweb.selectors.non_final_entity
       
    69 .. autoclass:: cubicweb.selectors.implements
       
    70 .. autoclass:: cubicweb.selectors.score_entity
       
    71 .. autoclass:: cubicweb.selectors.rql_condition
       
    72 .. autoclass:: cubicweb.selectors.relation_possible
       
    73 .. autoclass:: cubicweb.selectors.partial_relation_possible
       
    74 .. autoclass:: cubicweb.selectors.has_related_entities
       
    75 .. autoclass:: cubicweb.selectors.partial_has_related_entities
       
    76 .. autoclass:: cubicweb.selectors.has_permission
       
    77 .. autoclass:: cubicweb.selectors.has_add_permission
       
    78 
       
    79 
       
    80 Logged user selectors
       
    81 ~~~~~~~~~~~~~~~~~~~~~
       
    82 Those selectors are looking for properties of the user issuing the request.
       
    83 
       
    84 .. autoclass:: cubicweb.selectors.anonymous_user
       
    85 .. autoclass:: cubicweb.selectors.authenticated_user
       
    86 .. autoclass:: cubicweb.selectors.match_user_groups
       
    87 
       
    88 
       
    89 Web request selectors
       
    90 ~~~~~~~~~~~~~~~~~~~~~
       
    91 Those selectors are looking for properties of *web* request, they can not be
       
    92 used on the data repository side.
       
    93 
       
    94 .. autoclass:: cubicweb.selectors.match_form_params
       
    95 .. autoclass:: cubicweb.selectors.match_search_state
       
    96 .. autoclass:: cubicweb.selectors.match_context_prop
       
    97 .. autoclass:: cubicweb.selectors.match_view
       
    98 .. autoclass:: cubicweb.selectors.primary_view
       
    99 .. autoclass:: cubicweb.selectors.specified_etype_implements
       
   100 
       
   101 
       
   102 Other selectors
       
   103 ~~~~~~~~~~~~~~~
       
   104 .. autoclass:: cubicweb.selectors.match_transition
       
   105 
       
   106 You'll also find some other (very) specific selectors hidden in other modules
       
   107 than :mod:`cubicweb.selectors`.