Skip to content
Permalink
Browse files

Many minor fixxes to documentation

  • Loading branch information...
steveire committed Jul 28, 2019
1 parent 2e7191f commit 160b14d6cd9eaf88411e744e471c1126c53593a7
@@ -29,14 +29,16 @@ namespace Grantlee
<tr><th class="library" colspan="3">%Grantlee Templates</th></tr>
<tr><th class="section" >Application API</th><th class="section">%Plugin API</th><th class="section">Guides</th></tr>
<tr><td>
- AbstractLocalizer
- AbstractTemplateLoader
- CachingLoaderDecorator
- Context
- Engine
- OutputStream
- Template
- AbstractTemplateLoader
- FileSystemTemplateLoader
- AbstractLocalizer
- InMemoryTemplateLoader
- OutputStream
- QtLocalizer
- Template
</td><td>
- AbstractNodeFactory
- Exception
@@ -45,6 +47,7 @@ namespace Grantlee
- Node
- NodeList
- Parser
- RenderContext
- SafeString
- TagLibraryInterface
- Variable
@@ -6,11 +6,11 @@ namespace Grantlee

@section django_builtins Tags and filters ported from Django

See the <a href="https://docs.djangoproject.com/en/1.9/ref/templates/builtins/">Builtins documentation for Django 1.1</a> for an overview of the builtin tags and filters available in %Grantlee. Almost all tags and filter in django are available in %Grantlee. Exceptions are <a href="https://docs.djangoproject.com/en/1.9/ref/templates/builtins/#url">the url tag</a>, because %Grantlee does not have a views system. Additionally the ssi tag is disabled because of potential security risks. The dictdort, dictsortreversed, filesizeformat, iriencode, phone2numeric, pluralize, pprint, title, truncatewords_html, urlencode, urlize and urlizetrunc filters have not yet been ported due to time constraints.
See the <a href="https://docs.djangoproject.com/en/1.9/ref/templates/builtins/">Builtins documentation for Django 1.9</a> for an overview of the builtin tags and filters available in %Grantlee. Almost all tags and filter in django are available in %Grantlee. Exceptions are <a href="https://docs.djangoproject.com/en/1.9/ref/templates/builtins/#url">the <tt>url tag</tt></a>, because %Grantlee does not have a views system. Additionally the <tt>ssi</tt> tag is disabled because of potential security risks. The <tt>dictdort</tt>, <tt>dictsortreversed</tt>, <tt>filesizeformat</tt>, <tt>iriencode</tt>, <tt>phone2numeric</tt>, <tt>pluralize</tt>, <tt>pprint</tt>, <tt>title</tt>, <tt>truncatewords_html</tt>, <tt>urlencode</tt>, <tt>urlize</tt> and <tt>urlizetrunc</tt> filters have not yet been ported due to time constraints.

@section grantlee_extras Additional tags available in Grantlee

%Grantlee also provides some extra tags not available in DJango.
%Grantlee also provides some extra tags not available in Django.

@subsection media_finder_tag media_finder

@@ -22,9 +22,9 @@ namespace Grantlee
<img src="{% media_finder "someimage.png" %}" />
@endcode

The media_finder tag retrieves the result through Engine::mediaUri, which in turn queries the TemplateLoaders for the URL to return via the TemplateLoader::getMediaUri interface.
The <tt>media_finder</tt> tag retrieves the result through Engine::mediaUri, which in turn queries the TemplateLoaders for the URL to return via the AbstractTemplateLoader::getMediaUri interface.

It is possible to configure whether absolute or relative urls are created by using the Context::setUrlType method. If the path to external media is not the same as the path to the template, the Context::setRelativeMediaPath method can be used to specify a relative base path. For example, if creating a template <tt>/home/user/myoutput.html</tt> which references someimage.png, the path "myoutput_media/" can be set so that the @gr_tag{media_finder} puts the path <tt>myoutput_media/someimage.png</tt> into the template. This way the output and the media it references are portable together.
It is possible to configure whether absolute or relative urls are created by using the Context::setUrlType method. If the path to external media is not the same as the path to the template, the Context::setRelativeMediaPath method can be used to specify a relative base path. For example, if creating a template <tt>/home/user/myoutput.html</tt> which references <tt>someimage.png</tt>, the path <tt>"myoutput_media/"</tt> can be set so that the @gr_tag{media_finder} puts the path <tt>myoutput_media/someimage.png</tt> into the template. This way the output and the media it references are portable together.

It is the responsibility of the caller to copy the media to the <tt>/home/user/myoutput_media/</tt> directory.

@@ -31,15 +31,15 @@ namespace Grantlee
public:
AudioTextHtmlBuilder();

/* reimp */ void addAudioTag( const QString &source );
void addAudioTag( const QString &source ) override;
};

class AudioPlainTextBuilder : public Grantlee::PlainTextMarkupBuilder, public AbstractAudioBuilder
{
public:
AudioPlainTextBuilder();

/* reimp */ void addAudioTag( const QString &source );
void addAudioTag( const QString &source ) override;
};
@endcode

@@ -53,7 +53,7 @@ namespace Grantlee

void AudioPlainTextBuilder::addAudioTag(const QString& source)
{
int ref = addReference( source );
auto ref = addReference( source );
appendRawText( QString( "[%1]" ).arg( ref ) );
}
@endcode
@@ -69,14 +69,14 @@ namespace Grantlee

AudioTextDocumentDirector(AbstractAudioBuilder* builder);

/* reimp */ void processCustomFragment( const QTextFragment& fragment, const QTextDocument* doc);
void processCustomFragment( const QTextFragment& fragment, const QTextDocument* doc) override;

private:
AbstractAudioBuilder *m_builder;
};
@endcode

We create a subclass of Grantlee::MarkupDirector to take our new <tt>AbstractAudioBuilder</tt> interface and implement the processCustomFragment method to handle QTextFragments with our custom format type. The name of the audio file referenced in the document is then extracted and used as a parameter in the <tt>addAudioTag</tt> method.
We create a subclass of Grantlee::MarkupDirector to take our new <tt>AbstractAudioBuilder</tt> interface and implement the <tt>processCustomFragment</tt> method to handle QTextFragments with our custom format type. The name of the audio file referenced in the document is then extracted and used as a parameter in the <tt>addAudioTag</tt> method.

@code
AudioTextDocumentDirector::AudioTextDocumentDirector(AbstractAudioBuilder* builder)
@@ -99,8 +99,8 @@ namespace Grantlee
The custom AudioTextDocumentDirector and builders can then be used to create output including markup for custom types.

@code
AudioTextHtmlBuilder *builder = new AudioTextHtmlBuilder();
AudioTextDocumentDirector *director = new AudioTextDocumentDirector(builder);
auto builder = new AudioTextHtmlBuilder();
auto director = new AudioTextDocumentDirector(builder);

director->processDocument(document);
QString result = builder->getResult();
@@ -6,23 +6,21 @@ namespace Grantlee

@page differences_django Differences between Django and Grantlee

There are several notable differences between Django and %Grantlee, which arise mostly due to different implementation languages and features of the Qt framework.
There are several notable differences between Django and %Grantlee, which arise mostly due to different implementation languages and features of the %Qt framework.

Everything in python is a first class object, which means that django filter functions and tag functions can have properties and attributes. In %Grantlee, it is necessary to use classes to obtain the same effect, where Django uses only functions for filters. Additionally, C++ classes need to share an interface if they are to be treated the same way. This is not necessary in Django because python uses dynamic typing, and all methods behave similarly to virtual functions. %Grantlee uses the Abstract Factory pattern to achieve the same affect for tags, and a simple interface for filters.

Django tag libraries are loaded through normal python modules. This means that all libraries can be loaded dynamically. %Grantlee achieves the same effect by using the <a href="http://doc.trolltech.com/latest/plugins-howto.html">QtPlugin system</a> to load additional libraries dynamically.

In Django, any python object can be inserted into a Context. Then, methods which can change a class must have the 'alters_data' attribute, so that rendering a template can not alter the objects being rendered. Objects in %Grantlee are only introspectable to a limited amount determined by Q_PROPERTIES defined in wrapper classes. Therefore, the programmer can decide which properties to make available to the template system by wrapping them or not. It is encouraged, but not enforced to make sure scriptable wrapper methods are const.

Python dictionary objects can be processed in templates. In %Grantlee, QVariantHash is supported, which has the same effect. QVariantHash keys must be strings, whereas python dictionary keys may be any pickle-able object.
In Django, any python object can be inserted into a Context. Then, methods which can change a class must have the '<tt>alters_data</tt>' attribute, so that rendering a template can not alter the objects being rendered. Objects in %Grantlee are only introspectable to a limited amount determined by <tt>Q_PROPERTIES</tt> defined in wrapper classes. Therefore, the programmer can decide which properties to make available to the template system by wrapping them or not. It is encouraged, but not enforced to make sure scriptable wrapper methods are const.

Django uses PHP datetime string format for the @gr_tag{now} tag, whereas %Grantlee uses QDateTime format.

The Django autoescape system is based on marking a string object as safe. In Qt, this is not directly possible, so a wrapper class, Grantlee::SafeString is provided with several convenient operator overloads. This has (hopefully) minimal impact on plugin writers.
The Django autoescape system is based on marking a string object as safe. In %Qt, this is not directly possible, so a wrapper class, Grantlee::SafeString is provided with several convenient operator overloads. This has (hopefully) minimal impact on plugin writers.

Django performs string escaping on the assumption that the output string is HTML. In %Grantlee it is possible to implement escaping for other markups and text outputs by reimplementing OutputStream::escape.

The Django dictsort filter only works on a list of dictionary-like-objects. In %Grantlee, is is possible to sort a list of any kinds of objects by any property of the objects. For example a list of QObjects can be sorted by a certain property, a list of lists can be sorted by size etc.
The Django <tt>dictsort</tt> filter only works on a list of dictionary-like-objects. In %Grantlee, is is possible to sort a list of any kinds of objects by any property of the objects. For example a list of QObjects can be sorted by a certain property, a list of lists can be sorted by size etc.

The Django cache system makes a lot of sense where templates are rendered in a fire-and-forget manner for a stateless protocol. It is not implemented in %Grantlee because we're generally not rendering similar templates from scratch multiple times and the templates can keep state for multiple uses.

@@ -8,19 +8,19 @@ namespace Grantlee

@section books_example Books

The Books application from Qt Demos is modified to export the available data to a rendered html file. The example shows a use of the extends tag to override some parts of a base template. The templates can be edited to change the exported content without any recompiling. The themer has broad control over how the data os rendered and can even alter the structure of the presented data.
The Books application from %Qt Demos is modified to export the available data to a rendered html file. The example shows a use of the <tt>extends</tt> tag to override some parts of a base template. The templates can be edited to change the exported content without any recompiling. The themer has broad control over how the data os rendered and can even alter the structure of the presented data.

<center><b>
@image html grantlee_book_simple.png "A simple export of the data"
<br/>
@image html grantlee_book_coloured.png "A coloured export of the data showing the use of the &quot;cycle&quot; tag."
@image html grantlee_book_coloured.png "A coloured export of the data showing the use of the &quot;<tt>cycle</tt>&quot; tag."
<br/>
@image html grantlee_book_coloured_grouped.png "A restructured export of the data showing the use of the &quot;ifchanged&quot; tag."
@image html grantlee_book_coloured_grouped.png "A restructured export of the data showing the use of the &quot;<tt>ifchanged</tt>&quot; tag."
</b></center>

@section codegen_example Codegen

The codegen example shows how to use %Grantlee for code generation in multiple languages. The application can be used to generate classes in C++, python and ruby based on the content of the dialog. The user can define properties, which are generated appropriately to the language. For C++ it uses the Q_PROPERTY macro and creates an accessor a mutator and a notify signal. It can also be used to generate methods with arguments of any type in each language.
The codegen example shows how to use %Grantlee for code generation in multiple languages. The application can be used to generate classes in C++, python and ruby based on the content of the dialog. The user can define properties, which are generated appropriately to the language. For C++ it uses the <tt>Q_PROPERTY</tt> macro and creates an accessor a mutator and a notify signal. It can also be used to generate methods with arguments of any type in each language.

<center><b>
@image html codegen.png "The property and method configuration UI"
@@ -33,7 +33,7 @@ namespace Grantlee

@section contacts_example Contacts

The contacts application demostrates the use of the internationalization and localization features in %Grantlee. The user can select several contacts, whose details are formatted in templates for display in different themes. All strings in the templates are translatable, and the numbers, dates and currencies can be localized. The Contacts example can be used with the Qt or the KDE localization systems.
The contacts application demostrates the use of the internationalization and localization features in %Grantlee. The user can select several contacts, whose details are formatted in templates for display in different themes. All strings in the templates are translatable, and the numbers, dates and currencies can be localized. The Contacts example can be used with the %Qt or the KDE localization systems.

<center><b>
@image html contacts_multi_lang_tables.png "A theme showing selected contacts in localized tables"
@@ -62,7 +62,7 @@ namespace Grantlee

@section textedit_example Textedit application example

The textedit application example is a modified version of the same example which is bundled with Qt. The example shows how a custom type can be used in a text document and processed with the Grantlee::Textdocument library. It further demostrates how to add theming to the output using the Grantlee::Templates library.
The textedit application example is a modified version of the same example which is bundled with %Qt. The example shows how a custom type can be used in a text document and processed with the Grantlee::Textdocument library. It further demostrates how to add theming to the output using the Grantlee::Templates library.

@subsection textedit_blogs Related blog article
<a href="http://steveire.wordpress.com/2010/04/05/grantleerichtextbuilders/">Grantlee::RichTextBuilders</a>

0 comments on commit 160b14d

Please sign in to comment.
You can’t perform that action at this time.