Struct perseus::prelude::PerseusAppBase
source · pub struct PerseusAppBase<G: Html, M: MutableStore, T: TranslationsManager> { /* private fields */ }
Expand description
The options for constructing a Perseus app. This struct
will tie
together all your code, declaring to Perseus where your templates,
error pages, static content, etc. are.
Memory leaks
This struct
internally stores all templates and capsules as static
references, since they will definitionally be required for the lifetime
of the app, and since this enables support for capsules created and
managed through a lazy_static!
, a very convenient and efficient pattern.
However, this does mean that the methods on this struct
for adding
templates and capsules perform Box::leak
calls internally, creating
deliberate memory leaks. This would be …
Implementations§
source§impl<G: Html, T: TranslationsManager> PerseusAppBase<G, FsMutableStore, T>
impl<G: Html, T: TranslationsManager> PerseusAppBase<G, FsMutableStore, T>
sourcepub fn new() -> Self
pub fn new() -> Self
Creates a new instance of a Perseus app using the default
filesystem-based mutable store (see FsMutableStore
). For most apps,
this will be sufficient. Note that this initializes the translations
manager as a dummy (see FsTranslationsManager
), and
adds no templates or error pages.
In development, you can get away with defining no error pages, but
production apps (e.g. those created with perseus deploy
) MUST set
their own custom error pages.
This is asynchronous because it creates a translations manager in the background.
sourcepub fn new() -> Self
pub fn new() -> Self
Creates a new instance of a Perseus app using the default
filesystem-based mutable store (see FsMutableStore
). For most apps,
this will be sufficient. Note that this initializes the translations
manager as a dummy (see FsTranslationsManager
), and
adds no templates or error pages.
In development, you can get away with defining no error pages, but
production apps (e.g. those created with perseus deploy
) MUST set
their own custom error pages.
This is asynchronous because it creates a translations manager in the background.
source§impl<G: Html, M: MutableStore> PerseusAppBase<G, M, FsTranslationsManager>
impl<G: Html, M: MutableStore> PerseusAppBase<G, M, FsTranslationsManager>
sourcepub fn locales_lit_and_translations_manager(self, locales: Locales) -> Self
pub fn locales_lit_and_translations_manager(self, locales: Locales) -> Self
The same as .locales_and_translations_manager()
, but this accepts a
literal Locales
struct
, which means this can be used when you’re
using FsTranslationsManager
but when you don’t know if your app is
using i18n or not (almost always middleware).
sourcepub fn locales_and_translations_manager(
self,
default: &str,
other: &[&str]
) -> Self
pub fn locales_and_translations_manager( self, default: &str, other: &[&str] ) -> Self
Sets the internationalization information for an app using the default
translations manager (FsTranslationsManager
). This handles locale
caching and the like automatically for you, though you could
alternatively use .locales()
and .translations_manager()
independently to customize various behaviors. This takes the same
arguments as .locales()
, so the first argument is the default
locale (used as a fallback for users with no locale preferences set in
their browsers), and the second is a list of other locales supported.
If you’re not using i18n, you don’t need to call this function. If you
for some reason do have to though (e.g. overriding some other
preferences in middleware), use .disable_i18n()
, not this, as
you’re very likely to shoot yourself in the foot! (If i18n is disabled,
the default locale MUST be set to xx-XX
, for example.)
source§impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T>
impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T>
sourcepub fn new_with_mutable_store(mutable_store: M) -> Self
pub fn new_with_mutable_store(mutable_store: M) -> Self
Creates a new instance of a Perseus app, with the default options and a
customizable MutableStore
, using the default dummy
FsTranslationsManager
by default (though this can be changed).
sourcepub fn root(self, val: &str) -> Self
pub fn root(self, val: &str) -> Self
Sets the HTML ID of the <div>
element at which to insert Perseus.
In your index view, this should use PerseusRoot
.
Note: if you’re using string HTML, the <div>
with this ID MUST look
exactly like this: <div id="some-id-here"></div>
, spacing and
all!
sourcepub fn static_dir(self, val: &str) -> Self
pub fn static_dir(self, val: &str) -> Self
Sets the location of the directory storing static assets to be hosted
under the URL /.perseus/static/
. By default, this is static/
at
the root of your project.
sourcepub fn templates(self, val: Vec<Template<G>>) -> Self
pub fn templates(self, val: Vec<Template<G>>) -> Self
Sets all the app’s templates. This takes a vector of templates.
Usually, it’s preferred to run .template()
once for each template,
rather than manually constructing this more inconvenient type.
sourcepub fn template(self, val: impl Into<Forever<Template<G>>>) -> Self
pub fn template(self, val: impl Into<Forever<Template<G>>>) -> Self
Adds a single new template to the app. This expects the output of
a function that is generic over G: Html
. If you have something with a
predetermined type, like a lazy_static!
that’s using
PerseusNodeType
, you should use .template_ref()
instead. For
more information on the differences between the function and referrence
patterns, see the book.
See Template
for further details.
sourcepub fn template_ref<H: Html>(self, val: impl Into<Forever<Template<H>>>) -> Self
pub fn template_ref<H: Html>(self, val: impl Into<Forever<Template<H>>>) -> Self
Adds a single new template to the app. This can accept either an owned
Template
or a static reference to one, as might be created by a
lazy_static!
. The latter would force you to specify the rendering
backend type (G
) manually, using a smart alias like
PerseusNodeType
. This method performs internal type coercions to make
statics work neatly.
If your templates come from functions like get_template
, that are
generic over G: Html
, you can use .template()
, to avoid having
to specify ::<G>
manually.
See Template
for further details, and the book for further details
on the differences between the function and reference patterns.
sourcepub fn capsule<P: Clone + 'static>(
self,
val: impl Into<Forever<Capsule<G, P>>>
) -> Self
pub fn capsule<P: Clone + 'static>( self, val: impl Into<Forever<Capsule<G, P>>> ) -> Self
Adds a single new capsule to the app. Like .template()
, this expects
the output of a function that is generic over G: Html
. If you have
something with a predetermined type, like a lazy_static!
that’s
using PerseusNodeType
, you should use .capsule_ref()
instead. For more information on the differences between the function
and reference patterns, see the book.
See Capsule
for further details.
sourcepub fn capsule_ref<H: Html, P: Clone + 'static>(
self,
val: impl Into<Forever<Capsule<H, P>>>
) -> Self
pub fn capsule_ref<H: Html, P: Clone + 'static>( self, val: impl Into<Forever<Capsule<H, P>>> ) -> Self
Adds a single new capsule to the app. This behaves like
.template_ref()
, but for capsules.
See Capsule
for further details.
sourcepub fn error_views(self, val: ErrorViews<G>) -> Self
pub fn error_views(self, val: ErrorViews<G>) -> Self
Sets the app’s error views. See ErrorViews
for further details.
sourcepub fn global_state_creator(self, val: GlobalStateCreator) -> Self
pub fn global_state_creator(self, val: GlobalStateCreator) -> Self
Sets the app’s GlobalStateCreator
.
sourcepub fn locales(self, default: &str, other: &[&str]) -> Self
pub fn locales(self, default: &str, other: &[&str]) -> Self
Sets the locales information for the app. The first argument is the default locale (used as a fallback for users with no locale preferences set in their browsers), and the second is a list of other locales supported.
Note that this does not update the translations manager, which must be
done separately (if you’re using FsTranslationsManager
, the default,
you can use .locales_and_translations_manager()
to set both at
once).
If you’re not using i18n, you don’t need to call this function. If you
for some reason do have to though (e.g. overriding some other
preferences in middleware), use .disable_i18n()
, not this, as
you’re very likely to shoot yourself in the foot! (If i18n is disabled,
the default locale MUST be set to xx-XX
, for example.)
sourcepub fn locales_lit(self, val: Locales) -> Self
pub fn locales_lit(self, val: Locales) -> Self
Sets the locales information directly based on an instance of
Locales
. Usually, end users will use .locales()
instead for a
friendlier interface.
sourcepub fn translations_manager(
self,
val: impl Future<Output = T> + 'static
) -> Self
pub fn translations_manager( self, val: impl Future<Output = T> + 'static ) -> Self
Sets the translations manager. If you’re using the default translations
manager (FsTranslationsManager
), you can use
.locales_and_translations_manager()
to set this automatically
based on the locales information. This takes a Future<Output = T>
,
where T
is your translations manager’s type.
The reason that this takes a Future
is to avoid the use of .await
in
your app definition code, which must be synchronous due to constraints
of Perseus’ browser-side systems. When your code is run on the
server, the Future
will be .await
ed on, but in Wasm, it will be
discarded and ignored, since the translations manager isn’t needed in
Wasm.
This is generally intended for use with custom translations manager or specific use-cases with the default (mostly to do with custom caching behavior).
sourcepub fn disable_i18n(self) -> Self
pub fn disable_i18n(self) -> Self
Explicitly disables internationalization. You shouldn’t ever need to call this, as it’s the default, but you may want to if you’re writing middleware that doesn’t support i18n.
sourcepub fn static_aliases(self, val: HashMap<String, String>) -> Self
pub fn static_aliases(self, val: HashMap<String, String>) -> Self
Sets all the app’s static aliases. This takes a map of URLs (e.g.
/file
) to resource paths, relative to the project directory (e.g.
style.css
). Generally, calling .static_alias()
many times is
preferred.
sourcepub fn static_alias(self, url: &str, resource: &str) -> Self
pub fn static_alias(self, url: &str, resource: &str) -> Self
Adds a single static alias. This takes a URL path (e.g. /file
)
followed by a path to a resource (which must be within the project
directory, e.g. style.css
).
sourcepub fn plugins(self, val: Plugins) -> Self
pub fn plugins(self, val: Plugins) -> Self
Sets the plugins that the app will use. See Plugins
for
further details.
sourcepub fn mutable_store(self, val: M) -> Self
pub fn mutable_store(self, val: M) -> Self
Sets the MutableStore
for the app to use, which you would change for
some production server environments if you wanted to store build
artifacts that can change at runtime in a place other than on the
filesystem (created for serverless functions specifically).
sourcepub fn immutable_store(self, val: ImmutableStore) -> Self
pub fn immutable_store(self, val: ImmutableStore) -> Self
Sets the ImmutableStore
for the app to use. You should almost never
need to change this unless you’re not working with the CLI.
sourcepub fn index_view_str(self, val: &str) -> Self
pub fn index_view_str(self, val: &str) -> Self
Sets the index view as a string. This should be used if you’re using an
index.html
file or the like.
Note: if possible, you should switch to using .index_view()
, which
uses a Sycamore view rather than an HTML string.
sourcepub fn index_view<'a>(self, f: impl Fn(Scope<'_>) -> View<SsrNode> + 'a) -> Self
pub fn index_view<'a>(self, f: impl Fn(Scope<'_>) -> View<SsrNode> + 'a) -> Self
Sets the index view using a Sycamore view, which avoids the need to
write any HTML by hand whatsoever. Note that this must contain a
<head>
and <body>
at a minimum.
Warning: this view can’t be reactive (yet). It will be rendered to a static string, which won’t be hydrated.
sourcepub fn pss_max_size(self, val: usize) -> Self
pub fn pss_max_size(self, val: usize) -> Self
Sets the maximum number of pages that can have their states stored in the page state store before the oldest will be evicted. If your app is taking up a substantial amount of memory in the browser because your page states are fairly large, making this smaller may help.
By default, this is set to 25. Higher values may lead to memory difficulties in both development and production, and the poor user experience of a browser that’s substantially slowed down.
WARNING: any setting applied here will impact HSR in development! (E.g. setting this to 1 would mean your position would only be saved for the most recent page.)
sourcepub fn panic_handler(
self,
val: impl Fn(&PanicInfo<'_>) + Send + Sync + 'static
) -> Self
pub fn panic_handler( self, val: impl Fn(&PanicInfo<'_>) + Send + Sync + 'static ) -> Self
Sets the browser-side panic handler for your app. This is a function that will be executed if your app panics (which should never be caused by Perseus unless something is seriously wrong, it’s much more likely to come from your code, or third-party code).
In the case of a panic, Perseus will automatically try to render a full popup error to explain the situation to the user before terminating, but, since it’s impossible to use the plugins in the case of a panic, this function is provided as an alternative in case you want to perform other work, like sending a crash report.
This function must not panic itself, because Perseus renders the
message after your handler is executed. If it panics, that popup
will never get to the user, leading to very poor UX. That said,
don’t stress about calling things like web_sys::window().unwrap()
,
because, if that fails, then trying to render a popup will
definitely fail anyway. Perseus will attempt to write an error
message to the console before this, just in case anything panics.
Note that there is no access within this function to Sycamore, page
state, global state, or translators. Assume that your code has
completely imploded when you write this function. Anything more advanced
should be left to your error views system, when it handles
ClientError::Panic
.
This has no default value.
sourcepub fn get_root(&self) -> Result<String, PluginError>
pub fn get_root(&self) -> Result<String, PluginError>
Gets the HTML ID of the <div>
at which to insert Perseus.
sourcepub fn get_index_view_str(&self) -> String
pub fn get_index_view_str(&self) -> String
Gets the index view as a string, without generating an HTML shell (pass
this into ::get_html_shell()
to do that).
Note that this automatically adds <!DOCTYPE html>
to the start of the
HTML shell produced, which can only be overridden with a control plugin
(though you should really never do this in Perseus, which targets
HTML on the web).
sourcepub fn get_locales(&self) -> Result<Locales, PluginError>
pub fn get_locales(&self) -> Result<Locales, PluginError>
Gets the locales information.
sourcepub async fn get_translations_manager(self) -> T
pub async fn get_translations_manager(self) -> T
Gets the server-side TranslationsManager
. Like the mutable store,
this can’t be modified by plugins due to trait complexities.
This involves evaluating the future stored for the translations manager,
and so this consumes self
.
sourcepub fn get_immutable_store(&self) -> Result<ImmutableStore, PluginError>
pub fn get_immutable_store(&self) -> Result<ImmutableStore, PluginError>
Gets the ImmutableStore
.
sourcepub fn get_static_aliases(&self) -> Result<HashMap<String, String>, PluginError>
pub fn get_static_aliases(&self) -> Result<HashMap<String, String>, PluginError>
Gets the static aliases. This will check all provided resource paths to
ensure they don’t reference files outside the project directory, due to
potential security risks in production (we don’t want to
accidentally serve an arbitrary in a production environment where a path
may point to somewhere evil, like an alias to /etc/passwd
).
sourcepub fn take_panic_handlers(
&mut self
) -> (Option<Box<dyn Fn(&PanicInfo<'_>) + Send + Sync + 'static>>, Arc<dyn Fn(Scope<'_>, ClientError, ErrorContext, ErrorPosition) -> (View<SsrNode>, View<G>) + Send + Sync>)
pub fn take_panic_handlers( &mut self ) -> (Option<Box<dyn Fn(&PanicInfo<'_>) + Send + Sync + 'static>>, Arc<dyn Fn(Scope<'_>, ClientError, ErrorContext, ErrorPosition) -> (View<SsrNode>, View<G>) + Send + Sync>)
Takes the user-set panic handlers out and returns them as an owned tuple, allowing them to be used in an actual panic hook.
Future panics
If this is called more than once, the view panic handler will panic when called.