Wt  4.0.0
Public Member Functions | Protected Member Functions | List of all members
Wt::Dbo::QueryModel< Result > Class Template Reference

A Wt MVC Model to view/edit query results. More...

#include <Wt/Dbo/QueryModel.h>

Inheritance diagram for Wt::Dbo::QueryModel< Result >:
Inheritance graph
[legend]

Public Member Functions

 QueryModel ()
 Creates a new query model. More...
 
void setQuery (const Query< Result > &query, bool keepColumns=false)
 Sets the query. More...
 
Query< Result > query () const
 Returns the query. More...
 
int addColumn (const std::string &field, const WString &header, WFlags< ItemFlag > flags=ItemFlag::Selectable)
 Adds a column. More...
 
int addColumn (const std::string &field, WFlags< ItemFlag > flags=ItemFlag::Selectable)
 Adds a column. More...
 
void setColumnFlags (int column, WFlags< ItemFlag > flags)
 Sets column item flags. More...
 
WFlags< ItemFlagcolumnFlags (int column) const
 Returns column item flags. More...
 
void addAllFieldsAsColumns ()
 Adds all the columns from the field list. More...
 
Result stableResultRow (int row) const
 Returns a stable result row. More...
 
const Result & resultRow (int row) const
 Returns a result row. More...
 
virtual Result & resultRow (int row)
 Returns a result row. More...
 
int indexOf (const Result &row) const
 Returns the index of row. More...
 
void reload ()
 Rereads the data from the database. More...
 
void setBatchSize (int count)
 Sets the batch size for fetching results. More...
 
int batchSize () const
 Returns the batch size for fetching results. More...
 
const std::vector< FieldInfo > & fields () const
 Returns the query field list. More...
 
const FieldInfofieldInfo (int column) const
 Returns the FieldInfo structure for a column.
 
const std::string & fieldName (int column) const
 Returns the field name for the a column.
 
virtual int columnCount (const WModelIndex &parent=WModelIndex()) const override
 Returns the number of columns. More...
 
virtual int rowCount (const WModelIndex &parent=WModelIndex()) const override
 Returns the number of rows. More...
 
virtual WFlags< ItemFlagflags (const WModelIndex &index) const override
 Returns the flags for an item. More...
 
virtual cpp17::any data (const WModelIndex &index, ItemDataRole role=ItemDataRole::Display) const override
 Returns the data for an item. More...
 
virtual bool setData (const WModelIndex &index, const cpp17::any &value, ItemDataRole role=ItemDataRole::Edit) override
 Sets data at the given model index. More...
 
virtual void sort (int column, SortOrder order=SortOrder::Ascending) override
 Sorts the model according to a particular column. More...
 
virtual std::string createOrderBy (int column, SortOrder order)
 Create specialized orderBy clause for sort. More...
 
virtual bool insertRows (int row, int count, const WModelIndex &parent=WModelIndex()) override
 Inserts one or more rows. More...
 
virtual bool removeRows (int row, int count, const WModelIndex &parent=WModelIndex()) override
 Removes one or more rows. More...
 
virtual bool setHeaderData (int column, Orientation orientation, const cpp17::any &value, ItemDataRole role=ItemDataRole::Edit) override
 Sets header data for a column. More...
 
virtual cpp17::any headerData (int section, Orientation orientation=Orientation::Horizontal, ItemDataRole role=ItemDataRole::Display) const override
 Returns header data. More...
 
virtual void * toRawIndex (const WModelIndex &index) const override
 Converts a model index to a raw pointer that remains valid while the model's layout is changed. More...
 
virtual WModelIndex fromRawIndex (void *rawIndex) const override
 Converts a raw pointer to a model index. More...
 
- Public Member Functions inherited from Wt::WAbstractTableModel
 WAbstractTableModel ()
 Creates a new abstract list model.
 
 ~WAbstractTableModel ()
 Destructor.
 
virtual WModelIndex parent (const WModelIndex &index) const override
 Returns the parent for a model index. More...
 
virtual WModelIndex index (int row, int column, const WModelIndex &parent=WModelIndex()) const override
 Returns the child index for the given row and column. More...
 
- Public Member Functions inherited from Wt::WAbstractItemModel
 WAbstractItemModel ()
 Creates a new data model.
 
virtual WFlags< HeaderFlagheaderFlags (int section, Orientation orientation=Orientation::Horizontal) const
 Returns the flags for a header. More...
 
virtual bool hasChildren (const WModelIndex &index) const
 Returns if there are children at an index. More...
 
virtual DataMap itemData (const WModelIndex &index) const
 Returns all data at a specific index. More...
 
virtual WModelIndexList match (const WModelIndex &start, ItemDataRole role, const cpp17::any &value, int hits=-1, WFlags< MatchFlag > flags=WFlags< MatchFlag >(MatchFlag::StartsWith|MatchFlag::Wrap)) const
 Returns an index list for data items that match. More...
 
cpp17::any data (int row, int column, ItemDataRole role=ItemDataRole::Display, const WModelIndex &parent=WModelIndex()) const
 Returns the data item at the given column and row. More...
 
virtual bool hasIndex (int row, int column, const WModelIndex &parent=WModelIndex()) const
 Returns if an index at the given position is valid (i.e. falls within the column-row bounds). More...
 
virtual bool insertColumns (int column, int count, const WModelIndex &parent=WModelIndex())
 Inserts one or more columns. More...
 
virtual bool removeColumns (int column, int count, const WModelIndex &parent=WModelIndex())
 Removes columns. More...
 
virtual bool setItemData (const WModelIndex &index, const DataMap &values)
 Sets data at the given model index. More...
 
bool setHeaderData (int section, const cpp17::any &value)
 Sets column header data. More...
 
virtual void expandColumn (int column)
 Expands a column. More...
 
virtual void collapseColumn (int column)
 Collapses a column. More...
 
virtual std::string mimeType () const
 Returns a mime-type for dragging a set of indexes. More...
 
virtual std::vector< std::string > acceptDropMimeTypes () const
 Returns a list of mime-types that could be accepted for a drop event. More...
 
virtual void dropEvent (const WDropEvent &e, DropAction action, int row, int column, const WModelIndex &parent)
 Handles a drop event. More...
 
bool insertColumn (int column, const WModelIndex &parent=WModelIndex())
 Inserts one column. More...
 
bool insertRow (int row, const WModelIndex &parent=WModelIndex())
 Inserts one row. More...
 
bool removeColumn (int column, const WModelIndex &parent=WModelIndex())
 Removes one column. More...
 
bool removeRow (int row, const WModelIndex &parent=WModelIndex())
 Removes one row. More...
 
bool setData (int row, int column, const cpp17::any &value, ItemDataRole role=ItemDataRole::Edit, const WModelIndex &parent=WModelIndex())
 Sets data at the given row and column. More...
 
virtual Signal< WModelIndex, int, int > & columnsAboutToBeInserted ()
 Signal emitted before a number of columns will be inserted. More...
 
virtual Signal< WModelIndex, int, int > & columnsAboutToBeRemoved ()
 Signal emitted before a number of columns will be removed. More...
 
virtual Signal< WModelIndex, int, int > & columnsInserted ()
 Signal emitted after a number of columns were inserted. More...
 
virtual Signal< WModelIndex, int, int > & columnsRemoved ()
 Signal emitted after a number of columns were removed. More...
 
virtual Signal< WModelIndex, int, int > & rowsAboutToBeInserted ()
 Signal emitted before a number of rows will be inserted. More...
 
virtual Signal< WModelIndex, int, int > & rowsAboutToBeRemoved ()
 Signal emitted before a number of rows will be removed. More...
 
virtual Signal< WModelIndex, int, int > & rowsInserted ()
 Signal emitted after a number of rows were inserted. More...
 
virtual Signal< WModelIndex, int, int > & rowsRemoved ()
 Signal emitted after a number of rows were removed. More...
 
virtual Signal< WModelIndex, WModelIndex > & dataChanged ()
 Signal emitted when some data was changed. More...
 
virtual Signal< Orientation, int, int > & headerDataChanged ()
 Signal emitted when some header data was changed. More...
 
virtual SignallayoutAboutToBeChanged ()
 Signal emitted when the layout is about to be changed. More...
 
virtual SignallayoutChanged ()
 Signal emitted when the layout is changed. More...
 
virtual SignalmodelReset ()
 Signal emitted when the model was reset. More...
 
- Public Member Functions inherited from Wt::WObject
void addChild (std::unique_ptr< WObject > child)
 Add a child WObject whose lifetime is determined by this WObject.
 
template<typename Child >
Child * addChild (std::unique_ptr< Child > child)
 Add a child WObject, returning a raw pointer. More...
 
std::unique_ptr< WObjectremoveChild (WObject *child)
 Remove a child WObject, so its lifetime is no longer determined by this WObject.
 
virtual const std::string id () const
 Returns the (unique) identifier for this object. More...
 
virtual void setObjectName (const std::string &name)
 Sets an object name. More...
 
virtual std::string objectName () const
 Returns the object name. More...
 
void resetLearnedSlots ()
 Resets learned stateless slot implementations. More...
 
template<class T >
void resetLearnedSlot (void(T::*method)())
 Resets a learned stateless slot implementation. More...
 
template<class T >
WStatelessSlot * implementStateless (void(T::*method)())
 Declares a slot to be stateless and learn client-side behaviour on first invocation. More...
 
template<class T >
WStatelessSlot * implementStateless (void(T::*method)(), void(T::*undoMethod)())
 Declares a slot to be stateless and learn client-side behaviour in advance. More...
 
void isNotStateless ()
 Marks the current function as not stateless. More...
 
template<class T >
WStatelessSlot * implementJavaScript (void(T::*method)(), const std::string &jsCode)
 Provides a JavaScript implementation for a method. More...
 
- Public Member Functions inherited from Wt::Core::observable
 observable ()
 Default constructor.
 
virtual ~observable ()
 Destructor. More...
 
template<typename... Args, typename C >
auto bindSafe (void(C::*method)(Args...))
 Protects a method call against object destruction. More...
 
template<typename... Args, typename C >
auto bindSafe (void(C::*method)(Args...) const) const
 Protects a const method call against object destruction. More...
 
template<typename Function >
auto bindSafe (const Function &function)
 Protects a function against object destruction. More...
 

Protected Member Functions

virtual Result createRow ()
 Creates a new row. More...
 
virtual void addRow (Result &result)
 Adds a row to the session. More...
 
virtual void deleteRow (Result &result)
 Deletes a row from the session. More...
 
virtual long long resultId (const Result &result) const
 Returns a unique id for a result. More...
 
virtual Result resultById (long long id) const
 Returns a result by id. More...
 
- Protected Member Functions inherited from Wt::WAbstractItemModel
void reset ()
 Resets the model and invalidate any data. More...
 
WModelIndex createIndex (int row, int column, void *ptr) const
 Creates a model index for the given row and column. More...
 
WModelIndex createIndex (int row, int column,::uint64_t id) const
 Creates a model index for the given row and column. More...
 
void beginInsertColumns (const WModelIndex &parent, int first, int last)
 Method to be called before inserting columns. More...
 
void beginInsertRows (const WModelIndex &parent, int first, int last)
 Method to be called before inserting rows. More...
 
void beginRemoveColumns (const WModelIndex &parent, int first, int last)
 Method to be called before removing columns. More...
 
void beginRemoveRows (const WModelIndex &parent, int first, int last)
 Method to be called before removing rows. More...
 
void endInsertColumns ()
 Method to be called after inserting columns. More...
 
void endInsertRows ()
 Method to be called after inserting rows. More...
 
void endRemoveColumns ()
 Method to be called after removing columns. More...
 
void endRemoveRows ()
 Method to be called after removing rows. More...
 
- Protected Member Functions inherited from Wt::WObject
virtual WStatelessSlot * getStateless (Method method)
 On-demand stateless slot implementation. More...
 

Additional Inherited Members

- Public Types inherited from Wt::WAbstractItemModel
typedef std::map< ItemDataRole, cpp17::any > DataMap
 Data map. More...
 
- Public Types inherited from Wt::WObject
typedef void(WObject::* Method) ()
 Typedef for a WObject method without arguments.
 

Detailed Description

template<class Result>
class Wt::Dbo::QueryModel< Result >

A Wt MVC Model to view/edit query results.

The model fetches results from the query and presents the data in a table. It supports sorting the underlying SQL query using Query::orderBy().

The default implementation of data() converts Query results to model data using query_result_traits<Result>::getValues(). You may define your own data presentation using the underlying Result by specializing data() and accessing data from resultRow().

You may selectively add fields that you want to display using addColumn(), or you can also add all columns based on the query using addAllFieldsAsColumns().

The model supports editing of the underlying data (even if the underlying query fetches results from multiple tables!). Values in columns that correspond to fields that have been mapped (and are writable) in a Database Object can be edited. The default implementation of setData() uses query_result_traits<Result>::setValue() to manipulate the database object, and thus uses the same write-behind properties as ptr<C>::modify(). To customize editing, you can specialize setData() and use resultRow() to modify the result object directly.

The model supports also inserting rows (only at the end), and removing rows, which are reflected in object additions and removals from the Session.

Editing is directly to the underlying database objects (change, insert and remove). Note that these changes will be flushed to the database whenever a transaction is committed, or before a query is run. The model will not explicitly create a transaction for the modification, but since the model uses a query for reading data, the change may be committed to the database depending on how the model is loading data. Still, this implies that usually inserting a row and setting its data happens within a single SQL "insert" statement.

To get good performance, the model keeps the following data cached:

Moreover, the model will try to fetch a batch of data even if you ask for the rowCount(), which may provide the row count as a side-effect if the query returns less results than a single batch size. If you do not want this behaviour (which might be the case if you are only interested in rowCount(), not the actual data) then you can avoid this behaviour by setting batchSize to 0.

Constructor & Destructor Documentation

template<class Result >
Wt::Dbo::QueryModel< Result >::QueryModel ( )

Creates a new query model.

You need to seed the model with a query using setQuery().

Member Function Documentation

template<class Result >
void Wt::Dbo::QueryModel< Result >::addAllFieldsAsColumns ( )

Adds all the columns from the field list.

All fields are added as columns. Fields that are mutable are marked as editable columns.

This is a convenient alternative to selectively adding columns using addColumn().

See also
fields()
template<class Result >
int Wt::Dbo::QueryModel< Result >::addColumn ( const std::string &  field,
const WString header,
WFlags< ItemFlag flags = ItemFlag::Selectable 
)

Adds a column.

The field name may be a qualified or unqualified field name. The list of available fields can be inspected using fields().

The header is used as Wt::ItemDataRole::Display for the column header data.

For the column items, flags() will returned the given flags. For example, to indicate that a field is editable, you can set the Wt::ItemFlag::Editable flag.

See also
fields()
template<class Result >
int Wt::Dbo::QueryModel< Result >::addColumn ( const std::string &  field,
WFlags< ItemFlag flags = ItemFlag::Selectable 
)

Adds a column.

This is an overloaded function for convenience, which uses the field name as the header value.

See also
setHeaderData()
template<class Result >
void Wt::Dbo::QueryModel< Result >::addRow ( Result &  result)
protectedvirtual

Adds a row to the session.

This method is called from within insertRows() to add (and save) a new result row to the Dbo session.

The default implementation uses query_result_traits<Result>::add().

template<class Result >
int Wt::Dbo::QueryModel< Result >::batchSize ( ) const

Returns the batch size for fetching results.

See also
setBatchSize()
template<class Result >
int Wt::Dbo::QueryModel< Result >::columnCount ( const WModelIndex parent = WModelIndex()) const
overridevirtual

Returns the number of columns.

Returns the number of columns that have been added using addColumn() or addAllFieldsAsColumns().

Since the query model implements a flat table model, this returns 0 when parent is valid.

Implements Wt::WAbstractItemModel.

template<class Result >
WFlags< ItemFlag > Wt::Dbo::QueryModel< Result >::columnFlags ( int  column) const

Returns column item flags.

See also
setColumnFlags()
template<class Result >
std::string Wt::Dbo::QueryModel< Result >::createOrderBy ( int  column,
SortOrder  order 
)
virtual

Create specialized orderBy clause for sort.

The sort() method calls createOrderBy() to format a SQL clause for use in Query<BindStrategy>::orderBy(). The default is to return a string that will sort on a single column in the specified order.

Customize this method if you need a more complex orderBy clause, e.g. to break ties consistently.

See also
sort()
template<class Result >
Result Wt::Dbo::QueryModel< Result >::createRow ( )
protectedvirtual

Creates a new row.

This method is called from within insertRows() to create a new row.

The default implementation uses query_result_traits<Result>::create().

template<class Result >
cpp17::any Wt::Dbo::QueryModel< Result >::data ( const WModelIndex index,
ItemDataRole  role = ItemDataRole::Display 
) const
overridevirtual

Returns the data for an item.

Returns data of type Wt::ItemDataRole::Display or Wt::ItemDataRole::Edit based on the field value corresponding to the index. If necessary, this fetches a batch of results from the underlying database.

The default implementation of data() converts Query results to model data using query_result_traits<Result>::getValues(). You may define your own data presentation using the underlying Result by specializing data() and accessing data from resultRow().

Implements Wt::WAbstractItemModel.

template<class Result >
void Wt::Dbo::QueryModel< Result >::deleteRow ( Result &  result)
protectedvirtual

Deletes a row from the session.

This method is called from within removeRows() to remove (and delete) a new result row from the Dbo session.

The default implementation uses query_result_traits<Result>::remove().

template<class Result >
const std::vector< FieldInfo > & Wt::Dbo::QueryModel< Result >::fields ( ) const

Returns the query field list.

This returns the field list from the underlying query.

template<class Result >
WFlags< ItemFlag > Wt::Dbo::QueryModel< Result >::flags ( const WModelIndex index) const
overridevirtual

Returns the flags for an item.

Returns the flags set for the column using setColumnFlags().

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
WModelIndex Wt::Dbo::QueryModel< Result >::fromRawIndex ( void *  rawIndex) const
overridevirtual

Converts a raw pointer to a model index.

Use this method to create model index from temporary raw pointers. It is the reciproce method of toRawIndex().

You can return an invalid modelindex if the rawIndex no longer points to a valid item because of the layout change.

See also
toRawIndex()

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
cpp17::any Wt::Dbo::QueryModel< Result >::headerData ( int  section,
Orientation  orientation = Orientation::Horizontal,
ItemDataRole  role = ItemDataRole::Display 
) const
overridevirtual

Returns header data.

See also
setHeaderData()

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
int Wt::Dbo::QueryModel< Result >::indexOf ( const Result &  row) const

Returns the index of row.

If the row isn't contained in the model, returns -1.

template<class Result >
bool Wt::Dbo::QueryModel< Result >::insertRows ( int  row,
int  count,
const WModelIndex parent = WModelIndex() 
)
overridevirtual

Inserts one or more rows.

Row insertions are only supported at the end (row == rowCount()). For each added row, a new result is added to the underlying database.

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
Query< Result > Wt::Dbo::QueryModel< Result >::query ( ) const

Returns the query.

See also
setQuery()
template<class Result >
void Wt::Dbo::QueryModel< Result >::reload ( )

Rereads the data from the database.

This invalidates the current (cached) data and informs views that they should rerender. This emits the layoutAboutToBeChanged() signal to inform the views that data and perhaps also row count was changed.

template<class Result >
bool Wt::Dbo::QueryModel< Result >::removeRows ( int  row,
int  count,
const WModelIndex parent = WModelIndex() 
)
overridevirtual

Removes one or more rows.

For each removed row, the result is removed from the underlying database.

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
Result Wt::Dbo::QueryModel< Result >::resultById ( long long  id) const
protectedvirtual

Returns a result by id.

This should be the inverse of the resultId() function.

The default implementation uses query_result_traits<Result>::findById().

template<class Result >
long long Wt::Dbo::QueryModel< Result >::resultId ( const Result &  result) const
protectedvirtual

Returns a unique id for a result.

This should, if possible, identify the result using a unique long long id, and otherwise return -1.

The default implementation uses query_result_traits<Result>::id().

This is required for a working stableResultRow() implementation.

See also
resultById()
template<class Result >
const Result & Wt::Dbo::QueryModel< Result >::resultRow ( int  row) const

Returns a result row.

This returns the result corresponding to a particular row, and could be used to customize the model behaviour, e.g. by specializing data() for certain columns.

Returns a const reference to an entry in the result cache.

template<class Result >
Result & Wt::Dbo::QueryModel< Result >::resultRow ( int  row)
virtual

Returns a result row.

This returns the result corresponding to a particular row, and could be used to customize the model behaviour, e.g. by specializing setData() for certain columns.

Returns a reference to an entry in the result cache.

See also
resultRow(int row) const
template<class Result >
int Wt::Dbo::QueryModel< Result >::rowCount ( const WModelIndex parent = WModelIndex()) const
overridevirtual

Returns the number of rows.

Returns the number of rows return from the underlying query.

Since the query model implements a flat table model, this returns 0 when parent is valid.

Implements Wt::WAbstractItemModel.

template<class Result >
void Wt::Dbo::QueryModel< Result >::setBatchSize ( int  count)

Sets the batch size for fetching results.

The model fetches results from the query in batch, and caches these in memory to avoid repetitive querying of the database.

The default batch size is 40.

template<class Result >
void Wt::Dbo::QueryModel< Result >::setColumnFlags ( int  column,
WFlags< ItemFlag flags 
)

Sets column item flags.

For items in column column, flags() will returned the given flags. For example, to indicate that a field is editable, you can set the Wt::ItemFlag::Editable flag.

template<class Result >
bool Wt::Dbo::QueryModel< Result >::setData ( const WModelIndex index,
const cpp17::any &  value,
ItemDataRole  role = ItemDataRole::Edit 
)
overridevirtual

Sets data at the given model index.

If role = Wt::ItemDataRole::Edit, sets the value for the field corresponding to the index. All other editing is ignored.

See also
setCachedResult()

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
bool Wt::Dbo::QueryModel< Result >::setHeaderData ( int  column,
Orientation  orientation,
const cpp17::any &  value,
ItemDataRole  role = ItemDataRole::Edit 
)
overridevirtual

Sets header data for a column.

The model will return this data in headerData(). Only column headers are supported (orientation == Wt::Orientation::Horizontal).

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
void Wt::Dbo::QueryModel< Result >::setQuery ( const Query< Result > &  query,
bool  keepColumns = false 
)

Sets the query.

The query is used to query the database.

Unless keepColumns is true, this resets the column list, so you will need to (re-)add one or more columns using addColumn().

When keeping the current columns, a LayoutChange rather than a Reset is emitted by the model, allowing views to keep their column geometry as well.

template<class Result >
void Wt::Dbo::QueryModel< Result >::sort ( int  column,
SortOrder  order = SortOrder::Ascending 
)
overridevirtual

Sorts the model according to a particular column.

This sorts the model by changing the query using Query<BindStrategy>::orderBy().

See also
createOrderBy()

Reimplemented from Wt::WAbstractItemModel.

template<class Result >
Result Wt::Dbo::QueryModel< Result >::stableResultRow ( int  row) const

Returns a stable result row.

This return the same result row as was previously returned by resultRow(), even if there were database inserts going on.

This requires suitable implementations for resultId() and resultById() functions.

If the row wasn't fetched before (or since a reload()), then the result of resultRow() is returned instead.

template<class Result >
void * Wt::Dbo::QueryModel< Result >::toRawIndex ( const WModelIndex index) const
overridevirtual

Converts a model index to a raw pointer that remains valid while the model's layout is changed.

Use this method to temporarily save model indexes while the model's layout is changed by for example a sorting operation.

The default implementation returns 0, which indicates that the index cannot be converted to a raw pointer. If you reimplement this method, you also need to reimplemnt fromRawIndex().

See also
layoutAboutToBeChanged, sort(), fromRawIndex()

Reimplemented from Wt::WAbstractItemModel.


Generated on Mon Sep 4 2017 for the C++ Web Toolkit (Wt) by doxygen 1.8.11