Skip to content

Commit

Permalink
Docs: move internationalization chapter
Browse files Browse the repository at this point in the history
  • Loading branch information
@mmontone
mmontone committed May 30, 2024
1 parent 341609b commit 1d2408b
Show file tree
Hide file tree
Showing 7 changed files with 222 additions and 222 deletions.
332 changes: 166 additions & 166 deletions docs/djula.texi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2621,6 +2621,172 @@ We create a new template in @code{includes/blog-entry.html} and we use the @code

See also the @code{ssi} tag for Server-Side Includes.

@node Errors and debugging
@anchor{error-handling doc}@anchor{error-handling error-handling}
@chapter Errors and debugging

@section Error handling

Djula catches errors and barfs them to the template output by default.

That is controlled via the @code{*CATCH-TEMPLATE-ERRORS-P*} variable.
If changed to @code{NIL}, then errors are not caught anymore and are
debuggable from the lisp listener.

Djula provides more or less verbosity in template errors. Verbosity is
controlled via the variable @code{*VERBOSE-ERRORS-P*}.

Also, there’s a fancy page to display errors, which can be disabled if
desired. That is controlled via the variable @code{*FANCY-ERROR-TEMPLATE-P*}

@section Displaying template information

Use the @code{debug} tag in your templates to display the arguments being passed to templates together with other debugging information.

Enable the @code{*debug-mode*} for displaying debug information for all rendered templates.

@section Strict mode

When @code{*strict-mode*} is enabled, access to variables not bound in templates signals an error.

For instance, trying to render @code{@{@{foo@}@}} without passing a @code{:foo} argument to @code{render-template*} will signal an error. Whereas if strict mode is disabled, the variable access is bypassed and nothing is rendered.
@menu
* API: API<2>.
@end menu

@node API<2>
@anchor{error-handling api}
@section API

@deffn {Variable} *catch@w{-}template@w{-}errors@w{-}p*

When enabled, caught errors during the rendering of the template are written to the output instead of being handled by the lisp listener.
This is enabled by default.
@end deffn

@deffn {Variable} *fancy@w{-}error@w{-}template@w{-}p*

When enabled, show a fancy template when an error ocurrs.
This is enabled by default.
@end deffn

@deffn {Variable} *verbose@w{-}errors@w{-}p*

When enabled, errors are displayed more verbosely. Good for debugging.
This is enabled by default.

@end deffn

@deffn {Variable} *debug@w{-}mode*

When in debug mode, debugging information is attached to rendered templates.

@end deffn

@deffn {Variable} *strict@w{-}mode*

When enabled, unbound template variables access signals an error.

@end deffn

@node Deployment
@anchor{deployment doc}@anchor{deployment error-handling}
@chapter Deployment - Building standalone binaries

By default, when asked to compile a template, Djula searches the file
system, in the directories you told it to look into. When you render a
template that @code{extends} or @code{includes} another one, Djula
searches for that one too. Moreover, Djula will try to re-compile a
template at each access, whenever you reload a web page. This is very
convenient for development, it doesn't bother us to deploy our
application from sources (although you may want to disable
auto-reloading), but it prevents us from building a standalone binary
that will run on another machine, when the search path's directories
don't exist anymore.

To build a standalone binary, we will need to:

@itemize
@item
list all our templates (we can do that in our .asd system declaration)

@item
instantiate @code{djula:*current-store*} as an instance of @code{memory-template-store},

@item
compile our templates: they get compiled into memory.

@item
disable the auto-reload: @code{setf djula:*recompile-templates-on-change* nil)}.

@end itemize

Below is a simple ASDF system declaration that declares two templates
as static files located in the ``src/templates'' directory:

@lisp
(asdf:defsystem "djula-binary"
:depends-on (:hunchentoot
:djula)
:components ((:module "src"
:components
((:file "web")))
(:module "src/templates"
:components
;; Order is important: the ones that extend base.html
;; must be declared after it, because we compile all of them
;; at build time one after the other.
((:static-file "base.html")
(:static-file "search.html")))
(:static-file "README.md"))
:build-operation "program-op"
:build-pathname "djula-binary"
:entry-point "djula-binary::main"
:description "How to embed Djula templates in a self-contained binary.")
@end lisp

At the top level of ``src/web.lisp'', we set Djula's store to a memory
store, and we disable the autoreload feature. This code would be
called when we @code{load} the .lisp file, so it will be called when
we create the binary with @code{(asdf:make :djula-binary)}.

@lisp
(setf djula:*current-store* (make-instance 'djula:memory-template-store
:search-path (list (asdf:system-relative-pathname "djula-binary"
"src/templates/"))) ;; meaningful trailing /
djula:*recompile-templates-on-change* nil)
@end lisp

Now, we compile all those declared templates. We use the
@code{djula:list-asdf-system-templates} utility that will return a
list of pathnames to our templates.

@lisp
(mapcar #'djula:compile-template* (djula:list-asdf-system-templates :demo-djula-in-binaries "src/templates"))
@end lisp

Finally, you can declare templates as usual in your application:

@lisp
(defparameter +base.html+ (djula:compile-template* "base.html"))
@end lisp

and render a template that @code{extends} another one, it will work
(and that was actually the main difficulty: the default store always
looks for this inherited template on the filesystem).

You can now send to your web server your self-contained, one file
binary that you built on your machine or on a CI server.

@quotation Note
For a real-world web application you'll likely need
@url{https://github.com/Shinmera/deploy, Deploy} to ship foreign
libraries in your binary.
@end quotation

@node Internationalization
@anchor{internationalization doc}@anchor{internationalization internationalization}
@chapter Internationalization
Expand Down Expand Up @@ -2831,172 +2997,6 @@ Run the following function to reload the translations when developing:
#.(asdf:system-relative-pathname :my-project "locale/")))
@end lisp

@node Errors and debugging
@anchor{error-handling doc}@anchor{error-handling error-handling}
@chapter Errors and debugging

@section Error handling

Djula catches errors and barfs them to the template output by default.

That is controlled via the @code{*CATCH-TEMPLATE-ERRORS-P*} variable.
If changed to @code{NIL}, then errors are not caught anymore and are
debuggable from the lisp listener.

Djula provides more or less verbosity in template errors. Verbosity is
controlled via the variable @code{*VERBOSE-ERRORS-P*}.

Also, there’s a fancy page to display errors, which can be disabled if
desired. That is controlled via the variable @code{*FANCY-ERROR-TEMPLATE-P*}

@section Displaying template information

Use the @code{debug} tag in your templates to display the arguments being passed to templates together with other debugging information.

Enable the @code{*debug-mode*} for displaying debug information for all rendered templates.

@section Strict mode

When @code{*strict-mode*} is enabled, access to variables not bound in templates signals an error.

For instance, trying to render @code{@{@{foo@}@}} without passing a @code{:foo} argument to @code{render-template*} will signal an error. Whereas if strict mode is disabled, the variable access is bypassed and nothing is rendered.
@menu
* API: API<2>.
@end menu

@node API<2>
@anchor{error-handling api}
@section API

@deffn {Variable} *catch@w{-}template@w{-}errors@w{-}p*

When enabled, caught errors during the rendering of the template are written to the output instead of being handled by the lisp listener.
This is enabled by default.
@end deffn

@deffn {Variable} *fancy@w{-}error@w{-}template@w{-}p*

When enabled, show a fancy template when an error ocurrs.
This is enabled by default.
@end deffn

@deffn {Variable} *verbose@w{-}errors@w{-}p*

When enabled, errors are displayed more verbosely. Good for debugging.
This is enabled by default.

@end deffn

@deffn {Variable} *debug@w{-}mode*

When in debug mode, debugging information is attached to rendered templates.

@end deffn

@deffn {Variable} *strict@w{-}mode*

When enabled, unbound template variables access signals an error.

@end deffn

@node Deployment
@anchor{deployment doc}@anchor{deployment error-handling}
@chapter Deployment - Building standalone binaries

By default, when asked to compile a template, Djula searches the file
system, in the directories you told it to look into. When you render a
template that @code{extends} or @code{includes} another one, Djula
searches for that one too. Moreover, Djula will try to re-compile a
template at each access, whenever you reload a web page. This is very
convenient for development, it doesn't bother us to deploy our
application from sources (although you may want to disable
auto-reloading), but it prevents us from building a standalone binary
that will run on another machine, when the search path's directories
don't exist anymore.

To build a standalone binary, we will need to:

@itemize
@item
list all our templates (we can do that in our .asd system declaration)

@item
instantiate @code{djula:*current-store*} as an instance of @code{memory-template-store},

@item
compile our templates: they get compiled into memory.

@item
disable the auto-reload: @code{setf djula:*recompile-templates-on-change* nil)}.

@end itemize

Below is a simple ASDF system declaration that declares two templates
as static files located in the ``src/templates'' directory:

@lisp
(asdf:defsystem "djula-binary"
:depends-on (:hunchentoot
:djula)
:components ((:module "src"
:components
((:file "web")))
(:module "src/templates"
:components
;; Order is important: the ones that extend base.html
;; must be declared after it, because we compile all of them
;; at build time one after the other.
((:static-file "base.html")
(:static-file "search.html")))
(:static-file "README.md"))
:build-operation "program-op"
:build-pathname "djula-binary"
:entry-point "djula-binary::main"
:description "How to embed Djula templates in a self-contained binary.")
@end lisp

At the top level of ``src/web.lisp'', we set Djula's store to a memory
store, and we disable the autoreload feature. This code would be
called when we @code{load} the .lisp file, so it will be called when
we create the binary with @code{(asdf:make :djula-binary)}.

@lisp
(setf djula:*current-store* (make-instance 'djula:memory-template-store
:search-path (list (asdf:system-relative-pathname "djula-binary"
"src/templates/"))) ;; meaningful trailing /
djula:*recompile-templates-on-change* nil)
@end lisp

Now, we compile all those declared templates. We use the
@code{djula:list-asdf-system-templates} utility that will return a
list of pathnames to our templates.

@lisp
(mapcar #'djula:compile-template* (djula:list-asdf-system-templates :demo-djula-in-binaries "src/templates"))
@end lisp

Finally, you can declare templates as usual in your application:

@lisp
(defparameter +base.html+ (djula:compile-template* "base.html"))
@end lisp

and render a template that @code{extends} another one, it will work
(and that was actually the main difficulty: the default store always
looks for this inherited template on the filesystem).

You can now send to your web server your self-contained, one file
binary that you built on your machine or on a CI server.

@quotation Note
For a real-world web application you'll likely need
@url{https://github.com/Shinmera/deploy, Deploy} to ship foreign
libraries in your binary.
@end quotation

@node API<3>
@anchor{api doc}@anchor{api api}
@chapter API
Expand Down
6 changes: 3 additions & 3 deletions docs/djula/API_003c3_003e.html
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 1d2408b

Please sign in to comment.