Struct perseus::PerseusAppBase

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

The options for constructing a Perseus app. These encompass all the information Perseus needs to know to create your app. Every Perseus app using the engine must export one of these.

Note that this is an interim storage point, it’s not depended on by any part of the core logic, and therefore custom engines can entirely ignore this.

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. For most apps, this will be sufficient. Note that this initializes the translations manager as a dummy, 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 custom mutable store.

pub fn root(self, val: &str) -> Self

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

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

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.

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.

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

Sets the app’s error pages.

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

Sets the app’s global state creator.

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’ client-side systems. When your code is run on the server, the Future will be .awaited on, but on 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).

pub fn static_alias(self, url: &str, resource: &str) -> Self

Adds a single static alias (convenience function). 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.

pub fn mutable_store(self, val: M) -> Self

Sets the mutable store 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 immutable store 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 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 overriden 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 requries 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 error pages used in the app. This returns an Rc.

pub fn get_global_state_creator(&self) -> GlobalStateCreator

Gets the global state creator. 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 translations manager. 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 immutable store.

pub fn get_mutable_store(&self) -> M

Gets the mutable store. 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.