search

tajmone / PBCodeArcProto

PB CodeArchiv Rebirth Indexer Prototype
4 stars 0 forks source link

HTML Template #4

Open tajmone opened 6 years ago

tajmone commented 6 years ago

For the website template, I was thinking of something rather minimalistic.

I'll definitely go for a Sass project that compiles a single CSS file. It will add a subfolder in the assets folder, but end users won't be bothered by it, and administrators won't need to deal with it either — unless they are changing the stylesheet and need to recompile it to CSS.

Do you have in mind any open source ready-to-use HTML5 template that you'd like to use? Or can provide some examples of the style you had in mind?

Personally, I've found that taking a ready-made template and then editing it to adapt to your needs often requires more work than to build one from scratch using some Sass framework and modules. But of course, sometimes you find a ready to use template which fits your project like a glove.

As for techinicalities, there are the usual questions:

The HTML pages will be used both as website (through GitHub pages) and for local browsing of the cloned project. The former might require mobile-friendliness, the latter use is going to be limited to Desktop PCs and Netbooks/Notebooks — since PureBasic only runs on x86, it's unlikely that it will be cloned on non x86 platforms; so mobile devices and tablets are not a main concern when it comes to local browsing.

What's your view on this?

tajmone commented 6 years ago

Template Resources Links

I'll paste/update here some links to open source HTML templates and resources.

Boilerplates

Usually boilerplates are a good starting point to build a custom template from scratch. All elements have to be built on top of the boilerplate; so, total freedom but more work (other sass modules required to cover grid, typography, etc).

Tiny CSS/Sass Frameworks

Minimal CSS frameworks that cover the styling of basic elements, grid system, and provide some helper classes (or SCSS helpers). They offer a complete solution for building a template (as opposed to using different Sass componenets).

Arragned in order of complexity (from minimal to features-rich):

Free Templates

Websites offering good free/open source HTML5 templates, ready to use. Just need to tweak the css to adapt it to needs.

tajmone commented 6 years ago

The more I look at the Bulma framework, the more I like it. It might be a bit to rich for the scopes of this project, but the Sass modular approach should allow us to take just what we need. It's base styles are plain but colorful, with a tendency toward Metro UI.

I like it because it provides a full set of ready-to-use elements: bradcrumbs, pagination, header, footer, sidbar menu, and nice containers for the resume cards. Also, I like that it comes with no JavaScript (all JS needs are left to the end users).

I'm going to download it and start working on some page prototypes, and see if it actually works right for this project. Unless I try it out I can't really come to conclusions about it.

tajmone commented 6 years ago

I've created a first template draft:

You can live preview it here:

I've used HTML5 Boilerplate and Bulma.

Of course, it's just a draft (color choices is temporary) intended to try and see how the layout could be.

As you can see, the sidebar has the full list of root categories (taken from the current status of the project), and active subcategories are shown also.

This simulates how the page will show the README text and how resume cards could be shown to the user.

It's just a starting point so we can have something to discuss.

SicroAtGit commented 6 years ago

Do you have in mind any open source ready-to-use HTML5 template that you'd like to use? Or can provide some examples of the style you had in mind?

I am not familiar with SASS and HTML5 templates. The websites I have created so far, I have always written completely in pure PHP, HTML5, CSS and javascript (without frameworks). Recently I used JQuery on a website that needs a lot of javascript code to make the javascript codes simply compatible with all browsers - which is also the sense behind JQuery.

That's why I can't help you to choose the most suitable HTML5 template for our purposes without familiarizing myself intensively with this new technique.

As you created the sample template, I imagined it.

Do we need/want it to be mobile friendly and responsive?

As you said, the CodeArchive is for PC software developers, so we didn't need any support for mobile devices for the HTML5 pages

Do we want an liquid or fixed-width layout?

A fixed width layout is better in our case, I think. Our content doesn't need much space in the width. Also, a text that has too long lines is more strenuous to read.

I've created a first template draft

Looks very good! The darker blue colour stands out too much, but we can think about the colours later. With the choice of colours I also have my difficulties. The focus of the work is now on the layout creation. I can't think of any improvements at the moment.

Will "Access_Adress_Book[Mac].pbi" etc. later be converted to links that navigate to the code in the git repository?

tajmone commented 6 years ago

I'm glad you like it, and I see that we agree on most points here.

As long as the general look of the template is ok I can then carry on with the project and put all the elements (code and template) together.

For the colors scheme we have full choice of customization: Bulma has a setting file where the color scheme can be customized. So we'll take care of colors at the end.

Will "Access_Adress_Book[Mac].pbi" etc. later be converted to links that navigate to the code in the git repository?

I've been thinking about this but didn't come to a definite conclusion yet. Because multifile items will parse the CodeInfo.txt, they'll be showing the folder name instead of pointing to a specific source file.

So, the ideal approach would be that for single-file resources a direct link to the source file is provided, so website users can either open in the browser (to preview the source code) or save it locally via the "Save As..." option. For single files, this allow visitors of the project's website to actually download single-file resources without having to clone the whole repository.

The issue then concerns sub-foldered items. For consistency, we'd need to provide a link that would download a Zip archive with the whole folder. This is actually possible and I've used it in the PureBASIC Archives project by using gitzip, a tool that leverages the GitHub API:

https://github.com/KinoLien/gitzip

It works by means of links, no need to install anything anywere, or add scripts to the project (although we can include them if we want). The good thing is that the Zip archive is built on the spot, so the website visitors would actually get a copy of the latest version of the folder (as found on master branch), and not some old Zip created at a certain point of time. This means that there is no maintainance work regarding these downloadable files.

Maybe it makes sense to provide these links, after all some users might just want to download a specific resource, not the whole project — especially if they don't want to setup Git. It's true that they can always download the Zipped repo via GitHub's web inteface (I don't think they even require to register to do that), but we should make life easier for the endusers and allow them to download isolated resources.

Add Name Key?

Having said that, I think that it would look nicer if resources actually had a name of sorts, instead of their file/folder name. We could add to the header comments a name entry to provide the name of the resource to be shown in the resume card. In most cases, the name will be similar to its filename, but with spaces between words, no file extension and better readability.

For example, "Access_Adress_Book[Mac].pbi" could have a name like Access Adress Book or Access Adress Book (for Mac). And so on.

The name could be shown in the card's top bar (without link), and the actual source file/folder name would be displayed inside the card's contents, with a link to preview or download the resource. This would allow to easily associate the card to its corresponding resource file(s) on the disk (offline use).

SicroAtGit commented 6 years ago

https://github.com/KinoLien/gitzip ... Maybe it makes sense to provide these links, after all some users might just want to download a specific resource, not the whole project — especially if they don't want to setup Git. It's true that they can always download the Zipped repo via GitHub's web inteface (I don't think they even require to register to do that), but we should make life easier for the endusers and allow them to download isolated resources.

The possibility to download only specific codes and not only the entire archive, we can integrate with pleasure. However, there are also codes that are dependent on other codes, e.g.: PureBasic-CodeArchive-Rebirth/FileSystem/GetAbsolutePath.pbi needs PureBasic-CodeArchive-Rebirth/FileSystem/GetParentDirectory.pbi

The complete archive can be downloaded without registration at GitHub.

Add Name Key?

I agree with that, but without OS specifications, because they are already specified in the code header. Duplicate information in different places should be avoided, because in case of adjustments the other places could be forgotten.

tajmone commented 6 years ago

However, there are also codes that are dependent on other codes, e.g.: PureBasic-CodeArchive-Rebirth/FileSystem/GetAbsolutePath.pbi needs PureBasic-CodeArchive-Rebirth/FileSystem/GetParentDirectory.pbi

... regarding this point, see my further considerations and proposal at https://github.com/tajmone/PBCodeArcProto/issues/11#issuecomment-384647849

Bulma Major Update

In the meantime, Bulma framework has been update to v7.1, which introduces some nice new features, especially regarding the use of custom colors in addition to the base palette:

The new version might require slight tweaks to the HTML template, but it's worth it.