Main  /  Edit  /  History  /   /  Users Area

Forms in CppCMS

Table of Contents

Basic Concepts

First of all, it is recommended to read a tutorial Start With Forms

Forms system of CppCMS has three major types of classes:

  1. Form -- cppcms::form --- the base class for form container, It is responsible on form validation, rendering. Usually, user derives its own classes from cppcms::form
  2. Widgets in the namespace cppcms::widgets. They are basic elements of form like input text, number, checkbox, submit button etc.
  3. cppcms::widgetset --- simple class for partial rendering of forms for easier integration with templates.

All of them are derived from base_form that provide basic interface for loading, rendering and validation of forms.

Class cppcms::form

This class used as base class for any HTML form developer wants to create. This class is non-copyable and used as container for loading, validating and rendering widgets.

Member functions

Class cppcms::widgetset

Is a container that is similar to form but it is used only for rendering different types of widgets.

It has following important member function:

widgetset &operator<<(widgets::base_widget &w);

That allows registering of various widgets to the set. For example:

struct op {
  widgets::number<int> x,y;
  widgets::button add,sub,mul,div;
  widgetset inputs;
  widgetset ops;
  op() : 
     *this & x & y & add & sub & mul & div;

Now can write template:

<% form as_table ops_form.inputs %>
<p><% form as_space ops_form.ops %></p>

Now push buttons and input fields are rendered using different methods.


Widgets are used for actual data loading and rendering. Each widget is derived from widgets::base_widget that hold all common data for all widgets. It is also used for creation of custom widgets by users.

Core Widget base_widget

Public Members

Note: Generally you should not assign values of is_set and is_valid directly. They are provided as public members for simpler integration with template system for custom widgets rendering.

Public Member Functions

Other functions would be described in section of custom widgets creation.

Text Input: widgets::text

This is text input widget.

Numerical Input: widgets::number<>

This widget is defined as:

template<typename N>
number : public text { ... };

It is used as input for numerical values. In addition to text members it implements following member functions:

Note: This widget uses boost::lexical_cast for conversion. Any type that is supported by boost::lexical_cast is supported by number widget.

Password Input: widgets::password

Used for input password values. It inherits from widgets::text.

Text Area: widgets::textarea

Inherits from widgets::text.

Complex Field Validation: widgets::regex_field

This widget allows you to check an input using regular expression. It uses boost::regex for this purpose. It inherits from widgets::text as well.

Note: You should provide regular expression of your own. For example:

static const regex date("\\d\\d-\\d\\d-\\d\\d\\d\\d");
regex_field date_input(date,"data","Enter Date");

Hidden Field: widgets::hidden

Hidden field can be used as widgets::hidden. This class inherits for widgets::text and by default it is set to non-empty.

Check Box: widgets::checkbox

This widget renders a checkbox.


Members Functions:

Public Members For Form Rendering

Note: You should never set these members directly. You may use them only for form rendering:

For example:

<intput name="<% %>" value="<% form.opt.input_value %>" 
  <% if form.opt.value %>checked="checked"<% end %> onclick="alert('Clicked!')" />

Single Choice Select

There are two widgets that are used for these purpose: select and radio that both inherit from select_base.

select_base members

Usually you should use string values or integer values and not mix them.

Public members for rendering:

Both widgets::select and widgets::radio has following ordinary constructors:

widgets::select members

widgets::radio members

Multiple Selection widgets::select_multiple

Multiple selection drop down list:


Public Member Functions

These functions are used similarly to those of select_base but they have selection marks options. Generally, you should not use both add(int,...) and add(string,...).

Public Members for Form Rendering

As in above cases these members may be used only for form rendering. Do not change them directly.

Submit Button: widgets::submit

Note: This widget checks only name filed and ignores value that may be localized. Thus, you should generally specify different names for different buttons:


Dynamic Creation Of Forms

In many cases it is required to create forms on-the-fly according to data that should be used. This can be done simply --- all widgets are default and copy constructable and assignable --- thus you just can create STL collections of them.

However, you should remember, that when you register your widgets in cppcms::form or in cppcms::widgetset you pass pointers to them and not their copies. Thus, be careful, make sure your widgets are not copied to other place.

For example:

struct opts : public form {
  std::vector<widgets::checkbox> options;
  widgets::submit button;

Wrong Code:

opts::opts() : button("send","Send")
  for(i=0;i<10;i++) {
                                        "Chose "_lexical_cast<string>(i+1)));
    *this & options.back();
  *this & button;

Correct Code:

opts::opts() : button("send","Send")
  for(i=0;i<10;i++) {
                                 "Chose "_lexical_cast<string>(i+1)));
    *this & options[i]; // Now vector would not reallocate its members
  *this & button;

Extending and Unsupported Features

If any of given widgets does not satisfy your needs you may:

  1. Create your own widgets. See, form.h and form.cpp for examples.
  2. Use cgicc library directly without no restriction.

See CgiCC Documentation


CppCMS is a web development framework for performance demanding applications.

Support This Project Logo

Поддержать проект

CppCMS needs You


Main Page

Valid CSS | Valid XHTML 1.0