Hubzilla:Extending a Theme

From Federated Fandom Wiki
Revision as of 04:53, 12 January 2019 by Demitas (talk | contribs) (Added link to cyberpunk theme (derived theme with schema), fixed a path typo)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Most themes so far are derived from the 'redbasic' theme - they take its basic properties and skin it, basically. The redbasic theme is defined in the core repository, under view/theme/redbasic, so you can get a feel for what it contains there.

Getting Started

  • You will need to be a little bit familiar with git. See the Git Primer for more details.
  • You should also be a little familiar with php. You do not need to be a programmer, but just be able to avoid running screaming into the night at the sight of a few lines of code.
  • You will need an installed copy of Hubzilla to test your theme on, and shell access.

Setting up your theme

There is a great tutorial up on DeadSuperHero's site that will help you get your theme started.

One thing that is not clear from the instructions: generally, you can find the themes you've installed in extend/theme. That is the actual location that the data gets copied to when you initially add the theme repo. However, it also creates a symbolic link inside view/themes that points to extend/theme! So if you have created your new theme and aren't seeing it in the admin panel even though you have the three main files (php/theme.php, php/style.php, and css/styles.css), use the shell to go to the view/themes folder. If you type ls -l you will probably see something that looks like this: 

total 12
drwxr-xr-x  3 username username 4096 Jan  4 20:48 ./
drwxr-xr-x 23 username username 4096 Dec  9 12:41 ../
lrwxrwxrwx  1 username username 40 Dec  9 15:19 bookish -> ../../extend/theme/DeadSuperHero/bookish/
lrwxrwxrwx  1 username username 40 Dec  9 15:19 clarity -> ../../extend/theme/DeadSuperHero/clarity/
lrwxrwxrwx  1 username username 41 Dec  9 15:19 frontier -> ../../extend/theme/DeadSuperHero/frontier/
drwxr-xr-x  8 username username 4096 Dec  9 12:41 redbasic/
...
lrwxrwxrwx  1 username username 41 Dec  9 15:19 sporadic -> ../../extend/theme/DeadSuperHero/sporadic/

The arrow means that it is a link to another folder. You can create one of these by entering ln -s ../../path/to/your/theme yourthemename. (The destination is first, and the link name is second.)

Now if you refresh the admin panel, you should see your theme in the list. If you check the checkbox, you can then go to your channel settings and choose your new theme to activate it.

Making Basic Changes

When you go to activate your theme, the first thing you might notice is that it has no preview image. If you create an img/screenshot.jpg file, it will use that as the preview of your theme.

I ran into an issue after activating the new theme where it did not seem to be inheriting any of the layout items from redbasic at all, and I had lots of overlapping text and divs going on. I was able to make a change, re-upload, then change it back, upload again, and the problem was fixed. I'm not sure if this is a code bug we need to track down or something else going on. Let us know on the talk page if you have this issue and can't fix it!

If you just want to make stylesheet changes, you can do that now. Any changes in the style.css file you added will be reflected on the site after uploading and refreshing.


Schemes

It appears that you should be able to create schemes for derived themes. I got this mostly working but couldn't for the life of me get it to use the stylesheet correctly. To be revisited in the future.

ETA: the Cyberpunk Theme at disroot may support this, so could be a good resource for investigating this in the future.


Changing Widget Layouts

If you want to change the layout of the page in a way that can't be handled in CSS, you definitely should be comfortable reading through PHP code (for now). The layout code is not documented very well and you'll have to do some digging to figure out what templates you want to change and how to change them.

The default page template php file can be found in view/php/default.php. Its matching css file is in view/php/default.css. Most modules take over the full page, and use default.php as their template. From there, they will use the Comanche page description language to define what widgets go where, located in a .pdl file.

Your theme can override the default .pdl file for the module in question, you just have to track down which module it is. The module templates are named mod_[module].pdl, where "module" is the name of the module class found in Zotlabs/Module.

For example, if you want to change the way a channel looks, you might notice that the address bar says something like http://yourdomain.com/channel/yourchannelname. The modules are routed to by way of the address bar, so you can probably infer from this that the module you want is "Channel". (You might have guessed that anyway, but for the sake of more complicated module naming, it's a good fact to know.) You can verify that Zotlabs/Module/Channel.php exists, and then find the applicable pdl file view/pdl/mod_channel.pdl.

At the time of this writing, mod_profile.pdl looks like this: 

[region=banner]
  [widget=cover_photo][/widget]
[/region]
[region=aside]
  [widget=fullprofile][/widget]
  [widget=common_friends][/widget]
  [widget=archive][var=wall]1[/var][/widget]
  [widget=categories][/widget]
  [widget=tagcloud_wall][var=limit]24[/var][/widget]
[/region]
[region=right_aside]
  [widget=notifications][/widget]
  [widget=newmember][/widget]
[/region]

This tells the code base to look for three regions in default.php: "banner", "aside", and "right_aside".

  • In "banner", it will display the Cover_photo widget (this is another case where the name maps to the code file, this time under Zotlabs/Widget).
  • In "aside", it will display:
    • the Fullprofile widget
    • the Common_friends widget
    • the Archive widget (and pass the variable "wall" in with a value of 1)
    • the Categories widget
    • the Tagcloud_wall widget (and pass the variable "limit" in with a value of 24)
  • In "right_aside", it will display the Notifications widget and the Newmember widget.

You can, in fact, link any widget from within the pdl file, limited only by what makes sense to you to put in your theme.

To figure out where these are actually going to be placed, you can look at the view/php/default.php template again. You'll see <?php if(x($page,'aside')) echo $page['aside']; ?> on line 15, and <?php if(x($page,'right_aside')) echo $page['right_aside']; ?> on line 20. Those are the regions you're setting from the pdl file. You can see that there are a number of other $page['(region name)'] places in default.php, which can probably be replaced by your theme if you think it wise.

You can change to any of the available templates by adding the [template] tag: [template]full[/template] will use the full template, located in view/php/full.php. [template=three]choklet[/template] will use the choklet template with the "three" flavor, located in view/php/choklet.php.

For choklet, it uses a different stylesheet depending on which flavor you choose.

You can find more info on templates in the comanche.bb file in the code base.

Retrieved from "https://www.fandom-federation.space/wiki/index.php?title=Hubzilla:Extending_a_Theme&oldid=33"