Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2025-12-18 23:05:07 +01:00
Code Issues Packages Projects Releases Wiki Activity

MyST conversion

Browse Source
This commit is contained in:
Ariel Rin
2023-10-31 23:31:41 +10:00
parent 7024552c4e
commit 98e91fe207
25 changed files with 348 additions and 332 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
docs/development/custom/integrating-services.md
View File

@@ -20,19 +20,21 @@ Typically a service will contain 5 key components:
The architecture looks something like this:
urls -------▶ Views
▲ |
| |
| ▼
ServiceHook ----▶ Tasks ----▶ Manager
▲
|
|
AllianceAuth
```none
urls -------▶ Views
▲ |
| |
| ▼
ServiceHook ----▶ Tasks ----▶ Manager
▲
|
|
AllianceAuth
Where:
Module --▶ Dependency/Import
Where:
Module --▶ Dependency/Import
```
While this is the typical structure of the existing services modules, there is no enforcement of this structure and you are, effectively, free to create whatever architecture may be necessary. A service module need not even communicate with an external service, for example, if similar triggers such as validate_user, delete_user are required for a module it may be convenient to masquerade as a service. Ideally though, using the common structure improves the maintainability for other developers.
@@ -40,27 +42,31 @@ While this is the typical structure of the existing services modules, there is n
In order to integrate with Alliance Auth service modules must provide a `services_hook`. This hook will be a function that returns an instance of the `services.hooks.ServiceHook` class and decorated with the `@hooks.registerhook` decorator. For example:
@hooks.register('services_hook')
def register_service():
return ExampleService()
```python
@hooks.register('services_hook')
def register_service():
return ExampleService()
```
This would register the ExampleService class which would need to be a subclass of `services.hooks.ServiceHook`.
:::{important}
The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
:::
A subclassed `ServiceHook` might look like this:
class ExampleService(ServicesHook):
def __init__(self):
ServicesHook.__init__(self)
self.urlpatterns = urlpatterns
self.service_url = 'http://exampleservice.example.com'
```python
class ExampleService(ServicesHook):
def __init__(self):
ServicesHook.__init__(self)
self.urlpatterns = urlpatterns
self.service_url = 'http://exampleservice.example.com'
"""
Overload base methods here to implement functionality
"""
"""
Overload base methods here to implement functionality
"""
```
### The ServiceHook class
@@ -70,9 +76,9 @@ You will need to subclass `services.hooks.ServiceHook` in order to provide imple
Instance Variables:
- [self.name](#self-name)
- [self.urlpatterns](#self-url-patterns)
- [self.service_ctrl_template](#self-service-ctrl-template)
- [self.name](#selfname)
- [self.urlpatterns](#selfurlpatterns)
- [self.service_ctrl_template](#selfservice_ctrl_template)
Properties:
@@ -87,8 +93,6 @@ Functions:
- [update_groups](#update_groups)
- [update_groups_bulk](#update_groups_bulk)
- [update_all_groups](#update_all_groups)
- [service_enabled_members](#service_enabled_members)
- [service_enabled_blues](#service_enabled_blues)
- [service_active_for_user](#service_active_for_user)
- [show_service_ctrl](#show_service_ctrl)
- [render_service_ctrl](#render_service_ctrl)
@@ -101,18 +105,20 @@ Internal name of the module, should be unique amongst modules.
You should define all of your service URLs internally, usually in `urls.py`. Then you can import them and set `self.urlpatterns` to your defined urlpatterns.
from . import urls
...
class MyService(ServiceHook):
def __init__(self):
...
self.urlpatterns = urls.urlpatterns
```python
from . import urls
...
class MyService(ServiceHook):
def __init__(self):
...
self.urlpatterns = urls.urlpatterns
```
All of your apps defined urlpatterns will then be included in the `URLconf` when the core application starts.
#### self.service_ctrl_template
This is provided as a courtesy and defines the default template to be used with [render_service_ctrl](#render-service-ctrl). You are free to redefine or not use this variable at all.
This is provided as a courtesy and defines the default template to be used with [render_service_ctrl](#render_service_ctrl). You are free to redefine or not use this variable at all.
#### title
@@ -134,10 +140,12 @@ Validate the users service account, deleting it if they should no longer have ac
An implementation will probably look like the following:
def validate_user(self, user):
logger.debug('Validating user %s %s account' % (user, self.name))
if ExampleTasks.has_account(user) and not self.service_active_for_user(user):
self.delete_user(user, notify_user=True)
```python
def validate_user(self, user):
logger.debug('Validating user %s %s account' % (user, self.name))
if ExampleTasks.has_account(user) and not self.service_active_for_user(user):
self.delete_user(user, notify_user=True)
```
No return value is expected.
@@ -206,37 +214,39 @@ Should the service be shown for the given `user` with the given `state`? The `us
Usually you wont need to override this function.
For more information see the [render_service_ctrl](#render-service-ctrl) section.
For more information see the [render_service_ctrl](#render_service_ctrl) section.
#### render_service_ctrl
`def render_services_ctrl(self, request):`
Render the services control row. This will be called for all active services when a user visits the `/services/` page and [show_service_ctrl](#show-service-ctrl) returns `True` for the given user.
Render the services control row. This will be called for all active services when a user visits the `/services/` page and [show_service_ctrl](#show_service_ctrl) returns `True` for the given user.
It should return a string (usually from `render_to_string`) of a table row (`<tr>`) with 4 columns (`<td>`). Column #1 is the service name, column #2 is the users username for this service, column #3 is the services URL, and column #4 is the action buttons.
You may either define your own service template or use the default one provided. The default can be used like this example:
def render_services_ctrl(self, request):
"""
Example for rendering the service control panel row
You can override the default template and create a
custom one if you wish.
:param request:
:return:
"""
urls = self.Urls()
urls.auth_activate = 'auth_example_activate'
urls.auth_deactivate = 'auth_example_deactivate'
urls.auth_reset_password = 'auth_example_reset_password'
urls.auth_set_password = 'auth_example_set_password'
return render_to_string(self.service_ctrl_template, {
'service_name': self.title,
'urls': urls,
'service_url': self.service_url,
'username': 'example username'
}, request=request)
```python
def render_services_ctrl(self, request):
"""
Example for rendering the service control panel row
You can override the default template and create a
custom one if you wish.
:param request:
:return:
"""
urls = self.Urls()
urls.auth_activate = 'auth_example_activate'
urls.auth_deactivate = 'auth_example_deactivate'
urls.auth_reset_password = 'auth_example_reset_password'
urls.auth_set_password = 'auth_example_set_password'
return render_to_string(self.service_ctrl_template, {
'service_name': self.title,
'urls': urls,
'service_url': self.service_url,
'username': 'example username'
}, request=request)
```
the `Urls` class defines the available URL names for the 4 actions available in the default template:
@@ -293,3 +303,9 @@ You should have a look through some of the other service modules before you get
## Testing
You will need to add unit tests for all aspects of your service module before it is accepted. Be mindful that you don't actually want to make external calls to the service so you should mock the appropriate components to prevent this behavior.
```{eval-rst}
.. autoclass:: allianceauth.services.hooks.ServicesHook
:members:
:undoc-members:
```

11
docs/development/custom/logging.md
View File

@@ -1,7 +1,9 @@
# Logging from Custom Apps
Alliance Auth provides a logger for use with custom apps to make everyone's life a little easier.
## Using the Extensions Logger
AllianceAuth provides a helper function to get the logger for the current module to reduce the amount of
code you need to write.
@@ -15,19 +17,28 @@ This works by creating a child logger of the extension logger which propagates a
to the parent (extensions) logger.
## Changing the Logging Level
By default, the extension logger's level is set to `DEBUG`.
To change this, uncomment (or add) the following line in `local.py`.
```python
LOGGING['handlers']['extension_file']['level'] = 'INFO'
```
*(Remember to restart your supervisor workers after changes to `local.py`)*
This will change the logger's level to the level you define.
Options are: *(all options accept entries of levels listed below them)*
* `DEBUG`
* `INFO`
* `WARNING`
* `ERROR`
* `CRITICAL`
```{eval-rst}
.. automodule:: allianceauth.services.hooks.get_extension_logger
:members:
:undoc-members:
```

13
docs/development/custom/menu-hooks.md
View File

@@ -4,10 +4,10 @@ The menu hooks allow you to dynamically specify menu items from your plugin app
To register a MenuItemHook class you would do the following:
```Python
```python
@hooks.register('menu_item_hook')
def register_menu():
return MenuItemHook('Example Item', 'glyphicon glyphicon-heart', 'example_url_name',150)
return MenuItemHook('Example Item', 'fas fa-users fa-fw', 'example_url_name',150)
```
The `MenuItemHook` class specifies some parameters/instance variables required for menu item display.
@@ -41,13 +41,14 @@ A list of views or namespaces the link should be highlighted on. See [django-nav
This is a great feature to signal the user, that he has some open issues to take care of within an app. For example Auth uses this feature to show the specific number of open group request to the current user.
:::{hint}
Here is how to stay consistent with the Auth design philosophy for using this feature:
1. Use it to display open items that the current user can close by himself only. Do not use it for items, that the user has no control over.
2. If there are currently no open items, do not show a badge at all.
Here is how to stay consistent with the Auth design philosophy for using this feature:
1. Use it to display open items that the current user can close by himself only. Do not use it for items, that the user has no control over.
2. If there are currently no open items, do not show a badge at all.
:::
To use it set count the `render()` function of your subclass in accordance to the current user. Here is an example:
```Python
```python
def render(self, request):
# ...
self.count = calculate_count_for_user(request.user)

4
docs/development/custom/url-hooks.md
View File

@@ -19,8 +19,8 @@ In addition is it possible to make views public. Normally, all views are automat
An app can opt-out of this feature by adding a list of views to be excluded when registering the URLs. See the `excluded_views` parameter for details.
:::{note}
Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the apps label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
```
Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the apps label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
:::
## Examples