OJS OCS OMP OHS

You are viewing the PKP Support Forum | PKP Home Wiki



Theme development: Segmentation, control and normalization?

OJS development discussion, enhancement requests, third-party patches and plug-ins.

Moderators: jmacgreg, btbell, michael, bdgregg, barbarah, asmecher

Forum rules
Developer Resources:

Documentation: The OJS Technical Reference and the OJS API Reference are both available from the OJS Documentation page.

Git: You can access our public Git Repository here. Comprehensive Git usage instructions are available on the wiki.

Bugzilla: You can access our Bugzilla report tracker here.

Search: You can use our Google Custom Search to search across our main website, the support forum, and Bugzilla.

Questions and discussion are welcome, but if you have a workflow or usability question you should probably post to the OJS Editorial Support and Discussion subforum; if you have a technical support question, try the OJS Technical Support subforum.

Theme development: Segmentation, control and normalization?

Postby mbria » Mon Dec 03, 2012 12:48 pm

Hi fellows,

I'm building a new theme for a new magazine and as in every OJS theme... I found I need to deal with /styles or /lib/pkp/sytles folders (In other words: shared CSS for every OJS magazine).

May be it's just me, but would be nice to avoid those shared CSS if you want.

So those are my suggestions to improve OJS's templates:
a) Separate "presentation" and "functionalities" (just in case somebody don't want -for instance- change notifications tooltips, but wants to remove the CSS responsible of the fonts, colors and so on...)
b) Add a new function in vim lib/pkp/classes/template/PKPTemplateManager.inc.php called "deleteStyleSheet' or so (resetStyleSheet function could be a fast easy solution).
c) And last, but not least: Work over normalize.css (or resetCSS if is your preference)

BTW, I normally take the uncommon theme (or one of my theme adaptations) as an starting point but today I started over Vanilla.
Any suggestion about the BaseTheme?

Just my two cents, hoping it will be useful for OJS' improvement.

Cheers,
m.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Mon Dec 03, 2012 12:53 pm

I missed to say that normalize.css could be added to your theme (pe: FooThemePlugin.in.php) with activate method as follows:

Code: Select all
    function activate(&$templateMgr) {
            // Subclasses may override this function.

            if (($stylesheetFilename = $this->getStylesheetFilename()) != null) {
                    $templateMgr->addStyleSheet($path);
                    $path = Request::getBaseUrl() . '/' . $this->getPluginPath() . '/' . 'normalize.css';
                    $templateMgr->addStyleSheet($path);
                    $path = Request::getBaseUrl() . '/' . $this->getPluginPath() . '/' . $stylesheetFilename;
                    $templateMgr->addStyleSheet($path);
            }
    }


But I think it's a good idea to include it directly in every theme... and if somebody doesn't like it, just "resetStyleSheet()".

Cheers,
m.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby asmecher » Mon Dec 03, 2012 12:57 pm

Hi Marc,

The CSS that's currently in OJS (and OCS and OHS) is pretty garbled and has been for some years. We've been hesitant to tackle it because a lot of people have tweaked the CSS and we wanted to overhaul it properly, once, rather than forcing people to adapt to successive refinements when they just wanted a stable layout.

The structures in OMP are most of the way towards the solution we want for OJS. They still involve lib/pkp, and in fact divide the stylesheets up into many more pieces than OJS did, but they use much more logical structures -- and in the coming spring we'll be working to improve those structures and fold them into OJS. One of our major goals here is to make theming easier.

In the meantime, the best way to theme OJS is to build a stylesheet overriding the specific styles that exist in the built-in stylesheets that you want to change. It shouldn't be necessary to modify existing stylesheets, just to override the styles they specify. This means the resulting stylesheet will be tasked with undoing many of the styles you don't like, but that's unfortunately a necessary evil at the moment.

Regards,
Alec Smecher
Public Knowledge Project Team
asmecher
 
Posts: 8479
Joined: Wed Aug 10, 2005 12:56 pm

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Tue Dec 04, 2012 9:03 am

Hi Alec,

Thanks for your comments.

I noticed that OMP is better on a) [Separate "presentation" and "functionalities"]
but still lacks on b) [Methods to control CSS/JS loading from theme definition]
and c) [normalize.css or resetCSS libraries]

Finally, CSS mix and compression is not mandatory but would be also appreciated as performance improvement.

From this list, if I'm reading the code correctly "b)" could be implemented in less than 10 minutes (at least a simple resetStyleSheets()) and I believe will help themers that want a completely clean starting point to build their "skins".

What do you think?
I can submit a patch with the new resetCSS method if you like.

Cheers,
m.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby asmecher » Tue Dec 04, 2012 9:54 am

Hi Marc,

Your assessment looks correct to me; the remainder of the work will need to be done in the coming few months. (Note that we're using LessPHP, which compiles Less-format stylesheets into a single compiled CSS file; further compression could be added there.)

The style has not yet been well separated from the structure. My thinking is currently that we'll do a better job of this, and then allow the user to use their own style CSS rather than load it on top of the existing theme CSS to override previous styling (as is currently done with OJS). However, I'm very much open to input on the details of this, i.e. how much styling should be built in and how much should be left to the CSS author.

Thanks,
Alec Smecher
Public Knowledge Project Team
asmecher
 
Posts: 8479
Joined: Wed Aug 10, 2005 12:56 pm

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Fri Dec 07, 2012 5:38 am

Including a CSS compiler are a really good news.
Thanks. It will definitively make themers' live easier. :-)

About the resetStyleSheet() method I suggested "could be developed in 10 minutes"... I found it's not as easy as I expected. :oops:
Looks like in OJS 2.3.6 some CSS are hardcoded in header's templates so "templateMgr" object can't remove them in the same way addStyleSheet() method can add.

Any case, would be nice if PKP takes in consideration the proposal of improving theme/CSS/JS methods in future OxS releases with methods like deleteStyleSheet($path), resetStyleSheet().

Cheers,
m.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby asmecher » Fri Dec 07, 2012 10:07 am

Hi Marc,

When we get to coding that (which shouldn't be too long) I'll try to make sure we do some consultation on the forums first.

Thanks,
Alec Smecher
Public Knowledge Project Team
asmecher
 
Posts: 8479
Joined: Wed Aug 10, 2005 12:56 pm

Re: Theme development: Segmentation, control and normalizati

Postby asmecher » Tue Jun 18, 2013 3:35 pm

Hi all,

FYI, I'm gathering requirements for some theme work for the forthcoming OJS 3.0 release. If you're interested in contributing, or want to follow the discussion, please let us know or CC yourself to the following bug entry:

http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=8265

The CSS structures already introduced to the OJS 3.0 codebase will make CSS work much less painful for future releases. Help us get modern theming done right!

Regards,
Alec Smecher
Public Knowledge Project Team
asmecher
 
Posts: 8479
Joined: Wed Aug 10, 2005 12:56 pm

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Wed Jun 19, 2013 9:29 am

Alec, I was unsure if I need to publish here or it's better if I post in bugzilla, or in a new specific post...
Let me know if I need to move it.

I still didn't find time to review OMP/OJS 3.0 in deep (I just took a fast brief look so sorry in advance if I'm talking rubbish or some points were taken in consideration in your new approach) but I know well former 2.x versions and I can say the main problem was in the HTML code that is not created thinking in making themers' live easier. :-)

I mean, more div-grouping is required, css IDs&classes are inconsistent (or worst when missing) and some stuff is harcoded (the first think comes to my head is ">>" for "li" tags)... and this is an incomplete list.

Fixing HTML is, IMHO the "priority 0" of the work that need to be done with OxS theming (in other words: a full and detailed template review is required).

Alec posted at bugzilla the following comment:

> Need to consider how to treat "default" theme -- is it actually a theme, or should it be always included and selectively overridden as per OJS?

This is a good question. In short: Both. :-)
We need to offer a basic theme that could be "selectively overridden".

I'm sorry to say that default theme (OxS 2.x) is useless when not an annoyance. From my experience, you spend most of the time overwriting styles instead of building what you need.

Any case, we need to distinguish between "default" and "base" themes. Alec, I know this is perfectly clear for you but let me clarify for other readers.

The "default" theme will be the one enabled by default when OxS is delivered so it will be the most usable, solid, nicer... the most impressive theme we have (and by the way, I suggest OxS to hire a designer to create this default theme).

In the other hand, the "base" theme need to be the most boring one... need to be the "minimal expression", need to be those CSS that we are completely sure will be required in absolutely every theme build in future. It very means very, very basic styling, but also normalization, cross browser styles and responsiveness (normalize, reset, modernizer...) etc.

Till now I was talking about how I think OxS theming system could be fixed (a first/fast approach). Let me talk a little about how to improve it:

As I pointed in former posts, would be nice to give themers a better control over the CSS that are loaded with functions as deleteCSS() or resetCSS() but this is just the beginning. In future we will need a template system that allows themes to build variations based on inheritance and functions to get all the control.

Let's see an example: What happens if I like to move the menu to the footer in just one magazine of my OJS?

Right now, with OxS 2.x the only solution I know now is the "mojo" approach (viewtopic.php?f=8&t=7578)... but also with "mojo" it means that we need to keep different templates for each "themed" magazine and it makes maintenance a little bit more difficult.

I believe template overwriting (or to be more precise "inheritance") it's an important improvement, a "must be" in future for every OxS product.

I'm not a big fan of smarty but if we are following with it (I full understand a change here means a huge task and in confidence I'm unsure it will mean a real improvement in performance and features) I believe we need to migrate to version 3 to take advantage of the "Template Inheritance" features.

Here you have a very biased list with some opinions, comparatives and features of different template engines to start the discussion:

We also need to establish CSS coding standards (for code and comments) and best practices.
Here I publish some links as an inspiration (or to adopt directly as our own standards).


There are a lot of CSS "frameworks" but today "bootstrap" would be my suggestion (again IMHO).
Taking advantage of http://bootswatch.com would be a very nice feature for every OxS... and this is only one of the benefits of bootstrap.

I didn't know the work done in this sense by CUDevMaxwell&tikidream until today (viewtopic.php?f=28&t=9464), but it could be a very good starting point. If bootstrap means we need to modify OxS code I think we must adapt it to support it natively.

It finally drives us to the CSS preprocessor: Although SaSS&Compass is richer in features I'm happy you decided you use LESS, because:

    * Bootstrap compiles faster with LESS
    * LESS is written in JS, whereas SASS is written in Ruby. We also have lessphp compiler at server side.
    * "LESS is simple"

As a themer...
    * I would like a system that let me start a theme "from scratch".
    * I would like to have a system that lets me start a new "subtheme" as a little variation of a former one.
    * I would like to have a built-in structure to build responsive sites.
    * I would like to have a CSS preprocessor.
    * I would like to have a better documentation and rigid coding standards.
    * I would like to have a bigger gallery of themes as starting point.
    * ...

So in conclusion, I think would be wonderful that OxS base themes would be a bootstrap over smarty 3 and a set of new theming functions that could be preprocessed with LESS. :-)

Sorry for the long post. Hope this makes sense to you... at least as an starting point for the discussion.

Cheers,
Marc Bria.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby asmecher » Wed Jun 19, 2013 11:53 am

Hi Marc,

Thanks for all the details -- yes, it's a long post, but this is a big subject and we want to do it right. Let's continue the discussion here for now.

First, the good news:
  • As you've noticed, LessPHP is being used already for the new theming structures
  • We're using much better markup, and it's much more centrally generated using standardized UI tools like grids and modals (often inheriting from JQueryUI and extending with a few additions and a PHP-backed implementation)
  • More or less all of the old CSS will be torn out of OJS by the time 3.0 is released
Already the OJS 3.0 codebase (git master branch) contains very little of the old OJS mark-up -- though we do need to complete more refactoring before it'll all be gone.

I think a look at the alpha release will give you a good sense for what we have in mind. This will be available fairly soon, though if you want to get a jump on it, you can look at the master branch. Or OMP 1.0, for that matter.

LessPHP has been good to us so far; there are a few options for using it to bring in themes as well. My current preference is:
  • Ship OJS with a compiled CSS file from LessCSS sources
  • Theme plugins may ship with Less files if they like, but maintainers should compile these into CSS and include the compiled CSS as part of the plugin
  • The compiled CSS for OJS will be included in the header template, followed by any theme CSS file(s), which may have also been compiled with Less or may be written directly in CSS.
This means that all Less compilation will happen manually. It does limit the theme's ability to intervene in the OJS Less files, except by overriding shipped styles in a later include, as is currently done with OJS. The massive improvement in CSS and markup structure should make this a much less inconvenient way to work than it has been in the past.

Alternative approaches include giving the system enough smarts to know when to recompile its own CSS files with LessPHP. Generally I'm not in favour of this because I don't like treating compilation as a runtime activity, and it breaks the KISS principle. On the other hand, it would permit themes to mix in CSS at other points in the process, and would compile system and theme CSS into a single file rather than having the reader's browser fetch them separately.

Currently the "base CSS" provides basic structure and layout, and the "default theme" adds a fairly neutral set of design decisions such as colours and fonts. The separation between the two is basically there but will need some cleanup. When another theme is chosen, the "default theme" CSS will not be applied (unlike current OJS practices).

As for Bootstrap and responsive design, we will need some outside expertise: our development team is fairly heavy on back-end development skills and correspondingly light on front-end. There are already several CSS libraries included in OMP 1.0 (the same for OJS 3.0) and I would like someone with front-end expertise to look at the set we're using and determine whether which we should turf and which others to incorporate.

I haven't yet assessed Smarty 3.0 but I'm fairly sure it's off the table for the OJS 3.0 release; we simply have too many other things to tackle at the moment. I think the way we're treating templates already in the master branch shows major improvement on the 2.x approach. Like transitioning away from ADODB, I would love to modernize our Smarty implementation, but other things are currently more pressing. Once we have OJS fully modernized as per OMP 1.0, our platform will be much easier to shift in this way -- currently we're basically maintaining two (or more) platforms at once. (We will have to consider how OCS and OHS fit into this, of course, but that's a discussion we're putting off until later.)

Caveats: 1) I have not done my homework yet by reading the links you provided above; and 2) Front-end development has never been a particularly strong skill. Your ideas are more than welcome, even (especially) if they contradict mine.

Regards,
Alec Smecher
Public Knowledge Project Team
asmecher
 
Posts: 8479
Joined: Wed Aug 10, 2005 12:56 pm

Re: Theme development: Segmentation, control and normalizati

Postby beuseful » Thu Jun 20, 2013 12:26 am

It's encouraging to see there are so many thoughts to improve the front end of OJS, just want to say thanks :D
beuseful
 
Posts: 9
Joined: Mon Jan 14, 2013 8:36 am

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Fri Jun 21, 2013 8:07 am

Yes, I know it's my fault. My initial post was a kind of spaghetti of topics and now we have lots of sub-subjects over the table.

I will try to split the discussion in topics (a divide&conquer is usually a good idea) so people can talk about all of them or just the part they are more expert or interested in. If we see a topic is eating the whole discussion I suggest it will be the moment of creating a new post.

Those are the "sub-subjects" I think we are discussing right now:

  • Improve HTML structure
  • Default VS Base theme
  • Extending OxS API with new theming functions
  • Theming inheritance VS CSS precompilation
  • Coding standards for HTML & CSS
  • Best practices/Patterns for HTML & CSS
  • Adopting a CSS framework
  • CSS preprocessor

1. Improve HTML structure

"We're using much better markup, and it's much more centrally generated using standardized UI tools like grids and modals (often inheriting from JQueryUI and extending with a few additions and a PHP-backed implementation). More or less all of the old CSS will be torn out of OJS by the time 3.0 is released"


Your answer makes clear that a big effort was done in this sense and it's really good news. Congratulations and thanks.
I plan to take a deep look to OJS alpha after summer vacations.

Any case, would be nice to adopt and share "HTML coding standards" and make explicit the "best practices or patterns" used... for internal development coordination but also for 3rd pary developers that can join someday.

I know it means time, but it will be translated in a better quality in code.

2. Default VS Base theme

Currently the "base CSS" provides basic structure and layout, and the "default theme" adds a fairly neutral set of design decisions such as colours and fonts. The separation between the two is basically there but will need some cleanup. When another theme is chosen, the "default theme" CSS will not be applied (unlike current OJS practices).


It is also a really good news but I think we are mixing stuff.

In my former post I suggested a "default" theme designed to impress, to be functional, to be the official image of OxS... (that could be what we have now although I encourage PKP to improve it hiring a designer or start a competition to create a more modern look&feel)

Right now (2.x) any theme is taking styles from the own theme but also from: /styles and /lib/pkp/styles
I'm really happy to hear that "default theme won't be applied" but we need more than this. :-)

This is why I also suggested a "base" theme with only the very, very essential and without any design.
It will be extremely useful for themers as an starting point.

Sometimes themes will also need to overwrite those "base" styles (for instance to build a "fluid theme" or "responsive"...) but this will be discussed in next points.

So, what do you think about distinguish between "default" and "base" in OxS?

3.Extending OxS API with new theming functions

Let me start saying that this point need to be thought in deep.

As a themer sometimes I missed functions as:
    deleteCSS(): To remove an specific CSS (based on path?)
    resetCSS(): Remove every CSS (including specially /style and /lib/pkp/style)

and now I will also suggest compileCSS()... but it's not only CSS functions that are required.

I'm more concerned about how to let us play with the template system and "overwrite" an existing template (header?) without hacking OxS.
Those tools will be great for themers, but also for plugin developers.

If you think it's useful we all can start an open wiki to list and discuss the functions missed.

4.Theming inheritance VS CSS precompilation

In my opinion is not "one or the other"... soon we will need both because they address different issues (you wanted me to contradict you) ;-)

I understand (and also like) your approach with the CSS precompilation and I agree it's a big jump that will give us a big potential but...
this only let us play with the CSS (the presentation) but not against the templates-HTML (the structure).

This is why I'm suggesting develop "theming inheritance" to let developers build themes and plugins that can modify OxS html markup when the project requires it. I can give you lots of examples where this will be extremely useful (content plugins? layout alterations? ...)

We are not in a hurry with this but to reduce the development effort I suggested jumping to smarty 3 (that aims to be 2 compliant and include "inheritance"...).
Any case I didn't play with smarty 3 either so more expert opinions are required here.

To be fair I think this is also a point to analyze in detail before we develop a single line... maybe taking other CMS as an inspiration/example.

5.Coding standards for HTML & CSS

I didn't see any answer in your post about this point. I suspect we agree that's a MUST but we need somebody to write a consistent proposal... and all our agendas are full.

Any volunteer? :-)

I missed to say that as in PHP, here also would be nice to include comments in a way doxygen (or similar parsers) could autodocument our code.

If not, I will start adopting the standards of other communities (see former links about drupal, worpress, mediawiki...), but I really think we need to make it all explicit.

If no volunteers rise up, I can write a mix of coding standards based on former mails.

6.Best practices/Patterns for HTML & CSS

It's a big task if we want to do it from zero... or we can build it collaboratively in a wiki while we are writing the code.
I vote for the wiki approach. :-)

7.Adopting a CSS framework

"As for Bootstrap and responsive design, we will need some outside expertise: our development team is fairly heavy on back-end development skills and correspondingly light on front-end. There are already several CSS libraries included in OMP 1.0 (the same for OJS 3.0) and I would like someone with front-end expertise to look at the set we're using and determine whether which we should turf and which others to incorporate."


Any brave volunteer?
Are CUDevMaxwell and tikidream reading us? :-)

8.CSS preprocessor

Although Alec and I are happy with LESS... I know this is a very controversial point so I put here to keep the discussion open.

--------

I think thats all: Please, feel free to add new topics and/or refute the former ones.

Again a LONG post, but the subject is huge so I don't feel bad for this. ;-)

Cheers,
m.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Mon Jul 22, 2013 3:05 am

No comments means you agree? :D
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Re: Theme development: Segmentation, control and normalizati

Postby asmecher » Tue Jul 30, 2013 9:48 am

Hi Marc,

I'm in broad agreement with what you describe; there are still a number of details to work out but I think the Alpha release of OJS 3.0 will make a good platform to start.

Have you ever seen autodocumentation in CSS? I haven't; I'm not sure OTOH whether Doxygen supports such a thing. It might be interesting, though.

For the deleteCSS, resetCSS, and compileCSS functions, do you have a particular lifecycle in mind? For example, if a plugin wanted to modify the built-in CSS (resulting presumably in a recompile), would it take effect upon installation? I'd imagine we could add a hook that triggers some specialized code e.g. in plugins when a CSS recompile is requested, to ensure that plugins get a chance to control the regeneration of CSS when it happens.

In any case, I suggest we dust off this conversation after the alpha release and start coding in earnest.

Regards,
Alec Smecher
Public Knowledge Project Team
asmecher
 
Posts: 8479
Joined: Wed Aug 10, 2005 12:56 pm

Re: Theme development: Segmentation, control and normalizati

Postby mbria » Wed Jul 31, 2013 3:25 am

Have you ever seen autodocumentation in CSS? I haven't; I'm not sure OTOH whether Doxygen supports such a thing. It might be interesting, though


Not Doxytgen, but there are alternatives.
I didn't try myself (and I must :-P), but those 3 links worth a look (by order of preference):


  • StyleDocco: Also is able to work with CSS preprocessors (documenting mixins, variables...). Parses SCSS & LESS. Runs over Node.js


For the deleteCSS, resetCSS, and compileCSS functions, do you have a particular lifecycle in mind? For example, if a plugin wanted to modify the built-in CSS (resulting presumably in a recompile), would it take effect upon installation? I'd imagine we could add a hook that triggers some specialized code e.g. in plugins when a CSS recompile is requested, to ensure that plugins get a chance to control the regeneration of CSS when it happens.


In confidence I didn't thought much about how to implement it. Those functions were more a need I saw when we develop a new theme.
I was thinking in just let theme plugins reach those functions but now you open the box, would be really nice to let every plugin.

I'm far, far away from your knowledge of OJS code but your proposal seams logical to me: CSS recompilation would be a good moment to do all the job.

If I catch you, it means that the original OJS css will be ignored-replaced and the final CSS will only include the plugin ones, that will be delivered by the OJS cache, isn't it?

It's an smart solution to avoid performance issues as the ones that some CMS have when including plugins review in the bootstrap.

In any case, I suggest we dust off this conversation after the alpha release and start coding in earnest.


Times are up to you. :-)

BTW when we "undust" this, we need to remember that we have here a few of subjects that I think we need to close (coding standards? theming inheritance? template overwriting? code patterns?)

Meanwhile, if you think it it's useful, I can work in the proposals I made in some of the former points.

Finally a "bonus pack". :-) Did you know about:


Cheers,
m.
mbria
 
Posts: 292
Joined: Wed Dec 14, 2005 4:15 am

Next

Return to OJS Development

Who is online

Users browsing this forum: Google [Bot] and 1 guest