@lknecht that is a fantastic question!
Setup views could do with some better documentation (which we're working on as we speak!)
In the mean time, I would suggest you take a look at the talk from .conf 2017 call "Friction Free Splunk Application Certification"
You can find the link here
That session has a video, and some slides that can be used to help guide this discussion about setup views by explaining what it looks like, and how its implemented from a high-level.
Additionally there is a Splunk App that was built by myself and uploaded to Splunkbase called "Developer Guidance - Setup View Example For Splunk". And, in this Splunk App you can see an incredibly simple implementation of a setup view.
If anything, take the time to look at the app on Splunkbase, and then using that you can implement a setup view for your own app so that users can configure your Splunk App as needed!
Now, if you're a little lazy (just like me) you may not want to look at all this information. That's totally fair. So I'm going to break down how to implement a setup view here, and if you have any questions feel free to ask for more information.
First a setup view starts in the app.conf file.
app.conf - [install] stanza - is_configured property
This property is what tells Splunk if the Splunk App has already been configured
If false, it will ALWAYS redirect to a page prompting the Splunk User to perform the setup configuration
If true, it will not show that page, and instead run the Splunk App as normal execution
app.conf - [ui] stanza - setup_view property
After the Splunk App has determined that a setup is required it will determine which dashboard should be redirected to
The dashboard that will be redirected to is determined by the "app.conf - [ui] - setup_view" property
This property will point to a dashboard that exists in $SPLUNK_HOME/etc/apps/{APP_NAME}/default/data/ui/views/{DASHBOARD_FILE_NAME}.xml
I have not tested this, but I believe you can use relative pathing to specify files in nested directories
$SPLUNK_HOME/etc/apps/{APP_NAME}/default/data/ui/views/{DASHBOARD_FILE_NAME}.xml
This is essentially a simple xml view
This dashboard should be very simple
It should use the {dashboard} element's stylesheet attribute to specify a CSS file for the styling of the page
It should use the {dashboard} element's script attribute to specify a JavaScript file for the logic of the page
The CSS and JavaScript will be searched for in $SPLUNK_HOME/etc/apps/{APP_NAME}/appserver/static/
This can use relative pathing to specify files nested in sub-directories of that path
Suggested: The {html} element should be used inside the {dashboard} element to create a {div} for the purpose of hooking in a Backbone View to render the view
$SPLUNK_HOME/etc/apps/{APP_NAME}/appserver/static/{JAVASCRIPT_FILE_NAME}.js
This will be where the logic of your setup page can be performed
This page can import other JavaScript files to simplify logic management
This JavaScript logic will be implemented using the Splunk Web Framework and its respective Splunk Web Framework API
From here you'll have to configure the custom render and input logic yourself!
And here is all that information in picture form!
app.conf
XML Dashboard
JavaScript Setup Pages
Again, I would definitely suggest looking at the demo application and the .conf 2017 session in order to see how the implementation looks for yourself!
Good luck!
... View more