Struct perseus::PerseusAppBase

pub struct PerseusAppBase<G: Html, M: MutableStore, T: TranslationsManager> { /* private fields */ }

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.

Implementations

impl<G: Html, T: TranslationsManager> PerseusAppBase<G, FsMutableStore, T>

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.

impl<G: Html, M: MutableStore> PerseusAppBase<G, M, FsTranslationsManager>

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).

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.)

impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T>

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).

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!

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.

pub fn templates(self, val: Vec<Box<dyn Fn() -> Template<G>>>) -> Self

Sets all the app’s templates. This takes a vector of boxed functions that return templates.

Usually, it’s preferred to run .template() once for each template, rather than manually constructing this more inconvenient type.

pub fn template(self, val: impl Fn() -> Template<G> + 'static) -> Self

Adds a single new template to the app (convenience function). This takes a function that returns a template (for internal reasons).

See Template for further details.

pub fn error_pages(self, val: impl Fn() -> ErrorPages<G> + 'static) -> Self

Sets the app’s error pages. See ErrorPages for further details.

pub fn global_state_creator(self, val: GlobalStateCreator) -> Self

Sets the app’s GlobalStateCreator.

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.)

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.

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 .awaited 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).

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.

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.

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).

pub fn plugins(self, val: Plugins<G>) -> Self

Sets the plugins that the app will use. See Plugins for further details.

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).

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.

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.

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.

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.)

pub fn get_root(&self) -> String

Gets the HTML ID of the <div> at which to insert Perseus.

pub fn get_static_dir(&self) -> String

Gets the directory containing static assets to be hosted under the URL /.perseus/static/.

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).

pub async fn get_html_shell(
    index_view_str: String,
    root: &str,
    immutable_store: &ImmutableStore,
    plugins: &Plugins<G>
) -> HtmlShell

Gets an HTML shell from an index view string. This is broken out so that it can be executed after the app has been built (which requires getting the translations manager, consuming self). As inconvenient as this is, it’s necessitated, otherwise exporting would try to access the built app before it had actually been built.

pub fn get_templates_map(&self) -> TemplateMap<G>

Gets the templates in an Rc-based HashMap for non-concurrent access.

pub fn get_atomic_templates_map(&self) -> ArcTemplateMap<G>

Gets the templates in an Arc-based HashMap for concurrent access. This should only be relevant on the server-side.

pub fn get_error_pages(&self) -> ErrorPages<G>

Gets the ErrorPages used in the app. This returns an Rc.

pub fn get_pss_max_size(&self) -> usize

Gets the maximum number of pages that can be stored in the page state store before the oldest are evicted.

pub fn get_global_state_creator(&self) -> Arc<GlobalStateCreator>

Gets the GlobalStateCreator. This can’t be directly modified by plugins because of reactive type complexities.

pub fn get_locales(&self) -> Locales

Gets the locales information.

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.

pub fn get_immutable_store(&self) -> ImmutableStore

Gets the ImmutableStore.

pub fn get_mutable_store(&self) -> M

Gets the MutableStore. This can’t be modified by plugins due to trait complexities, so plugins should instead expose a function that the user can use to manually set it.

pub fn get_plugins(&self) -> Rc<Plugins<G>>

Gets the plugins registered for the app. These are passed around and used in a way that doesn’t require them to be concurrently accessible, and so are provided in an Rc.

pub fn get_static_aliases(&self) -> HashMap<String, String>

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).

Trait Implementations

impl<G: Debug + Html, M: Debug + MutableStore, T: Debug + TranslationsManager> Debug for PerseusAppBase<G, M, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.