diff options
Diffstat (limited to 'src/ivicore/doc/src/ivigenerator')
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/filter-reference.qdoc | 196 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/generator-usage.qdoc | 427 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/getting-started.qdoc | 77 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc | 318 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc | 46 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc | 121 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/remotebackends.qdoc | 70 | ||||
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/template-syntax.qdoc | 477 |
8 files changed, 1732 insertions, 0 deletions
diff --git a/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc b/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc new file mode 100644 index 0000000..c330fff --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc @@ -0,0 +1,196 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page filter-reference.html +\title Filter Reference +\previouspage Autogenerator Usage +\nextpage Qmake Integration + +In addition to the built-in Jinja filters listed \l +{http://jinja.pocoo.org/docs/2.9/templates/#list-of-builtin-filters} {here}, the following +additional features are implemented in the ivigenerator. + +\target return_type(symbol) +\target return_type() +\section1 return_type(symbol) + +Returns the C++ type for the passed symbol. + +E.g. QString for a symbol of type "string". + +\target parameter_type(symbol) +\section1 parameter_type(symbol) + +Return the C++ type for the passed symbol. This returns the same type as return_type(), but already +prepared to be used as a parameter for methods. + +E.g. "const QString &<name>" for a symbol of type "string" + +\target getter_name(symbol) +\section1 getter_name(symbol) + +Returns the getter name of the property, if defined by the \c @getter_name annotation. Otherwise +retuns the passed symbol. + +\target setter_name(symbol) +\section1 setter_name(symbol) + +Returns the setter name of the property, if defined by the \c @setter_name annotation. Otherwise +retuns the passed symbol. + +\target default_type_value(symbol) +\section1 default_type_value(symbol) + +Returns the default value for the passed symbol. Models are initialized as \c nullptr + +\target default_value(symbol, zone="=") +\section1 default_value(symbol, zone="=") + +Returns the default value for the passed symbol set by the \c @default annotation. If not set uses +\c default_type_value instead. + +The zone parameter is used to identify different default values per zone. + +\target model_type(symbol) +\section1 model_type(symbol) + +Returns the C++ class name for this model. + +\target flag_type(symbol) +\section1 flag_type(symbol) + +Returns the name defined by the \c @type annotation for the passed flag. If this is not set, tries to +pluralize the passed name by adding an 's' at the end. + +\target parse_doc(string) +\section1 parse_doc(string) + +Parses the passed comment string and adds every javadoc command into its own group. Sentences +without tag are put into the 'description' group. + +\badcode +{% with doc = comments|parse_doc -%} +{% if doc.brief %} \brief {{doc.brief}} +{% endif %} + +{% if doc.description %} + {{doc.description}} +{% endif %} +{% endwith %} +\endcode + +\target lowerfirst(string) +\section1 lowerfirst(string) + +Only lowers the first character of the given string. + +\target range_low(property) +\section1 range_low(property) + +Returns the minimum value for the passed property using the \c @range or \c @minimum annotations. + +\target range_high(property) +\section1 range_high(property) + +Returns the maximum value for the passed property using the \c @range or \c @maximum annotations. + +\target strip_QT(string) +\section1 strip_QT(string) + +Removes the 'QT' at the beginning, if the string starts with it. + +\target domain_values(symbol) +\section1 domain_values(symbol) + +Returns the domain values for the passed property using the \c @domain annotation. + +\target enum_value(value, module_name) +\section1 enum_value(value, module_name) + +Returns the fully qualified C++ name of the given value. The passed module_name is used as C++ class +name containing the enum. + +Also supports passing '|' connected values. + +\target tag_by_path(symbol, path, default_value=False) +\section1 tag_by_path(symbol, path, default_value=False) + +Find the tag given by its full path in the object hierarchy, like +\c property.config_sim.zones.right. If some parts of the path are missing, return \c None. + +\target conf_sim_tag(symbol, path, default_value=False) +\section1 conf_sim_tag(symbol, path, default_value=False) + +Find the tag, given by its path, located under the "config_simulator" sub-object. Returns \c None, +if parts of the path are missing. + +\target jsonify(obj) +\section1 jsonify(obj) + +Returns a JSON representation of the given obj. + +\target has_domains(properties) +\section1 has_domains(properties) + +Returns \c true if any of the given properties has \c @range or \c @domain annotations. + +\target json_domain(properties) +\section1 json_domain(properties) + +Returns the property domains for the given properties formated in JSON. + +\target qml_type(interface) +\section1 qml_type(interface) + +Returns the name of the interface for use in QML. This name is defined by the \c @qml_type +annotation. This annotation is optional: if not provided, the interface name is used. + +\target qml_control(symbol, backend_obj) +\section1 qml_control(symbol, backend_obj) + +Returns the QML code for the control (or group of controls) to represent the editing UI for the +passed symbol. + +\target qml_binding_property(symbol) +\section1 qml_binding_property(symbol) + +Returns the name of the property of the QML control to be bound with. + +E.g. "value" for a Slider and "checked" for a CheckBox. + +\target qml_control_signal_parameters(symbol) +\section1 qml_control_signal_parameters(symbol) + +Returns the parameters for calling the signal using the values from the UI controls. + +\target struct_includes(symbol) +\section1 struct_includes(symbol) + +Returns the includes for the structs that the interface or a struct depends on. The returned +strings are complete and in format #include "struct.h". +*/ + diff --git a/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc new file mode 100644 index 0000000..688633b --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc @@ -0,0 +1,427 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page generator-usage.html +\title Autogenerator usage +\previouspage Jinja template syntax +\nextpage Filter Reference + +This page is about the usage of the QtIVI auto-generator. + +\section1 Introduction + +The Generator is a Python script that can be run manually or using the \l {QMake Integration}. +This script uses QFace as the autogenerator framework which parses the IDL +file, generates the domain-model (similar to AST) and then feeds it to the actual generator. +Depending on the type of the generated project, different \e{formats} are specified. + +\section1 Command line parameters +The generation is run using the following command: +\code +$$[QT_HOST_BINS]/ivigenerator/generate.py --format=backend_simulator interface.qface out_dir +\endcode + +The options and parameters are: +\table + \row + \li --reload / --no-reload [optional] + \li specifies whether the generator should keep track of the changes in the IDL file + and update output on the fly (--no-reload by default) + \row + \li -f, --format [frontend|backend_simulator|control_panel|backend_qtro|server_qtro|<folder>] + \li see below + \row + \li --help + \li Show options and exit. + \row + \li source + \li Path or paths to the IDL source files. In case of multiple entries present, each one + will be handled. In case a directory path is provided, it will be scanned for all the IDL + files. + \row + \li outputdir + \li Generation destination folder +\endtable + +At the moment the generator is able to generate 5 kinds of projects given an interface IDL file +based on the \e {--format} option value. +These are: +\table + \row + \li \l {frontend} + \target frontend-template + \li Generates a developer facing API using base classes from qtivicore and the \l {Dynamic + Backend System} + \row + \li \l {Backend Simulator} {backend_simulator} + \target backend-simulator-template + \li Generates a simulation backend for the API generated by the "frontend" option. This + backend serves as a mock implementation. + \row + \li \l {Control Panel} {control_panel} + \target control-panel-template + \li Generates a controller application, consisting of an UI and a C++ plugin, which communicates + to the simulation backend generated from the same qface file using QtSimulator. + \row + \li \l {QtRemoteObjects Backend} {backend_qtro} + \target backend-qtro-template + \li Generates a QtRemoteObjects based backend client for the API generated by the "frontend" option. + This backend connects to a backend server. + \row + \li \l {QtRemoteObjects Server} {server_qtro} + \target server-qtro-template + \li Generates a QtRemoteObjects based backend server stub for the API generated by the "frontend" option. + \row + \li folder path + \li Uses templates inside the folder. A YAML file with the same name as the folder (and .yaml + extension) should provide a list of template files in the folder (see YAML format specification below). +\endtable + +\section1 YAML configuration + +The Python script is responsible for parsing the input files and for the creation of a domain +model. This domain model is passed as a context to the Jinja template engine. To control which +files are generated, the "Generation YAML" can be used. In addition, an "Annotations YAML" can be +used to add more information to the IDL file, which are generator specific. + +\section2 Generation YAML + +After the domain model tree has been created, this tree is traversed and each leaf of the domain +model object tree (module, interface, structure, etc) is passed to a specific Jinja template +defined by the configuration file. This file must be in YAML format and for every particular +generation format its name is defined in the script. This file must have the following structure: + +\code +generate_rules: + module_rules: + - dest_file: "{{module.module_name|lower}}plugin.h" + template_file: "plugin.h.tpl" + interface_rules: + - dest_file: '{{interface|lower}}backend.h' + template_file: 'backend.h.tpl' + struct_rules: +\endcode + +For every entity there is a list of templates needed to be called when traversing this entity +in the domain model tree. Here, \e{dest_file} is a name of the file need to be created specified in +the \l {Jinja template syntax}{Jinja template language} format: the value of the object property +used in the name template will be processed and substituted into the template, thus forming the +final name of the file to create. \e{dest_file} is a name of the template to be used. For the IVI +generator, rules for three kinds of entities need to be specified: modules, interfaces and +structures. + +\section2 Annotations YAML + +At the moment not all aspects of the interface description cannot be expressed using the IDL +itself. For instance there is no language construct to define default value for the property or +values the property can take on. Still this can be achieved via a mechanism called \l +{annotations_reference} {Annotations}. Annotations allow great freedom and flexibility of +expressing any concepts and constructs. + +Below is an example of using annotations in the IDL. Here it's defined that interface is zoned and +its identifier is specified. + +\code +@config: {zoned: true, id: "org.qt-project.qtivi.ClimateControl/1.2" } +\endcode + +Not all of the annotations make sense to be put in the main IDL file either. For instance, one may +need to define some aspects of generation of the auto-testing code. Such annotations can be put in +the YAML file accompanying the main IDL file and named after it. During the parse phase +QFace picks this file up automatically and merges annotation specified in this YAML file with those +defined in the IDL file. + +For QtIvi there are following annotations used for the IDL definition: + +\table + \header + \li Tag + \li Where + \li Object type + \li Purpose + \row + \li @config(interfaceBuilder: "FunctionName") + \li Main IDL file + \li Module + \li Declares a function which will be called in the plugin to generate the instances for every interface. + The function takes a pointer to the plugin instance and returns a \c {QVector<QIviFeatureInterface *>}. + Interfaces should be generated in the same order as defined by \c {Plugin::interfaces()}. + + This can be used to instanciate classes derived from the generated plugin interfaces classes. + \row + \li @config(zoned) + \li Main IDL file + \li Interface + \li tells the generator whether the interface is zoned or not. This allows to define + whether the backend feature interface is derived from QIviZonedFeatureInterface or from + QIviFeatureInterface + \row + \li @config(id=org.qt.project.qtivi.ClimateControl.1.0) + \li Main IDL file + \li Interface + \li defines the interface id. The id is a string used by the QtIvi service manager to glue + frontend interface and backend implementation together. See \l {Dynamic Backend System} + for more details. + \row + \li @config(getter_name) + \li Main IDL file + \li Property + \li Overrides the default getter method name. Useful for boolean properties (for example, getter + for property 'enabled', should be 'isEnabled' rather than the default). + \row + \li @config(setter_name) + \li Main IDL file + \li Property + \li Overrides the default setter method name. + \row + \li @config(qml_name) + \li Main IDL file + \li Module, Interface + \li Defines the name this interface/module should be using in QML. For interfaces, it is the + name which is used to export the interface to QML. For modules it defines the uri of the + complete module. +\endtable + +The annotations that are not logically part of the interface description but rather the ones used +for specifying additional information are put in the accompanying YAML file. Here is the list of +annotations used for defining various aspects of the generation of the backend-simulator: + +\table + \header + \li Tag + \li Where + \li Object type + \li Purpose + \row + \li + \code + config_simulator: + zones: { left : FrontLeft, right : FrontRight, rear: Rear } + \endcode + \li Accompanying YAML file + \li Interface + \li For the backend simulator defines a list of zones supported by the simulation code + with their names + \row + \li \code + config_simulator: + default: AirflowDirection.Floor | AirflowDirection.Dashboard + \endcode + \li Accompanying YAML file + \li Property + \li Defines the initial values for the property returned by the simulator backend. + + For zoned properties a mapping from a zone to a default value can be used. The default key of the map is "=". + \code + config_simulator: + default: { left: 21.0, right: 22.5, =: 0.0 } + \endcode + \row + \li \code + config_simulator: + minimum: 10 + \endcode + \li Accompanying YAML file + \li Property + \li Defines the minimum value for integer and real properties, generated code in the simulator backend will check for validity. + \row + \li \code + config_simulator: + maximum: 10 + \endcode + \li Accompanying YAML file + \li Property + \li Defines the maximum value for integer and real properties, generated code in the simulator backend will check for validity. + \row + \li \code + config_simulator: + range: [10, 20] + \endcode + \li Accompanying YAML file + \li Property + \li Defines the range value for integer and real properties, generated code in the simulator backend will check for validity. + \row + \li \code + config_simulator: + domain: {10, 20, 30} + \endcode + \li Accompanying YAML file + \li Property + \li Defines the possible values for the property, generated code in the simulator backend will check for validity. +\endtable + + +\section1 Generated projects structure + +In the generator output directory first a new subfolder with the name of the module id will be +created. All the generated files will be put in this folder. The following files will be generated: + +\section2 Frontend +\table + \header + \li File name + \li Purpose + \row + \li "{{module.module_name|lower}}global.h" + \li Standard file with global EXPORT defines + \row + \li "{{module.module_name|lower}}module.h/cpp" + \li Files defining a module class used for module global variables and types. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. + \row + \li "{{interface|lower}}backendinterface.h/cpp" + \li Files defining the interface need to be implemented by the backend implementation of + the feature + \row + \li "{{interface|lower}}.h/cpp" + \li Front end implementation of the feature, ready to be used from QML. + \row + \li "{{interface|lower}}_p.h" + \li Private part of the frontend implementation +\endtable + +\section2 Backend simulator + +\table + \header + \li File name + \li Purpose + \row + \li "{{module.module_name|lower}}plugin.h/cpp" + \li Files defining implementation of QtIvi backend plugin implementing + QIviServiceInterface + \row + \li "{{module.module_name|lower}}.json" + \li File containing identifiers of the exposed feature interfaces needed by the Qt plugin + system. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. + \row + \li "{{interface|lower}}backend.h/cpp" + \li Files containing the implementation of the simulation backend. +\endtable + +\section2 Control Panel + +The control_panel template is only available if the QtSimulator module was found. Please see the \l{feature-qtsimulator}{Configuration Page} +for more information. + +\table + \header + \li File name + \li Purpose + \row + \li "main.cpp" + \li Launcher code loading the QML code and exporting the C++ interface. + \row + \li "main.qml" + \li Main QML file containing the code to load the Control UIs for every interface. + \row + \li "qml.qrc" + \li QRC file for all QML code. + \row + \li "FlagControl.qml" + \li UI Element to control a flag inside a interface. + \row + \li "EnumControl.qml" + \li UI Element to control a enum inside a interface. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. + \row + \li "{{module.module_name|lower}}global.h" + \li Standard file with global EXPORT defines + \row + \li "{{module.module_name|lower}}module.h/cpp" + \li Files defining a module class used for module global variables and types. + \row + \li "{{interface|lower}}.h/cpp" + \li C++ code retrieving and forwarding the state using QtSimulator. + \row + \li "{{module.module_name|lower}}ControlUi.qml" + \li Control UI for this interface. Contains a interface to control every + property and method and log calls to signals. +\endtable + +\section2 QtRemoteObjects Backend + +The backend_qtro template is only available if the QtRemoteObjects module was found. +Despite the name, the remote object backend is not the location for the implementation of the actual backend logic, but just a client for connecting to the remote backend server. + +\table + \header + \li File name + \li Purpose + \row + \li "{{module.module_name|lower}}plugin.h/cpp" + \li Files defining implementation of QtIvi backend plugin implementing + QIviServiceInterface + \row + \li "{{module.module_name|lower}}.json" + \li File containing identifiers of the exposed feature interfaces needed by the Qt plugin + system. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. Also adds the .rep file + to the project and calls the remote object compiler. + \row + \li "{{interface|lower}}backend.h/cpp" + \li Files containing the implementation of the remote object backend. + Establishes the connection and initializes the remote object replica. + \row + \li "{{interface|lower}}.rep" + \li The input file for Qt’s \l [QtRemoteObjects] {Qt Remote Objects Compiler} {replica compiler} for producing the replica class code. +\endtable + +\section2 QtRemoteObjects server + +The server_qtro template is only available if the QtRemoteObjects module was found. The produced code contains merely the source classes to inherit and code for establishing the connection. It is up to the developer to implement the actual backend logic. + +\table + \header + \li File name + \li Purpose + \row + \li "core.h/cpp" + \li Code for establishing the connection and starting the remoting for the source objects. + \row + \li "{{srcBase|lower}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. Also includes the .rep file + to the project and calls the remote object compiler. + \row + \li "{{interface|lower}}.rep" + \li The input file for the Qt’s \l [QtRemoteObjects] {Qt Remote Objects Compiler} {replica compiler} for producing the source class code. +\endtable +*/ diff --git a/src/ivicore/doc/src/ivigenerator/getting-started.qdoc b/src/ivicore/doc/src/ivigenerator/getting-started.qdoc new file mode 100644 index 0000000..0249f2c --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/getting-started.qdoc @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page gettingstartedivigenerator.html +\title Getting Started Using the Qt IVI Generator + +This guide explains how to get started with the Qt IVI Generator. +The generator is used to generate source code from an IDL file. It supports +multiple templates to select what kind of code should be generated. + +The Qt IVI Generator can be found inside the \c bin folder of your Qt installation. +If it is not available, please make sure all prerequisites listed in the qmake +configuration summary are met. See \l {Configuration} for more information on how +Qt IVI can be configured. + +\section1 Basics + +The generator takes an IDL file as input for generating its source code. The +following code shows a minimal IDL file: + +\code +module my.idl 1.0 + +interface MyInterface { + property int value; + void increment(); + signal valueIncremented(int newValue); +} +\endcode + +The IDL pretty much self-explanatory: it defines a new module (namespace) +\e my.idl in version \e 1.0. Inside there should be an interface called \e MyInterface. +The interface provides a property storing a value and a function to increment and notify +the user. The \l {QFace IDL syntax} page provides a more detailed documentation about the IDL. + +Using the previously defined IDL file, the \l {frontend-template}{frontend} template can be used to generate +a library providing an implementation of \e MyInterface. The generated class will use the +\l {Dynamic backend System} provided by Qt IVI for an abstraction of \e frontend and \e backend code. + +The actual implementation of the class behavior is done inside a \e backend plugin. A very basic +backend plugin can be generated by using the \l {backend-simulator-template}{backend_simulator} template. For more information +how Qt locates and loads its plugins, please see \l {How to Create Qt Plugins} {here}. + +For more in-depth information, the \l {Qt IVI Generator Example} comes with a step by step documentation. +*/ + +/* +This provides ideas on how this page should be extended in the future. + +\section1 Generating a complete qt module +\section1 Extending the autogenerator +\section1 Android Deployment +*/ diff --git a/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc b/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc new file mode 100644 index 0000000..f44eee1 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc @@ -0,0 +1,318 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/* + NOTE: Some content in this file was copied from the QFace Documentation +*/ +/*! +\page idl-syntax.html +\title QFace IDL syntax +\nextpage Jinja template syntax +\keyword IDL + +This page explains the basic usage of the QFace IDL. A more detailed description of the library +can be found on its \l {https://pelagicore.github.io/qface/}{page} + +QFace (Qt interface language) is an Interface Description Languge (IDL). While it is primarily +designed to define an interface between Qt, QML and C++, it is intended to be flexible enough also +to be used in other contexts. + + +\section1 The IDL + +The IDL uses common API concepts such as modules, interfaces, properties, structs and enums/flags. +Additionally it knows about lists and \l {Model/View Programming}{models}. +A list is an array of primitive or complex types. A model is an indicator for large data sets +which are typical used via a defined API (e.g. pagination). + +\code +module org.example 1.0 + +interface Echo { + string message; + void echo(string message); + signal broadcast(string message); + Status status; +} + +enum Status { + Null, Loading, Ready, Error +} +\endcode + +The data types provided by QFace can be divided into primitive and complex types: + +\b {Primitive Types} +\list + \li bool + \li int + \li real + \li string + \li var +\endlist + +\b {Complex Types} +\list + \li Interface + \li Struct + \li Enum + \li Flag + \li Array + \li Model +\endlist + +The language as such does not provide any support for maps or dictionaries. The reason for not +providing a map container type is that keys in dictionaries requires a hash which can not always +be guaranteed to be available in complex types. + +\section1 Grammar +The grammar of QFace is well defined and is based on the concepts of modules as a larger +collection of information. + +A module can have several interfaces, structs and/or enums/flags. + +\code +module <module> <version> +import <module> <version> + +interface <Identifier> { + [readonly] <type> <identifier> + <type> <operation>(<parameter>*) + signal <signal>(<parameter>*) +} + +struct <Identifier> { + <type> <identifier>; +} + +enum <Identifier> { + <name> = <value>, +} + +flag <Identifier> { + <name> = <value>, +} +\endcode + +A QFace document always describes one module. Each document can contain one or more interfaces, +structs, flags or enums. Each document can import other modules using the import statement. + +\section1 Module + +A module is identified by its name. The name should normally be a URI where all parts are +lowercase (e.g. \e {entertainment.tuner}). A module may import other modules with the primary +purpose being to ensure that dependencies are declared inside the QFace file. + +\code +// org.example.qface +module org.example 1.0 + +import org.common 1.0 +\endcode + +\section1 Interface + +An interface is a collection of properties, operation and signals. Properties carry data, whereas +the operations normally modify the data. Signals are used to notify the user of changes. + +\code +interface WeatherStation { + real temperature; + void reset(); + signal error(string message); +} +\endcode + +\section1 Struct + +The struct is supposed to serve as a container to transport structured data. It supports neither +properties nor operations. + +\section1 Property + +Interfaces and structures data are carried by properties: syntax elements allowing to describe +some attributes of the entity. A property can be of any type, known to IDL. It can be marked as \e +{readonly}, in which case this attribute of the interface is not supposed to be written to from +the outside code. It's up to the generator to enforce this constraint. + +\section1 Enum/Flag +Enums and flags are the concepts known from many popular programming languages (C++,Java,etc). +They differ only in what values they can take: enums are allowed to take only a single value, +whereas flags can be an OR-ed combination of multiple values. + +\section1 Types + +Types are either local and can be referenced simply by their name, or they are from an external +module in which case they need to be referenced with the fully qualified name (module + '.' + +name). A type can be an interface, struct, enum or flag. + +A module consists of either one or more interfaces, structs and enums/flags. They can come in any +number or combination. The interface is the only type which can contain operations and signals. +A struct is merely a container to transport structured data. Enum and flags allows the user to +encode information used inside the struct or interface as datatype. + +The QFace library does not allow to extend interfaces. It is by design kept simple. + +Below is an example of a QFace file. + +\code +module entertainment.tuner 1.0; + +import common 1.0 + +interface Tuner { + // property currentStation + readonly Station currentStation; + // operation nextStation + void nextStation(); + // operation previousStation + void previousStation(); + // operation updateCurrentStation + void updateCurrentStation(int stationId); + + list<int> primitiveList; + list<Station> complexList; + model<int> primitiveModel; + model<Station> complexModel; +} + +\endcode + + +\section1 Annotations +\target annotations_reference + +Annotations is a way to add meta information to your interface definition. It is available to each +symbol in the interface. + +Annotations allows an interface author to extend the existing interface with additional meta +information, called tags, aka annotations. One or several annotations can precede a module, +interface, struct or enum. They are also allowed before an operation, property or signal. +Everywhere where a documentation comment is allowed you can also add annotations. + +An annotation looks like this: + +\code +@service: {port: 12345} +interface Tuner { +} +\endcode + +An in code annotation precedes a symbol and it starts with an @ sign. A symbol can have more than +one one annotation line. Each line should be one individual annotation. The content is YAML +content. All @ signs preceding a symbol are collected and then evaluated using a YAML parser. + +For larger annotations one can use the external annotation document feature. + +\code +@singleton: yes +@data: [1,2,3] +@config: { values: [LEFT, RIGHT, TOP] } +\endcode + +This will be result into a YAML content of + +\code +singleton: yes +data: [1,2,3] +config: { values: [LEFT, RIGHT, TOP] } +\endcode + +And the result as Python object would be + +\code +{ + "data": [ 1, 2, 3 ], + "singleton": true, + "config": { + "values": [ "LEFT", "RIGHT", "TOP" ] + } +} +\endcode + +\section1 Annotation Documents + +QFace allows also to specify these annotations in external documents using the YAML syntax. For +this you need to create a document with the same name as the QFace document but with the extension +.yaml. It should have roughly the following format + +\code +com.pelagicore.ivi.Tuner: + service: + port: 12345 +\endcode + +On the root level should be a fully qualified name of a symbol. The symbol will be looked up and +the following annotation information merged with the existing annotations from the QFace document. + +\section1 Merging Annotations + +The external annotations will be merged on top of the embedded annotations on per symbol base. +Dictionaries will be merged. If a merge can not be done then the external document based +annotations will override the embedded annotations. + +The annotation are available later when navigating the domain model. + +\code +{% if "service" in interface.tags %} +interface {{interface}} is served on port: {{interface.tags.service.port}} +{% else %} +interface {{interface}} is not served +{% endif %} +\endcode + +\note +QFace does not specify specific annotations, but defines just the annotation format. The set of +annotations supported must be defined and documented by the generator. + +\section1 Domain Model + +As a result of parsing the IDL document, a domain model object must be created. The domain model +resembles the structure of our system as objects. It is build by the parser and serves as the +input into the generator. + +The IDL is converted into an in memory domain model (see qface/idl/domain.py) + +\code +- System + - Module + - Import + - Interface + - Property + - Operation + - Event + - Enum + - Flag + - Struct + - Property +\endcode + +The domain model is the base for the code generation. You traverse the domain tree and trigger +your own code generation. + +Detailed description of QFace library API is found on the library \l +{http://qface.readthedocs.io/en/latest/api.html} {page} +*/ diff --git a/src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc b/src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc new file mode 100644 index 0000000..3a50a38 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page ivigenerator.html +\title The Qt IVI Autogenerator +\keyword QFace + +Qt IVI provides a way to describe interfaces using its own IDL (interface definition language) and +then generate Qt/QML API code based on this definition. The generator is based on the QFace +library, which provides a generic autogeneration framework. + +\list + \li \l {QFace IDL syntax} + \li \l {Jinja template syntax} + \li \l {Autogenerator Usage} + \li \l {Filter Reference} + \li \l {QMake Integration} + \li \l {QtIVI Remote backends}{Remote backends} + \li \l {ivicore/qface-ivi-climate}{Generator Example} + \li \l {ivicore/qface-ivi-remote}{Remote Backend Example} +\endlist +*/ diff --git a/src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc b/src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc new file mode 100644 index 0000000..3085efc --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qmake-integration.html +\title QMake Integration +\previouspage Autogenerator usage + +Qt IVI Generator has been integrated with QMake to generate all or part of projects. + +In it's simplest form, QMake can generate all the source code and the project only +need to configure what type of project is built. + +For complex setups, generated code can be combined with application specific code +which can extend and use it. + +Example: +\code +CONFIG += ivigenerator + +QT_FOR_CONFIG += ivicore +!qtConfig(ivigenerator): error("No ivigenerator available") + +QFACE_FORMAT = frontend +QFACE_SOURCES = example.qface +QFACE_MODULE_NAME = myModule +QFACE_OUTPUT_DIR = myOutputDir +\endcode + +Available QMake Variables: +\table + \row + \li QFACE_FORMAT + \li frontend (default), simulator_backend + \row + \li QFACE_SOURCES + \li list of .qface input files + \row + \li QFACE_MODULE_NAME + \li The (optional) name of the module that is using the generated code + \row + \li QFACE_OUTPUT_DIR + \li Output folder where the generated code will be created. The default + is to use the current build folder +\endtable + + +See \l {Autogenerator usage} for more details on the generator command line arguments. + +\quotation +\note As the ivigenerator has specific system dependencies, it may not be available in every QtIviCore installation. +In this case the ivigenerator qmake feature is also not available and this can result in build errors. + +The following code snippet makes sure to stop the build and give a meaningful error message in this case: +\code +QT_FOR_CONFIG += ivicore +!qtConfig(ivigenerator): error("No ivigenerator available") +\endcode +\endquotation + +\section1 QtModule support + +The Qmake Integration also supports generating code which enables you to compile the generated code +as a qt module. As it needs to work more closely with the Qt's module build system, it shouldn't be +loaded using the \e CONFIG variable, but using the \e load() function instead. The \e +ivigenerator_qt_module feature replaces the \e load(qt_module) call. The following shows how the +integration of the QtIviVehicleFunctions module is done. + +\badcode +TARGET = QtIviVehicleFunctions +QT = core core-private ivicore ivicore-private +CONFIG += c++11 ivigenerator + +QT_FOR_CONFIG += ivicore +!qtConfig(ivigenerator): error("No ivigenerator available") + +... + +QFACE_MODULE_NAME = QtIviVehicleFunctions +QFACE_SOURCES += ivivehiclefunctions.qface + +load(ivigenerator_qt_module) +\endcode + +In addition to the project file for the module library also the \e sync.profile needs to be +changed, as this is used to call the \e syncqt.pl script which generates the forwarding headers. +Usually the \e sync.profile is setup to search for the headers in the source folders. Using +\e $out_basedir it can be extended to also search in the build folder. + +\badcode +... +%modules = ( # path to module name map + "QtIviVehicleFunctions" => "$basedir/src/ivivehiclefunctions;$out_basedir/src/ivivehiclefunctions" +); +... +\endcode + +*/ diff --git a/src/ivicore/doc/src/ivigenerator/remotebackends.qdoc b/src/ivicore/doc/src/ivigenerator/remotebackends.qdoc new file mode 100644 index 0000000..064a062 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/remotebackends.qdoc @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page remotebackends.html +\title QtIvi Remote Backends + +One of the features of the Qt IVI Generator is the possibility to create remote backends +that utilize the QtRemoteObjects module. +A remote backend may be an independently running process, even on a separate host machine, that can +be accessed by multiple clients, or frontends. Such frontends are e.g. the main infotainment system +UI, different applications running within the UI or mobile devices. + +\section1 Motivation + +The purpose of having remote backends is to enable the distribution of functionality and the sharing +of information. This may be between multiple processes and even between multiple host machines. +Separate processes improve the overall reliability of a complex system and make it possible to +separate computationally intensive code from the UI code. Additionally, remote backends can be +accessible by multiple frontend points, be it the central UI, separate applications or even mobile +devices or third party applications. +Combined with the automatic generation of code and uniform feature loading of QtIvi, the development +of distributed features comes with a minimal development overhead and interchangeability and +transparency on the UI code side. + +\section1 Code Generation + +The remote objects generator produces client side code as a QtIvi backend plugin and a remote server +stub. The client is generated using the \l {backend-qtro-template}{backend_qtro} template and the s +erver using the \l {server-qtro-template}{server_qtro} template. Both the plugin and the server +contain generated c++ code and an intermediate .rep -file that is further processed by Qt’s +\l [QtRemoteObjects] {Qt Remote Objects Compiler} {replica compiler} to produce the actual source +and replica classes. + +The generated plugin is loaded and used as any other QtIvi plugin and is interchangeable with any +other backend implementation with the same API. As all method calls over QtIvi feature interfaces +are asynchronous, the use of a remote backend is similar to any other type of backend. + +The generated plugin is buildable and usable as it is, and does not require further changes by the +developer. The task of the developer will be then to implement the intended functionality at the +server side. To support getting started with the server, there is a generated class that initializes +the connection. All connection parameters to the plugin and to the server are passed currently over +a config file, either in a default location or at an user specified path. + +For a steb-by-step introduction to remote backends, see the \l {ivicore/qface-ivi-remote}{Remote Backend Example}. + +*/ diff --git a/src/ivicore/doc/src/ivigenerator/template-syntax.qdoc b/src/ivicore/doc/src/ivigenerator/template-syntax.qdoc new file mode 100644 index 0000000..96a4b78 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/template-syntax.qdoc @@ -0,0 +1,477 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Copyright (C) 2017 Jinja Team. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/* + NOTE: Some content in this file was copied from the Jinja Template Engine Documentation + and from the QFace Documentation +*/ +/*! +\page template-syntax.html +\title Jinja template syntax +\previouspage QFace IDL syntax +\nextpage Autogenerator usage + +This page is about the Jinja template engine. While the most detailed description of the template +language can be found at \l {http://jinja.pocoo.org/docs/dev/templates/}{Jinja documentation}, +some basic concepts are given in this article. + + +\section1 Code Generation Principle + +The code generation is driven by a small script which iterates over the domain model and writes +files using the Python Jinja template language. + + +Given that generator script has read and parsed the IDL file into a domain model, this latter one +is then used as the root object for the code generation inside the template language. Below is an +example of the code traversing the domain model: + +\code +{% for module in system.modules %} + {%- for interface in module.interfaces -%} + SERVICE, {{module}}.{{interface}} + {% endfor -%} + {%- for struct in module.structs -%} + STRUCT , {{module}}.{{struct}} + {% endfor -%} + {%- for enum in module.enums -%} + ENUM , {{module}}.{{enum}} + {% endfor -%} +{% endfor %} +\endcode + +The template iterates over the domain objects and generates text which is written into a file. + +\section1 Laguage constructs +\section2 Synopsis + +A template contains variables and/or expressions, which get replaced with values when a template +is rendered; and tags, which control the logic of the template. + +There are a few kinds of delimiters. The default Jinja delimiters are configured as follows: + +\list + \li {% ... %} for Statements + \li {{ ... }} for Expressions to print to the template output + \li {# ... #} for Comments not included in the template output + \li # ... ## for \l {line_statements}{Line Statements} +\endlist + +\section2 Control structures + +A control structure refers to all those things that control the flow of a program - conditionals +(i.e. if/elif/else), for-loops, as well as things like macros and blocks. With the default syntax, +control structures appear inside {% ... %} blocks. + +\section3 For + +Loop over each item in a sequence. For example, to display a list of users provided in a variable +called users: + +\code +<h1>Members</h1> +<ul> +{% for user in users %} + <li>{{ user.username|e }}</li> +{% endfor %} +</ul> +\endcode + +As variables in templates retain their object properties, it is possible to iterate over +containers like dict: + +\code +<dl> +{% for key, value in my_dict.iteritems() %} + <dt>{{ key|e }}</dt> + <dd>{{ value|e }}</dd> +{% endfor %} +</dl> +\endcode + +Inside of a for-loop block some special variables are available: + +\table + \header + \li Variable + \li Description + \row + \li loop.index + \li The current iteration of the loop. (starting with \e 1) + \row + \li loop.index0 + \li The current iteration of the loop. (starting with \e 0) + \row + \li loop.revindex + \li The number of iterations from the end of the loop (starting with \e 1) + \row + \li loop.revindex0 + \li The number of iterations from the end of the loop (starting with \e 0) + \row + \li loop.first + \li True if first iteration. + \row + \li loop.last + \li True if last iteration. + \row + \li loop.length + \li The number of items in the sequence. +\endtable + +See for more \l{http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures}{Jinja +documentation} + + +Unlike in Python, it’s not possible to break or continue in a loop. One can, however, filter the +sequence during iteration, which allows one to skip items. The following example skips all the +users which are hidden: + +\code +{% for user in users if not user.hidden %} + <li>{{ user.username|e }}</li> +{% endfor %} +\endcode + +The advantage is that the special loop variable will count correctly; thus not counting the users +not iterated over. + +If no iteration took place because the sequence was empty or the filtering removed all the items +from the sequence, one can render a default block by using else: + +\code +<ul> +{% for user in users %} + <li>{{ user.username|e }}</li> +{% else %} + <li><em>no users found</em></li> +{% endfor %} +</ul> +\endcode + +In Python, \e {else} blocks are executed whenever the corresponding loop did not break. Since +Jinja loops cannot break anyway, a slightly different behavior of the \e {else} keyword was chosen. + +It is also possible to use loops recursively. This is useful when dealing with recursive data such +as sitemaps or RDFa. To use loops recursively, one basically has to add the recursive modifier to +the loop definition and call the loop variable with the new iterable where recursion is needed. + +The following example implements a sitemap with recursive loops: + +\code +<ul class="sitemap"> +{%- for item in sitemap recursive %} + <li><a href="{{ item.href|e }}">{{ item.title }}</a> + {%- if item.children -%} + <ul class="submenu">{{ loop(item.children) }}</ul> + {%- endif %}</li> +{%- endfor %} +</ul> +\endcode + +The loop variable always refers to the closest (innermost) loop. If we there is more than one +level of loops, we can rebind the variable loop by writing {% set outer_loop = loop %} after the +loop that we want to use recursively. Then, we can call it using {{ outer_loop(...) }} + +Please note that assignments in loops will be cleared at the end of the iteration and cannot +outlive the loop scope. Older versions of Jinja2 had a bug where in some circumstances it appeared +that assignments would work. This is not supported. + +\section3 If + +The if statement in Jinja is comparable with the Python if statement. In the simplest form, one +can use it to test if a variable is defined, not empty and not false: + +\code +{% if users %} +<ul> +{% for user in users %} + <li>{{ user.username|e }}</li> +{% endfor %} +</ul> +{% endif %} +\endcode + +For multiple branches, elif and else can be used like in Python. One can use more complex +Expressions there, too: + +\code +{% if kenny.sick %} + Kenny is sick. +{% elif kenny.dead %} + You killed Kenny! You bastard!!! +{% else %} + Kenny looks okay --- so far +{% endif %} +\endcode + +\section2 Tests +Beside filters, there are also so-called “tests” available. Tests can be used to test a variable +against a common expression. To test a variable or expression, its name is used followed by the +name of the test. For example, to find out if a variable is defined, one can try \e {name is +defined}, which will then return true or false depending on whether name is defined in the current +template context. + +Tests can accept arguments, too. If the test only takes one argument, one can leave out the +parentheses. For example, the following two expressions do the same thing: + +\code +{% if loop.index is divisibleby 3 %} +{% if loop.index is divisibleby(3) %} +\endcode + +The List of builtin tests can be found on the \l{http://jinja.pocoo.org/docs/2.9/ +templates/#builtin-tests}{Jinja documentation page}. +\section2 Filters + +Variables can be modified by functions called filters. Filters are separated from the variable by +a pipe symbol (|) and may have optional arguments in parentheses. Multiple filters can be chained. +The output of one filter is applied to the next. + +For example, {{ name|striptags|title }} will remove all HTML Tags from variable name and +title-case the output (title(striptags(name))). + +Filters that accept arguments have parentheses around the arguments, just like a function call. +For example: \code {{ listx|join(', ') }}\endcode will join a list with commas (equivalent to +\code str.join(', ', listx)\endcode). Nevertheless, the variable filter is applying to is always +passed as a first argument to the filter function. + +One can define custom filters by registering a Python function as a new filter with the +Environment object: + +\code +def lower_first_filter(s): + s = str(s) + return s[0].lower() + s[1:] + + +env = Environment( + loader=FileSystemLoader(search_path), + trim_blocks=True, + lstrip_blocks=True + ) +env.filters['lowerfirst'] = lower_first_filter +\endcode + +After that filter called lower first will be available from the template: +\code +{{ var | lowerfirst }} +\endcode + +A list of all supported filters can be found in the \l{Filter Reference}. + + +\section2 Variables +Template variables are defined by the context dictionary passed to the template. Variables can be +complex object having their own attributes. + +One can use a dot (.) to access attributes of a variable in addition to the standard Python +__getitem__ “subscript” syntax ([]). + +The following lines are equivalent: + +\code +{{ foo.bar }} +{{ foo['bar'] }} +\endcode + +If a variable or attribute does not exist, its value will result to undefined value. The +interpretation of that kind of value depends on the application configuration: the default +behavior is to evaluate to an empty string if printed or iterated over, and to fail for every +other operation. + +\section2 Comments + +To comment-out part of a line in a template, use the comment syntax which is by default set to {# +... #}. This is useful to comment out parts of the template for debugging or to add information +for other template designers or yourself: + +\code +{# note: commented-out template because we no longer use this + {% for user in users %} + ... + {% endfor %} +#} +\endcode + +\section2 Line Statements +\target line_statements + +If line statements are enabled by the application, it’s possible to mark a line as a statement. +For example, if the line statement prefix is configured to #, the following two examples are +equivalent: + +\code +<ul> +# for item in seq + <li>{{ item }}</li> +# endfor +</ul> +\endcode + +\code +<ul> +{% for item in seq %} + <li>{{ item }}</li> +{% endfor %} +</ul> +\endcode + +The line statement prefix can appear anywhere on the line as long as no text precedes it. For +better readability, statements that start a block (such as for, if, elif etc.) may end with a +colon: + +\code +# for item in seq: + ... +# endfor +\endcode + +Line statements can span multiple lines if there are open parentheses, braces or brackets: + +\code +<ul> +# for href, caption in [('index.html', 'Index'), + ('about.html', 'About')]: + <li><a href="{{ href }}">{{ caption }}</a></li> +# endfor +</ul> +\endcode + +Since Jinja 2.2, line-based comments are available as well. For example, if the line-comment +prefix is configured to be ##, everything from ## to the end of the line is ignored (excluding the +newline sign): + +\code +# for item in seq: + <li>{{ item }}</li> ## this comment is ignored +# endfor +\endcode + +\section2 Assignments + +Inside code blocks, you can also assign values to variables. Assignments at top level (outside of +blocks, macros or loops) are exported from the template like top level macros and can be imported +by other templates. + +Assignments use the set tag and can have multiple targets: + +\code +{% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %} +{% set key, value = call_something() %} +\endcode + +It is not possible to set variables inside a block and have them show up outside of it. This also +applies to loops. The only exception to that rule are if statements which do not introduce a scope. + + +\section2 Whitespace Control + +In the default configuration: + +\list + \li a single trailing newline is stripped if present + \li other whitespace (spaces, tabs, newlines etc.) is returned unchanged +\endlist + +If an application configures Jinja to trim_blocks, the first newline after a template tag is +removed automatically (like in PHP). The lstrip_blocks option can also be set to strip tabs and +spaces from the beginning of a line to the start of a block. (Nothing will be stripped if there +are other characters before the start of the block) + +With both trim_blocks and lstrip_blocks enabled, you can put block tags on their own lines, and +the entire block line will be removed when rendered, preserving the whitespace of the contents. +For example, without the trim_blocks and lstrip_blocks options, this template: + +\code +<div> + {% if True %} + yay + {% endif %} +</div> +\endcode + +gets rendered with blank lines inside the div: + +\code +<div> + + yay + +</div> +\endcode + +But with both trim_blocks and lstrip_blocks enabled, the template block lines are removed and +other whitespace is preserved: + +\code +<div> + yay +</div> +\endcode + +One can manually disable the lstrip_blocks behavior by putting a plus sign (+) at the start of a +block: + +\code +<div> + {%+ if something %}yay{% endif %} +</div> +\endcode + +It's also possible to strip whitespace in templates by hand. With a minus sign (-) at the start or +end of a block (e.g. a For tag), a comment, or a variable expression, the whitespaces before or +after that block will be removed: + +\code +{% for item in seq -%} + {{ item }} +{%- endfor %} +\endcode + +This will yield all elements without whitespace between them. If seq was a list of numbers from 1 +to 9, the output would be 123456789. + +If Line Statements are enabled, they strip leading whitespace automatically up to the beginning of +the line. + +By default, Jinja2 also removes trailing newlines. To keep single trailing newlines, configure +Jinja to keep_trailing_newline. + +\note + +One must not add whitespace between the tag and the minus sign. + +valid: +\code +{%- if foo -%}...{% endif %} +\endcode +invalid: +\code +{% - if foo - %}...{% endif %} +\endcode + +*/ |