view release on metacpan or  search on metacpan

lib/Developer/Dashboard/SKILLS.pm  view on Meta::CPAN

=item *

C<CODE1:> and other C<CODE*> blocks

=back

Rules that matter:

=over 4

=item *

C<TITLE:> sets the browser title and is exposed to templates as C<title>

=item *

Earlier C<CODE*> blocks run before final template rendering

=item *

Returned hashes merge into stash

=item *

Printed C<STDOUT> becomes visible runtime output

=item *

C<STDERR> becomes visible error output

=item *

C<---> can also act as a section separator

=back

=head1 BOOKMARK HELPERS

The bookmark bootstrap exposes:

=over 4

=item *

C<fetch_value(url, target, options, formatter)>

=item *

C<stream_value(url, target, options, formatter)>

=item *

C<stream_data(url, target, options, formatter)>

=back

Bookmark pages can also use the built-in C</js/jquery.js> compatibility shim
for C<$>, C<$(document).ready(...)>, and C<$.ajax(...)>.

For normal saved runtime bookmarks, C<Ajax(file =E<gt> 'name', ...)> can create
stable saved Ajax endpoints. That capability is tied to the saved runtime
bookmark path. Skill bookmarks render through the skill route surface, so do
not assume stable saved C</ajax/E<lt>fileE<gt>> handlers there unless you have
tested that path explicitly.

=head1 NAV AND DASHBOARD-WIDE CLI

Normal runtime bookmarks support shared C<nav/*.tt> fragments above non-nav
saved pages. Skill pages auto-load C<dashboards/nav/*> into
C</app/E<lt>repo-nameE<gt>> and C</app/E<lt>repo-nameE<gt>/...> routes, and
the same installed skill nav fragments are also rendered above normal saved
C</app/E<lt>pageE<gt>> routes such as C</app/index>. Skills can still render
files such as C<dashboards/nav/help.tt> directly through
C</skill/E<lt>repo-nameE<gt>/bookmarks/nav/help.tt>.

Dashboard-wide custom CLI hooks are separate from skill hooks. They live under
F<./.developer-dashboard/cli/E<lt>commandE<gt>.d> or
F<~/.developer-dashboard/cli/E<lt>commandE<gt>.d> and are used for normal
C<dashboard E<lt>commandE<gt>> commands. They can also use directory-backed
C<run> commands, which skill commands do not currently use.

=head1 FAQ

=head2 Do I need every folder?

No. Use the parts your skill actually needs.

=head2 Can a skill expose browser pages?

Yes, through C<dashboards/> with C</app/...> routes and the older
C</skill/.../bookmarks/...> route.

=head2 Can a skill ship collectors or indicators?

Yes. Declare them in the skill's C<config/config.json>. They join the managed
fleet under repo-qualified names such as C<example-skill.status>, and their
indicator config participates in the normal prompt and browser status flow.

=head2 Can I use isolated Perl dependencies?

Yes. Ship a C<cpanfile> for shared skill dependencies in C<~/perl5>, and ship
a C<cpanfile.local> when that skill also needs a skill-local C<./perl5> tree.

=head2 Can a skill install system packages first?

Yes. Ship a C<ddfile> for dependent skills, a C<ddfile.local> for dependent
skills that must stay at the current install level, an C<aptfile> for
Debian-family packages, an C<apkfile> for Alpine packages, a C<dnfile> for
Fedora packages, a C<brewfile> for
macOS packages, or a C<package.json> for Node dependencies that should land under
C<$HOME/node_modules>. The
explicit operator manifest order for C<dashboard skills install --ddfile> is
the deferred C<ddfile -> ddfile.local> pass, while the automatic per-skill
dependency order is C<aptfile -> apkfile -> dnfile -> brewfile -> package.json ->
cpanfile -> cpanfile.local -> ddfile -> ddfile.local>.

=head2 Where is the long-form guide?

The repository ships a separate skill authoring guide, while the installed
distribution keeps this POD available through C<perldoc>.