Coding Standards (2015)

Software Support
1

Although it was an underlying subject during years, last [pkp tech cmte] conversations raised an urgent need of “coding standards”
(aka. coding conventions) for HTML and CSS.

Now that the box is open I will suggest define the style for PHP, JS and also for PKP tools and UX/UI.

It’s obvious we can not decide and apply standards for everything and modify the existing code overnight, but we need to start the process if we want it finished.

The task we are proposing here is huge and could take years to be accomplished, so this is why I suggest going step by step: prioritize what coding that need conventions first, and then open a discussion about the standard to assume in this specific area and finally, when we arrive to an agreement, apply it to new code and start it all again with a new language.

In all the cases I suggest go with an existing (and widely extended) documentation project and over it, add our peculiarities (a
preliminary list of projects working on HTML/CSS is added to the end of this post).

Indeed, this is what “Jerico.dev” did with the PKP’s Javascript coding standards we have in PKP wiki. (BTW, I think this is a
perfect example about how to document coding. Great work)

About the priorities, this is my subjective list (please, modify as you wish… adding and removing if it’s required):

  1. HTML/CSS
  2. LESS
  3. PHP
  4. PKP
  5. JS (it is mostly done and only need to be reviewed to unify with the rest).
  6. UX/UI (Patterns?)

BTW, I added UX/UI ot the list, because I think components it also need to be documented.
I know Kevin is working hard on it… In an ideal world, I love to see PKP style guide for UX/UI explained as BBC or bootstrap.

Conventions will help new developers write and understand the code easily but will also more comfortable for our expert ones.

Finally, we are far from this, but with this process we can start a convergence process.

Opinions?

Cheers,
m.

FURTHER READING…

Existing documentation (by Alec)

Long story short: we essentially don’t have any written conventions yet for HTML/CSS. I thought I remembered some but I can’t find them. We’d be starting from a blank slate here.

HTML/CSS coding standards (by Marc):

About UI/UX (ideas to define the “visual style guide” of PKP products):

COLLATERAL DAMAGES

Although is not the focus of this conversation, those are subjects that are more or less related with the work proposed.

Documentation to be updated

Hook list description.

Bonus pack
Visual representation of our git model:Pe: http://nvie.com/posts/a-successful-git-branching-model/

2

It may be useful adding the current effort on UX/UI documentation from the PKP wiki:

I didn’t know that even existed until @marc mentioned @stranack’s effort.

Maybe an UX/UI style guide for PKP products could be in the higher abstraction level

Other kind of guide would be an aesthetical one, describing layouts, colors, etc as the default bootstrap style does. That style will often be customized by each institution journals.

3

Hi all,

@marc, I think this is a good idea. I’ve been engaged to assist Kevin and Alec in analysing and then simplifying the way HTML+CSS are handled in OJS. Part of the work involves making a clearer distinction between the system and the templates that are used to display tools and content, defining a minimal and flexible set of resources for front-end development (such as Bootstrap, GEL, Foundation, or other appropriate framework) for implementation.

Obviously this work will have direct bearing on what we’ll need to cover in coding standards as the adopted tools will bring with them assumptions about HTML tags and classes as well as javascript and the final form of the templating engine.

I also think it would be useful to make some distinctions about the audiences for this material, so we can structure and formulate the content accordingly. I imagine that we have participants with different goals and responsibilities:

  1. The PKP development team and network of contributors – this group focussing on core system logic and database tooling (MySQL, PHP, PKP, Javascript, front-end framework)
  2. The System Admins implementing PKP software in widely diverse situations who may need to customize the software or write special code for their installations (MySQL, PHP, PKP, Javascript, front-end framework+templating)
  3. The Publishers and their continent design/theming participants (Javascript, front-end framework+templating with a sprinkling of PHP and PKP as appropriate)

The code layers you outline, I think are great. I’d suggest a variation:

  1. Front-end framework (HTML, CSS/LESS, and Javascript as defined by a chosen framework or set of tools)
  2. PHP
  3. PKP
  4. JS
  5. MySQL
  6. HIG – Human Interface Guidelines defining the objectives, patterns and standards for PKP tools for editors and authors, as well as best practices for web-design for readers.

Making the distinction between specific ways to implement a UI and what the principles and goals of that UI are, will reduce confusion and contention as PKP software continues to develop.

4

Haven’t check them all (yet), but these talks looks a useful resource for the front-end framework discussion.

CSS Frameworks and The Evolution of Airbnb’s Frontend

5

@ajspadial This looks really good. I’ll be watching the talks starting today. Thanks for sharing.

6

Thanks @jwhipple and @ajspadial for your comments.

Let me start with general statements before going to practical stuff.

  1. My initial post aims to be an “overall view”, but IMHO, if we want to succeed we need to go with baby steps… instead of trying to assume too much.

  2. I’m ok if we assume 3 kind of “participants” to think in our “audience” but always taking in consideration that in real world everyone is a mixture of them and you will never find “pure roles”.

  3. This is a loooong way road, so I propose making clear our goals to avoid getting lost during the journey. I agree with @jwhipple that we need to “simplify the way HTML+CSS are handled in OJS”, as well as “writing code in an uniform way” to let others understand, adapt and recycle OxS code easier and faster (and hopefully, one day… vice versa)

Going to specific…

About the priority list

I like the modifications @jwhipple made to the list, joining first point and adding mysql (BTW, @alec I’m unsure if we need mysql, as far as DB is abstracted) and the idea of going with a single framework (for HTML, CSS/LESS and JS) was also really tempting for me but I finally suggested an split approach to keep all the impressive work done by “Jerico.dev” with JS.

Any way, we need consistent coding standards, and single framework is the smart way, so…

What about keeping Javascript low in our list? Is this why you include JS in point 4?

As @ajspadial, I also encourage UX/UI team to work with an standard and even higher abstraction level. I’m a big fan of Kevin’s work, but will be even greater if could be translated into components, patterns, and so on.

What about moving up in our list HIG stuff? Point 2?

About our “audience”

Are you suggesting writing documentation adapted for each profile or those roles are just to reflect about our target?

About our primary goals

But I insist in going with little steps and start with something very specific, so…

DECISIONS?

Last tech.committee minutes show a bet to bootstrap, so…

Could we translate it all in specific actions and draw a road map?
What’s next step?

My guess is…

  1. Decide HTML/CSS/LESS framework
  2. Start testing coding standards and bootstrap benefits in a small areas of OJS 3.x
  3. Extend and document the experience to the rest of the code.
  4. Follow working in HIG standards.

Further questions need to be resolved, as:

  • How do we evaluate the different frameworks to take a decision?
  • Do we need a full re-factor of OxS 3.x code or we prefer a gradual approach in very specific areas?

BTW, @asmecher and @stranack, your perspective is essential for this discussion. :wink:

7

Hi all,

I’m following this conversation with great interest, but without adding too many of my own thoughts, because my focus on back-end coding over front-end is part of why we’re having this conversation in the first place :smile:

About frameworks, before we make concrete decisions on what we need, I’d like to suggest looking at what we already have, particularly going into CSS, and trying to decrease the number of elements there. Some components are definitely needed (e.g. JQueryUI) and others are worth the effort (e.g. LessPHP) but I think we could easily do away with OOCSS, which I’ve never liked. That’ll mean replacing its impact with something else, either custom CSS or a framework (and of course I prefer the latter idea, especially if it’s something people already want like Bootstrap).

As for how we approach adding this to the existing OJS 3.0 pre-release codebase, it will certianly be a lot of work, but the good news is that the markup and CSS are much more centrally generated. It’ll be a matter of identifying the UI pieces that need work, then applying new styles tot those general tools. This is something I’d like to watch but not participate in, again because I have a kind of colour-blindness for design elements.

As for documentation, it might help to bring @stranack in, since he’s been tinkering with a few methods of documentation recently. In my opinion maintaining documentation outside the software itself will always lead to poor documentation maintenance, though the wiki has proven useful for general elements. I’d love to see good coding and design standards moved into gitbooks and maintained right in the release tree.

Excellent discussion so far!

Regards,
Alec Smecher
Public Knowledge Project Team

8

Hello all,

Has anyone checked this page?
It seems, IMHO, to have a lot of info on how to get started with planning HTML+CSS coding, as well as creating responsive designs, which is of high interest as mobile devices are growing fast.

Ramón Martins Sodoma da Fonseca
Coordenador de Editoração
Portaria N 46, de 30 de Abril de 2014
Analista em Ciência e Tecnologia

Instituto Brasileiro de Informação em Ciência e Tecnologia/IBICT
Ministério da Ciência, Tecnologia e Inovação/MCTi
SAUS - Setor de Autarquias Sul
Quadra 05 Lote 06 Bloco H - Sala 500
70070-912
Brasília/DF

9

Thanks for sharing this. A nice clear overview with good examples.

10

Let’s undust this post…

But, first let me add a little bit noise with two nice links that worth a look: :wink:

After this OT… please guys, let’s focus again in the main subject. :stuck_out_tongue:

I didn’t read any objections to the roadmap described in the former post so I think we all agree in this:

So, once again, it drives us to a very specific question that we must solve in this conversation:

Here you have a few posts with comparatives. Please, extend the list if you got more sources:

Only got time to read one link? This is a great analysis:
http://www.monolinea.com/css-frameworks-comparison

As an starting point, those could be my first “must” about our future CSS framework.
Extend or remove as you wish:

  • Free license: I prefer GPL, but I can live with MIT’s one.
  • Reset & normalization
  • Less compliant: as far as OxS works with Less)
  • Widely extended: big community means more testing and debugging, but also will be easier for “converse” developers to understand OxS.
  • Fixed & fluid
  • Responsive ready: I really don’t mind if “mobile-first”, but responsiveness is a must.
  • Easy syntax:
  • Beter small core, than big core: …

Would be nice if it also include:

  • A good set of widgets.
  • Framework gallery.

Hope to read you soon,
m.

11

Hello Marc,

I haven’t had time, nor think will ever have the time to read all of this any time soon, but, I’ll try to follow up on this and try to be timely on my comments.

This things have to done as you get them, otherwise, they get sidetracked and never accomplished… I only read the monlinea link and it sounds pretty much on target.

One suggestion, if it can be accomplished, and this is the greatest issue with technology, is to use one that could allow replacement. Somethings grow so big that they blow up, while other promising ideas never go too far due to other technological updates… It’s a very difficult decision. I think it may be worse than choosing the baseline technology because it never really fits everything you need, sometimes forcing you to go back and change a lot of the groundwork for it to fulfill its promise.

I’ve used bootstrap before, not very difficult if there’s enough done already in the system templates… I’ve always been a fan of Joomla’s template overriding possibilities and overall theme/template structure (the terms have different meanings in OxS x Joomla, which requires a long explanation for the uninitiated). This is something I’d love to see in OxS, but don’t know how much of the system would have to change…

I believe mobile-first and responsiveness go hand-in-hand, while planning for mobile first forces you to create leaner interface and code and it’s easier to bloat it later, while trying to simplify something complex may be harder to do. At least, that’s what I’ve read…

After this long “overview”, I’ll comment directly on Marc’s ideas (a spreadsheet on Google Drive could be better for listing and commenting…)

Future CSS framework.

- Free license: I prefer GPL, but I can live with MIT's one.

No restrictions here… Not really aware of the differences and the impact of each one…

- Reset & normalization

Not really sure what this means, I may need a lecture on this so I get on the same page as everyone else…

- Less compliant: as far as OxS works with Less)

Whatever compression works best…

- Widely extended: big community means more testing and debugging, but also will be easier for "converse" developers to understand OxS.

TinyMCE has a big community and lots of “support”/acceptance (over FCK, I think) but has its drawbacks… and maintenance of thir-party technology is always trouble…

- Fixed & fluid

No page can be fixed and fluid at the same time. Marc probably meant a vs. in there… This can be accomplished with CSS viewport queries. And it means, being responsive, so I would take this out as it is already being dealt by the responsiveness/mobile-first approach.

- Responsive ready: I really don't mind if "mobile-first", but responsiveness is a must.
As I mentioned above, OTOH, they go hand-in-hand, but mobile-first forces you to start simple.

- Easy syntax:

Not sure what “easy syntax” means. There are a lot of CSS shortcuts for a lot of things. I would prefer the ability to easily override a feature or style over “easiness of syntax”… Some CSS rules get pretty nasty, especially those who try to cater to all browsers…

- Better small core, than big core: ...

Definitely agree. I think the trick is to be able to separate the GRID layout from the styling. Again taking examples from Joomla, there’s T3 and Gantry as Joomla’s templating frameworks. They allow you, from the administration, to define how many columns on each horizontal division available on the template, as well as the distribution (small or large space occupation…). The templating takes care of the “modules” that are displayed, organizing them accordingly. The modules are defined in Joomla’s admin, allowing you to define where and the order of the modules (content, such as menus, content blocks, logos, headers, search boxes, etc…).

Would be nice if it also include:
- A good set of widgets.
What is a widget in this context? The RSS feeds block? The reviewer tasks? Editor submissions queue tables?

- Framework gallery.
What is a framework gallery in this context? Similar to Joomla’s Templates, Joomla’s Template Frameworks or OxS themes? Or something completely different?

I would like to add:
- flexibility through Overrides. Meaning the ability to override any HTML output through a set of HTML/PHP templates and CSS. For example, the Editor’s page elements code could be overwritten by a theme template, without need to change the original file. This would also make upgrading the system easier for those with lots of custom code. Joomla’s templating system allows you to load JS, CSS and any other thing you need without the need to change the original code. The template complexity depends on the needs and knowledge.

- “Module positioning”. Meaning the ability to move blocks around more easily. Some of it is already in place, though the sidebar blocks, but it’s not available for other “modules”, like the Header content, menu, footer elements. This is not necessarily a CSS Framework issue, but it will impact on it (I guess). Again, in Joomla’s templates, a basic “index.php” file defines the structure (module positions). If we could define a rigid set of positions, any template could override those positions at will, without compromising the system or template choice. Joomla’s is too flexible as it allows you to create positions, which may cause some trouble when creating/changing templates if the position names don’t match, but not much harm.

- Page publication options. Not sure if it fits here, but I would love to be able to decide in which pages something gets published (all, none, by user, etc…), allowing to create content modules in specific pages and with specific user access (public, guest, logged in, author, editor, admin…). This will definitely force a lot of rework…

12

I think this is a very good point. There are probably many things that we can clear out. Additionally, a CSS framework will bring with it some implicit assumptions about fashioning a UI and other screens, so there will be some rockiness when we start experimenting.

13

What I mean is this:

  • When I am reading content, I am (in the role) of Reader
  • When I’m adding a plugin to my system, I’m a System Admin
  • When I’m reviewing contributions, I’m a Reviewer
  • when I’m assigning/inviting participants, I’m an Editor

and so forth.

A single person may do all of these activities, but they are all distinct activities. A user may review some work but then switch to some other task. The UI should provide tools accordingly.

14

Hi @jwhipple,

Don’t forget Authors. But for the sake of themes, I think that’s overly specific. I’d suggest considering…

  • Insiders: site admins, editors, series/section editors, copyeditors, etc.
  • “Middle ground”: Authors, reviewers
  • Outsiders: readers, subscribers

Regards,
Alec

15
  • Free license: I prefer GPL, but I can live with MIT’s one.

Free, yes. I like MIT, but I wonder is there any legal/license conflict in using MIT within a GPL project? I suspect not, but I’m not conversant with all the ins and outs of licenses.

  • Reset & normalization

This is pretty much a given, as frameworks all strive for a consistent outcome

  • Less compliant: as far as OxS works with Less)

Not sure how this relates to OxS per se. I guess in as much as OxS core embeds a LESS compiler as part of the page generation and rendering process, then I’d agree. But is seems to me somewhat distinct from OxS. As I see it, LESS (or any CSS extension/abstraction like SASS or SCSS) is part of creating a final outcome. In as much as a framework can be used by manipulating LESS files, I’m all for it!

  • Widely extended: big community means more testing and debugging, but also will be easier for “converse” developers to understand OxS.

Yes, I agree with this.

  • Fixed & fluid

If you mean the framework supports declaring a layout ‘fixed’, or ‘fluid’ and is simple to implement, then I agree with this.

  • Responsive ready: I really don’t mind if “mobile-first”, but responsiveness is a must.

Yes, responsiveness is a must. I think mobile-first is very useful when it comes to thinking about web app UIs, but I suspect we’re quite a ways from that on our imaginary roadmap.

  • Easy syntax:

Yes. Class names that make sense and HTML that is clear and not complex is best.

  • Beter small core, than big core: …

Yes. Although many frameworks can be used in their default state very easily, many also offer the ability to focus their features through selecting only some of their parts for your final case.

Would be nice if it also include:

  • A good set of widgets.

Not sure what you mean by this? If you mean the framework supports combinations of HTML and CSS is particular ways for a particular outcome then I agree. Bootstrap for example has the notion of Components which are used to provide various menus, listings and other useful distinctions in a reading experience and a UI context.

  • Framework gallery

Examples are always ,good.

These considerations are more about the UI itself. The choice of a framework simply stipulates how these might be expressed in HTML and appear using CSS and behave through JS or the templating system.

Frameworks are essentially (but probably not fully) agnostic about things like dragging content modules into a particular position.

More soon…

16

Whowww… to much open fronts. :slight_smile:

I think we are kind of mixing conversations, don’t we?

I mean, we really need to talk somewhere about OxS tools global users but in this post we are focused in coding standards so in this sense, I bought this “target list”:

About the items to evaluate CSS frameworks, mostly are taken from the comparatives.

Let me clarify to be sure we all are in the same page:

- Free license: I prefer GPL, but I can live with MIT’s one.

In short: http://stackoverflow.com/questions/3902754/mit-vs-gpl-license
But as I said, MIT is ok.

- Reset & normalization

I just wanted to be exhaustive about the features the framework must include, but as @jwhipple pointed, every good framework include this, so we can forget this one.

This is exactly the point. Right now, OMP include a LESS compiler in server side so would be nice keeping diversity to minimum. I mean: Our programmers will only need to learn LESS instead of a mixture.

Exactly.

  • Better small core, than big core: …

Let me notice this this will play against Bootstrap: http://www.monolinea.com/css-frameworks-comparison

  • A good set of widgets.

With “widgets” I’m using the terminology of this comparative: http://responsive.vermilion.com/compare.php but @jwhipple pointed in Bootstrap this is called Compontents: http://getbootstrap.com/2.3.2/components.html

@ajspadial also pointed before (and I full agree) the benefits of components in the definition of a UI/UX style guide… but please, don’t jump to this point yet. We can talk about this when we finish with de CSS discussion.

Framework gallery

This point is not well defined. Sorry. Let me refrase…
What I wanted to say is, that as far as Bootstrap class-names and components are always the same using this framework we will benefit of generic themes as: https://bootswatch.com/
As it will also open the door to recycle themes from other CMS.

Reading this thread again I noticed the decision was pretty much taken in the tech committee meeting of 10 March 2015.

So, making it short:
Looking into the comparatives the “conservative” decision is between Bootstrap and Fundation.
Fundation is more small core thant Bootstrap.
Bootstrap wins in all the other items (with nice extras like components)

So the list we are discussing, let us confirm the we are in the right way. :wink:

  • focus has been on OMP/OJS3 branches

Fits perfectly with our second proposed second steep:
“Start testing coding standards and framework benefits in a small areas of OJS 3.x”

  • Alec has been working on implementing a template file overwriter plugin

@ramon, this is what you pointed in your comment, don’t you?

I’m not clear about how it will be faced:

  • Scratch the new code (kind of “if you find a folder, load this instead of that”)
  • Based on Smarty 3 (that allows template heritage).

As this outrages the focus of this thread, I encourage you or @asmecher to open a new post if you want to talk about it.

Finally, seams to me that we all agree in moving to Bootstrap, starting with non critical developments as 3.X branches (please, advice me if I’m wrong).

But does it means that most of the CSS code will be generated by the preprocessor and we don’t need to worry any more about “tabs vs spaces” or “variables in chamelCase” or whatever?

This is mostly true. Bootstrap is kind of rigid i variable names, structures, etc. and the official documentation (http://getbootstrap.com/css/) resolves most of our doubts based on exeamples, but not everything is covered.

Although BS will generate our CSS, the essential questions (identation, variable name, etc.) need to be explicit somewhere for those that create html templates, mixins, and so on… don’t you think?

I made a deep search in google looking for stuff like “LESS coding standards for developers that use bootstrap” and I didn’t find much. :frowning:

Am I losing the north?

17

This is the closest document I found about those “essentials”:

This manual is “everything you should know about BS in an hour” with a very brief intro about those “basic coding rules”:

They mention RECESS and CSSLINT that worth a look as tools to ensure code quality:

Moodle people have an specific guide for LESS coding:

But a final hurting question rises to me: Is there any big free software project using bootstrap in it’s core? The only I know is Odoo (formelly openERP) and most of the CMS I know don’t get married with any specific framework, but play well with all them… :expressionless:

Bad and blur Friday… probably the best I can do is delete the last two posts and look into this on Monday. :smile:

18

Hi all,

I worry about this conversation turning into a black hole – all-consuming and giving only darkness in return :smile:

I think the less we do in the application itself, and the more we permit themes etc. to make concrete decisions, the richer an ecosystem we’ll support. It might be that our developer community will never be big enough to fully make use of that potential, but it’ll help us internally too.

Rather than design by committee and end up with a really complicated mash of philosophies, I’d like to see if we can’t cut a few people loose on the OJS 3.0 front end (or OMP 1.2) and have them come up with some concrete, specific recommendations. There are a thousand ways forward, and probably a hundred of those would work more or less equally well.

Meanwhile, we’ve already made some improvements based on this discussion: I’ve broken up the templates further in OMP, we’ve recently added some interesting ideas to TinyMCE, and plugins can now easily override system templates. Let’s watch for more of these concrete steps. (Marc, I haven’t gone to Smarty 3 yet, but recently re-did the proof of concept from last year’s sprint with more recent versions of everything, so we can continue sometime.)

Regards,
Alec Smecher
Public Knowledge Project Team

19

Alec is right.
I think the system should be flexible enough to allow whoever wants to use it to implement the layout with the tools they know, without compromising the core. Allowing to load BS, Fundation or any other framework within the template is what should be the goal. This is why Drupal, Wordpress and Joomla, and other CMS’s that follow the same idea are welcome by the community. The system provides the processes, but we’re allowed to play with how that is presented.

But this still poses the question on coding standards, mobile-first and other issues. Too much flexibility and the system becomes too bare; too rigid, it’s filled with clutter and hard to maintain, learn and implement new ideas…

Sorry to contribute to the blackness of the hole…

20

Um. OK. As usual, I’m flying around things at 30,000 ft based on what I think people said.

From my perspective, OxS should be entirely agnostic about what HTML and CSS can be used to publish the content for readers from the system. For the OxS system and content authoring-reviewing-editing tasks, OxS should adopt a specific way to present the tools. If that means adopting a framework like Bootstrap, that’s fine (even good), and it’s that state of affairs that coding standards would seek to describe.

So if you’re coding a plugin for OxS, or extending some core functionality, you use the standards set forth for plugins based on the OxS API and conventions for adding functionality. If you’re coding a theme you use the conventions set forth partly by OxS and then those from whatever other things you’re using.

The result would be something like WordPress has, a Coding Standard for those contributing to WordPress Core, another for those writing plugins, and another for those writing themes.

I hope I’m in the ball park now?