Understanding styling and layout in GigaDB

pli888 commented 4 years ago

There are two layouts being used in GigaDB:

Current green layout	Previous grey layout

These layouts are being generated by CSS files (some via less files) and Yii view classes:

CSS files

CSS file	Version	Referenced In	Function
jquery-ui.css	1.12.1	new_main.php	Current green layout
bootstrap.min.css	3.3.7	new_main.php	Current green layout
font-awesome.min.css	4.7.0	new_main.php	Current green layout
open_sans.css	13	new_main.php	Current green layout
pt_sans.css	8	new_main.php	Current green layout
lato.css	11	new_main.php	Current green layout
datatables.css	Not known	new_dataset.php	Current green layout
common.css	Not known	views/layouts/new_datasetpage.php, views/layouts/new_faq.php, views/layouts/new_main.php	Current green layout
site.css*	Not known	views/layouts/datasetpage.php, views/layouts/main.php	Previous grey layout
chosen.min.css	1.3.0	views/report/index.php	For displaying Google Analytics data
jquery.tag-editor.css	Not known	datasetSubmission/create1.php, adminDataset/_form.php, datasetSubmission/_form1.php	For editing tags in WL submission wizard
pager.css	1.0?	SiteLinkPager.php	For pagination in dataset pages

*This file is created from site.less using lesscompilercommand in webapp_setup.sh script which is executed by docker-compose.yml and docker-compose.staging.yml.

Less files

Less file	Function
bootstrap/*.less	Less files for Bootstrap (3?)
about.less	About page?
admindataset.less	Dataset pages?
datasetupdate.less	Dataset update pages?
globals.less	General variables, e.g. font type, button colours
pagesetting.less	Not known
site.less	General site CSS rules
thumbnailSlider.less	CSS rules for carousel in old grey layout
updatelog.less	CSS rules for dataset log pages?
userprofile.less	CSS rules for user profile page?

Files in views/layouts directory

File	Function	Used By	URL
column1.php	One-column layout, no sidebar	protected/components/Controller.php	/adminDataset/admin, /adminDataset/create
column2.php	Two-column layout, has sidebar	Many Controller classes in protected/controllers directory	/adminDatasetAuthor/admin, /adminDatasetAuthor/create, /adminDatasetAuthor/view/id/251, /adminDatasetAuthor/update/id/251, /adminPublisher/admin, /adminPublisher/create
datasetpage.php		views/layouts/column2.php	/adminDatasetAuthor/admin, /adminDatasetAuthor/create, /adminDatasetAuthor/view/id/251, /adminDatasetAuthor/update/id/251, /adminPublisher/admin, /adminPublisher/create
main.php	Contains header, footer, other common components	column1.php	/site/admin, /adminDataset/admin, /adminDataset/create, /user/admin
new_column1.php	One-column layout, no sidebar	Not used?
new_column2.php	Two-column layout, has sidebar	DatasetController	/dataset/100142
new_datasetpage.php		new_column2.php	/dataset/100142
new_faq.php		SiteController.php in actionFaq()	/site/faq
new_main.php		DatasetSubmissionController in actionChoose(), SearchController in actionNew(), SiteController in actionIndex(), actionGuide(), actionGuidegenomic(), actionGuideimaging(), actionGuidemetabolomic(), actionGuideepigenomic(), actionGuidemetagenomic(), actionGuidesoftware(), actionContact(), actionMapbrowse(), actionTeam(), actionAbout(), actionAdvisory(), actionTerm(), actionHelp(), UserController in actionLogin(), actionCreate(), actionView_Profile(), actionChangePassword; new_column1.php	/site/index, /site/about, /site/team, /site/contact, /site/advisory, /site/help, /site/guide, /site/term, /user/view_profile, /site/mapbrowse

The views that uses column2.php can also use column1.php without any change is layout as there is nothing in sidebar.

rija commented 4 years ago

thanks @pli888,

This is quite enlightening. I wonder if it's also worth tracking here the versions of CSS libraries being in use curently on develop, because I have advanced the version (minor revision only) on my branch for at least Bootstrap (and use CDN distribution rather than the one copied within the codebase).

pli888 commented 3 years ago

@rija

This is quite enlightening. I wonder if it's also worth tracking here the versions of CSS libraries being in use curently on develop, because I have advanced the version (minor revision only) on my branch for at least Bootstrap (and use CDN distribution rather than the one copied within the codebase).

I've added, where available, the version numbers for the CSS libraries to the above table.

I have also found out that the GigaDB website was created using version 1.6 of the Unify bootstrap-based responsive template. Documentation about the Unify template can be downloaded here.

rija commented 3 years ago

Hi @pli888,

I've looked at the Unify theme's code. I then searched for Unify code snippets in GigaDB codebase and found nothing. My guess is that some selectors and values that renders the Unifiy look-and-feel were replicated by hand in GigaDB. I can definitely see a resemblance between Unify and GigaDB look on public pages. There is some organisation in the Unify CSS files. None of it is replicated in GigaDB organisation of the CSS files though.

The original organisation of GigaDB's CSS uses a build pipeline for CSS based on LESS, not perfect but it made a good foundation. The CSS codebase has become a mess when some major changes were done that bypassed the CSS build pipeline (which is how common.css might have come to existence and me adding datatables.css didn't help setting a good example).

The benefit of a build pipeline for CSS are numerous:

Agnostic of/engaging with technology evolution: Whatever we use as source, we always produce CSS file in the end, so we can keep our frontend practices up-to-date and use more efficient methods, knowing the web site will still work as we still output CSS.
Modern Javascript applications (based on reactive frameworks like Vue.js used in File Upload Wizard) also require a build pipeline and the toolset for building CSS and javascript are the same so we can share the pipeline tooling to a large extent.
Better performance as we can programmatically tweak the output CSS files for optmised loading (one file that's loaded in one request for all pages, multiple files each specific to a single page or somewhere in between)
Easier to maintain, adapt to different devices and extend when using preprocessors (like LESS or SASS)

So our strategy for resolving the CSS issue should probably have a build pipeline as backbone.

With that in mind, it would probably be a good idea to also list on this issue the LESS files from the less/ directory as you did for the CSS files: There are still in use, are domain named, and some of them were added post initial introduction (by me).

When both tables are established, it will be easier to see that most files in the css/ directory that are not auto-generated are actually associated with third party libraries/frameworks (the exception being common.css and datatables.css) while domain related stylesheets are located in the less/ directory.

I have read the SMACSS book, and I found the advices and guidelines very sound and practical. It matches good practices I've seen elsewhere. I think there's great benefit in using it as foundation for our coding guideline for CSS (because there are still too many directions we could go from the book, we should come up with our own guidelines built upon it but more narrow focused, domain and technology specific).

I found the book's content to complement the last three sections (Module and program/Consistent layouts/Establish patterns) of chapter 8 of Web Style Guide (Patrick J. Lynch and Sarah Horton, Harvard Press) in which they highlight the importance of developing our own pattern library. Here are the benefits they list (quoting the book):

A solid, reliable code library can save huge amounts of time, as new features become cut-and-paste affairs, and reduces redundancy, as nobody wastes time reinventing objects and features that already exist in your pattern library.
A single code repository makes the HTML and CSS of your site much easier to check and maintain. This is particularly true if you keep all your pattern examples in one long web page. If you have new code to test, you can add it to the pattern library page and quickly assess whether your new code breaks any older code, or whether any of your new CSS, HTML, or JavaScript class or variable names conflict with existing site code.
The pattern library becomes a powerful communications tool, as designers, front-end developers, and everyone else on the team have a common reference point and shared vocabulary for existing styles and features, and a quick means to check to see whether a feature already exists and can be modified from existing code.
A thorough pattern library specifies a compatible style for all plausible HTML tags, even ones that you (currently) never plan on using. You may never have used a or tag, but specifying a style for seldom-used HTML can prevent unpleasant surprises (ugly browser-default styling) if somebody does use those tags within your site.

The one page pattern library would be the example part of a CSS coding guidelines.

Here's a suggested step by step approach toward resolution of the CSS situation:

Remove common.css and datatable.css, and see what breaks on the current site from develop branch. Then, one by one, fix the CSS by creating the files in the less directory and add there the selectors that would fix a breakage, using SMACSS and Bootstrap documentation (and maybe Unify) as guides (creating new files instead of using existing ones, later it would be easier to remove the old ones).
Start a rudimentary pattern library by concatenating the components from the major sections of the web site into one single web page. The page has to be dynamic and has to pull the CSS and javascript the same way we want to do on normal pages. Make sure there's no CSS or JS error on that page.
Write an automated functional test that check CSS/JS error on the pattern library
Merge back to develop
Start authoring new CSS rules as needed on our feature branch (Submission Wizard, File Upload Wizard,...) in LESS, trying to adhere to convention from the steps above and adding the never-seen-before-in-Gigadb HTML/CSS/JS snippets to the pattern library and ensure the page still works.
Start first version of codified guidelines to go with the pattern library based on the experience above and SMACSS section on code formatting and rules categorisation.

The above doesn't have to be perfect immediately, it just has to work good enough. We can always refine later as the process, conventions and starting from a good foundation are the most important.

Things that, IMHO, do not require immediate decision and can be left for later after the fire is extinguished:

LESS is not the best preprocessor, what else to use
Migrate to Bootstrap 4
What become of CSS workflow when using component-based reactive frameworks
JQuery is not necessary
Is there a better way than dropping third party CSS rules in the css/ directory.

Let me know your views on all this.

pli888 commented 3 years ago

@rija I have broken down common.css into groups of new less files. You can view these on my fork. This is work in progress but obviously the set of less files need to be cleaned and refined.

I have started work on a pattern library for GigaDB using this tool. With the code in the fix-css-less branch of my fork, you can view the pattern library at http://gigadb.gigasciencejournal.com:9170/style-guide/index.php. At the moment, I have only listed the colours which are used in common.css.

pli888 commented 3 years ago

The pattern library is now available on staging server.

Diagrams showing how components in the pattern library are organised in web pages are available here.

only1chunts commented 5 months ago

clsoing this as luis has now fixed these styling issues.

gigascience / gigadb-website