Developers
Reference for theme developers: template files, functions, shortcodes and CSS variables.
Templates and functions
Sparrow Portfolio is built to be overridden from a theme without filters: add a file with the right name and the plugin steps aside.
Names used by the plugin
| Thing | Name |
|---|---|
| Post type | portfolios |
| Taxonomy | portfolios_categories |
| Block | sparrow-portfolio/grid |
| Text domain | sparrow-portfolio |
Template files
| File in your theme | Replaces |
|---|---|
single-portfolios.php | The project page |
archive-portfolios.php | The automatic archive at /portfolios/ |
A theme file always wins. Start from the plugin’s own files in sparrow-portfolio/templates/.
On block themes the plugin does not load PHP templates at all; edit the Single and Archive templates in the Site Editor instead.
A minimal project template:
1<?php2get_header();3?>4<main class="my-project">5 <?php6 while ( have_posts() ) :7 the_post();8 the_title( '<h1>', '</h1>' );9 the_content();10 endwhile;1112 if ( function_exists( 'sparrow_portfolio_single_nav' ) ) {13 sparrow_portfolio_single_nav();14 }15 ?>16</main>17<?php18get_footer();Functions
| Function | What it does |
|---|---|
sparrow_portfolio_single_nav() | Prints the Previous / Next navigation using the style and options from Settings. Prints nothing when navigation is off, the project is locked, or there is no neighbour |
sparrow_portfolio_search_form( $args ) | Returns the search button markup. Arguments: align, placeholder, radius, button_radius |
sparrow_portfolio_enqueue_search_assets() | Loads the search styles and script. Call it on wp_enqueue_scripts when the search sits in your header |
sparrow_portfolio_project_image( $size, $class ) | Prints the featured image of the current project, or the placeholder |
Search in a theme header:
1add_action( 'wp_enqueue_scripts', function () {2 if ( function_exists( 'sparrow_portfolio_enqueue_search_assets' ) ) {3 sparrow_portfolio_enqueue_search_assets();4 }5} );1<?php2if ( function_exists( 'sparrow_portfolio_search_form' ) ) {3 echo sparrow_portfolio_search_form( array( 'align' => 'right' ) );4}5?>Shortcodes
| Shortcode | Output |
|---|---|
[sparrow_portfolio_grid id="123"] | A portfolio block with the settings saved under that id. Copy it from the block’s Shortcode panel |
[sparrow_portfolio_search] | The search button and dropdown |
Removing all data from wp-config.php
To wipe projects, categories and settings when the plugin is deleted without using the settings switch, add this line to wp-config.php before deleting the plugin:
1define( 'SPARROW_PORTFOLIO_REMOVE_ALL_DATA', true );CSS variables
The plugin’s colours and sizes are CSS variables, so a theme can restyle it without overriding individual rules.
Controls: filter, sorting, search, pagination
Set these on .sprw-portfolio (and on .sprw-search for the search shortcode).
| Variable | Used for | Light | Dark |
|---|---|---|---|
--sprw-ui-text | Main text, strong borders, background of the active item | #1a1a1a | #f2f2f2 |
--sprw-ui-text-2 | Text of chips and buttons | #666 | #c4c4c4 |
--sprw-ui-muted | Inactive links, icons, hints | #8a8f98 | #9a9a9a |
--sprw-ui-faint | Counters | #bbb | #6f6f6f |
--sprw-ui-border | Borders and dividers | #e0ddd8 | #3d3d3d |
--sprw-ui-surface | Background of buttons, fields and dropdowns; text of the active item | #fff | #262626 |
--sprw-ui-fill | Background of chips and hovered rows | #f5f5f5 | #2f2f2f |
--sprw-ui-fill-hover | Background of a hovered chip | #eaeaea | #3a3a3a |
Example: your own dark palette that follows the theme switch.
1[data-theme="dark"] .sprw-portfolio,2[data-theme="dark"] .sprw-search {3 --sprw-ui-text: #ffffff;4 --sprw-ui-surface: #101418;5 --sprw-ui-border: #2a3038;6}Project navigation
Set these on .sprw-single-nav.
| Variable | Used for | Default |
|---|---|---|
--sp-nav-text | Text and arrows | #1d2327 |
--sp-nav-muted | Captions | #8c8f94 |
--sp-nav-border | Borders and dividers | #dcdcde |
--sp-nav-hover-bg | Background on hover | #f6f7f7 |
--sp-nav-accent | Accent: Next circle, focus outline, first icon square | #ee3023 |
--sp-nav-accent-hover | Accent on hover | #d1281c |
--sp-nav-tile-2 | Dark squares of the “all projects” icon | #1d2327 |
--sp-nav-tile-4 | Light square of the icon | #c8c9cb |
Project cards
The block sets these on its own wrapper from the Style panel. Override them in Custom CSS with selector { ... } when you need a value the panel does not offer.
| Variable | Used for |
|---|---|
--sprw-portfolio-columns | Number of columns |
--sprw-portfolio-gap | Gap between cards |
--sprw-portfolio-thumb-ratio | Thumbnail aspect ratio |
--sprw-portfolio-thumb-radius | Thumbnail corner rounding |
--sprw-portfolio-title-color, --sprw-portfolio-title-size | Title colour and size |
--sprw-portfolio-cat-color, --sprw-portfolio-date-color | Category and date colour |
--sprw-portfolio-meta-gap | Gap between title and category/date |
--sprw-portfolio-filter-radius, --sprw-portfolio-sort-radius | Rounding of the filter and sort dropdown buttons |
--sprw-search-radius, --sprw-search-button-radius | Rounding of the search field and button |
Classes
| Class | Element |
|---|---|
.sprw-portfolio | The block |
.sprw-portfolio__toolbar | Row with filter, sorting and search |
.sprw-portfolio__items | The grid of cards |
.sprw-portfolio__item | One card |
.sprw-portfolio__thumb, __title, __cat, __date | Parts of a card |
.sprw-portfolio__badge--locked | Lock badge |
.sprw-search | Search button and dropdown |
.sprw-single-nav | Project navigation; the style is added as --group, --arrows, --titles or --cards |
#sprw-password | Password form |
Still stuck? Write to support.
Contact