mayamcdougall / notepaper Goto Github PK

So, NotePaper has a lot of configuration options. They're in an array to make it easier to reference them in Twig, and also to make them a little neater. In preview versions, the sample config was part of the readme. In 1.5, it's going to be a separate sample file.

When writing the readme, I felt it sounded really messy to say "Copy the config snippet from the sample file and paste it into your Pico config".

So then I had an idea: Why not use PHP's include to import a second config file, keeping all the NotePaper stuff separate? Instead of copying a large array of options, you could simply add something like this to your Pico Config:

include 'NotePaper-Config.php';

@PhrozenByte Would this be acceptable / in line with your idea* of how Pico should work? (*couldn't think of a better way to phrase that). If so, are there any downsides or catches I should be aware of? Thanks in advance. 😉

Packaging

• Provide sample config in a file.
  • Remove from ReadMe
  • "include" php and separate config file?
• Include theme variants as Overrides in release.
  • WritingDesk
    • Menu Styles
    • Bullet Styles
    • Other Updates
  • SideBar
    • Sterilize Theme, move personal styles into a separate file.
    • New Background
    • Ribbon
    • Fix for Clearing Widgets Include note in readme.
• Tag Cloud is another reason for TwigGetUrl
• Update Readme
• Spell Check All Files
• Syntax Check All Files
• Known Issues Section
• Upgrade Instructions (replace config and migrate options as needed)
• Temporary plugin
• Alternate Readme's for sample themes. Used Lorem ipsum instead.
  • Sample tags, Documentation and Themes
  • Themes Subfolder for Header.
• ToC Section change for new recursive mode (no _title)

Easy

• Change "Defining" configs to True/False?
  • Change Facebook dark theme to True/False.
• Fix SideBar Ribbon Zoom (partial)
• Reverse Numerical Tag order. Right now, default is lowest first.
• If statements for the Tag Widget Headers
• Standardize Config Commas?
• Capitolize "Theme: default" for consistancy?
• Improved Recursive Navigation
• Input validation for tags.cloud.levels? (prevent divide by zero, negatives)
• Tag List is the only Bulleted list. Inconsistent.
• Config.css array.
• Move disabling options to a Disable array.
• Blog posts aren't in Tag Cloud. Fixed.
• Background Color for all elements (Especially Main. For fallback / loading)
• Transitions for a:hover. feels slow... bad UX
• Add a new "User Overrides" style sheet, independent of new themes.
• Description rendering is triggered if not on front page when using TwigGetUrl....
• New Variable for processed pages (widgets & etc removed) to simplify "page in pages" loops.
• Padding and/or <hr> above bottom_links / search navigation buttons.
• Custom font embed.
• Configurable description length.
• Max width instead of width for responsive design.
• Option to hide ToC widget entirely.
• Facebook Comments alternative to discuss.
  • Make sure Moderation and AppID works
  • Add Additional Facebook Options
  • NoScript Text (But FB Comments only work with blank tag)
• Add Facebook's Debug page to readme for OG Image.
• Other OG Options from variables
• Option to disable page header
• Option to turn off Display of Date (ribbon)?
• Changed bottom_links.enabled == 'Blog' to 'blog' for consistency.
• Investigate blog button behavior. At present, buttons still navigate to non-blog pages, trapping the user there.
• YAML Error Message Notification

Medium

• Themes
  • Include an override folder config option? This would allow multiple themes for NotePaper, emphasizing NotePaper as more of a layout / structure than a set theme.
  • Use meta header for per-file override!
  • {{ base_url ~ "assets/override/" ~ config.NotePaper.css_override ~ "/override.css" }}
  • Must decide before continuing: Dedicated Theme folder or use config options?
    • If I'm including some themes (internally or externally), they either need to be set in stone or the user has to correctly configure them...
  • Name them "themes" instead of override(s)? Is this too confusing?
  • An option to ignore override and load default theme, per file.
• og:description from content or meta.description.
• Fix Date Ribbon alignment if no page author.
  • Give article header a minimum size.
• Tag List (create array of unique tags then print)
• Tag Cloud (precount occurrences then break into sizes by percent. Config option for number of sizes?)

Hard

• Combine front page and regular page code. If front page, swap meta.* for page.*, loop at end.
  • Refine, try to accomplish without Macro.
• Option to move widgets to the Left side (using alternate CSS class)
• Recursive Sub-navigation. Use an if _title function to detect a new layer of navigation instead of having it hard-coded to two levels of <ul>.
  • Sub-navigation Error Protection (Pico Shortcoming?)
  • Test against new "Ignore YAML parse errors" code in Pico
• Recursive Folder Navigation (semi-experimental)
  • Incorrect rotation on Odd stickies.

Requires Pico Change / Plugin

• Search Feature. Likely requires url access through php, either via plugin or an upstream change in Pico.
  • Simplify Front Page and search (and maybe regular page and comic layout) with a function that accepts different rendering conditions.
  • Refine and debug search.
  • Fix layout of short pages.
  • Fix search buttons.
• Use Pico to generate link-able id's on headers. Handled by Markdown Extra
• Better Pagination. Either work with Pico / write a plugin to get URL access or work with Pagination plugin to add a way to exclude Widgets.
  • For url access method, read url and advance loop count page-number * front-page-limit times before writing to front page.
  • Refine Pagination Bottom Links code.
    • Make bottom links hide on front page if no TwigGetUrl
    • Option to manually disable bottom links on front page
  • Should Bottom Links be automatically enabled in Front Page Mode? Should they be mandatory or have an optional toggle to disable? Yes, they are automatic (if FPM and TGU), but have an option to disable.
  • Prevent Out-of-Bounds on Front Page and search. (Move Precount up and check against it.)

Remember not to break things in point versions. Use a new version number for things that break.

Since the theme has so many configuration options, it's probably best to organize it into a $config['NotePaper'] = array(); instead of placing multiple (possibly conflicting) different $config['setting'] = val; lines in the config/config.php

Something like...

$config['NotePaper'] = array(
    #Basic Config
    'site_logo'         => '/content/site_logo.png',
    'css_override'      => null, # e.g. '/content/css-override.css',
    'og_image'          => 'assets/site_logo_og.png',
    'ToC'               => 'Table of Contents',
    'copyright'         => 'Copyright © 20XX - Your Name',
    #Front Page Mode
    'front_page_mode'   => array(
        'enabled'           => '',
        'front_page_limit'  => 5
    ),
    #Disqus Config 
    'disqus' => array(
        'enabled'   => 'yes',
        'shortname' => 'your-shortname-here'
    ),
    #Bottom Links Config
    'bottom_links' => array(
        'enabled'           => 'yes',
        'first_text'        => '<< First',
        'first_image'       => 'assets/button_first.png',
        'prev_text'         => '< Prev',
        'prev_image'        => 'assets/button_prev.png',
        'next_text'         => 'Next >',
        'next_image'        => 'assets/button_next.png',
        'last_text'         => 'Last >>',
        'last_image'        => 'assets/button_last.png',
        'top_text'          => 'Back to Top',
        'top_image'         => 'assets/button_top.png',
        'separator'         => '|',
        'separator_image'   => 'assets/button_separator.png'
    )
);

In your .twig/.html file, you could access them by config.NotePaper.disqus.shortname, etc..
in PHP $config['NotePaper']['disqus']['shortname'] = '';`

Thoughts?

Easy

• New Search Widget
  • Reset default value when clicked out of, if no value.
• Debug: Displays no content without NP Config on Pico's Sample-Content
• Hide ToC on GitHub (Somehow comment it out without affecting Pico?)
• meta.css_override for per-page css overrides.
• Check Content length before adding ellipsis to description.
  • Debug to make sure it properly adheres to the description length cutoff
  • Move description code to a macro?
  • Actually render beginning of document in search instead of tag-stripped description?
    • Would probably break HTML flow (random headers, etc)
  • Move description to separate variable? (Would need to be an array/merged?)
• Move bottom_links.enabled = 'blog' to bottom_links.blog. (Permanent fix for issue 1.5.2 solves)
• Option to reverse front page order. (Careful not to reverse search order)
• Fixed in v1.5.1 overflow: hidden on SideBar's h1 was a bad idea ("g"s and etc get cut off)
• Facebook comments improvements.
  • Better / More consistant NoScript for both Discus and Facebook
    • Combine comment "Sections" into one shared section?
  • Creative, floating sticky note style NoScript. Separate element, floating over a padded comments section.
  • Loading Animation?
• Standardize Quotes
• Indicate current page of Table of Contents in a non-invasive way. Maybe a list-style-type image or a character (~) in ::before content.
• Always Display Sub-Navigation (config option)

Medium

• Animations for loading! Maybe. It'll be an option to enable.
• Recent Posts Widget
• SideBar: Fix for Clearing Widgets
• Better Processing of Tags: Trim leading/trailing spaces and escape middle ones.
• Fix for Tags all being the largest size if they're all the same number (eg one of each)
• Custom widget types using css_override and {{ page.meta.widget }} as an html class.
  • Built in styles / formatting options (such as centered text) to stack with regular widget styles.
    • How would sticky_num work in this situation? Only for stickies? Or add a new, separate class?
• Webcomic Layout Option for Front Page.
• Date Ribbon Fixes
  • Fix title vertical alignment if no author.
  • Change Ribbon Margins to relative positioning? Move ribbon below title/author.
• Change widgets into different html element since they aren't really navigation. (Currently using <nav> tag).
• Use an Image in a page title. It would be defined with a Meta header and use the Title header as an alt tag. (designed for System Panic)
• Better Processing of search? Handle Spaces
  • Author Search
  • Combine Tag and Author Search into a universal "Search Type" variable.
  • Move enhanced search logic out of main loop.
• Alphabetical Sub-Ordering for Numerical Tag Order

Hard

• Make input validations write to NotePaper array directly instead of temporary variables.
• Simplify the Front Page logic to be less repetitive. Condense many tests (search, tags, etc) into one true/false variable. Maybe calculate this in advance and store it in an array (or np_pages).
• Front Page Excerpt Mode using Meta Description / page excerpts.
• Separate out "blog" pages into a separate navigation array? (Regular pages navigate to regular pages, blog pages navigate to other blog pages).
• An option to limit the Front Page to only display "blog" pages.
• Option to utilize Folder Menus for meta.toc's
• Images that resize around widgets.
• Include embedded fonts instead of Google fonts? (Performance?)
• Sub-Folder Front Page (A index page that combines only items in that subfolder)
  • Should there then be an option to hide sub-folder pages from the main front page?
• Folder Menu Z-Index Issues
• Option to disable individual bottom_link buttons, but only on front page
• Find a better way to make bottom links hide on front page if no TwigGetUrl, without additional variable
• Fix for the "Kind of awful" ampersand2 in url generation
  • Loop on an array of query variables. ? on loop.first unless using rewrite engine.
• Fix SideBar Ribbon Zoom (size calculation differences on borders)

Fun (Stashed, not commited)

• Special Pages. The ability to parse a markdown file and insert twig code into main article area. Might not be currently possible with Pico. Might be able to accomplish with hooks in NotePaper's twig template that look for a file matching the name of a custom meta header.
  • Add an override to config to turn this off (for permission reasons). Should be disabled by default. Requires Plugin, so innately disabled by default.
  • Extend "Include" rendering to Search/Tag/OG Descriptions Impossible. Automatic descriptions could truncate a Twig tag and bring down the entire page.
    • Only possible if Template can be processed first, then returned to a string.
    • Might behave unexpectedly if meta is referenced since you're on a different page than the content. This also applies to Front Page Mode though, and so may already be an issue.
    • meta. is replaced with page. automatically, but this happens regardless of whether it appears in tags or content. Not a good solution.
  • Meta substitution with page.id.
  • If this is too messy, perhaps just disable Twig processing on Front/Search/Tag pages. Also, someone may want to use meta. in a widget to reference the current page and not have it converted to page. accidentally referencing the widget...
  • Use "Special Pages" to import Readme onto theme example pages.
  • Special Pages could also be used for dynamic widgets.
    • Tags widgets could potentially be external.

Other / Future

• Modularize Widgets, allowing a user to specify their order in NotePaper's config.
• Modularize NotePaper (features, widgets, etc) into a more customizable framework.
  • Separate features from their structure.
    • Features would be macros / code blocks that could be imported into a customized structure.
    • Ideally, this should allow completely rewriting of NotePaper into a new template without losing any features.
    • All features / code blocks would need to be capable of working independently of one another.
  • NotePaper may become a Theme/Structure of this new environment.
    • NotePaper's current features should continue being developed under the new system, while NotePaper (theme) and other templates would be able to utilize them.

So, originally I put my LICENSE and readme files inside the theme folder, that way they'd always be included in an installation of my theme, in case someone was looking for them (mostly for the sake of the readme though, not the license).

On GitHub however, this contradicts the usual layout of a project, where the license and readme files are at the root of the project. For the time being, I just symlinked them from the theme folder, but this isn't a great solution.

I'm thinking that for the next version, I'll move the license to the project root because if anyone is really looking for that they'll probably come to GitHub anyway. The readme I'm not sure though.

I don't really want to maintain two copies of the readme, but at the moment I think I'd need one copy for the website and one copy that's modified for GitHub (to remove the toc at least because it's ugly on the front page).

I may just remove the copy from the theme folder though, since it'll already be provided online in two places and in the root of the release zip. There's also a little (removable) link at the bottom of the theme the user could follow if they really forgot where it came from.

(Note to self, I could always add another link at the bottom of the theme (and in the readme) about contributing on GitHub. Not really looking for code, but issues and suggestions would always be welcome.)

@theshka Sorry for the long post, but could I get your input on it? It can be ten words or less, you don't need to write your life's story like I apparently do. 😉

For the last two releases, I've done all my work on a separate branch (testing) and merged it into master when it was done. When I started that, I didn't know much about how GitHub works and I didn't know that when you tag a release you can get back to that point in time easily by using that tag.

Going forward, I'm considering doing most of the work on Master. I'm the only one working on NotePaper, so I don't really see why I should continue using a special bench for development.

@PhrozenByte What's your advice? Should working directly on Master be okay? Anything I should worry about? As always, thanks in advance for your help. 😄

The SideBar Theme's Widgets can't be cleared and stick out the bottom of the page if it is too short. This is because the sidebar is using absolute positioning and is outside the normal flow of the page.

If the sidebar is no longer absolutely positioned however, it will no longer extend to the length of the content. Absolute positioning is required to be able to set it's height to 100%.

I need a solution that will both cause the page to extend if the widgets are longer than the page AND cause the sidebar to extend if the page is longer than the widgets. The solution also needs to not modify the HTML structure, or at least modify it in a way that doesn't affect the default theme.

The solution is a little beyond me at this point, but if anyone has any input, feel free to comment below.

I tried to install this, at first I get error saying no style.css file found, so I found it in the zip file. I moved it to the root folder and zipped it up and tried to install again. then I get error saying, The style.css stylesheet does not contain a valid theme header.

Theme installation failed.

I am trying to install this to a free site called X10 Hosting site, wordpress is up and running, just can't get this theme to work.

any help would be appreciated.

Folder Navigation is in a weird place right now. It works, but not under the default theme.

The default theme uses rotation to make the Sticky Note widgets appear more lifelike. This transformation brings them outside of the page's normal Z-Index. This means that the answer isn't as simple as applying a z-index because the transformed widgets appear above all other elements.

While floating in this "above space", each widget is also rendered above the previous widget on the page. When the Folder Navigation menus pop up, they are rendered inside the previous widget element, and thus below any subsequent widgets.

It's been a while since I've looked at this issue, but from what I remember, each subsequent widget transformation is essentially being rendered on a new layer above the previous, ignoring z-index entirely.

Right now, the folder menus are being hidden using opacity, not display, for the sake of animations. They have a fade-in animation that makes them much easier to use than just immediately appearing and disappearing with display.

However, if they used display, they'd essentially be rendered "on-demand" and placed properly above all elements. The problem with opacity is that they are always rendered ahead of time, then hidden, causing them to be below everything.

I suspect the answer may lie in combining the two, but so far I've had little success.

Feel free to leave a comment if you have any ideas on this issue.

Without breaking the file paths. Is there a way to use theme_url in config.php?