cppmicroservices-webconsole - Man Page

cppmicroservices-webconsole — CppMicroServices Web Console API

These classes are the main API to the WebConsole bundle

WARNING:

class AbstractWebConsolePlugin : public cppmicroservices::HttpServlet

The Web Console can be extended by registering an OSGi service for the interface HttpServlet with the service property org.cppmicroservices.webconsole.label set to the label (last segment in the URL) of the page.

The respective service is called a Web Console Plugin or a plugin for short.

To help rendering the response the Web Console bundle provides two options. One of the options is to extend the AbstractWebConsolePlugin overwriting the RenderContent(HttpServletRequest&, HttpServletResponse&) method.

Subclassed by cppmicroservices::SimpleWebConsolePlugin

Public Types

using TemplateData = Kainjow::Mustache::Data

Public Functions

virtual std::string GetLabel() const = 0

Retrieves the label.

This is the last component in the servlet path.

Returns

the label.

virtual std::string GetTitle() const = 0

Retrieves the title of the plug-in.

It is displayed in the page header and is also included in the title of the HTML document.

Returns

the plugin title.

virtual std::string GetCategory() const

This method should return category string which will be used to render the plugin in the navigation menu.

Default implementation returns null, which will result in the plugin link rendered as top level menu item. Concrete implementations wishing to be rendered as a sub-menu item under a category should override this method and return a string or define org.cppmicroservices.webconsole.category service property. Currently only single level categories are supported. So, this should be a simple string.

Returns

category

virtual std::shared_ptr<WebConsoleVariableResolver> GetVariableResolver(HttpServletRequest &request)

virtual void SetVariableResolver(HttpServletRequest &request, std::shared_ptr<WebConsoleVariableResolver> const &resolver)

Protected Functions

virtual bool IsHtmlRequest(HttpServletRequest &request)

Detects whether this request is intended to have the headers and footers of this plugin be rendered or not.

This method always returns true and may be overwritten by plugins to detect from the actual request, whether or not to render the header and footer.

Parameters

request -- the original request passed from the HTTP server

Returns

true if the page should have headers and footers rendered

virtual void DoGet(HttpServletRequest &request, HttpServletResponse &response)

Renders the web console page for the request.

This consist of the following five parts called in order: .INDENT 7.0

i.

Send back a requested resource

ii.

StartResponse(HttpServletRequest&, HttpServletResponse&)

iii.

RenderTopNavigation(HttpServletRequest&, std::ostream&)

iv.

RenderContent(HttpServletRequest&, HttpServletResponse&)

v.

EndResponse(HttpServletRequest&, std::ostream&)

If the IsHtmlRequest(HttpServletRequest&) method returns false only the RenderContent(HttpServletRequest&, HttpServletResponse&) method is called.

SEE ALSO:

HttpServlet::DoGet(HttpServletRequest&, HttpServletResponse&)

NOTE:

If a resource is sent back for the request only the first step is executed. Otherwise the first step is a null-operation actually and the latter four steps are executed in order.

virtual void RenderContent(HttpServletRequest &request, HttpServletResponse &response) = 0

This method is used to render the content of the plug-in.

It is called internally from the Web Console.

Parameters

• request -- the HTTP request send from the user
• response -- the HTTP response object, where to render the plugin data.

std::ostream &StartResponse(HttpServletRequest &request, HttpServletResponse &response)

This method is responsible for generating the top heading of the page.

SEE ALSO:

EndResponse(HttpServletRequest&, std::ostream&)

Parameters

• request -- the HTTP request coming from the user
• response -- the HTTP response, where data is rendered

Returns

the stream that was used for generating the response.

void RenderTopNavigation(HttpServletRequest &request, std::ostream &writer)

This method is called to generate the top level links with the available plug-ins.

Parameters

• request -- the HTTP request coming from the user
• writer -- the writer, where the HTML data is rendered

void EndResponse(HttpServletRequest &request, std::ostream &writer)

This method is responsible for generating the footer of the page.

SEE ALSO:

StartResponse(HttpServletRequest&, HttpServletResponse&)

Parameters

• request -- the HTTP request coming from the user
• writer -- the writer, where the HTML data is rendered

std::vector<std::string> GetCssReferences() const

Returns a list of CSS reference paths or null if no additional CSS files are provided by the plugin.

The result is an array of strings which are used as the value of the href attribute of the <link> elements placed in the head section of the HTML generated. If the reference is a relative path, it is turned into an absolute path by prepending the value of the WebConsoleConstants::ATTR_APP_ROOT request attribute.

Returns

The list of additional CSS files to reference in the head section or an empty list if no such CSS files are required.

std::string ReadTemplateFile(std::string const &templateFile, cppmicroservices::BundleContext context = cppmicroservices::GetBundleContext()) const

class SimpleWebConsolePlugin : public cppmicroservices::AbstractWebConsolePlugin

SimpleWebConsolePlugin is a utility class that provides a default implementation of the AbstractWebConsolePlugin and supports the following features:

• Methods for (un)registering the web console plugin service
• Default implementation for resource loading

Public Functions

SimpleWebConsolePlugin(std::string const &label, std::string const &title, std::string category = std::string(), std::vector<std::string> css = std::vector<std::string>())

Creates new Simple Web Console Plugin with the given category.

Parameters

• label -- the front label. See AbstractWebConsolePlugin::GetLabel()
• title -- the plugin title . See AbstractWebConsolePlugin::GetTitle()
• category -- the plugin's navigation category. See AbstractWebConsolePlugin::GetCategory()
• css -- the additional plugin CSS. See AbstractWebConsolePlugin::GetCssReferences()

virtual std::string GetLabel() const

SEE ALSO:

AbstractWebConsolePlugin::GetLabel()

virtual std::string GetTitle() const

SEE ALSO:

AbstractWebConsolePlugin::GetTitle()

virtual std::string GetCategory() const

SEE ALSO:

AbstractWebConsolePlugin::GetCategory()

std::shared_ptr<SimpleWebConsolePlugin> Register(BundleContext const &context = GetBundleContext())

This is an utility method.

It is used to register the plugin service. Don't forget to call Unregister() when the plugin is no longer needed.

Parameters

context -- the bundle context used for service registration.

Returns

A shared pointer to this plugin.

void Unregister()

An utility method that removes the service, registered by the Register(const BundleContext&) method.

Protected Functions

std::vector<std::string> GetCssReferences() const

SEE ALSO:

AbstractWebConsolePlugin::GetCssReferences()

BundleContext GetContext() const

struct WebConsoleConstants

WebConsoleConstants provides some common constants that are used by plugin developers.

Public Static Attributes

static std::string SERVICE_NAME

The name of the service to register as to be used as a "plugin" for the web console (value is "cppmicroservices::HttpServlet").

static std::string PLUGIN_LABEL

The URI address label under which the Web Console plugin is called (value is "org.cppmicroservices.webconsole.label").

This service registration property must be set to a single non-empty string value. Otherwise the Servlet services will be ignored by the Web Console and not be used as a plugin.

static std::string PLUGIN_TITLE

The title under which the Web Console plugin is called (value is "org.cppmicroservices.webconsole.title").

For Servlet services not extending the AbstractWebConsolePlugin this property is required for the service to be used as a plugin. Otherwise the service is just ignored by the Web Console.

For Servlet services extending from the AbstractWebConsolePlugin abstract class this property is not technically required. To support lazy service access, e.g. for plugins implemented using the Service Factory pattern, the use of this service registration property is encouraged.

static std::string PLUGIN_CATEGORY

The category under which the Web Console plugin is listed in the top navigation (value is "org.cppmicroservices.webconsole.category").

For Servlet services not extending the AbstractWebConsolePlugin this property is required to declare a specific category. Otherwise the plugin is put into the default category.

For Servlet services extending from the AbstractWebConsolePlugin abstract class this property is not technically required. To support lazy service access with categorization, e.g. for plugins implemented using the Service Factory pattern, the use of this service registration property is strongly encouraged. If the property is missing the AbstractWebConsolePlugin::GetCategory() is called which should be overwritten.

static std::string PLUGIN_CSS_REFERENCES

The name of the service registration properties providing references to addition CSS files that should be loaded when rendering the header for a registered plugin.

This property is expected to be a single string value or a vector of string values.

This service registration property is only used for plugins registered as SERVICE_NAME services which do not extend the AbstractWebConsolePlugin. Extensions of the AbstractWebConsolePlugin should overwrite the AbstractWebConsolePlugin::GetCssReferences() method to provide additional CSS resources.

static std::string ATTR_APP_ROOT

The name of the request attribute providing the absolute path of the Web Console root (value is "org.cppmicroservices.webconsole.appRoot").

This consists of the servlet context path (from HttpServletRequest::GetContextPath()) and the Web Console servlet path (from HttpServletRequest::GetServletPath(), /us/console by default).

The type of this request attribute is std::string.

static std::string ATTR_PLUGIN_ROOT

The name of the request attribute providing the absolute path of the current plugin (value is "org.cppmicroservices.webconsole.pluginRoot").

This consists of the servlet context path (from HttpServletRequest::GetContextPath()), the configured path of the web console root (/us/console by default) and the plugin label PLUGIN_LABEL.

The type of this request attribute is std::string.

static std::string ATTR_LABEL_MAP

The name of the request attribute providing a mapping of labels to page titles of registered console plugins (value is "org.cppmicroservices.webconsole.labelMap").

This map may be used to render a navigation of the console plugins as the AbstractWebConsolePlugin::RenderTopNavigation(HttpServletRequest&, std::ostream&) method does.

The type of this request attribute is AnyMap.

static std::string ATTR_CONSOLE_VARIABLE_RESOLVER

The name of the request attribute holding the WebConsoleVariableResolver for the request (value is "org.cppmicroservices.webconsole.variable.resolver").

SEE ALSO:

WebConsoleVariableResolver

SEE ALSO:

AbstractWebConsolePlugin::GetVariableResolver

SEE ALSO:

AbstractWebConsolePlugin::SetVariableResolver

class WebConsoleDefaultVariableResolver : public cppmicroservices::WebConsoleVariableResolver

The default Web Console variable resolver class.

This variable resolver uses Mustache template logic to resolve variables.

Public Functions

virtual std::string Resolve(std::string const &variable) const

Returns a replacement value for the named variable.

Parameters

variable -- The name of the variable for which to return a replacement.

Returns

The replacement value.

MustacheData &GetData()

struct WebConsoleVariableResolver

The WebConsoleVariableResolver interface defines the API for an object which may be provided by plugins to provide replacement values for variables in the generated content.

Plugins should call the AbstractWebConsolePlugin::SetVariableResolver method to provide their implementation for variable resolution.

The main use of such a variable resolver is when a plugin is using a static template which provides slots to place dynamically generated content parts.

SEE ALSO:

AbstractWebConsolePlugin::GetVariableResolver(HttpServletRequest&)

SEE ALSO:

AbstractWebConsolePlugin::SetVariableResolver

NOTE:

The variable resolver must be set in the request before the response stream is retrieved calling the HttpServletResponse::GetOutputStream method. Otherwise the variable resolver will not be used for resolving variables.

Subclassed by cppmicroservices::WebConsoleDefaultVariableResolver

Public Functions

virtual ~WebConsoleVariableResolver()

virtual std::string Resolve(std::string const &variable) const = 0

Returns a replacement value for the named variable.

Parameters

variable -- The name of the variable for which to return a replacement.

Returns

The replacement value.

CppMicroServices Team

2017-2023, CppMicroServices Contributors