update docs

This commit is contained in:
Manuel Gugger 2023-01-17 18:10:27 +01:00
parent 7ea7882dfa
commit 7960814233
4 changed files with 245 additions and 1 deletions

View File

@ -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::<AppState, Comment>(&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::<AppState, Comment>(&comment_view_model);
admin_builder.add_entity_to_category::<AppState, Comment>(&comment_view_model, "Group 1");
```

View File

@ -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 %}
<p>This is a custom index page shown under /admin/ extending the base template<p>
{% 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<T: ActixAdminAppDataTrait + AppDataTrait>(
session: Session,
data: web::Data<T>
) -> Result<HttpResponse, Error> {
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::<AppState>(
web::get().to(custom_index::<AppState>)
);
```
## 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::<AppState>), 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::<AppState, Comment>(&comment_view_model, some_category);
admin_builder.add_custom_handler_for_entity::<AppState, Comment>(
"My custom handler",
"/custom_handler",
web::get().to(custom_handler::<AppState, Comment>),
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::<AppState, Comment>(&comment_view_model, some_category);
admin_builder.add_custom_handler_for_entity_in_category::<AppState, Comment>(
"My custom handler",
"/custom_handler",
web::get().to(custom_handler::<AppState, Comment>),
some_category,
show_in_menu
);
```

View File

@ -2,6 +2,86 @@
title: "Getting Started" title: "Getting Started"
date: 2023-01-17T11:44:56+01:00 date: 2023-01-17T11:44:56+01:00
draft: false draft: false
weight: 1
--- ---
# Getting Started # 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::<AppState>()
)
.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)