From d3d3a4e31534666f40b65d689a6dc2654a58a809 Mon Sep 17 00:00:00 2001 From: Stephen Kelly Date: Sun, 11 Aug 2019 18:23:42 +0100 Subject: [PATCH] Update documentation to reflect port to QtQml javascript --- dox/extension.dox | 12 ++++++------ dox/for_themers.dox | 2 +- dox/moduledeps_no_qml.dot | 12 ++++++++++++ dox/plugindeps.dot | 25 ------------------------- dox/using_and_deploying.dox | 35 +++++++++++++++++++++-------------- templates/lib/engine.cpp | 3 +-- 6 files changed, 41 insertions(+), 48 deletions(-) create mode 100644 dox/moduledeps_no_qml.dot delete mode 100644 dox/plugindeps.dot diff --git a/dox/extension.dox b/dox/extension.dox index 3f86a7e8..42da68c2 100644 --- a/dox/extension.dox +++ b/dox/extension.dox @@ -238,13 +238,13 @@ namespace Grantlee }; @endcode - @section qtscript_libraries QtScript Libraries + @section javascript_libraries Javascript Libraries - If you configure your application to use the grantlee_scriptabletags_library, it will be possible for you and theme writers to write tags and filters in QtScript instead of C++. Themers would have as much control as a C++ plugin writer over those steps of processing and rendering the template. + By default, it will be possible for you and theme writers to write tags and filters in Javascript instead of C++, using the QJSEngine from QtQml. Themers have as much control as a C++ plugin writer over those steps of processing and rendering the template. - Writing QtScript plugins is slightly different from writing C++ plugins, and is a bit more like writing Django plugins. Namely, in Javascript like python, functions are first-class objects, and javascript is dynamically typed. Additionally QtScript plugins are just text files, so they can easily be dynamically loaded at runtime. QtScript files must be UTF-8 encoded. + Writing javascript plugins is slightly different from writing C++ plugins, and is a bit more like writing Django plugins. Namely, in Javascript like python, functions are first-class objects, and javascript is dynamically typed. Additionally Javascript plugins are just text files, so they can easily be dynamically loaded at runtime. Javascript files must be UTF-8 encoded. - Here is a complete QtScript library defining an @gr_tag{echo} tag which outputs its arguments: + Here is a complete Javascript library defining an @gr_tag{echo} tag which outputs its arguments: @code var EchoNode = function(content) @@ -269,10 +269,10 @@ namespace Grantlee Some things to note: - Library is a globally accessible object used to register Factories. - The addFactory method takes a string which is the name of an object, not the object itself. - - The script factory function returns a %Node. The first argument to %Node is the name of the QtScript object in the library which defines the node. All additional arguments will be passed to the constructor of that node. + - The script factory function returns a %Node. The first argument to %Node is the name of the Javascript object in the library which defines the node. All additional arguments will be passed to the constructor of that node. - The %Node function must have a callable render property which takes a context argument. - @todo \@section qtscript_diff Differences between C++ and QtScript library plugins. + @todo \@section javascript_diff Differences between C++ and Javascript library plugins. @subsection loaders Loaders diff --git a/dox/for_themers.dox b/dox/for_themers.dox index 8fee865f..d7d94b24 100644 --- a/dox/for_themers.dox +++ b/dox/for_themers.dox @@ -348,7 +348,7 @@ namespace Grantlee @subsection extending_syntax Extending the syntax - It is also possible to extend the syntax of Granltee as you need it using javascript if the application developer chooses. See @ref qtscript_libraries for more. This is considered an advanced topic. + It is also possible to extend the syntax of Granltee as you need it using javascript if the application developer chooses. See @ref javascript_libraries for more. This is considered an advanced topic. */ diff --git a/dox/moduledeps_no_qml.dot b/dox/moduledeps_no_qml.dot new file mode 100644 index 00000000..862814e1 --- /dev/null +++ b/dox/moduledeps_no_qml.dot @@ -0,0 +1,12 @@ +digraph GG { + node [ + fontsize = "12" + ]; + "node27" [ label="QtCore" shape="ellipse"]; + "node30" [ label="QtGui" shape="ellipse"]; + "node2" [ label="grantlee_templates" shape="polygon"]; + "node19" [ label="grantlee_textdocument" shape="polygon"]; + "node2" -> "node27" + "node19" -> "node30" + "node30" -> "node27" +} diff --git a/dox/plugindeps.dot b/dox/plugindeps.dot deleted file mode 100644 index cbaac12d..00000000 --- a/dox/plugindeps.dot +++ /dev/null @@ -1,25 +0,0 @@ -digraph GG { - node [ - fontsize = "12" - ]; - "node27" [ label="libQtCore.so" shape="ellipse"]; - "node28" [ label="libQtScript.so" shape="ellipse"]; - "node2" [ label="grantlee_templates" shape="polygon"]; - "node3" [ label="grantlee_loadertags" shape="polygon"]; - "node4" [ label="grantlee_defaultfilters" shape="polygon"]; - "node5" [ label="grantlee_defaulttags" shape="polygon"]; - "node6" [ label="grantlee_scriptabletags" shape="polygon"]; - "node7" [ style=invis label="" height=0 width=0]; - "node3" -> "node2" - "node4" -> "node2" - "node5" -> "node2" - "node6" -> "node2" - "node3" -> "node27" - "node4" -> "node27" - "node5" -> "node27" - "node6" -> "node27" - "node2" -> "node27" - "node6" -> "node7" [ style=invis ] - "node7" -> "node28" [ style=invis ] - "node6" -> "node28" -} diff --git a/dox/using_and_deploying.dox b/dox/using_and_deploying.dox index f0f79d00..88a94092 100644 --- a/dox/using_and_deploying.dox +++ b/dox/using_and_deploying.dox @@ -125,7 +125,7 @@ namespace Grantlee @section deploying_custom_plugins Deploying custom tags and filters - Custom tags and filters can be defined in C++ code or in QtScript. + Custom tags and filters can be defined in C++ code or in Javascript. To create a custom C++ plugin it must be built as part of a library and installed in a location known to the application. @@ -171,11 +171,11 @@ namespace Grantlee Note that neither the path to the custom libarary nor the path to the %Grantlee default library should contain the version number when specified in C++ code with the Engine. The version is only specified when installing the plugin in CMake. - Custom tags and filters implemented in QtScript can also be deployed on the file system, or, like template files, can also be deployed in Qt Resource files. In that case, the version should be specified in the -root argument in CMake. + Custom tags and filters implemented in Javascript can also be deployed on the file system, or, like template files, can also be deployed in Qt Resource files. In that case, the version should be specified in the -root argument in CMake. @code # CMake code: - set (_rcc_file "my_qtscript_library.qrc") + set (_rcc_file "my_javascript_library.qrc") qt5_add_resources(_scripted_rcc_src ${_rcc_file} OPTIONS -root "/plugins/grantlee/${Grantlee5_VERSION_MAJOR}.${Grantlee5_VERSION_MINOR}" ) add_executable(my_app, ${my_app_srcs} ${_scripted_rcc_src}) @@ -184,22 +184,12 @@ namespace Grantlee engine->setPluginPaths( QStringList() << ":/plugins/" ); @endcode - Note again that when specifying the path in the virtual filesystem, the version is omitted. User defined filter written in QtScript can also be located similiarly to templates from either the filesystem or the Qt Resource virtual filesystem. + Note again that when specifying the path in the virtual filesystem, the version is omitted. User defined filter written in Javascript can also be located similiarly to templates from either the filesystem or the Qt Resource virtual filesystem. @section building_grantlee Building Grantlee It is possible to build only parts of %Grantlee if your application is a QCoreApplication that depends only on QtCore -
- - @dotfile "moduledeps.dot" "Dependency Graph for Grantlee" - - - - @dotfile "plugindeps.dot" "Dependency Graph for Grantlee plugins" - -
- The appropriate options may be specified in the cmake gui, or on the command line using the BUILD_TEXTDOCUMENT or BUILD_TEMPLATES CMake options. @code @@ -214,5 +204,22 @@ namespace Grantlee cmake .. -DBUILD_TEXTDOCUMENT:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_MAIN_PLUGINS:BOOL=OFF @endcode + By default, %Grantlee depends on the QtQml library in order to implement Javascript support. This support is only enabled if the QtQml library is found. + +
+ + @dotfile "moduledeps.dot" "Dependency Graph for Grantlee" + +
+ + To prevent CMake searching for that library, use the -DCMAKE_DISABLE_FIND_PACKAGE_Qt5Qml=ON argument to CMake. + +
+ + @dotfile "moduledeps_no_qml.dot" "Dependency Graph for Grantlee without QtQml" + +
+ + */ } diff --git a/templates/lib/engine.cpp b/templates/lib/engine.cpp index 81b19527..e67e675b 100644 --- a/templates/lib/engine.cpp +++ b/templates/lib/engine.cpp @@ -170,8 +170,7 @@ void Engine::loadDefaultLibraries() continue; // Warning. We load C++ plugins in this method, but not plugins written - // in - // QtScript. + // in Javascript. // This should be a better situation in Grantlee 0.2 when the // TagLibraryInterface // can have shared pointers instead of raw pointers in its API. The