Geeklog Forums

Several functions are available to render a glPage that includes a proper header, footer and configured blocks. These are php functions and they return the html. Depending on the complexity of a plugin the programmer has to display the generated html in a proper sequence. Recently a summary function became available that can create the complete glPage in one go (createHtmlDocument). This php function also returns the generated html and the plugin is in charge for setting up its parameters in a php array.

Now, to make this more transparent and introduce a OO approach, a glPage class is proposed. Having such a class will influence the interfaces with the template class (caching), the blocks, themed headers, footers and so on. But the main difference is that the new glPage class will maintain the content that will be fitted in the final page in memory as opposed to returning on each call the resulting html. This means that plugins that adjust the generated html (in subtle ways after acquiring it thru the current php functions) would encounter problems in doing so. The procedure would be to adjust the html inside the glPage class what would require to extend the glPage class to a desired flavour.
So, instead of maintaing your php array for COM_createHtmlDocument, the gl way would be to hand over the content to the glPage class (and loose the visibility of the php array). And calling site header, siteFooter, startBlock, endBlock would be replaced by a single glPage access. The following is just a simplified example:


Please comment this first thought on glPage. If possible with real examples for the best and for the worse. Thanks.

I am glad to see a conversation started about the glPage class.

My first thoughts on this is that we have to make it backwards compatible with the current COM_createHtmlDocument functionality. This function and the related functions COM_startBlock, etc.. we can move to a depreciated library file that is loaded by lib-common. These functions can then become wrapper functions for using the new glPage class (where possible).

I do think though the functions COM_siteHeader and COM_siteFooter should be removed from Geeklog and not supported anymore.

How far do you want the glpage class to take control (in the first version of it and beyond). For example do you see it taking over direct access to the scripts class?

Expanding on your example above, how do you see this implemented with the glpage class?

---

One of the Geeklog Core Developers.

Well, first is to realise that there is no glPage class yet. And second is to agree that a glPage class has some OO architecture and cannot break bc.
I think we must go ahead in this sequence. Starting with a proof of concept that bc is guaranteed is contra productive and will deliver just more overhead in the effort to create a proper class. This does not mean that a imaginary example cannot be produced.

Whatever glPage is needed, it has a close resemblance to the Template class because a page (in theory) is just a template. One may say that it has a layout, like left-center-right or similar, see wireframes.
The class itself will have more methods, and it can be extended for specific content. As example, it will need (compared to the Template class) a method like addTvar or addTvalue in order to create a tVar that behaves like a array. As another example it is obvious that glPage will be extended with ajaxPage, mobilePage and so on. Also, a glBlock class might do the rendering of blocks.

My first intention is to get comments from the community on how they see the OO functionality that will obsolete some control that is available now, but can do a tremendous job for coding the main logic.

To reply to your quest for the example, here's a imaginary one:


Please bear in mind that creating toolTips, navigation or pagination, lists etc. do not fit logically into a glPage class, except that they can be thought of as templates too. The example above demonstrates that one can create some snippets and stick them in the page. Even a page inside a page should be possible.

The $reference variable is not necessary and is contained in the code to show bc.
Than the first line might be new ajaxPage() or mobilePage() in order to render the wanted page as a response to a ajax call or create a responsive mobile page (with a different layout off course).

I see the scripts class as obsolete. The glPage class should replace that with a addResource method. The best solution is to contain such method in the template though, so you have all components in one place.

A minimal replacement would be available for the last two lines:

I do assume that the render method also outputs the page to a designated device or file (page, file, print, cli).

Templates with logic (coding) behind it.... like a block. Should common Geeklog page objects still be stand along functions?

---

One of the Geeklog Core Developers.

I feel good with the response because this expression hits the essence and delivers a good name for the concept: (common) geekLog Page object. Thanks.

What happens all the time in the code is handing over small to big pieces of (html)text to distinguished functions, either core functions, either customised functions. The idea is that this text be better encapsulated in a object and handed over just the reference to the object. The object glPage will be just the beginning.

We can define object classes like glPage, glBlock, glSnippet, .... , which all are basically a Template object. 80% of COM_functions do create a template object and render the text before returning. By smart categorising these functions become the common geek log page object, and the named COM_function is just a stub to retrieve their respective encapsulated text. When glPage is a static class, it could operate as a factory for page objects. A named COM_function would then create a glSnippet object (which is a template), add it to the glPage object and render it to return the text. So far about bc.

The glPage class is responsible for constructing the resulting page and does so by collecting all common geeklog page objects in the proper sequence. This can be done using a template, as is currently done. This can be done by a pageLayout parameter with ID's.
To create COM_functions as objects (and be able to manipulate them in the named COM_function_stub), is very similar to this process.
What is needed is a very lightweight templet class for snippets like createLink, getTooltip, and such. Such a class would be capable to accept a string as template source, handle arrays and/or objects. Such a class would be recursive by nature.

An objection to this OO approach can be found in the complex code in some plugins to assemble a proper html tag, like other plugins struggle with assembling the correct SQL statement. The technique of working with so called SQL prepared statements is similar to the snippet approach.
Another objection is the fact that you loose exact control over the generated html due to the encapsulation. My opinion is that this is overruled by page generating that fit distinguished frameworks like bootstrap, uikit, lemonade, etc. But first I would like to receive as extensive as possible comments on this discussion.

Nice idea this new class, but please keep a minimal compatibility with old plugins

As a plugin writer I need to be able to define the page tittle, display left/right/both blocks and content, add/load javascript or css. So, clear methods to do this will be a nice feature.

Can it be that this new class uses different layouts?



Ben

---

I'm available to customise your themes or plugins for your Geeklog CMS

Thanks Ben for your contribution.


The class will support full backward compatibility. Though I am not sure if mixing old style with new style is always a good idea. But lets see how this works out.
The class will contain clear methods to set (or configure) the desired layout. Writing this, it is obvious that it will support the (legacy) configuration options that are available.

Not yet resolved is how to handle themes and layout. GeekLog supports a lot of themes and generates several layouts. The (default) theme can be configured by the admin and the user. Than there are themes with a fixed or different layout, even responsive themes. There is a theme-switcher, even a language switcher. The intention is to introduce a layout switcher as well.
Would you share the opinion that maintaining the (dynamic) blocks layout (in reference to your code) is a requirement?

Than, the most important feature, the class would be used to embed a js framework and hopefully, would be able to switch the framework as well. But that is yet wishful thinking.



In my view stylesheets and javaScript are Resources of the page. The class will feature methods like addResource, addMeta, addLink in order to construct the head section. Other methods will handle the body element and the (not existing) trailer. Think of google analytics and html5.

Don't stop commenting now. Send in further requirements you have. It is appreciated.

Hey Ben,

Why would you need to switch themes in code?

I was planning to switch over to a responsive theme at some point to make my site more user friendly. The problem I have is my site displays a large number of blocks which creates a real long page if you use a responsive theme (since the blocks, content, etc.. are all stacked on top of each other). One new feature I was thinking of for the next version of Geeklog was to define (user definable) certain modes based on screen size ... (need to research this more). I would then update the block editor and allow blocks to display only when one or more modes are detected. This way if my site is being displayed on a small screen it would automatically turn off non essential blocks and maybe enable ones that are more suited for a mobile screen.

I know this is not directly related to the glpage class discussion but I am just throwing the thought out their since we are talking about themes.

---

One of the Geeklog Core Developers.

Displaying content in a complete different theme would be a nice feature. For exemole, if you display cooking infos or travel infos on the same site, it would be cool if you can display a custom header, footer, color and/or background. We could use a orange template, a blue template a red one... according to our contents.

---

I'm available to customise your themes or plugins for your Geeklog CMS

I had thought of something like that and combining it with topics. Depending on the topic a different theme would be displayed.

---

One of the Geeklog Core Developers.

Interesting thoughts. Which are feasible already with current COM_createHtmlDocument(), as long as you set the theme in the beginning of the code; that is, before any template is processed. Not to say that the effect would be intentionally in the new glClass.

The real problem is, in my views, that the meaning of theme and layout is not clear. It can be something different for everybody. F.i. we talk of a theme but do mean the usage of template switching or we want a certain layout to be able to do theme switching; while the effects are realized by loading different templates.
If we can come up with a proper definition on what a theme is and what a layout is, than a clear API can be assembled. Since there are themes around that provoke a certain fixed layout, the task seems pretty urgent.

A theme is the look and feel of a geeklog website. Therefor it contains css, icons, a color-scheme, templates. It should never be case that the usage of a specific theme requires code changes. A theme is configurable (as is language too).

A layout is the frame in which the content is assembled and displayed. A layout can be designed using wireframes (what is a wireframe). It contains css, div-id's, javascript, templates. A layout is referenced in the code.

Now, when themes imply a specific layout, problems arise with layout switching because the css to glue components together appear in the theme files. In above defintion there is no place for this (we cannot 'name' the technique).
Also, when specific content needs a different look and feel (but with same layout), we incorrect name that as a different theme. In above definition this attitude could be correct, but clashes with configuration options. And in order to allow this in standard gl behaviour, we need a proper name for it (a subTheme or topicTheme, a motif, a resolution, a ...?)
Than, since gL2.0 a default theme is around. It contains valid css, icons, etc. to use when nothing is configured. There could be a default layout too, I guess. Which contains css, div-id's, etc. so themes (conform the above definition) should not have to bother about glue-ing components together in a custom way: they must refer to glStandard naming of the layout.

So the question is: what is exactly a theme, what might it do, and what is a layout, how should it be glued?
Additional we should properly name subThemes and alike. Do we still allow themes and layout to intermix?

Thoughts, comments, innovations?

I like your definition of Geeklog layout's and themes. It makes sense.

Using your definitions I do not see the need to switch layouts in code beyond what the current layout provides. Allowing this would increases the complexity too much for little benefit. The only time I would see the layout being changed is if the user picked a different one (if available) from the user preferences.

I can see developers wanting sub-themes or at least alternate templates depending on the topic they are in or some other variable. Sub themes should just contain any changed templates or images. If the template file is not there then the main theme template file is used. This will allow for easier updating of themes when a new version of Geeklog comes out. Most people who use Geeklog tend to use one of the main themes and just change a few files.

Sub-Themes may not be the best name though... It makes sense to call it this when the change happens based on a setting or code and while the main theme is still the "main theme". For someone who creates a sub-theme (as described above) by changing the header and a few other template or graphics to act as the main theme it may not.

When I had thought about the topic theme change idea I had thought of a few other ways around it. I could of used an “if” construct in the template file to do the changes I wanted or even added a variable like so just to change an image:



I am just throwing that out as an example as there are ways around things.

The one thing we should try to do is make it easy for people to update their themes and try to balance the complexity, readability and usability of the layout and theme (from a creating point of view. easier said than done :-)

---

One of the Geeklog Core Developers.

Rethinking and evaluating the comments, I do suggest to use the naming of skin, layout and theme. I also introduce template and resource. Please read and comment:

A skin is a look and feel concept that can be applied to pages or their components. It contains a set of browser instructions. Therefor it bundles css, icons, a color-scheme. It should never be the case that the usage of a specific skin requires code changes other than invoking them.

A layout is the frame in which the content is assembled and displayed. A layout can be designed using wireframes (what is a wireframe). It contains css, div-id's, javascript and templates. A layout is referenced in the code.

A theme is the look and feel of a geeklog website, the sum of layouts and skins. It should never be the case that the usage of a specific theme requires code changes. A theme is configurable (as is language too).

A template is a general purpose macro text body that reflects the blueprint for a page or page component. Templates are used for layouts (and refererence by design the (wire)frames). And complex themes may embed their skins in them too. It consist of content (text) with replaceable parameters (variables), get parsed and may be recursive, either in itself, either by code.

A resource is anything that is needed to render a page in the local client (the browser). Resources of a page may vary depending on characteristics of the connection, on the (type of) browser and even on the device that runs the local browser: think of a page that is loaded by a browser script; since we think of pages as a central concept, the script that loads the page is a resource of the very page.
Current resources are limited to style sheets (css) and javascript (js). Resources can show mutual dependency; style sheets cascade and javascripts might depend on a library.


Geeklog, as a portal or CMS or blog or else, delivers in general a complete web page on a (http) request. This response consists of http-headers (amongst them cookies) and a html document. The structure of the html document is identified by a doctype as the first line. What follows is the document which is generally structured with a html-tag, head-node, title-tag and body-node. glPage and components governs only the body-node, but might access geekLog Core to construct the head-node and title-tag.

This body-node comes with a standard geekLog layout as default: header - body - footer.
While header and footer are represented in current themes as a template, body is not. This is considered as an error. There should be a body template that enables the theme to configure right-, center- and left-blocks. Being a geekLog standard too, the body-component of the body-node should have the default layout of left - center - right.

Note. Plugins often just manipulate a specific block, add a block to left or right, or construct a center. Numerous variations exist to build a menu, search box, login box, and differ only in the placement: be it in header, as a left-block or a custom-block in center.

While the contents of left and right is configurable, center is not. This is not seen as an error, though it is pretty difficult to insert a custom block on a certain relative position into left or right. It must also be clear that 'movable' blocks, f.i. login box and search box, are in need of a different rendering depending on the placement in f.i. left or header.

Note. Plugins (and staticpages) do have the requirement to optional suppress left and/or right and sometimes header and footer also. There is a Core setting that allows for that.

It is obvious that the user functions, which are delivered thru code, are in need for a flexible placement on the resulting page and must not be duplicated in themes, be it in code or in templates, what is the current praxis.

Example. A story might show a login box. The thinking behind this is that the site does not offer a login, unless the story is read first (a registration box would be a better example yet). However, having a few landing pages with a story that embeds a login, might enable you to track the starting-point of the user and act upon that.

To be continued.

I agree with your evaluation. The only thing I would change is the order listed:

Resource
Template
Skin
Layout
Theme

---

One of the Geeklog Core Developers.

So thinking about Themes a bit more.

I am assuming Skins would be tied directly to Layouts (ie you can't share a skin with another layout). A default skin will have to be defined then for that layout incase Geeklog or a plugin calls to use a skin that does not exist. I guess the same logic would apply then for layouts then... A theme would have a default layout (if there is more than one).

I am use to the current Geeklog theme structure and I have dabbled in Joomla a little bit. How do you see the file structure for a theme that has multiple layouts and skins?

With layouts how will Geeklog know which layout to use with the new page class?

Currently blocks are displayed based on 3 things.

1. Security the user has
2. What topic they are in (All, Homepage Only, Selected)
3. Left or Right Side

How do you see Geeklog Layouts handling this? With your wireframe wiki page it shows there can be more than just the left and right columns. I guess we would have to expand on #3... (and rename column to something else)

---

One of the Geeklog Core Developers.

Just a quick answer. It is very simple, and thought out-of-the-box. First a short intro.

Templates are used to tie a layout together, currently. One would expect the following template available (but it isn't yet):


We'll find a header.thtml and a footer.thtml, but no body.thtml.



GeekLog Core assembles the blocks for left and right and the plugin creates the center-content. A template is used by glCore to avoid coding in php.

The concept is that one ties a template to a layout (by name) in stead of defining the layout inside the template, as shown above. The confusing part is that a layout is a structure of templates. My view is that glPage maintains a array with elements that identifies a layout and the php-code refers to these id's. Well, not exactly a array of id's but merely a tree of layout components. Valid id's would than be (long form): header, body, body:left, body:center, body:right, footer. The coder would assign a template to such id as opposed to creating a template and assigning the finished content to a variable in the main template.
Example: A plugin could create id's like header:search or body:left:search and assigns the search-box.thtml template to it.

To answer the questions:

A page consists of several boxes (rectangles). We might group them by function, topic, security or else. Important is the grouping by position on the screen (the layout).
Now, every box must be seen as a page too and glPage assembles all those 'pages' into a layout (a page too). A tree of pages is constructed in memory, and every page can have many child-pages and has exactly one parent-page.

A skin is a skin; a theme consists of one of more skins; the current skin is applied to the layout it is set for. In extremum 'header' could be orange skinned, 'body' blue and 'footer' light-green. Additionally the skin of 'body' could be customised too: 'left' could be pink, 'center' dark-red and 'right' mint. Skins cascade as css does.

A theme has a default layout which is identical to the geekLog default layout. Since a layout is a template, the theme might adjust the default templates (or not) for this layout.

GeekLog 'knows' about one layout: page: [header, body: [left, center, right], footer] which happens to be the concept of GeekLog. The new glPage class knows only one layout, and custom layouts can be attached to any component of the known layout, building it's own themed and skinned pages.

Maybe a theme would be able to configure the layouts to use.

For selective blocks there will be no changes. Though it would be wise to rethink that.

The file structure of a theme would be better change, since it is a extensive melting pot of all kind of ideas, some smart, some obsolete. I do think that the directory-name of a theme is of no interest to the plugin and must be magically discovered by glPage.
A bigger problem is that a lot of code generate html attributes scattered all over the place.
These should be in (theme) templates because that is the first principle.

There is a page now on the wiki http://wiki.geeklog.net/index.php/GlPage.

I do realise that the audience to glPage is populated with besides php coders, also web designers. Descriptions and discussions are not special focussed on one of both skills. That might make the rumbling a bit vague.

While walking thru the theme directories it became very clear that templates are very, very customised to the current code. F.i. there are 4 list.thtml, even a specific directory for several formats and block-templates come in all kinds of flavours with an accompanying block-header and block-footer, while the only difference is the classname of the surrounding div-tag. Cleaning up will take a while, which is a understatement. This also looks like that the planned skinning feature would not work with such a massive amount of classnames.

But the most frightening experience is that in a lot of places javascript files are set to load, specifically jQuery components. Obviously it was very difficult to have jQuery smoothly implemented. Eliminating or bypassing that will take a separate configuration module, I guess.

For now, I do assume that a theme will have a configuration. Actually it has one (in functions.php), but most of the parameters are of no use with glPage. So this has to be redone and a skin will probably become a callable php-script, like skins/orange.php or skins/modals.php or skins/admin.php to suggest a few. Such script will have a php-function defined that accepts a layout parameter (which is a string or the object tbd).

The theme directory should contain a template for very layout used, with page.thtml as the root template. Optionally that is, because a layout might contain several layout-nodes. This means that a template-file-path must be scriptable like a template variable. To start with a first implementation of glPage, the default layout for GeekLog is set to 'header, body, footer' and the 'body' is default extended with the layout 'left, content, right'. Plugins will hook onto 'content', I guess. Second, a 'resources' directory should be present that contains all css and css-subdirs if necessary. Third, same for 'images' and 'javascript'. On the other occurrences I don't have a opinion yet. Proposals?

On the wiki glPage you define the template as:



In the current system templates can be cached and some templates like those dealing with stories, topics, staticpages, etc. can be cached to include the (or part) of the content that is processed by Geeklog. This caching does result in some major time savings depending on what is included in the page.

I assume the javascript directory for the theme will include just the theme specific javascript files. Geeklog will still have it's own JavaScript directory for jquery, etc...

One thing I think can be improved on is plugin template customization. Currently most plugins rely on the user to update the templates in place. This makes multi theme websites difficult as well as plugin updates difficult (since the customizations get over written). One idea to fix this maybe is having a plugins directory in the theme directory. In here Admins can add directories for the plugins they want to customize and in those directories any templates that have been customized. The template class can then look into the "customized" directories first and then fallback to the original plugin template location if no customized template file(s) are found.

---

One of the Geeklog Core Developers.