An introduction to Layouts

Layouts are how jDownloads displays Categories and Downloads in the Front End.
This article gives a general overview of the Layouts available with jDownloads.  Layouts are the html code fragments that jDownloads uses to dynamically construct page views on the front end.   Some people consider them as 'mini-templates'.   With an understanding of layouts you may control the look and feel of the views created by the jDownloads Component.  The layouts are responsive to different screen sizes as they use a < div> .. < /div> based html structure.

You can edit and change the layouts and this is discussed in other articles about layouts, the principle point to note about editing layouts however is that you should always make a copy first and resist the temptation to edit an existing default layout directly. There are several good reasons for making a copy, firstly if it goes wrong then you can quickly restore back to the relevant layout by simply 'Activating' the default one. Another reason is that a jDownloads update may change one of the default layouts so all your good work could be lost!


First where does one find the layouts?

Just go to the jDownloads Admin control panel and click on layout intro01  in the left hand side menu. 

This takes you to the main Layouts page as shown in the next picture.

As you can see there are seven types of layout.


Note
Sometimes, dependant on your main site template, the list of available types may not show as indicated above.

This is because the panel is in a sidebar.  So click in the arrow buttonbutton which will reveal the sidebar contents.
layout controlpanel01layout intro02layout controlpanel03
To see the choice of layouts in a type click on the relevant type, such as Downloads. This will then show all the layout styles for that type.

Note that in an update from jDownloads 3.2 series there are both 3.2 and 3.9 versions and either sort may be used but it is preferable to switch to the 3.9 versions as they support additional features. 

layout intro03
However if it is a completly new install then only the 3.9 layouts are installed, further they do not have the annotation 3.9 in the name!

Layout Types

As mentioned above, Layouts are separated into seven different types as listed below.  The layouts listed here are just the extra layouts available in jD3.9.  When upgrading from jDownloads 3.2.66 to jDownloads 3.9.x then any existing 3.2 layouts are retained as well as having the additional 3.9 versions as indicated in the picture above. 

The older 3.2 layouts will give the same or a very, very similar view in jD3.9 as they did in jD3.2.  The jD3.9 layouts give a similar view as in jD3.2 but with some enhancements to take advantage of the extra features.

It is intended to phase the 3.2 default versions out over a period of time.
  • Categories:

    These layouts only show the  'top level' Categories. No Sub Categories or Downloads are shown when using layouts from this type.  There are three additional jDownloads 3.9 Categories layouts.
    • Categories Example with 4 columns
    • Categories Example with 2 columns
    • Standard Categories Layout

  • Subcategories:

    Defines the layout for Subcategories when showing multiple categories that are not the top level categories.  This is a new layout type in jDownloads 3.9.  There are two subcategories layouts.  The ambiguous "Standard Categories Layout for paginated Subcategories 3.2"  has been replaced by these Subcategories layouts.
    • Multi-column Subcategories layout
    • Standard Subcategories layout

  • Category:

    Defines the layout when showing a single Category. There is just one additional Category layout in  jDowloads 3.9 . 
    • Standard Category Layout

  • Downloads:

    Defines the layout of the Download list (were formly listed as Files Layouts).  Displayed below the active Subcategories or Category layout. There are nine Download layouts in a new jD3.9 install.
    • Alternate Files Layout
    • Compact Files Layout
    • Compact Files Layout with Checkboxes
    • Files Layout Full Info
    • Files Layout Single Line
    • Files link only
    • Standard Files Layout
    • Standard Files Layout without Checkboxes9
    • Standard Files Layout with Checkboxes

  • Download Details:

    Defines the layout of the Download detailed view.   jDownloads 3.9 has four layouts in this section.
    • Example Details Layout
    • Example Details Layout with Tabs
    • Standard Details Layout - Full Info
    • Standard Details Layout - Full Info (with Related Module)

  • Summary:

    Defines the layout of the Download summary page. With Checkbox  Downloads it lists the files to be downloaded.  It is also used when passwords, Captcha and any similar need for additional user input.  There is just one summary layout.  It is an enhancement of the jD 3.2 series summary layout with a cleaner view.
    • Standard Summary Layout 3.9

  • Search form:

    Defines how the search form and how the results from the frontend search function are shown.  There are just two Search Layouts.
    • Search Form Vertical Layout - Standard
    • Search Form Horizontal Layout

Layout Previews


One of the features of jD3.9 is the ability to preview the layout in the backend.

For an upgrade from the jDownloads 3.2 series only the 3.9 layouts have previews.





An Example preview for the Compact  Files Layout is shown opposite
layout preview 01layout preview 01Alayout preview 02

Layout Structure


The general structure of a layout has up to six areas as noted below.

Header
, which is the first area shown.

Sub-header
, gives more details.

Before, rarely used but is before the first of the main areas.

Main, this section shows details of a Category or Download. It is repeated automatically for each entry.

After, again rarely used but is after all repetitions of the main area.

Footer
, appears at end of the layout
layout overview 01


The view on the screen may be constructed from areas of different active layouts.  For instance in the above example the Header and Footer areas came from the active Category layout whilst the rest came from the active Downloads layout.

Also if there is only one layout in a section then it cannot be de-activated.
In the layouts various items of information are displayed by using what are often referred to as placeholders.  These are enclosed in braces { ... }.  An example would be say {filesize_value} which would be replaced with the actual size of the file to be downloaded.  If the information is not available or should not be shown then jD automatically removes them dynamically when creating the executable code that generates the on screen view.  This is illustrated below in the various 'header' views that may be shown depending on circumstances.  The actual layout code remains unchanged as it is just a template, the 'intelligence' comes from the jD code that processes the layouts.

Layouts may of course be edited but always make a copy as the default ones may be replaced at any update!  For more information on the structure of layouts please see  the article the anatomy of a layout.

The layouts are written as HTML statements and make use of CSS classes.  However to just see how the layouts relate it is not necessary to be an expert in HTML or CSS.  Usually one can see which 'lines' need deleting or modifying.  And of course you can always ask in the Forum.

Place Holders

Layouts use what are called 'place-holders' to place information associated with the Download in the view created by the layout.  These place-hoders are enclosed in { } such as {description} or {home_link}.  They are like an internal jDownload layout simple macro.  For example the placeholder {description} is replaced by code that shows the discription area of theDownload or Category.  Actually it is a little bit more clever;  in a Download it shows the Description but in Download Details layout it shows the Long Description, if it exists.  If the long description is empty then it reverts to the Description.  That is the action of a placeholder is sometimes dependant on which type of layout is being used.  Not all place-holders are avialable in all layout types..

For example the available place holder 'pairs' in the Downloads layouts include: {file_name_title} {file_name} - {release_title} {release} - {file_date_title} {file_date} - {price_title} {price_value} - {license_title} {license_text} - {language_title} {language_text} - {filesize_title} {filesize_value} - {system_title} {system_text} - {author_title} {author_text} - {author_url_title} {author_url_text} - {created_date_title} {created_date_value} - {hits_title} {hits_value} - {created_by_title} {created_by_value} - {modified_by_title} {modified_by_value} - {modified_date_title} {modified_date_value} - {rating_title} {rating} - {tags_title} {tags}

Whilst generating the actual view on the screen using the layouts, jDownloads will only display the relevant information that the user is permitted to see.

For instance if a Download does not have Download permission for say the Public  user group then the Download button will not appear for public users.  The two Downloads shown opposite are identical except a slight difference in name and that the second one does not have Download permission so it has no Download button.

layout overview 02
But what happens if the name of the Download has been specified to link to a Download Details view?

If the user clicks on that link they will indeed be taken to the Download Details view as illustrated opposite.  As well as not having a download button there will also be an appropriate message saying that it is not possible to download the file! layout overview 03

Another simple example is that sometimes only some of the header is shown.  When showing all header items then the view will be such as illustrated below.
layout header01
The Add button only appears if you have permission to create a new Download. The Up does not appear if there is no preceding Category.  That is if some of the information does not exist or it is not meant to appear then they are automatically removed by jDownloads. So you may see headers such as below.
layout header04 layout header03 layout header02
Once again please note that if the data, such as for example an image, is not present then jDownloads effectively skips the relevant area of the layout.

Import and Export

It is also simple to Export and Import layouts to make them shareable in the community, and of course to enable keeping layout backups.  For more details on exporting or importing layouts please see import and export
The tool bar has Export Layout and  Activate buttons.  To select a Layout style as the active one click the checkbox opposite its name.  Clicking on the activate button button will then select that Layout to be used for that type.

If you click on the export button button it will initiate a downloading sequence for the selected layout.  Similarly the button import  button will import a layout

Also available are button edit and button delete buttons, but you cannot delete a Default or Active Layout, or if it is the only layout of that type.


ColinM January 2020

Tags: index

Print Email

This site uses cookies. By continuing to browse the site, you are agreeing to our use of cookies.