Coding Standards (2015)

Yes… but will be a standardized black hole, isn’t it? :stuck_out_tongue:

Not as far Jon. :wink:
As I said, was a blur Friday… and I recognize I fall in a loop in my last posts but from your comments I feel we are in the same page.

I mean, it’s true that we rumble a little around the topic, but this let us focus and define clear what we need. In your words:

Exactly.

And we can define it before doing the refactoring (as I suggested, to get the developers a common coding guide) or after (as alec suggested, to make rules that make sense in real world).

I’m unsure about it but I full trust in Alec’s experience and… where the captain rules, a sailor has no sway. :wink:

Any case, I believe the list of “HTML/CSS coding standards” published in first post will be still useful in 2-3 months, that is the time I suspect development guys will need to look around and come with comments about their experience.

Take care,
m.

PD: Thanks Alec to keep smarty3 changes. May be UI/UX developers (is @jwhipple doing the job, isn’t he?) find this useful.

Hi all,

I like the technical aspects of what we’re talking about, but I’m mostly thinking about the social engineering. Practically speaking, I think if I pointed a developer or a community member at this thread, they’d run away screaming. I think what we need is more like one of our sprint events, where a small subgroup tackles some very concrete work and goes ahead with it. We’d need to check to ensure that it wasn’t running at cross purposes with any of this before it got merged in, but I don’t think there are many conflicting requirements here.

I’d suggest that any of us with initiative and time (ha!) could simply start working on any of the following without further specifications:

  • Improving the separation between base styles and default theme
  • Removing the old OOCSS library
  • Cleaning up the default theme’s visuals, e.g fonts, spacing, etc.
  • Improving templating with documentation standards, Smarty3 proof of concepts, etc.
  • …etc

Think do-ocracy, with a free hand to experiment and suggest, rather than starting with a huge spec. I think some of these tasks, which largely involve clean-up what we know needs doing on our current codebase, will make great stepping-stones towards the bigger and tougher elements: for example, how do we tackle responsive design?

Thanks,
Alec

Hello Alec,

I’m not sure if this is what you are looking for, but I liked this article and this one.

Ramon, nice links to get a general overview about responsive development.
Take a look to boostrap manual to understand grids and how the framework works:
http://www.tutorialrepublic.com/twitter-bootstrap-tutorial/bootstrap-grid-system.php

And here you have examples to play with:
http://www.w3schools.com/bootstrap/bootstrap_grid_system.asp

Very much agree Alec with your proposal… but please, don’t point any body to this post if they are not really interested in the subject. I mean, this is a conversation, with the inevitable steps back and forward, not a clear roadmap or a guide. :wink:

I was suggesting giving a “direction” to the one that will do the cleaning job. I mean, at the same time you clean, you can sort a little the mess adding class names and html tags following a few rules. Indeed it lack of direction stops me in past when I was thinking in doing the job by my own.

But I really don’t mind if we find somebody with energy to face the task and we go in the other direction. BTW, I love to commit myself to do the job, but it won’t happen until july at least. :frowning:

Take care,
m.

Hello all,

I think we can vote on naming standards for ID, class, color styles.
For example, should we use hifens (-), upperLowerCase, underscore(_) for special tags?

Should the names be self explanatory? For example: articleLink, article_link, OR article_link (if such class/id existed…)?

We could leave this alone and free for custom code, but, for core/default themes, a standard should be defined, just to make the code more readable and understandable, specially when reading the CSS and knowing beforehand where that style is being applied, without having to guess.

ID’s should be minimal, mostly for structure and GRID elements (such as sidebars, header, footer, content), and everything else should have a class attributed to it, as they enable overrides according to context/need and multiple attribution:<htmltag class=“myClass someOtherClass myPargraphClass” …>. Adding classes, even if they have no style makes it easier for JQuery and CSS to identify clearly what needs to be styled. I mean, direct naming is shorter and faster, in terms of page load.

For example:

p.myStyle {} 

is faster than

div #content div p {}

I recommend shortcuts whenever possible and lowercase whenever possible, especially for attributes, such as colors as they are smaller (less bites than uppercase). For example, #000, instead of ‘black’ or #00000.

All style rules should be closed by semi-colon ;
No spaces between colon : to reduce file size.

I’m not sure how these could fit in an “OxS Theme and Styling Rule Book”…

Hi @ramon,

There’s a little bit of documentation here: http://pkp.sfu.ca/wiki/index.php?title=CSS

…plus some reflection of that documentation in the current LessPHP CSS structures.

I think it would be a mistake to generate a style guide that went into extreme detail. I’d suggest we adopt someone else’s widely-used style guide, and let tools like LessPHP deal with details like minification.

Regards,
Alec Smecher
Public Knowledge Project Team

1 Like

Hi Alec,

That Less thingy is far more complicated than I anticipated…
But I think the documentation is going on the right direction.
May need some more examples, and the use inline comments within themes will be more than enough documentation.

Hello all,
Has anyone checked this out?
http://handlibrary.definitysolutions.com/

Thanks for the link ramon. I didn’t know about them and it worth a deep look.

Please, guys check this post:
http://pkp-disc.lib.sfu.ca/t/relaciones-internacionales-ojs-2-4-2-bootstrap-google-fonts-and-more/1365

Hi all,

@marc invited me to this conversation, and I’m really proud he did. Even more after reading all the posts: I think this may be a little over my knowledge.

First, let me introduce myself a bit. I’m Andy (Andrés, in fact but Andy is easier) and I’ve made the OJS custom installation that Marc posted above. I’m a self-taught amateur of PHP, HTML & CSS. I’m more used to !Joomla & WordPress but OJS introduced me to the PHP world, that’s why I’ve got a kind of special relation with it.

Anyway, long conversation and it seems that there’s still a long way to go.

Right now I’ve got a cold, so I may not be thinking clearlyl and I may be wrong about lots of things. But, here are my suggestions (I know there’s a lot topics already discussed, so please forgive me if I talk about them or if I simplify too much):

  • Responsive design: I think this could be easily done with CSS3 & HTML5. BS also helps, installing it directly on OJS does not look bad, so it’s maybe the best option. Regarding older browsers compatibility if other CSS3 rules were added, Modernizr.js could fix for them. So I really don’t see the problem here, really.

  • And that involves the use of LessPHP: I will go for CSS3 and forget about it! :sunglasses: Minification shouldn’t be a problem with [Mr Clay’s Minify code on Github][1].

  • Naming standards. I’d vote for using hiphens and I’d use self-explanatory names, maybe adding some prefix to avoid conflicts. Example: article-link or pkp-article-link. Something like that. I agree with Ramon on everything else.

  • Cleaning up the default theme’s visuals: if that implies messing with HTML or CSS I’ll risk myself and say that I’ll be glad to help.

And that’s it for now. I really think you guys know much more than me, and I’m sure that these suggestions have any sense at all. But I also think this may be an opportunity for me to learn some nice coding.

Cheers to all,
Andy

Gracias Andrés for your contribution and welcome to the thread. :smile:

Your comments make a lot of sense to me.

At the beginning I was thinking in BS mainly for responsiveness… although I like the idea of a kind of theme standarization (as far as BS is becoming a “facto sandard”). Modernizr is a nice addition. Thanks to mention.

@asmecher, I remember you told once that OJS 2.4.x implements CSS and JS minification and compression. I’m asking because I can see any change in my 2.4 journals… did I dream it? :wink:

Otherwise, this is also a nice addition.

Right now we have a mixure of “hyphens-vars” (more or less a 25%) and “camelCaseVars” (75%) so a decision should be taken.

FIG clean their hands about this subject:

4.2. Properties
This guide intentionally avoids any recommendation regarding the use of
$StudlyCaps, $camelCase, or $under_score property names.

Whatever naming convention is used SHOULD be applied consistently within a
reasonable scope. That scope may be vendor-level, package-level, class-level,
or method-level.

I like best camelCase (java style) names, but I won’t start a war for this. :wink:

My suggestion here will be “do the same others are doing”… and if we take a look to the big projects (drupal, joomla, symphony, mediawiki…) in CSS classes and id, hyphens-var is by far, much more extended.

So, I vote for hyphens to.

My proposal here is offer 2 default themes for OJS: the first one is a “clean” theme. No styles, no decorations, very basic, very minimal… Never mind if this theme is ugly because it’s not created to been shown, just be a base to let themers build upon. And the second theme (based on this first one) will be the nice, cool, extended official OJS theme.

Any way, this is a OT, so if anybody is interested in extend the conversation, please open a new thread.

More or less, we all share the same opportunity. :wink:

Finally, here you have a link that could be useful to create our codding standards:
http://edorian.github.io/php-coding-standard-generator/#phpmd

Hi all,

OJS 2.4.x does include LessPHP-compiled CSS (see lib/pkp/tools/buildCss.php) and minified Javascript (see lib/pkp/tools/buildjs.sh) but neither of these are used very comprehensively until OJS 3.0/OMP 1.x. You’ll see a lot more refinement in both once OJS 3.0a comes out in August.

Regards,
Alec Smecher
Public Knowledge Project Team

Hi everyone,

Over the last couple of months I’ve been working with PKP on a part-time basis to improve the UI for OJS 3.0 beta. I’ve been watching this thread for a while but I didn’t want to jump in until I had a better understanding of the OJS 3.0 codebase and a good sense of what we can actually accomplish in time for the beta release in August.

Thanks to some work from @beghelli, the OJS 3.0 beta will have a (pretty) clean separation between the reader frontend and the administrative/editorial backend. That means we’ll get independent HTML markup and different CSS stylesheets (compiled from unique LESS files).

The upshot is that we will be able to dramatically rethink the UI for the backend without worrying about how this will effect the reader frontend. On the flip side, themers like yourselves will be able to build completely customized reader frontends, using whatever toolset/framework you like, without having to worry about whether or not you’ve broken the administrative and editorial functions of OJS.

In order to make our August deadline, I’ve been focusing on cleaning up typography, contrast, visual hierarchy and vertical rhythm. I’ve also targetted some big low-hanging fruit, like restructuring the backend navigation and content panels to de-clutter the management UI. But the bulk of the application’s complex components (grids, tabs and forms) are only getting a re-skin to enforce good design standards across the backend.

I’ve focused entirely on the backend so far. In the process, I’ve made some snap decisions regarding code structure, naming standards, etc. Often I’ve just adopted a pattern which was already there in the code and tried to stick to it as best as possible. There’s no reason these patterns need to be set in stone, but I’d much rather push forward for OJS 3.0 beta and, once there, talk about which patterns work best for us, which are worth changing and what needs documentation.

My sense, though, is that the standardization discussion we’re having here is primarily geared towards the reader frontend. There we have blue skies. We can pursue just about whatever we want, and we can produce multiple themes tackling different goals.

In the short term, my goal for the August deadline is to have a clean, attractive default theme in place. I’ll probably be doing the bare minimum in order to make that happen on time.

In the long term, though, I’d love to help you work towards a community-built “starter” theme, built on a common framework and designed to be easily adapted and extended by third-party themers. I’d recommend you use Bootstrap. It gives you a complete set of standards for HTML, CSS and JavaScript components, so you don’t need to document things yourselves. Other frameworks are good, too. But Bootstrap’s wide adoption is it’s primary benefit: people know it and can find answers to their problems quickly by searching Google.

I hope that the final 3.0 release of OJS will ship with an ambitious default theme that makes strong, informed choices about the reader frontend. But the truth is that a default theme needs to be a platform serving diverse needs more than a highly tailored product. That may limit the scope of what we can do out-of-the-box.

For this reason, I think it’s good to begin thinking about the reader frontend in pluralistic terms. A community-built starter theme is a great foundation on which other people can iterate.

If I can be of any help, please let me know. I think you’ve nailed down a pretty good consensus on what to use. I’d suggest your next step is to start building a custom theme based on these principles. But to be honest, you’re probably better off waiting until the 3.0 beta, because a lot of things will be changing in the next two months.

2 Likes

Hi @NateWr,

Thanks a lot for your comments and sorry for the silence.

I feel like in this post we are just making questions that need to be solved (that is also a task that need to be done) but for the answers, the perspective of the one (or ones) that is/are getting his/their hands dirty with the real job is/are the most important and the first opinions to take in consideration.

Let’s wait till OJS 3 beta is relased then.

BTW, reading the thread, looks like we all agree that Bootstrap is the safe bet (hurray!!), but it’s good to keep an eye in emerging alternatives. :wink:

BS will be also my choice, but this article worth a look:

Chers,
m.

1 Like

Bootstrap 4 alpha is released:

They moved from Less to Sass. :no_mouth:

Yeah, to be honest the shift from Less to Sass will be difficult for us, because PKP’s software uses a PHP compiler that ships with the software. I don’t see us switching everything over to Sass any time soon.

That said, I wouldn’t be surprised if we see a Less port of Bootstrap 4 pretty soon, so this problem may go away before too long.

1 Like

By the way, I haven’t forgotten about this thread now that OJS 3.0 beta is out. One of our goals is to produce a developer blog post that outlines some of the improvements for theming. Since we’re charging forward on so many fronts I don’t know if it will happen imminently but it’s definitely planned.

In the meantime, I would just point out two things that ought to be helpful.

  1. (Almost) all of the frontend templates are in one directory now. The structure for them is explained in this commit message.

  2. The only stylesheet loaded on the frontend is derived from an index.less file in the theme plugin. Although the current Less file loads some styles from pkp-lib, you don’t need to and could implement whatever styles you wanted in your custom theme plugin.

3 Likes

Nice article that worth 10 minutes of our time:

1 Like

Till we find the coding standards grail, a list of things that would be nice to avoid:

Cheers,
m.

Nice ideas to take in consideration: