New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pico 1.0 #252

Merged
merged 120 commits into from Nov 6, 2015

Conversation

Projects
None yet
8 participants
@PhrozenByte
Collaborator

PhrozenByte commented Aug 28, 2015

First of all: Why? The sourcecode of existing forks like BaunCMS and PhilleCMS isn't "stupidly simple" anymore... You can read Picos sourcecode from top to down and even copy&paste programmers will understand what's going on. It's all about "understanding at first glance".

Most important second: All changes are 100% backward compatible.

I considered writing something own, but then caught up with Pico. The only thing missing was clean code - Picos concept, workflow and code really is "stupidly simple", but very powerful. Actually I just did a code refactoring. I don't want to fork Pico and I won't do it even if you reject my changes (obviously I'll still use it myself 馃槃).

This should be v1.0 ready. I recommend to release it as v1.0-beta, waiting some weeks to test it on a large user basis (I'll fix all appearing problems) and finally releasing it as Pico 1.0 馃槃

Please give me a hint if you'll merge this, I'll then update the homepage (gh-pages branch), changelog.txt etc. accordingly.

What did I do?

  • Fixes #79, Closes #93, Fixes #99, Closes #103, Closes #116, Fixes #140, Fixes #158, Closes #171, Fixes #210, Closes #241, Closes #244, Closes #246, Fixes #248, Fixes #249, Fixes #250, Fixes #251, Fixes #253, Fixes #257, Fixes #267
  • The code is now documented, code styling follows PSR. Pico superficially grows from 400 LoC to 1000 LoC, when removing all comments, Pico grows from 300 LoC to 500 LoC, mostly because of new public getter and helper methods (= 100 LoC) and PSR code styling. As said, there are no big functional changes, it's more a code refactoring.
  • The new routing system now works out-of-the-box (even without rewriting) with any webserver using the QUERY_STRING routing method. Internal links now look like ?sub/page, rewriting to basically remove the ? is still possible and recommended. Contrary to Pico 0.9 every webserver should work just fine. Pico 0.9 required working URL rewriting, so if you want to use old plugins/themes/contents, a working rewrite setup may still be required. If you're not using the default .htaccess, you must update your rewrite rules to follow the new principles. Internal links in content files are declared with %base_url%?sub/page. Internal links in templates should be declared using the new link filter (e.g. {{ "sub/page"|link }}), what basically calls Pico::getPageUrl(). You musn't change anything if you setup rewriting (what was required in Pico 0.9...), so I assume this to be fully backward compatible 馃槃
  • I've implemented a whole new plugin system while maintaining full backward compatibility. See the class docs of IPicoPlugin for details. The new event system supports plugin dependencies as well as some new events. It was necessary to reliably distinct between old and new events, so all events were renamed. The new PicoDeprecated plugin is crucial for backward compatibility, it's enabled on demand. Refer to its class docs for details.
  • I completely overhauled the sorting algorithms, so sorting by date now works as expected by using timestamps and index files are listed before their sub pages (so e.g. sub/index.md is listed before sub/foo.md).
  • Inaccessible files (like sub.md while sub/index.md exists) are now excluded from the pages list.
  • Now supporting per-directory 404.md files (if there is a sub/404.md, this file is displayed in favour of the global 404.md file, when e.g. the non-existing sub/notexisting.md is requested)
  • The file extension of content files is now configurable.
  • Heads up! #158 is fixed only when the PicoParsePagesContent plugin isn't enabled. It's disabled by default, but gets automatically enabled with PicoDeprecated as soon as an old plugin is loaded. This is necessary to maintain backward compatibility. You can still disable it manually by executing $pico->getPlugin('PicoParsePagesContent')->setEnabled(false); or adding $config['PicoParsePagesContent.enabled'] = false; to your config.php.
  • The meta headers are now parsed by the YAML component of the Symfony project (see #116) and it isn't necessary to register new headers during the onMetaHeaders event anymore. The implicit availability of headers is supposed to be used by users and pure (!) theme developers only, so we're still instructing plugin developers to register their headers. See the commit message of 7537159 for more detail.
  • Meta header variables are now accessible in content files using %meta.*%, so you mustn't repeat yourself. You can now put an excerpt into the description meta variable and output the same content at the beginning of the article using %meta.description% (see index.md for a example).
  • Initialization of Pico now works completely different: rather than defining constants (which are probably conflicting with other applications...), Pico now expects its paths to be passed as parameters to the constructor. The constructor doesn't start Picos processing anymore, you now have to call the Pico::run() method, which returns the parsed page contents instead of directly echoing them. The PicoDeprecated plugin defines the now deprecated constants ROOT_DIR, LIB_DIR etc., so old plugins can still use them. Those constants are defined before reading config.php in Picos root folder, so upgrading users usually aren't bothered with e.g. a PHP Notice: Use of undefined constant ROOT_DIR - assumed 'ROOT_DIR' error when using ROOT_DIR in their config.php (so: no BC break). New users don't need the constants anymore, relative paths are now always interpreted to be relative to Picos root dir, so $config['content_dir'] = 'content'; is always sufficient (previously this was depending on the webserver config). All these changes are supposed to improve Picos interoperability with other applications and allows developers to integrate Pico in other applications, therefore I additionally added a new Pico::setConfig() method to even make the use of a config.php optional.
  • The Twig cache dir doesn't exist anymore. The provided directory never was helpful, in most cases one still had to make the directory writable for the webserver, so it never worked out-of-the-box.
  • All index.html files were removed; instead of helping users to secure their website, they create a false sense of security. This leads to situations like "I'm receiving a empty website when navigating to the content folder, thus everything must be safe!"
  • I decided explicitly to NOT implement pages as objects ("stupidly simple", see above). Anyway, I think plugin developers shouldn't manipulate data in "wrong" events, this could lead us to unexpected behaviour. Sure, plugin developers still can do this, we're passing variables by reference, but it's not that obvious. I even thought about dereferencing the values after the corrosponding event was called, but that would be backward incompatible. What do you think?
  • How to fix the "composer problem" discussed in #221 and #223? There's a very simple solution: When creating a release on GitHub (after you've pushed the tag) you can upload "binaries". Simply execute composer locally, create a ZIP archive and upload the result as "binary".
  • I didn't care much about #110, #238, #239 and #240 because I simply don't need these features. But I think they are good ideas and the core should support this. Just my 2 cents 馃槃
  • #201 and #231 should be closed - this can easily be achieved with plugins. In fact, there are already plugins adding support for these features...
  • Imo distinct documentations for users, theme designers and plugin devs is MUCH more important than unit tests... Pico is a project with just about 500 LoC (+ comments), such a manageable project doesn't necessarily require unit tests - they are nice to have, but that's it. Documentation should be the top priority!
  • Note: I'm no english native speaker. Maybe someone should look through my code comments 馃槃

PhrozenByte added some commits Aug 28, 2015

Remove index.html
A empty index.html is a solution for nothing...
Pico 1.0
I unfortunately messed up my repo so this is just a single commit... :(
Add AbstractPicoPlugin
The plugin magic takes place here...
Replace Pico_Plugin with DummyPlugin
DummyPlugin is a template for Pico plugins. You're a plugin developer? This template may be helpful :-)
Add PicoDeprecated, PicoParsePagesContent, PicoExcerpt
These plugins are crucial for backward compatibility
@theshka

This comment has been minimized.

Show comment
Hide comment
@theshka

theshka Aug 30, 2015

Collaborator

Great work! I would definitely like to push this upstream-- it's so fresh, so clean 馃憤

Just a couple small problems to fix straight away:

In global.php there's some funky paths still set to your environment; replacing the first two lines, and THEMES_DIR path does the trick:

//define('HTTPDOCS', realpath(rtrim(__DIR__, '/')) . '/');
//define('ROOT_DIR', realpath(HTTPDOCS . '../httpdocs-includes') . '/');
define('ROOT_DIR', realpath(rtrim(__DIR__, '/')) . '/');

//define('THEMES_DIR', HTTPDOCS . 'themes/');
define('THEMES_DIR', ROOT_DIR . 'themes/');

and line 377 of pico.php throws a NOTICE when $_SERVER['QUERY_STRING'] is null.

//$pathComponent = $_SERVER['QUERY_STRING'];
$pathComponent = (isset($_SERVER['QUERY_STRING']) ? $_SERVER['QUERY_STRING'] : '');

I'd like to get some more input, anyone else still following Pico??

Collaborator

theshka commented Aug 30, 2015

Great work! I would definitely like to push this upstream-- it's so fresh, so clean 馃憤

Just a couple small problems to fix straight away:

In global.php there's some funky paths still set to your environment; replacing the first two lines, and THEMES_DIR path does the trick:

//define('HTTPDOCS', realpath(rtrim(__DIR__, '/')) . '/');
//define('ROOT_DIR', realpath(HTTPDOCS . '../httpdocs-includes') . '/');
define('ROOT_DIR', realpath(rtrim(__DIR__, '/')) . '/');

//define('THEMES_DIR', HTTPDOCS . 'themes/');
define('THEMES_DIR', ROOT_DIR . 'themes/');

and line 377 of pico.php throws a NOTICE when $_SERVER['QUERY_STRING'] is null.

//$pathComponent = $_SERVER['QUERY_STRING'];
$pathComponent = (isset($_SERVER['QUERY_STRING']) ? $_SERVER['QUERY_STRING'] : '');

I'd like to get some more input, anyone else still following Pico??

@PhrozenByte

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Aug 30, 2015

Collaborator

Oops, that was the wrong global.php 馃槃
Sure, it's a good idea to wait for about 1-2 weeks to get a little more feedback before merging this, it's a quite big update

Collaborator

PhrozenByte commented Aug 30, 2015

Oops, that was the wrong global.php 馃槃
Sure, it's a good idea to wait for about 1-2 weeks to get a little more feedback before merging this, it's a quite big update

@fourtonfish

This comment has been minimized.

Show comment
Hide comment
@fourtonfish

fourtonfish Sep 5, 2015

When ordering posts by date, would it make more sense to use something like this?

  if ($order_by == 'date' && isset($page_meta['date'])) {
      $sorted_pages[$page_meta['date_formatted'] . $date_id] = $data;
      $date_id++;
  } else {

Currently it's this.

      $sorted_pages[$page_meta['date'] . $date_id] = $data;

This seems to be the only thing that works for me, as I'm using the date format of MMMM DD, YYYY (eg August 31, 2015).

fourtonfish commented Sep 5, 2015

When ordering posts by date, would it make more sense to use something like this?

  if ($order_by == 'date' && isset($page_meta['date'])) {
      $sorted_pages[$page_meta['date_formatted'] . $date_id] = $data;
      $date_id++;
  } else {

Currently it's this.

      $sorted_pages[$page_meta['date'] . $date_id] = $data;

This seems to be the only thing that works for me, as I'm using the date format of MMMM DD, YYYY (eg August 31, 2015).

@PhrozenByte

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Sep 5, 2015

Collaborator

I'm not really sure what you mean. In this PR posts aren't sorted by the Date meta header directly, instead they are sorted by $data['time'], the timestamp resulting from a strtotime() call. What sorting would you expect?

Collaborator

PhrozenByte commented Sep 5, 2015

I'm not really sure what you mean. In this PR posts aren't sorted by the Date meta header directly, instead they are sorted by $data['time'], the timestamp resulting from a strtotime() call. What sorting would you expect?

@fourtonfish

This comment has been minimized.

Show comment
Hide comment
@fourtonfish

fourtonfish Sep 5, 2015

@PhrozenByte

Well, if you go to https://botwiki.org/tag/twitterbot, the posts are now correctly ordered while using the MMMM DD, YYYY format (see this for an example).

If I go back to using $page_meta['date'] for sorting, it seems almost random.

Feel free to clone https://github.com/botwiki/botwiki.org and play with it locally.

fourtonfish commented Sep 5, 2015

@PhrozenByte

Well, if you go to https://botwiki.org/tag/twitterbot, the posts are now correctly ordered while using the MMMM DD, YYYY format (see this for an example).

If I go back to using $page_meta['date'] for sorting, it seems almost random.

Feel free to clone https://github.com/botwiki/botwiki.org and play with it locally.

@PontusHorn

This comment has been minimized.

Show comment
Hide comment
@PontusHorn

PontusHorn Sep 5, 2015

This looks great to me. Would be more than happy to see it merged.

@fourtonfish, have you looked through the changes in the PR? The code you're referring to isn't used anymore in it. Your problem, as I understand it, is already fixed here.

PontusHorn commented Sep 5, 2015

This looks great to me. Would be more than happy to see it merged.

@fourtonfish, have you looked through the changes in the PR? The code you're referring to isn't used anymore in it. Your problem, as I understand it, is already fixed here.

@fourtonfish

This comment has been minimized.

Show comment
Hide comment
@fourtonfish

fourtonfish Sep 6, 2015

@PontusHorn Ah, my bad, I think I only looked at the most current stable, not this PR.

Well, great job, then :-)

fourtonfish commented Sep 6, 2015

@PontusHorn Ah, my bad, I think I only looked at the most current stable, not this PR.

Well, great job, then :-)

@bricebou

This comment has been minimized.

Show comment
Hide comment
@bricebou

bricebou Sep 6, 2015

Hi,

First of all, I'm not a developer and english is not my native language ; but it's great to see Pico under active development !

I don't understand all the implications of this pull request and I can't evaluate your code, but, based on some comments, it seems great. And it's coherent with the purpose of Pico : simple. And I agree with a proposition that have been already made : Pico should be available as an archive to keep its installation simple and the more wide as possible (you don't always have an SSH access to perform composer on shared hosting).

I've written some small plugins for Pico and I was wondering what would be necessary to make them coherent with the changes you made. I'd like them to be fully compatible with this new version, and not use the deprecated "way".

Would it be possible for someone here to review my code and give me some advice, recommendations... to perform an update.
Here are the repositories:

Thanks in advance and thanks for all the work @PhrozenByte, @theshka and others made !

bricebou commented Sep 6, 2015

Hi,

First of all, I'm not a developer and english is not my native language ; but it's great to see Pico under active development !

I don't understand all the implications of this pull request and I can't evaluate your code, but, based on some comments, it seems great. And it's coherent with the purpose of Pico : simple. And I agree with a proposition that have been already made : Pico should be available as an archive to keep its installation simple and the more wide as possible (you don't always have an SSH access to perform composer on shared hosting).

I've written some small plugins for Pico and I was wondering what would be necessary to make them coherent with the changes you made. I'd like them to be fully compatible with this new version, and not use the deprecated "way".

Would it be possible for someone here to review my code and give me some advice, recommendations... to perform an update.
Here are the repositories:

Thanks in advance and thanks for all the work @PhrozenByte, @theshka and others made !

@PhrozenByte

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Sep 6, 2015

Collaborator

@bricebou, sure, that's pretty easy. The most important changes are regarding the event system. You can use the transition table at the PicoDeprecated class docs to see the new event names. Some events changed their parameters to be more consistent, so you should compare them to the sourcecode of DummyPlugin (formerly Pico_Plugin) - or simply use the list below. Then add extends AbstractPicoPlugin to your class and you're done 馃槂

If you're using internal links to other pages, you shouldn't use $settings['base_url'] anymore. Use $this->getPageUrl($page) instead, otherwise your plugin requires a working URL rewriting setup. I recommend to delete the .htaccess file while developing, that's the easiest way to guarantee support of the new routing system.

It's recommended, but not required, that you rename your classes to follow the PSR principles, so e.g. Pico_Leaflet becomes PicoLeaflet and the plugin file name becomes PicoLeaflet.php.

Here's a list of changes to the event system that are relevant for existing plugins:

  • All events were renamed - see the transition table at the PicoDeprecated class docs for details
  • You can access all Pico variables using public getter methods, so instead of public function request_url(&$url) { $this->url = $url; } to remember the requested URL you can simply use $this->getRequestUrl()
  • onContentLoaded and on404ContentLoaded dropped $requestFile - use $this->getRequestFile() instead
  • onSinglePageLoaded dropped $meta - use $pageData['meta'] instead
  • onSinglePageLoaded passes $pageData indexed by ID - use array_values($pageData) when necessary
  • onPageRendering changed its parameter order to $twig, $twigVariables, $templateName
  • onPageRendering now passes $templateName with its file extension
Collaborator

PhrozenByte commented Sep 6, 2015

@bricebou, sure, that's pretty easy. The most important changes are regarding the event system. You can use the transition table at the PicoDeprecated class docs to see the new event names. Some events changed their parameters to be more consistent, so you should compare them to the sourcecode of DummyPlugin (formerly Pico_Plugin) - or simply use the list below. Then add extends AbstractPicoPlugin to your class and you're done 馃槂

If you're using internal links to other pages, you shouldn't use $settings['base_url'] anymore. Use $this->getPageUrl($page) instead, otherwise your plugin requires a working URL rewriting setup. I recommend to delete the .htaccess file while developing, that's the easiest way to guarantee support of the new routing system.

It's recommended, but not required, that you rename your classes to follow the PSR principles, so e.g. Pico_Leaflet becomes PicoLeaflet and the plugin file name becomes PicoLeaflet.php.

Here's a list of changes to the event system that are relevant for existing plugins:

  • All events were renamed - see the transition table at the PicoDeprecated class docs for details
  • You can access all Pico variables using public getter methods, so instead of public function request_url(&$url) { $this->url = $url; } to remember the requested URL you can simply use $this->getRequestUrl()
  • onContentLoaded and on404ContentLoaded dropped $requestFile - use $this->getRequestFile() instead
  • onSinglePageLoaded dropped $meta - use $pageData['meta'] instead
  • onSinglePageLoaded passes $pageData indexed by ID - use array_values($pageData) when necessary
  • onPageRendering changed its parameter order to $twig, $twigVariables, $templateName
  • onPageRendering now passes $templateName with its file extension
Access plugins by class name, not file name
Class name and file name can differ regarding case sensitivity
@bricebou

This comment has been minimized.

Show comment
Hide comment
@bricebou

bricebou Sep 6, 2015

Thanks for these precisions. I'll look into it, it will be my second semester's hobby...

If I understand correctly, each plugin should have its own config/config.php file ?

bricebou commented Sep 6, 2015

Thanks for these precisions. I'll look into it, it will be my second semester's hobby...

If I understand correctly, each plugin should have its own config/config.php file ?

@PhrozenByte

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Sep 6, 2015

Collaborator

No, I didn't change anything regarding configuration, it's still all inside a single config/config.php.

@ALL
There are some "What do you think?" questions in the PR message, the most important about the need to register new meta header variables during onMetaHeaders. It would be nice to get a little feedback about that, I'm currently tending to remove the need to register new meta variables (as it is required in Pico 0.9). Registering a meta variable still guarantees the existance of the array key, so you don't need isset() checks. It also still allows plugin developers to access a meta variable through another array key.

Collaborator

PhrozenByte commented Sep 6, 2015

No, I didn't change anything regarding configuration, it's still all inside a single config/config.php.

@ALL
There are some "What do you think?" questions in the PR message, the most important about the need to register new meta header variables during onMetaHeaders. It would be nice to get a little feedback about that, I'm currently tending to remove the need to register new meta variables (as it is required in Pico 0.9). Registering a meta variable still guarantees the existance of the array key, so you don't need isset() checks. It also still allows plugin developers to access a meta variable through another array key.

@bricebou

This comment has been minimized.

Show comment
Hide comment
@bricebou

bricebou commented Sep 6, 2015

Ah ok, I've misunderstood lines 36 to 38 in https://github.com/PhrozenByte/Pico/blob/pico1.0/plugins/00-PicoDeprecated.php

Thanks again.

@PontusHorn

This comment has been minimized.

Show comment
Hide comment
@PontusHorn

PontusHorn Sep 13, 2015

@PhrozenByte I think it's reasonable to require meta headers to be registered, as it makes the usage of the header more predictable. Not a huge issue either way though.

PontusHorn commented Sep 13, 2015

@PhrozenByte I think it's reasonable to require meta headers to be registered, as it makes the usage of the header more predictable. Not a huge issue either way though.

@PontusHorn

View changes

Show outdated Hide outdated lib/Pico.php
* Loads plugins from PLUGINS_DIR in alphabetical order
*
* Plugin files may be prefixed by a number (e.g. 00-PicoDeprecated.php)
* to indicate their processsing order. You MUST NOT use prefixes between

This comment has been minimized.

@PontusHorn

PontusHorn Sep 13, 2015

Typo in "processing".

@PontusHorn

PontusHorn Sep 13, 2015

Typo in "processing".

@PontusHorn

View changes

Show outdated Hide outdated lib/Pico.php
* ignored and won't be returned.
*
* @see <http://symfony.com/doc/current/components/yaml/introduction.html>
* @param string $content the raw file contents

This comment has been minimized.

@PontusHorn

PontusHorn Sep 13, 2015

Wrong parameter name - should be $rawContent

@PontusHorn

PontusHorn Sep 13, 2015

Wrong parameter name - should be $rawContent

@PontusHorn

View changes

Show outdated Hide outdated lib/Pico.php
* matching the specified file extension in alphabetical order
*
* @param string $directory start directory
* @param string $ext return files with this file extension only (optional)

This comment has been minimized.

@PontusHorn

PontusHorn Sep 13, 2015

Wrong parameter name - should be $fileExtension

@PontusHorn

PontusHorn Sep 13, 2015

Wrong parameter name - should be $fileExtension

@PhrozenByte

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Nov 2, 2015

Collaborator

Heads up! I'll merge this PR on 6th November, the new release will be called 1.0.0-beta.1. I would like to call you up for testing the new release, feedback is always appreciated!

Collaborator

PhrozenByte commented Nov 2, 2015

Heads up! I'll merge this PR on 6th November, the new release will be called 1.0.0-beta.1. I would like to call you up for testing the new release, feedback is always appreciated!

PhrozenByte and others added some commits Nov 2, 2015

Guess content directory
As pointed out by @Lomanic (see #260 (comment); thank you btw\!) we actually have to explain users how to change the content directory. This runs contrary to our "stupidly simple" claim. So Pico now simply uses the `content` directory when it exists...
Update README.md
- New Contributing section
- Various small improvements
Update CONTRIBUTING.md
Add "Keep documentation in sync" section
Small changes
- Use Travis build status
- Update version number in config template
Update .travis.yml: Name release archives "pico-release-$TRAVIS_TAG.t鈥
鈥r.gz"

Should make it easier for a ordinary user to distinct source code and release 馃槂

PhrozenByte added a commit that referenced this pull request Nov 6, 2015

@PhrozenByte PhrozenByte merged commit e5b0ec6 into picocms:master Nov 6, 2015

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@PhrozenByte PhrozenByte deleted the PhrozenByte:pico1.0 branch Nov 6, 2015

@smcdougall

This comment has been minimized.

Show comment
Hide comment
@smcdougall

smcdougall Nov 13, 2015

Collaborator

Although I like the idea of 404-ing access to files that you wouldn't want a nosy viewer poking around in, this makes it very inconvenient to include other files (images, downloads) in a page. I know you could still put them in a dedicated folder (a /images or /assets), but this would get really disorganized with a large number of pages. Also, the need to separate your images into another folder seems slightly counter-intuitive to the advantages of a flat file cms. If I wanted all my images in a special, obscure folder, I'd use WordPress (jk). Also, when I say files or images, I mean ones specific to an individual page, not site-wide logos / branding / etc.

Personally, I've removed "content" from the rewrite rule, keeping the other folders blocked. This isn't really an ideal solution, so much as a stop-gap method though. What are your / the project's thoughts on the matter? Should I move my extra files from the content folder, where I feel they belong (they are "content" after all), to another location? Do you plan to add better support for images / files later on? Right now it's kind of a pain to link to files anyway because of how rewriting of urls and hiding the content folder works.

Didn't mean to make this such a rant. Only wanted to voice my feedback / start a discussion. Maybe I should have opened this as an issue. =/

Collaborator

smcdougall commented on fbb744d Nov 13, 2015

Although I like the idea of 404-ing access to files that you wouldn't want a nosy viewer poking around in, this makes it very inconvenient to include other files (images, downloads) in a page. I know you could still put them in a dedicated folder (a /images or /assets), but this would get really disorganized with a large number of pages. Also, the need to separate your images into another folder seems slightly counter-intuitive to the advantages of a flat file cms. If I wanted all my images in a special, obscure folder, I'd use WordPress (jk). Also, when I say files or images, I mean ones specific to an individual page, not site-wide logos / branding / etc.

Personally, I've removed "content" from the rewrite rule, keeping the other folders blocked. This isn't really an ideal solution, so much as a stop-gap method though. What are your / the project's thoughts on the matter? Should I move my extra files from the content folder, where I feel they belong (they are "content" after all), to another location? Do you plan to add better support for images / files later on? Right now it's kind of a pain to link to files anyway because of how rewriting of urls and hiding the content folder works.

Didn't mean to make this such a rant. Only wanted to voice my feedback / start a discussion. Maybe I should have opened this as an issue. =/

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Nov 13, 2015

Collaborator

We recommend a separate assets folder as this is common sense. Additionally relative URLs don't work as you would expect it: the file sub/page.md is accessible through http://example.com/sub/page, but the image sub/image.png is accessible through http://example.com/content/sub/image.png - quite messy, see #262.

Obviously you can still remove the RewriteRule as you did, but we neither recommend nor support this. Especially we will never do this as a default, we already know access control plugins, which are completely useless if the raw content dir is accessible from outside.

Collaborator

PhrozenByte replied Nov 13, 2015

We recommend a separate assets folder as this is common sense. Additionally relative URLs don't work as you would expect it: the file sub/page.md is accessible through http://example.com/sub/page, but the image sub/image.png is accessible through http://example.com/content/sub/image.png - quite messy, see #262.

Obviously you can still remove the RewriteRule as you did, but we neither recommend nor support this. Especially we will never do this as a default, we already know access control plugins, which are completely useless if the raw content dir is accessible from outside.

This comment has been minimized.

Show comment
Hide comment
@smcdougall

smcdougall Nov 13, 2015

Collaborator

Okay. I'll probably shift some of my assets into a separate folder when I update my sites to 1.0. In my case, there's nothing sensitive in the content folder. Folder indexes are disabled, so the only thing you could access would be the files I have linked to anyway.

I've been using absolute paths for my images/etc so far, but I would definitely love to see a way to process relative links if it ever became a targeted feature.

As far as your recommendation goes, I'd suggest maybe adding an example folder into the Pico release package and/or mention something in the documentation. I came across Issue #262 a few days ago, but you didn't really go into the specifics of "keeping things separate", so I thought I'd ask here. A section in the documentation about "Images and other files" might be a good idea for the future. 馃槂

Collaborator

smcdougall replied Nov 13, 2015

Okay. I'll probably shift some of my assets into a separate folder when I update my sites to 1.0. In my case, there's nothing sensitive in the content folder. Folder indexes are disabled, so the only thing you could access would be the files I have linked to anyway.

I've been using absolute paths for my images/etc so far, but I would definitely love to see a way to process relative links if it ever became a targeted feature.

As far as your recommendation goes, I'd suggest maybe adding an example folder into the Pico release package and/or mention something in the documentation. I came across Issue #262 a few days ago, but you didn't really go into the specifics of "keeping things separate", so I thought I'd ask here. A section in the documentation about "Images and other files" might be a good idea for the future. 馃槂

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Nov 13, 2015

Collaborator

Unfortunately it's virtually impossible for Pico to put assets into the content folder without allowing access to the raw contents by default. The only way to achieve this would be passing all assets through PHP, what is a very bad idea regarding the websites performance.

As always in computing there are some other options to achieve virtually the same, but they are simply out of Picos scope. You can e.g. use rewrite rules as described in #262 (they will bypass the 404-rules), but supporting this officially would increase support effort and doesn't work with alternative webservers like Nginx or Lighty - even though you can again achieve virtually the same with them, just with a completely different config. Sure, you can improve security by using rewrite conditions (RewriteCond) to only allow access to typical asset file extensions (.png, .zip etc.), but all that is pretty user-dependent. It's actually a matter of individual webserver config, not of Pico.

I'm not sure what you mean by "process relative links to assets". You can simply use %base_url%/assets/image.png resp. {{ base_url }}/assets/image.png or do I miss something? Apart from that I recommend you to use e.g. $config['site_logo'] = 'assets/logo.png'; in your config (please note the missing leading slash, this way it's more consistent to e.g. content_dir) and {{ base_url }}/{{ config.site_logo }} in your theme, how should a "techy" solution look like? My first thought would be something like {{ config.site_logo|asset }}, but that's imho less obvious and easy to understand. The only reason for the link filter is that we must check for URL rewriting, with Twig we can't simply replace the URLs as we are doing it with the %base_url% placeholder in Markdown files.

We'll add a sentence to the docs telling users that we recommend to use a separate assets folder. Thanks again for your feedback @smcdougall! 馃槂

Collaborator

PhrozenByte replied Nov 13, 2015

Unfortunately it's virtually impossible for Pico to put assets into the content folder without allowing access to the raw contents by default. The only way to achieve this would be passing all assets through PHP, what is a very bad idea regarding the websites performance.

As always in computing there are some other options to achieve virtually the same, but they are simply out of Picos scope. You can e.g. use rewrite rules as described in #262 (they will bypass the 404-rules), but supporting this officially would increase support effort and doesn't work with alternative webservers like Nginx or Lighty - even though you can again achieve virtually the same with them, just with a completely different config. Sure, you can improve security by using rewrite conditions (RewriteCond) to only allow access to typical asset file extensions (.png, .zip etc.), but all that is pretty user-dependent. It's actually a matter of individual webserver config, not of Pico.

I'm not sure what you mean by "process relative links to assets". You can simply use %base_url%/assets/image.png resp. {{ base_url }}/assets/image.png or do I miss something? Apart from that I recommend you to use e.g. $config['site_logo'] = 'assets/logo.png'; in your config (please note the missing leading slash, this way it's more consistent to e.g. content_dir) and {{ base_url }}/{{ config.site_logo }} in your theme, how should a "techy" solution look like? My first thought would be something like {{ config.site_logo|asset }}, but that's imho less obvious and easy to understand. The only reason for the link filter is that we must check for URL rewriting, with Twig we can't simply replace the URLs as we are doing it with the %base_url% placeholder in Markdown files.

We'll add a sentence to the docs telling users that we recommend to use a separate assets folder. Thanks again for your feedback @smcdougall! 馃槂

This comment has been minimized.

Show comment
Hide comment
@smcdougall

smcdougall Nov 13, 2015

Collaborator

What I meant by "process relative links to assets" was just being able to say "image.jpg" (relative to the markdown file) instead of writing the path from document root / base_url (which is an absolute path, not a relative one, even if it contains a variable).

That does sound like it would be quite the nightmare of webservers and rewrite rules though. I can see why it would be out of the scope of the project.

The "/content/site_logo.png" in my theme is merely a suggested location for a logo, but I'll change it to "assets/site_logo.png" in my next release.

It's gonna be a big update. I actually started working on some new features before I knew there was a new Pico version. I only noticed because the documentation had updated and it was throwing me for a loop.

I'd love to help out more with the project if I could. I don't know very much php though, but judging by my rewrite I am getting pretty good with Twig... 馃槙 馃槃

Collaborator

smcdougall replied Nov 13, 2015

What I meant by "process relative links to assets" was just being able to say "image.jpg" (relative to the markdown file) instead of writing the path from document root / base_url (which is an absolute path, not a relative one, even if it contains a variable).

That does sound like it would be quite the nightmare of webservers and rewrite rules though. I can see why it would be out of the scope of the project.

The "/content/site_logo.png" in my theme is merely a suggested location for a logo, but I'll change it to "assets/site_logo.png" in my next release.

It's gonna be a big update. I actually started working on some new features before I knew there was a new Pico version. I only noticed because the documentation had updated and it was throwing me for a loop.

I'd love to help out more with the project if I could. I don't know very much php though, but judging by my rewrite I am getting pretty good with Twig... 馃槙 馃槃

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Nov 13, 2015

Collaborator

We're seeking for help to improve the docs and the Pico website in general 馃槂

Collaborator

PhrozenByte replied Nov 13, 2015

We're seeking for help to improve the docs and the Pico website in general 馃槂

This comment has been minimized.

Show comment
Hide comment
@smcdougall

smcdougall Nov 13, 2015

Collaborator

Okay. Where do I sign up? lol.

Can you point me in the right direction? I'm embarrassingly less familiar with Git and GitHub than I'd like to be. Do I just fork and pull request like your readme suggests?

What in particular needs to be worked on? I see I've already forced you to create a "cookbook" of future documentation pages. 馃槢

Collaborator

smcdougall replied Nov 13, 2015

Okay. Where do I sign up? lol.

Can you point me in the right direction? I'm embarrassingly less familiar with Git and GitHub than I'd like to be. Do I just fork and pull request like your readme suggests?

What in particular needs to be worked on? I see I've already forced you to create a "cookbook" of future documentation pages. 馃槢

This comment has been minimized.

Show comment
Hide comment
@PhrozenByte

PhrozenByte Nov 14, 2015

Collaborator

Yep, just fork the project and create pull requests 馃槂

There are some things which need to be done before releasing the final 1.0.0, you can find a ToDo list here. Beyond that the user docs need a complete overhaul (see the _docs collection, it's Markdown), they are just a copy of the inline user docs at the moment, but should cover much more things in a more structured form. The CSS of the website is in some parts not optimal (like formatting code) and looks a bit outdated, unfortunately my CSS skills aren't the best. As explained previously, the website is realized with Jekyll and its template engine Liquid (be warned: it's not a joy to work with them...).

Collaborator

PhrozenByte replied Nov 14, 2015

Yep, just fork the project and create pull requests 馃槂

There are some things which need to be done before releasing the final 1.0.0, you can find a ToDo list here. Beyond that the user docs need a complete overhaul (see the _docs collection, it's Markdown), they are just a copy of the inline user docs at the moment, but should cover much more things in a more structured form. The CSS of the website is in some parts not optimal (like formatting code) and looks a bit outdated, unfortunately my CSS skills aren't the best. As explained previously, the website is realized with Jekyll and its template engine Liquid (be warned: it's not a joy to work with them...).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment