Allow using third-party templates without overwriting Shaarli's default

[nodiscc]

Users should be able to clone/unzip other templates into their tpl/your-template-here directories, and tell Shaarli to use them by setting the RAINTPL_TPL config variable to this path. This prevents breaking Shaarli's upgrade path, and allows users to upgrade templates to their latest version easily.

@ArthurHoaro has started something tending to this in #76.

• The default template should probably be moved to tpl/default, all links to/from the template rewritten and checked.
• The default shaarli.css is designd for the default template, so it should be moved inside the template directory.
• The proposed plugin system (Plugin system #164) has to adapt to this. That's to say, are plugins specific to a template, or do tyhey apply to any template? The directory path for plugins depends on that.

That also means each third-party template has to be in it's own archive/repository to be able to clone/unpack it easily in it's own tpl/your-template-here.

The https://github.com/shaarli/templates repo doesn't follow this model currently (the hoa.ro template is in a subdirectory). I'd be ok to rename it to template-hoaro and move contents directly at the root of the repo. @ArthurHoaro already has write access to this repo so he can keep maintaining it in the future.

@alexisju you also have a nice template at https://github.com/alexisju/Shaarli-AlbinoMouse, would you like me to create a template-albinomouse repository in the shaarli organization and give you write access there? You could sync your template there when you think it's ready, and maintain it in the future.

There are more third-party Shaarli templates listed in the wiki and it would be cool if the maintainers are willing to maintain their templates in the organization. So @kalvn @VinM @dhoko @AkibaTech @misterair ping. Do you want to join your work to the community fork and maintain your template in the oragnization? I can create repos and give you write access there.

We'll have to agree about a directory structure in this issue, or on https://gitter.im/shaarli/Shaarli (english only here, english or French on Gitter if that's more comfortable for you)

[ArthurHoaro]

Then wouldn't it be simplier if we all keep our template set in our "Github space" and list them somewhere here?

EDIT: Do you want me to close the PR as we're at it?

[nodiscc]

Yep you can close the PR as this issue is now open :)

wouldn't it be simplier if we all keep our template set in our "Github space" and list them somewhere here?

I don't know.

You can still maintain your theme in your own repos, but just git remote add organization git@github.com:shaarli/template-hoaro; git push organization master and your new version is also synced here.

Having all these templates in the org would ensure we have a list of known, maintained, compatible templates, and in the long run template maintainers can maintain each other's work (fixes, version bumps...) via the org. The templates would also be easily accessible/discoverable at https://github.com/shaarli/Shaarli.

But yeah, even if we don't create these repos, I'm pinging everyone to see if the change is worth it (will we have a significant number of compatible templates? currently people's work is not compatible for easy install, the CSS is still old school, etc. Maybe we can help each other with this)

[MarceauKa]

Good Idea! I'm in! :)

But what about assets (js, css, fonts)? Should Shaarli not be updated accordingly?

[nodiscc]

@VinM replied https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2#issuecomment-78364265:

Hello !

I answer to tell you that the theme for Shaarli I made few years ago is not very good, and is bad coded. If you want to use it, you can, but I advise you to don't use it because it is not responsive and not very user-friendly.

Do what you want ;)
Regards.

[nodiscc]

But what about assets (js, css, fonts)? Should Shaarli not be updated accordingly?

@AkibaTech Well this is what we have to solve. The way I see it, the dir structure could be like

Shaarli/
├── cache
├── data
├── doc
├── images
├── inc
├── pagecache
├── tmp
└── tpl
    ├── albinomouse
    ├── default
    └── superhero
        ├── daily.html
        ├── images
        │   ├── calendar.png
        │   ├── delete_icon.png
        │   ├── [ ... ]
        │   └── edit_icon.png
        ├── includes.html
        ├── linklist.html
        ├── page.footer.html
        ├── page.header.html
        └── res
            ├── bootstrap.css
            ├── bootstrap.js
            ├── bootstrap.min.css
            ├── bootstrap.min.js
            ├── coolfont.eot
            └── superhero.css

And we should do the same for the default template (mov inc/* to the tpl/default/inc). Just a quick thought. I may have missed something, please let me know.

[MarceauKa]

Dooooooooone!!!! (with a new branch called "shaarli-template")

MarceauKa/Shaarli---SuperHero-Theme@abdbafb

[ArthurHoaro]

@AkibaTech You should also include jQuery since we're trying to get rid of it. And it might be done soon if #165 is merged.

@nodiscc

Having all these templates in the org would ensure we have a list of known, maintained, compatible templates, and in the long run template maintainers can maintain each other's work (fixes, version bumps...)

Yep that's probably better.

And we should do the same for the default template (mov inc/* to the tpl/default/inc).

I agree for client side dependency (eg. not raintpl) and CSS. Except maybe reset.css. Also, images folder probably belong in theme folder.

[MarceauKa]

All right.

Theme updated :)

[nodiscc]

images folder probably belong in theme folder.

You're right! I updated the dir structure above ^ @AkibaTech think you could do this? Thanks for your quick reply, I'll start working on a new branch soon and test your template there. And yep, include everything you would need client side, including jQuery.

Edit: careful, I see you updated your readme, this feature is not implemented yet! :) Hope it will be soon.

[MarceauKa]

Know it :)

Branch "shaarli-template" is for this awesome upcoming feature.
Branch "master" is for current version as noticed in my readme :)

Edit: I'll try to find time to update my theme and have a better result.

[nodiscc]

•  When this is implemented, docs should also be updated with a warning (eg. config settings may not apply to all templates, for example SHOW_ATOM, or any other)

[kalvn]

Interested as well, I will update my template tomorrow to fit this new structure.

[kalvn]

It's done and available here: https://github.com/kalvn/shaarli-blocks/tree/shaarli-template

By the way, if you want to make it easy for people to build custom templates, you should really define some path variables in index.php (like the absolute URL to templates, or at least the absolute URL of the installation) and make them available in the template because I noticed that some head files are automatically renamed and some aren't (for example CSS files) and it can quickly become a mess to understand why it doesn't work.

[dhoko]

I'm in too. 👏

I will create a new version soon (with flexbox). Rewrite the default HTML \o/

@ArthurHoaro

Except maybe reset.css.

Reset.css does not have to come with Shaarli. Ex: some dev don't use it (ex: me), there are normalize etc. Dev must choose their one reset.

[alexisju]

I'll do it soon also :)

[nodiscc]

@kalvn

I indicated to update the variable $GLOBALS['config']['RAINTPL_TPL'] but it would be interesting to have a parameter in the config file and the config page.

You should never edit index.php directly. You should define GLOBALS['config']['RAINTPL_TPL'] = "tpl/shaarli-blocks"; in data/options.php! So this already supprted (I suggest you update your readme).

index. php. should. never. be. touched. Else we lose the benefit of having "modular" templates, and upgrade becomes painful as index.php is overwritten every time. data/options.php overrides existing options. It's the only config file you should need to edit for any config change. See https://github.com/shaarli/Shaarli/wiki#main-dataoptionsphp-file

Edit: I've opened #166 to help alleviate confusion about where to write options, and make configuration easier.

Edit2: @AkibaTech @kalvn Thanks for your work!

Edit3: We will not provide a way to set this from the Tools dialog because it would make it too easy to break your install by specifying a bogus path. If you screw your install from the Tools dialog and don't have SSH/FTP access at hand, your Shaarli will be down. So this should stay a manual edit. However yes #166 will make it easier.

Edit4: I've updated the wiki with template installation instructions. See https://github.com/shaarli/Shaarli/wiki#changing-template

[alexisju]

Albinomouse available as template : https://github.com/alexisju/albinomouse-template

[kalvn]

I finally moved mine on the master branch.

I also created a new theme with Material Design guidelines and also offered an installation for Shaarli 0.0.44 and above: https://github.com/kalvn/Shaarli-Material

[nodiscc]

@kalvn great work! Thanks for your time, I'll look into this in the coming days (short on time right now).

Another thing to consider when we will push the changes for 3rd party templates support (mainly changing the dir structure) is to know whether your templates will support plugins (eg. I see you're using the QR code library, but it is planned to make it optional/pluggable) and where we will put them in the dir structure.

Please have a look at #164, feedback welcome. The dir structure refactoring to support third party templates will probably be part of this Pull Request in the future.

@alexisju thanks to you too

[nodiscc]

misterair replied: misterair/limonade#7 (comment)

hi,
unfortunately I've no time to contribute :-/
But, you can, if you want, copy/modify my template in your project. Be careful, I've modified the Shaarli's default template structure...

[nodiscc]

Attention, you can no longer use $link.localdate when I merge #169 (this week :) ), you have to do date formatting inside your template. You can use function="strftime('%c', $link.timestamp)" instead

[alexisju]

ok

[ArthurHoaro]

Kinda duplicates #22. Also I think it's not a very good idea to have a main repo with all the themes. Everyone having its own repos and referencing in the docs is good enough. Closing.