diff --git a/docs/content/index.md b/docs/content/_index.md similarity index 100% rename from docs/content/index.md rename to docs/content/_index.md diff --git a/docs/content/docs/adding-crud-models.md b/docs/content/docs/adding-crud-models.md new file mode 100644 index 0000000..23803ac --- /dev/null +++ b/docs/content/docs/adding-crud-models.md @@ -0,0 +1,78 @@ +--- +title: "Adding Models & Views" +date: 2023-01-17T11:44:56+01:00 +draft: false +weight: 2 +--- + +# Adding CRUD Models + +CRUD Models can be added to the AdminInterface which will render a HTML table and the CRUD functions in the View. + +## Struct Annotations + +The struct for which the view is generated needs to be annotated and at least requires a primary key with the annotation ```#[actix_admin(primary_key)]```. + +```rust +use actix_admin::prelude::*; + +pub struct Model { + #[sea_orm(primary_key)] + #[serde(skip_deserializing)] + #[actix_admin(primary_key)] + pub id: i32, + pub comment: String +} +``` + +## Derive Implementations + +Actix-Admin relies on two traits to display models which can either be implemented automatically by Macros or manually: +* **ActixAdminViewModelTrait**: Handles how the CRUD Tables are displayed +* **ActixAdminModelTrait**: Acts as an abstraction between the internal ViewModel and the DB-specific interactions + +These can be implemented manually or auto derived by using the following macros: +* DeriveActixAdmin +* DeriveActixAdminModel +* DeriveActixAdminViewModel + +```rust +use sea_orm::entity::prelude::*; + +#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Deserialize, Serialize, + DeriveActixAdmin, + DeriveActixAdminModel, + DeriveActixAdminViewModel +)] +#[sea_orm(table_name = "comment")] +pub struct Model { + #[sea_orm(primary_key)] + #[serde(skip_deserializing)] + #[actix_admin(primary_key)] + pub id: i32, + pub comment: String +} +``` + +## Add the Views to Actix-Admin + +Within the ActixAdminBuilder, the entity can be added as per following code and they will appear in the NavBar in the admin interface. + +```rust +fn create_actix_admin_builder() -> ActixAdminBuilder { + let mut admin_builder = ActixAdminBuilder::new(configuration); + + let comment_view_model = ActixAdminViewModel::from(Comment); + admin_builder.add_entity::(&comment_view_model); + + admin_builder +} +``` + +## View Groups + +Views / Models can be grouped in the Navbar by using the following functions instead of ```admin_builder.add_entity```: +```rust +admin_builder.add_entity::(&comment_view_model); +admin_builder.add_entity_to_category::(&comment_view_model, "Group 1"); +``` \ No newline at end of file diff --git a/docs/content/docs/custom-handler.md b/docs/content/docs/custom-handler.md new file mode 100644 index 0000000..b604537 --- /dev/null +++ b/docs/content/docs/custom-handler.md @@ -0,0 +1,86 @@ +--- +title: "Custom Handlers" +date: 2023-01-17T11:44:56+01:00 +draft: false +weight: 3 +--- + +# Custom Handler + +While the derived models create predefined routes and views, custom routes can be added to the admin interface and also base templates can be extended. + +## Custom Index + +A custom *custom_index.html* view can be defined as follows by extending the base template: +```html +{% extends "base.html" %} +{% block content %} +

This is a custom index page shown under /admin/ extending the base template

+{% endblock content %} +``` + +To display the *custom_index.html*, define the corresponding function which extends the current tera context from actix-admin and also uses the actix-admin tera instance to render the custom index function. + +```rust +async fn custom_index( + session: Session, + data: web::Data +) -> Result { + + let mut ctx = Context::new(); + ctx.extend(get_admin_ctx(session, &data)); + + let body = data.get_tmpl() + .render("custom_index.html", &ctx).unwrap(); + + Ok(HttpResponse::Ok().content_type("text/html").body(body)) +} +``` + +After this in the builder, pass your custom index function defined above: +```rust +let mut admin_builder = ActixAdminBuilder::new(configuration); +admin_builder.add_custom_handler_for_index::( + web::get().to(custom_index::) +); +``` + +## Custom Handlers + +Similarly to the custom index above, the builder accepts additional routes to be passed to the admin interface. + +### Root Path +```rust +// This will be shown in the top level menu +let show_in_menu = true; +admin_builder.add_custom_handler("Custom Route in Menu", "/custom_route_in_menu", web::get().to custom_index::), show_in_menu); +``` + +### Tied to a specific entity +```rust +// this will expose a menu item which links to /admin/comment/custom_handler and is shown in the NavBar menu +let show_in_menu = true; +let some_category = "Some Category"; +admin_builder.add_entity_to_category::(&comment_view_model, some_category); +admin_builder.add_custom_handler_for_entity::( + "My custom handler", + "/custom_handler", + web::get().to(custom_handler::), + show_in_menu +); +``` + +### Added to an entity but shown grouped in a Category +```rust +// this will expose a menu item which links to /admin/comment/custom_handler and is shown in the NavBar menu in the group "Some Category" +let show_in_menu = true; +let some_category = "Some Category"; +admin_builder.add_entity_to_category::(&comment_view_model, some_category); +admin_builder.add_custom_handler_for_entity_in_category::( + "My custom handler", + "/custom_handler", + web::get().to(custom_handler::), + some_category, + show_in_menu +); +``` diff --git a/docs/content/docs/getting-started.md b/docs/content/docs/getting-started.md index b63aa14..423466c 100644 --- a/docs/content/docs/getting-started.md +++ b/docs/content/docs/getting-started.md @@ -2,6 +2,86 @@ title: "Getting Started" date: 2023-01-17T11:44:56+01:00 draft: false +weight: 1 --- -# Getting Started \ No newline at end of file +# Getting Started + +## Import actix-admin + +Cargo.toml: +```cargo +[dependencies] +actix-admin = "0.3.0" +``` + +## Implement the Trait for AppState + +Actix-Admin requires to get the database connection and its configuration from the actix AppState. The trait "ActixAdminAppDataTrait" must be implemented for your AppState: + +```rust +use actix_admin::prelude::*; + +#[derive(Clone)] +pub struct AppState { + pub db: DatabaseConnection, + pub actix_admin: ActixAdmin, +} + +impl ActixAdminAppDataTrait for AppState { + fn get_db(&self) -> &DatabaseConnection { + &self.db + } + fn get_actix_admin(&self) -> &ActixAdmin { + &self.actix_admin + } +} +``` + +## Build the Actix-Admin Configuration + +The configuration can be built like the followings, which initializes a ActixAdminBuilder entity: + +```rust +use actix_admin::prelude::*; + +fn create_actix_admin_builder() -> ActixAdminBuilder { + let configuration = ActixAdminConfiguration { + enable_auth: false, + user_is_logged_in: None, + login_link: None, + logout_link: None, + file_upload_directory: "./file_uploads" + }; + + let mut admin_builder = ActixAdminBuilder::new(configuration); + + admin_builder +} +``` + +## Pass the configuration to Actix-Web + +The AppState and the configuration can be passed to Actix-Web like in the following snippet. The ActixAdminBuilder creates an own */admin/* Scope which is registered as a service in the Actix-Web app. + +```rust +let actix_admin_builder = create_actix_admin_builder(); + +let app_state = AppState { + db: conn.clone(), + actix_admin: actix_admin_builder.get_actix_admin(), +}; + +let app = App::new() + .app_data(web::Data::new(app_state)) + .service( + actix_admin_builder.get_scope::() + ) + .wrap(middleware::Logger::default()) +``` + +## Complete Example + +The above steps will initialize an empty ActixAdmin interface under */admin/*. For a complete example please the following link: + +[https://github.com/mgugger/actix-admin/tree/main/examples/basic](https://github.com/mgugger/actix-admin/tree/main/examples/basic) \ No newline at end of file