Custom App Development Documentation

Technical aspects, customization, code samples.
Post Reply
davebauerart
Posts: 3
Joined: Tue Apr 14, 2020 5:50 pm

Custom App Development Documentation

Post by davebauerart »

I have looked all over, and there are some broken links to previous app development documentation, which I found the source for in gitlab. It is a little incomplete. I am curious what code I need to write to extend, add a custom app.

I started with the cookie cutter template. That is about 4 years old and developed for an older version of Mayan. I got it working be fixing errors and reading the source code. I am now working on adding templates for my custom views. Again, I have to guess, cause an error message, and figure out which code is executing, then read that source code to incrementally develop a model of what's going on.

Is there some documentation that explains the steps to develop a custom app? I am pretty sure this will be very powerful when I figure it out. I am willing to contribute to improving the documentation, but I want to make sure I start in the right place.
davebauerart
Posts: 3
Joined: Tue Apr 14, 2020 5:50 pm

Re: Custom App Development Documentation

Post by davebauerart »

Good news, after a couple of weeks of inspecting the code, and experimenting, I have made a lot of progress. I'm really curious is there are other developers out there that have implemented custom apps for Mayan and how they figured this all out. It's certainly possible, if you read enough source code, but is there an easier way?
RonObvious
Posts: 8
Joined: Sat Nov 28, 2020 6:06 pm

Re: Custom App Development Documentation

Post by RonObvious »

Would you mind sharing some of your insights?

Up to version 4.1 I've been using a custom validator. Because the available validators could be listed in the `METADATA_AVAILABLE_VALIDATORS` variable, it was easy to just drop a custom module into the user_data directory and reference that.

Now since version 4.2 the validators are registered automatically, and my custom validator is not displayed any more in the Mayan UI. Maybe a custom app could help with that problem.

My questions are:
  • What is the minimal code needed for an app, something like a "hello world" example? How do I "register" my app?
  • What is the best way to deploy an app? Do I have to put it into the apps subfolder of the main application, or is there a way to configure "sideloading" from the user data directory, for example?
  • How can I define the dependencies of my app?
I have just started, I'm sure all these questions can be answered by reading the code. But maybe there is a shortcut ;) Thanks, any help is appreciated!
RonObvious
Posts: 8
Joined: Sat Nov 28, 2020 6:06 pm

Re: Custom App Development Documentation

Post by RonObvious »

To (partly) answer my own questions:
  • The motd app has been renamed to "announcements", but it was left in the app folder as a stub for migrations. The __init__.py and apps.py can be used as a minimal example.
  • The variable COMMON_EXTRA_APPS can be used to reference python packages, which will be imported as apps. The string value has to be interpretable as python list, for example: "['custom.app1', 'custom.app2']". A package will be found in the user data directory (path "custom/app1", "custom/app2" in this example, with the __init__.py files present). My custom validator was registered by adding the right import statement to the __init__.py of the package.
  • Not sure about dependencies, but I suppose the apps in COMMON_EXTRA_APPS are loaded after all the built-in apps.
User avatar
michael
Developer
Developer
Posts: 297
Joined: Sun Apr 19, 2020 6:21 am

Re: Custom App Development Documentation

Post by michael »

Hello,
Now since version 4.2 the validators are registered automatically, and my custom validator is not displayed any more in the Mayan UI. Maybe a custom app could help with that problem.

To have your metadata validators registered put then in a module named metadata_validators.py in your or any other app. For metadata parsers the module is named metadata_parsers.py.
What is the minimal code needed for an app, something like a "hello world" example? How do I "register" my app?
Just the app folder converted into a valid Python module with the corresponding __init__.py file and a apps.py module with a subclass of MayanAppConfig. Then add the app path or short name if defined in the __init__.py file to the COMMON_EXTRA_APPS setting.
What is the best way to deploy an app? Do I have to put it into the apps subfolder of the main application, or is there a way to configure "sideloading" from the user data directory, for example?
This will depend on how much will your app modify Mayan's behavior. If your code is able to use Mayan's hooks and services like links, menus, models, then writing a separate app packaged as a Python library that is installed after Mayan is installed is the optimal method.

If your code makes low level changes to services that are not public or exposed for modification, then you will need to fork the project and make an app that resides together with the rest of the code tree.

The last method is forking the code and making your changes by overwriting the original code.
How can I define the dependencies of my app?
Dependencies are added via the dependencies.py module. Mayan currently supports Python, JavaScript (via npmjs.com) and binary dependencies. Python and JavaScript dependencies are automatically downloaded, patched (if required) and installed. Binary dependencies are only verified but not installed as this would be an operating system dependent action.
The motd app has been renamed to "announcements", but it was left in the app folder as a stub for migrations. The __init__.py and apps.py can be used as a minimal example.
Another good app to use an an example is the tags app. Has a simple model yet is able to interact with the documents app. It has links and its own main menu entry along with permissions.
Not sure about dependencies, but I suppose the apps in COMMON_EXTRA_APPS are loaded after all the built-in apps.
That is correct. If you need you app to be loaded before the core app, use instead COMMON_EXTRA_APPS_PRE.

Hope this helps. Cheers!
Post Reply