How to create a new admin theme?

[ryan]

The admin theme files are a combination of HTML/PHP, CSS, JS files and images. For the most part, it is no different from what you would create in your own site files (in /site/templates/). By default, the admin theme files  are located in this directory:

/wire/templates-admin/

STEP 1:

To create a new admin theme, you would copy the default admin-templates directory (/wire/templates-admin/) to here:

/site/templates-admin/

When ProcessWire sees /site/templates-admin/, it will use it instead of the default one.

STEP 2:

Now you can modify any of those files in /site/templates-admin/ and your changes should be reflected in the admin control panel.

STEP 3:

To distribute it to other people, you would just zip up the dir and then anyone else can unzip it to /site/templates-admin/ and have it work. I will be glad to setup a directory of admin themes on the site if anyone else decides to make one.

That is all there is too it. But here are some other details and recommendations you may find helpful:

MORE DETAILS:

---

Why not just edit the files in /wire/templates-admin/ ?

You certainly could do this, but you should consider everything in /wire/ specific to ProcessWire, and everything in /site/ specific to your installation. If you were to modify the files in /wire/templates-admin/, then your changes would get overwritten every time you upgraded ProcessWire. Whereas, /site/templates-admin/ is not overwritten during upgrades.

What if I only want to change stylesheets and images?

If you only need to change stylesheets and images, then I would recommend having your /site/templates-admin/default.php just include the one in /wire/templates-admin/, i.e.

/site/templates/default.php:

<?php include("/wire/templates-admin/default.php"); 

And likewise for any other files in there that have markup that you don't want to modify. This includes notices.inc and debug.inc. You'll also see a controller.php file there, but that is already just a placeholder so no need to make any changes to it.

What are all the files in ProcessWire's admin theme and what do they do?

Files you can edit:

• debug.inc - An HTML/PHP file that is included when $config->debug is true. It outputs general debugging information in the admin.
  
• default.php - The main HTML/PHP container template. All admin output goes through this file.
  
• notices.inc - Generates the markup for admin messages and error notices that appear at the top of the screen.
  
• scripts/ - Directory containing jQuery/javascript files.
  
• scripts/main.js - Main jQuery/javascript file that is run on all admin pages. All this does currently is setup a few minor form interactions.
  
• styles/ - Directory containing CSS files/stylesheets
  
• styles/main.css - Initial layout and styling for the admin control panel.
  
• styles/reset.css - Resets all browser styles
  
• styles/ui.css - User interface override styles. This is the last stylesheet loaded so it can more easily modify styles that came before it as needed.
  
• styles/JqueryUI/ Directory containing jQuery UI specific stylesheets and images. You can use jQuery UI's themeroller for these if you prefer. http://bit.ly/eTVbDC
  
• styles/ie.css - Styles specific to IE
  
• styles/ie7.css - Styles specific to IE7 and below. Because we don't support those, this basically just turns off IE7 support.
  
• styles/images/ - Images used by any of the above stylesheets.
  

Files you shouldn't bother editing:

• controller.php - This is just a placeholder that includes a controller in /wire/core/. You should leave this file as-is.
  
• install-head.inc - These HTML files are used by the installer. You can edit them, but ProcessWire will still use the one in /wire/templates-admin/ since they are only used before installation. As a result, you can delete them from your /site/templates-admin/ if you prefer.
  
• install-foot.inc - See above.
  
• scripts/install.js - See above.
  
• styles/install.css - See above.
  

Modifying form widgets with jQuery UI

Most of the form inputs in ProcessWire are based on a jQuery UI theme. It is located in this file /wire/templates-admin/styles/JqueryUI/JqueryUI.css (and the images directory below it). Like the other CSS files, that can be edited directly. But since this was originally built using JQuery UI's Themeroller, you can continue to modify it with that if you'd prefer. Here is a link to it with ProcessWire's admin styles already pre-populated: http://bit.ly/eTVbDC

Copyrights and Logo

You should leave existing copyright notices, links to processwire.com and the name ProcessWire in place. You should also add a notice indicating "[Admin theme name] copyright [your name]", i.e. "Widget admin theme copyright Gonzo Deutschdeung". We also prefer that you keep a copy of the ProcessWire logo somewhere in your design, but it's up to you. A photoshop file of the logo at high resolution is attached to this message.

pw2-logos.zip

[varvanin]

How to make a different form of the entrance to the adminpanel? We need to create a new template?

[ryan]

You don't need to create a new template for that unless you want to. It uses the default admin template, and the login form is created by the ProcessLogin module. The best place to modify it is probably in your admin theme's custom stylesheet. It's also possible to create a login form anywhere on your site (like on the front-end) and just use the $session API functions to authenticate the user. But if your intention is to create an admin theme, then it's best to let the existing one stay and customize it from the stylesheet.

[Remi]

Is there a fast and easy way to create a custom edit page only for one content type (pages using same template)?

[ryan]

Not sure that I know enough about the use case here, but you can get all the fields to edit a page by doing something like this:

$page = $pages->get('/'); // get some page

// make a form
$form = $modules->get('InputfieldForm');
$form->method = 'post';
$form->action = './';

// add the page's fields to the form
$form->add($page->getInputfields()); 

// add a submit button to the form
$submit = $modules->get('InputfieldSubmit'); 
$sumit->name = 'submit';
$form->add($submit); 

// process the form if it was submitted
if($input->post->submit) $form->processInput($input->post); 

// render the form output
echo $form->render(); 

But I'm not sure how useful this would be on it's own, because it would be lacking all the admin CSS and JS files that make the forms what they are. So these forms may not be all that useful outside of PW's admin side, as many inputfields go well beyond basic form controls.

[Remi]

Well, I would like to edit my pages on admin site, but I would like to remove some things from forms. For example: when I've got repeatable field (only one) I don't need "tables" like:

My Repeatable fields > Repeatable fields 1 > My field + Repeatable fields 2 > My field + Repeatable fields 3 > My field, etc...

I would like to have it displayed this way:

My Repeatable fields > My field + My field + My field.

[ryan]

I'm not sure that I understand completely, but if this is specific to repeatable fields you may need to modify the InputfieldRepeater.module to change the output to be what you want. If it's something that you can perform the adjustments with CSS or JS, then even better, as it would be simple to make a module that includes a CSS or JS file that modifies the output without you having to modify any modules. You can also use hooks, but repeaters are probably the most complex fieldtype/inputfield, and I've not put a lot of capability in those (yet) in terms of modifying the output via hooks.

[Valery]

Hello.

I am designing a publisher's backend where a lot of functions are equal to what ProcessWire's admin backend offers. Ryan's answer about dumping page Inputfields into a form struck me. I wrote so much redundant code while the solution was so close.

But indiscriminantly dumping Inputfields from a page into a form gives us a very rough solution. What if one needs to be able to select particular fields of interest and create Inputfields for them in a form?

Here is a quickie I did for this task. I have repeaters in my project, so played with them. Ryan is right: repeaters are beasts of a different type. This is why I decided to use them to show a way to create HTML form controls which would automatically match the field type and get the field value.

The code is loosely based on Ryan's code above.

// make a form
$form = $modules->get('InputfieldForm');
$form->method = 'post';
$form->action = './';

foreach ($pages->get(1213)->repeater as $v) {
    $rfs = $fields->get('repeater')->repeaterFields; // get an array of field names inside this repeater

    foreach ($rfs as $rf) {
        $field = $fields->get($rf);

        // here's a trick: here, the repeater is iterated by selecting its "child" pages.
        // They are visible under Admin->Repeaters in the admin backend.

        $pg = $pages->get("$v"); // weird: selector works only with the double quotes.

        $fld = $field->getInputfield($pg);
        $fld->set('value', $pg->$field); // you need to explicitly set the value

        $form->append($fld);
    }
}

$submit = $modules->get('InputfieldSubmit');
$submit->name = 'submit';
$form->add($submit);

// process the form if it was submitted
if ($input->post->submit)
    $form->processInput($input->post);

// render the form output
echo $form->render();
 

Of course, before $form->append() you can do setAttribute(), set('skipLabel', 2) to remove the label and other customizations.

Thanks for reading and commenting.

[Andrei]

The admin theme files are a combination of HTML/PHP, CSS, JS files and images. For the most part, it is no different from what you would create in your own site files (in /site/templates/). By default, the admin theme files  are located in this directory:

/wire/templates-admin/

STEP 1:

To create a new admin theme, you would copy the default admin-templates directory (/wire/templates-admin/) to here:

/site/templates-admin/

When ProcessWire sees /site/templates-admin/, it will use it instead of the default one.

Hi,

Is this still a valid way to do that today with the curent PW version (dev)?

I have copied indeed:

/wire/templates-admin/

and also:

/wire/modules/AdminTheme/

to

/site/templates-admin/
/site/modules/AdminTheme/

but there are still the files located in /wire/modules/AdminTheme/ who are rendered. Tested out by simply adding some extra characters to the footer and see who shows up. I'm mainly looking to a way to re style/write the login page UI/UX and then the rest.

---

Edit: My bad. PW Noob fail ^^

Forgot to "refresh" and chose witch one ov the versions I whant to be rendered (wire/ or site/).

[joer80]

I uploaded the /templates-admin/ folder to my /sites/ folder and the admin section is still loading the theme from the wire folder.  Is there anything I need to do to tell it to load the sites version?

ProcessWire 3.0.7 devns

[adrian]

Hey guys,

I believe that those instructions from Ryan about copying the templates-admin folder to site/modules/ are outdated. All you want now is the AdminThemeJoer or AdminThemeAndrei folder in site/modules/

[joer80]

Ok, I took the files in /wire/modules/AdminThemeDefault and uploaded them to /site/modules/AdminThemeDefault.  It appears it is still loading the wire version though.

Is there something I need to do to tell it to use the site one?

[adrian]

You need to go to the main Modules page and install the new Theme module. If you have not renamed it, ie left it as AdminThemeDefault, then I think you should get the option to choose which one to use.

[joer80]

Ah.  I tried that, but I had to hit Modules -> refresh to get it to pick up the changes!  Then I got a file compiled message and they showed up as a site module.

I was not required to select what version to make it load, it just started using the site version as soon as I hit refresh!

[Peter Knight]

Anyone know if this post is still the recommended way to reskin an existing template?

[abdus]

7 hours ago, Peter Knight said:

reskin an existing template

SASS source files for the admin template is available in the core, you can modify and compile them to suit your setup.

[Peter Knight]

16 hours ago, abdus said:

SASS source files for the admin template is available in the core, you can modify and compile them to suit your setup.

But are the original instructions about moving the files from

/wire/modules/AdminTheme/AdminThemeDefault

to

/site/modules/AdminTheme/AdminThemeDefault

still relavant?

I did the above, made some changes to the css file and the admin in still picking up the original CSS file in /wire/modules/AdminTheme/AdminThemeDefault

[abdus]

I was expecting to find a method to hook before admin theme in the hopes that I could modify $config->styles, but unfortunately there's none.

Here's how AdminThemeDefault uses it:

// /wire/core/modules/AdminTheme/AdminThemeDefault/default.php

$config->styles->prepend($config->urls->root . "wire/templates-admin/styles/AdminTheme.css?v=$version"); 
$config->styles->prepend($config->urls->adminTemplates . "styles/" . ($adminTheme->colors ? "main-$adminTheme->colors" : "main-classic") . ".css?v=$version"); 
$config->styles->append($config->urls->root . "wire/templates-admin/styles/font-awesome/css/font-awesome.min.css?v=$version"); 
	
$ext = $config->debug ? "js" : "min.js";
$config->scripts->append($config->urls->root . "wire/templates-admin/scripts/inputfields.$ext?v=$version");
$config->scripts->append($config->urls->root . "wire/templates-admin/scripts/main.$ext?v=$version"); 
$config->scripts->append($config->urls->adminTemplates . "scripts/main.$ext?v=$version");

...
<head>
	...
	<script type="text/javascript"><?php echo $helpers->renderJSConfig(); ?></script>
	<?php foreach($config->styles as $file) echo "\n\t<link type='text/css' href='$file' rel='stylesheet' />"; ?>
	<?php foreach($config->scripts as $file) echo "\n\t<script type='text/javascript' src='$file'></script>"; ?>
	<?php echo $extras['head']; ?>
</head>

Here's how AdminThemeReno uses it:

// /wire/core/modules/AdminTheme/AdminThemeReno/default.php

// Styles
$config->styles->prepend($colorFile . "?v=" . $version);
$config->styles->prepend($config->urls->root . "wire/templates-admin/styles/AdminTheme.css?v=$version");
$config->styles->append($config->urls->root . "wire/templates-admin/styles/font-awesome/css/font-awesome.min.css?v=$version");

// Scripts
$config->scripts->append($config->urls->root . "wire/templates-admin/scripts/inputfields.$ext?v=$version");
$config->scripts->append($config->urls->root . "wire/templates-admin/scripts/main.$ext?v=$version");
$config->scripts->append($config->urls->adminTemplates . "scripts/main.$ext?v=$version");

...
<head>
	...
	<script type="text/javascript"><?php echo $helpers->renderJSConfig(); ?></script>
	<?php foreach($config->styles as $file) echo "\n\t<link type='text/css' href='$file' rel='stylesheet' />"; ?>
	<?php foreach($config->scripts as $file) echo "\n\t<script type='text/javascript' src='$file'></script>"; ?>
	<?php echo $extras['head']; ?>
</head>

There arent any method calls anywhere.

BUT, with my SUPER hacky way, you can intercept the styles as they're added to $config->styles. 

<?php namespace ProcessWire;
// /site/templates/admin.php

class MyFileArray extends FilenameArray {
    private function intercept($filename) {
        if (strpos($filename, '/templates-admin')) return true;
        elseif (strpos($filename, '/AdminTheme')) return true;
    }

    public function append($filename) {
        if (!$this->intercept($filename)) {
            parent::append($filename);
        }
    }
    public function prepend($filename)
    {
        if (!$this->intercept($filename)) {
            parent::append($filename);
        }
    }
}

/** @var Config $config */
$config->styles = new MyFileArray();

require($config->paths->adminTemplates . 'controller.php');

 

[fbg13]

@Peter Knight you can take the theme module (wire/modules/AdminTheme/AdminThemeDefault) put it in site/modules and modify it to your needs.

[SamC]

On 26/09/2017 at 6:27 PM, abdus said:

$ext = $config->debug ? "js" : "min.js";
$config->scripts->append($config->urls->root . "wire/templates-admin/scripts/inputfields.$ext?v=$version");

Completely unrelated to this thread but thanks for sharing this @abdus. I've been looking for a way to serve up 'file.css' on local and 'file.min.css' on a live version and I never thought of using debug being true/false to change the file extension. Right now I have two header files and I have to awkwardly edit each one whenever something changes. Gonna implement something similar immediately! (and now to just remember to turn debug mode off on live site...)

=EDIT=

Did this in the end:

// /templates/includes/header.php
<link rel="stylesheet" type="text/css" href='<?= "$assets{$prependedFolder}css/styles.{$ext}css"; ?>' />

// /templates/_init.php (prepended)
$templatesUrl = $config->urls->templates;
$assets = $templatesUrl . "site-assets/";
$prependedFolder = $config->debug ? "src/" : "dist/";
$ext = $config->debug ? "" : "min.";

Works great.

[Olivia Reynolds]

Thanks for the detailed guide! I've been exploring customization options for the admin theme in ProcessWire, and your step-by-step breakdown makes the process much clearer. I appreciate the advice on keeping site-specific modifications in /site/templates-admin/ to avoid overrides during upgrades. Do you have any favorite tools or strategies for efficiently managing changes across multiple files in the admin theme?