Custom subresource in documentation (without parent constraint)

[andrea.s...@gmail.com]

By default, each time I define a media type as children of another one, in its documentation it correctly stands (on the left menu) under the parent's menu.
Is it possible to group sub resources basing on - for example - the route prefix - or any other kind of group hat, without the needing of defining a parent media-type (that would neither exists, logically).

In my case, I have a master resource (media-type) named BusinessUnit.
In the context of a business unit I have defined a set of many sub resources, such as Users or Guests, but I also have a set of resources - that are per business_unit configurable decoded values in the end - that have (and must do) BusinessUnit as parent resource, but that should also be considered as a whole group of "decoded values" as thus it would be nice to have them documented under a "Decoded values" submenu, under the BusinessUnit resource menu item:

Resources
|
↳ BusinessUnits
|
↳ Decoded Values # How can I define this submenu?
| ↳ In types
| ↳ Out types
| ↳ ParentalTypes
| ↳ ...
↳ Guest
↳ User

Thank you!
--
Andrea

[andrea.s...@gmail.com]

I have found a "standard" way to resolve.

I have defined the following (logical) media-type:

module MediaTypes
class Decode < Praxis::MediaType
identifier 'application/com.e-personam.decode'

description 'Decodifiche specifiche della struttura.'

attributes do
end
end
end
end

and the following (logical) resource:

require_relative 'business_units'

module V1
module Resources
class Decodes
include Praxis::ResourceDefinition

media_type V1::MediaTypes::Decode
version '1.0'

parent BusinessUnits

display_name 'Decodifiche di struttura'

action :show do
nodoc!
routing do
get '/'
end
end
end
end
end

Note that the show action was required to use this resource as parent to other resources, but I've also set the nodoc! statement at the show action level since that action is purely technical.

Then, in each decoded resource, I've defined the following parental relationship:

module V1
module Resources
module Decoded
class AnnuityTypes
include Praxis::ResourceDefinition

media_type V1::MediaTypes::Decoded::AnnuityType
version '1.0'

## before, it was directly bound to BusinessUnit as parent in this way:
## parent BusinessUnit
parent Decodes, business_unit_id: :business_unit_id

# actions and other stuff...
...
end
end
end
end

In this way, I can achieve my goal to have a well structured documentation.

Does it make sense, or there is an alternative way to achive the same goal, without defining new resources?

[Josep Blanquer]

ha! very creative Andrea :)

No, there is really no other way to logically change or customize the doc browser's menu.

Off the top of my head, it strikes me that one possible feature option would be to make the DocBrowser structure to be customizable/overridable based on a newmetadata attribute in a resource ( which would only exist for doc-browser purposes ) .

Adding the special metadata in a resource is already possible (through the metadata hash of a resource). That's what the `no_doc!` function uses: 

      def nodoc!

        metadata[:doc_visibility] = :none

      end

...what would be more difficult (but I don't know how much) is to make the doc browser use that metadata from the generated JSON to override the normal parent/child relationships when constructing the side menu.

Maybe @gampleman would have a ballpark idea about how much that would take.

 Cheers,

Josep M.

--
You received this message because you are subscribed to the Google Groups "praxis-support" group.
To unsubscribe from this group and stop receiving emails from it, send an email to praxis-suppor...@googlegroups.com.
To post to this group, send email to praxis-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/praxis-support/d5369da6-ecb6-4bd3-8aa5-67a695368384%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.