cutelyst 4.3.0
A C++ Web Framework built on top of Qt, using the simple approach of Catalyst (Perl) framework.
Cutelyst::Controller Class Reference

Cutelyst Controller base class. More...

#include <Cutelyst/Controller>

Inheritance diagram for Cutelyst::Controller:

Public Member Functions

 Controller (QObject *parent=nullptr)
 
ActionactionFor (QStringView name) const
 
ActionList actions () const noexcept
 
QString ns () const noexcept
 
bool operator== (const char *className)
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo () const const
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isQuickItemType () const const
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_GADGET_EXPORT (EXPORT_MACRO)
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_MOC_INCLUDE Q_MOC_INCLUDE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qobject_cast (const QObject *object)
 
qobject_cast (QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setObjectName (QAnyStringView name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Protected Member Functions

bool _DISPATCH (Context *c)
 
virtual bool postFork (Application *app)
 
virtual bool preFork (Application *app)
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Friends

class Application
 
class Dispatcher
 

Related Symbols

(Note that these are not member symbols.)

#define C_ATTR(X, Y)
 
#define C_NAMESPACE(value)
 
#define CActionFor(str)
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Properties inherited from QObject
 objectName
 

Detailed Description

Controllers are where the actions in the Cutelyst framework reside. Each action is represented by a function/method with an attribute to identify what kind of action it is. See the Cutelyst::Dispatcher for more information about how Cutelyst dispatches to actions.

Controller namespace

If not explicitely set by C_NAMESPACE() macro, the controller namespace will be generated from the C++ class name and optional C++ namespace name the class is part of. Camel-case class and namespace names like FooBar will be converted into a controller namespace foo/bar, while Foo would be only the foo controller namespace. A class FooBar inside C++ namespace FuBaz would have the controller namespace /fu/baz/foo/bar.

The controller namespace will be prepended to the public path of your controller methods unless you specify a global public path.

A root namespace can be created by setting an empty controller namespace with C_NAMESPACE("").

Private and public paths

Public paths are the routes that you can call with your user agent like the web browser. Private paths are internally used and can for example be used to get an URI via Context::uriForAction(). The public path has not to be the same like the private path, but it can be the same.

While the public path is created with the :Path attribute prepended by the controller namespace or from multiple
:Chained actions, the private path will be the function/method name prepended by the controller namespace.

Method attributes

Use the C_ATTR() macro to give hints about methods build like C_ATTR(methodName, options), where options are some of the following:

:Path
An ending public path relative to the controller namespace. The public path has not to be the same as the method name but it can. For example:
:Path("") - /namespace (used for the index)
:Path("foo") - /namespace/foo
:Path("/bar") - /bar
:Global
Alias to :Path("/methodname") which sets the method relative to your root.
:Local
Alias to :Path("methodname").
:Chained
Sets the name of this part of the chain. If it is specified without arguments, it takes the name of the action as default. To starte a chain use :Chained("/").
:PathPart
The part of the chained path.
:Args

Indicates the number of expected arguments on a public path. If omitted, an unlimited number of args will be accepted. Can also be set to 0 to expect no arguments.

Arguments are the request url parts behind your public route path. Like if your public path is /foo/bar and you call /foo/bar/fu/baz and there is no other path fitting that and if your /foo/bar path will expect two arguments, the method behind foo/bar would be called with the two arguments 'fu' and 'baz'.

:AutoArgs
Will calculate the number of expected arguments from the number of method arguments where the pointer to the Context ist not counted. Can not be mixed with :AutoCaptureArgs.
:CaptureArgs
Indicates the number of expected arguments on a publich chain path part.
:AutoCaptureArgs
Will calculate the number of expected capture arguments for chain parts from the number of method arguments where the pointer to the Context is not counted. Can not be mixed with :AutoArgs.
:Private
Marks a method as private. Can also be achieved by declaring the method in the private section of your class declaration. This attribute can be useful if you want to mark a public method as private for the dispatcher. It can still be used as public method by your C++ code but will be visible for the dispatcher as private.

Method arguments

Methods are only exposed to the dispatcher when they have a C_ATTR() macro in front and have a pointer to a Context object as first parameter. If the method should take request arguments it should either have QStringList to take the arguments from Request::arguments() or the expected amount of QString parameters.

Special methods

There are also three special methods that can be implemented that will be automatically dispatched, they are Begin(), Auto() and End().

Begin(Context*)

Called on the closest namespace match. If the Controller implements Begin(), it’s that action that will be called. Otherwise it will try to match looking at the namespace. So there will be only one Begin() action dispatched.

Begin will be dispached as first action before the Auto() actions and the actual action will be dispatched.

Auto(Context*)
Called in namespace order after the Begin() action (if any) and before the actual action. If you have a Foo and a FooBar controller with 'foo' and 'foo/bar' namespaces and both implement Auto() and you call an action on the 'foo/bar' namespace, you get Foo->Auto() and FooBar->Auto() called.
End(Context*)
Called on the closest namespace match. If the Controller implements End(), it’s that action that will be called. Otherwise it will try to match looking at the namespace. So there will be only one End() action dispatched.

Examples

#include <Cutelyst/Controller>
using namespace Cutelyst;
class Root : public Controller
{
// set this as the root namespace
C_NAMESPACE("")
Q_OBJECT
public:
explicit Root(QObject *parent = nulltr);
~Root() override;
// Will create a nameless path on the empty root path
// without any arguments expected what will give a public
// path of '/'. The private path will be '/index'.
C_ATTR(index, :Path :Args(0))
void index(Context *c);
// Will create a nameless path on the empty root path
// taking an unlimited count of arguments that will give
// a public path '/...', where the dots indicate the unlimited
// count of arguments.
C_ATTR(defaultPage, :Path)
void defaultPage(Context *c);
};
// will have the namespace 'foo/bar'
class FooBar : public Controller
{
Q_OBJECT
public:
explicit FooBar(QObject *parent = nullptr);
~FooBar() override;
// Will create a nameless path on the namespace 'foo/bar'
// without any arguments expected what will give a public
// path of '/foo/bar'. The private path will be '/foo/bar/index'.
C_ATTR(index, :Path :AutoArgs)
void index(Context *c);
// Will create the path 'baaaz' on the namespace 'foo/bar'
// with one expected argument what will give a public path
// of '/foo/bar/baaaz/∗', where the asterisk indicates the expected
// single argument that will be given to the arg parameter of the
// method. The private path will be '/foo/bar/baz'.
C_ATTR(baz, :Path("baaaz") :Args(1))
void baz(Context *c, const QString &arg);
};
namespace Api {
// will have the namespace 'api/books'
class Books : public Controller
{
Q_OBJECT
punlic:
explicit Books(QObject *parent = nullptr);
~Books() override;
// Will create a nameless path on the namespace 'api/books'
// without any arguments expected waht will give a public
// path of '/api/books'. The private path will be '/api/books/index'.
C_ATTR(index, :Path :Args(0))
void index(Context *c);
// Will create a chain start path capturing zero arguments.
// Can be used to setup stuff for other chained actions.
// There will be no public path for this. The private path will be
// '/api/books/base'.
C_ATTR(base, :Chained("/") :PathPart("api/books") :CaptureArgs(0))
void base(Context *c);
// Will create a chained action based on 'base' taking three arguments.
// The public path will be '/api/books/create/∗/∗/∗' while the private
// path will be '/api/books/create'. Will also end the chain with taking
// three arguments.
C_ATTR(create, :Chained("base") :PathPart("create") :Args(3))
void create(Context *c, const QString &title,
const QString &rating,
const QString &author);
// Will create a chain start path capturing one argument..
// Can be used to setup stuff for other chained actions.
// There will be no public path for this. The private path will be
// '/api/books/author'.
C_ATTR(author, :Chained("/") :PathPart("api/author") :CaptureArgs(1))
void author(Context *c, const QString &authorId);
// Will create a chained action based on 'author' taking zerog arguments
// and ending the chain. Will have a public path of '/api/author/∗/remove',
// the private path will be '/api/books/remove'.
C_ATTR(remove, :Chained("author") :PathPart("remove") :Args(0))
void remove(Context *c);
};
}
The Cutelyst Context.
Definition context.h:42
Cutelyst Controller base class.
Definition controller.h:56
The Cutelyst namespace holds all public Cutelyst API.

Definition at line 55 of file controller.h.

Constructor & Destructor Documentation

◆ Controller()

Controller::Controller ( QObject parent = nullptr)
explicit

Constructs a Controller object with the given parent.

Definition at line 240 of file controller.cpp.

◆ ~Controller()

Controller::~Controller ( )
virtual

Definition at line 246 of file controller.cpp.

Member Function Documentation

◆ _DISPATCH()

bool Controller::_DISPATCH ( Context c)
protected

This is called by the dispatch engine to do the contextual action dispatching. Transversing nearest Begin(), each namespace’s Auto(), the Action method of this controller and nearest End().

Definition at line 377 of file controller.cpp.

References Cutelyst::Context::action, and Cutelyst::Action::dispatch().

Referenced by Cutelyst::Dispatcher::dispatch().

◆ actionFor()

Action * Controller::actionFor ( QStringView  name) const

Returns the Cutelyst::Action object (if any) for a given method name in this class namespace.

You can also use the macro CActionFor to keep the resolved action around.

Definition at line 259 of file controller.cpp.

References QStringView::toString().

Referenced by Cutelyst::RoleACL::dispatcherReady().

◆ actions()

ActionList Controller::actions ( ) const
noexcept

Returns the Cutelyst::ActionList containing all actions which belongs to this controller.

Definition at line 269 of file controller.cpp.

Referenced by Cutelyst::Dispatcher::setupActions().

◆ ns()

QString Controller::ns ( ) const
noexcept

This specifies the internal namespace the controller should be bound to. By default the controller is bound to the URI version of the controller name. For instance a controller named 'MyFooBar' will be bound to 'my/foo/bar'. The default Root controller is an example of setting namespace to '' (the null string).

See also
Controller namespace

Definition at line 253 of file controller.cpp.

◆ operator==()

bool Controller::operator== ( const char *  className)

Return TRUE if className is equal to this Controller's name

Definition at line 275 of file controller.cpp.

References QObject::metaObject().

◆ postFork()

bool Controller::postFork ( Application app)
protectedvirtual

This method is called after the application has registered all controllers.

Reimplement this method if you need to configure internal variable and you need to know for example which configuration options are enabled.

Definition at line 286 of file controller.cpp.

◆ preFork()

bool Controller::preFork ( Application app)
protectedvirtual

This method is called right after Controller has been setup and before application forks and postFork() is called.

Reimplement this method if you need to configure internal variable and you need to know for example which configuration options are enabled.

Definition at line 280 of file controller.cpp.

Friends And Related Symbol Documentation

◆ Application

friend class Application
friend

Definition at line 129 of file controller.h.

◆ C_ATTR

#define C_ATTR (   X,
 
)
related

Sets method attributes Y to method X and marks the method as Q_INVOKABLE.

...
C_ATTR(index, :Path :Args(0))
void index(Context *c);
C_ATTR(pageNotFound, :Path)
void pageNotFound(Context *c;
...
#define C_ATTR(X, Y)
Definition controller.h:41

Definition at line 41 of file controller.h.

◆ C_NAMESPACE

#define C_NAMESPACE (   value)
related

Explicitely sets the controller namespace to value. Use this in the private part of your controller declaration.

Definition at line 23 of file controller.h.

◆ CActionFor

#define CActionFor (   str)
related

Definition at line 46 of file controller.h.

◆ Dispatcher

friend class Dispatcher
friend

Definition at line 130 of file controller.h.