Ch 09: Publishing, websites, URLS, PIDs and archiving

09a: Publishing websites and database archiving


The Publish menu

The Publish menu delivers easily edited CMS websites embedded directly within the database, as well as individual web pages which can be embedded in other sites. It also provides an archiving function which enables the download of a complete, documented copy of the data in the database in open format.  

embedded-image-fud0m8yr.png

The CMS : creating a website

Why use the Heurist CMS?

Heurist provides a powerful CMS capability tightly integrated with the database. There are several advantages to this approach:

Configuring website layout 

The initial web page may look somewhat different depending on what template has been set as the default. 
The default website is created with a set of commonly used menu entries and web pages with dummy content.

Note: If you are not logged in you will first need to login with the login link at top right of the screen, or in the backend interface.

image.png

The website editor can be displayed by clicking on the website editor link on the top left of the screen

image.png

At the top of the screen you have some general controls:

image.png

The << chevrons can be used to temporarily close up the website editor panel, without exiting the website editor. This may be useful to have extra screen space when editing text blocks on the page (which open in a WYSIWYG editor when yu click on them).

image.png

The website URL is the recommended compact URL for the website. Click on it to copy it to your clipboard.

The Website Layout / Properties button 

Changes the title, logo, background, languages and other settings of the website as a whole

image.png

Opens a standard record edit form for the CMS_Home record which defines the website:

image.png

The “Advanced” tab allows you to provide some custom CSS and/or Javascript : see below.
DT_THUMBNAIL (base field 2-39) is used as favicon for the website.

The Site tab (menu management)

Allows you to add, reorder, rename and delete menu entries

image.png

The Page tab (widgets)

Edits the currently selected page structure and modify the component styles and widget properties.
The widgets making up the page are shown on the left.

image.png

Creating and editing components in a page

The element you are currently working on is highlighted by an animated blue border. If you change the element in any way, the changes are immediately visible in the preview. You can therefore use Heurist’s web editor to experiment and learn by doing. 

You don’t need to know very much in advance about what these different settings do — just change them, and see the effect. You can actually learn a lot about web development just by playing with Heurist’s website builder. Anything you learn about your Heurist site will apply to most website development.

Advanced users can apply custom CSS classes to the element, or write inline CSS as they desire (see below).

After inserting the component, you can edit its content in the usual way. You can also add further elements to change the component. 

Using widgets

If you insert a widget you will first see a list of possible widgets.

embedded-image-oiibs4ht.png

What is a widget?

To add interactive content to your Heurist site, you need to use Heurist widgets. A widget is an interactive component which either retrieves or displays information about records in your database. The Map and Timeline widget, for example, plots records on a map and displays them in chronological order on a timeline below. The Saved Filters widget allows you to embed filters that you have defined in the Explore menu on a webpage, enabling visitors to your site to search the database.

Many of the widgets replicate tools that you are already familiar with from the Explore Menu (you are in fact using the same widgets that we use to build the backend interface). However, when you embed a widget on a Heurist site, you will have more ability to customise its look and behaviour, so you can control the user's experience.

The available widgets are:

How do I configure a widget?

Once you have inserted a widget into a page, it will appear in the treeview to the left. If you click on it, this will open all the settings for the widget, where you can alter its functionality. Note that there are several tabs with different fucntions - nasic setup, onscreen controls, image handling, messages (when data is missing etc.) and Connect (which sets connections between 

image.png

See the specific page for each widget for information on the specific settings.

How do I format a widget?

Most widgets will expand to fill up whatever space you provide them on your webpage. If you need to adjust the positioning or external appearance of a widget (e.g. by adding margins around it or a border), then you can do this using the Style tool, as you would for a static component such as some text or a heading.

How do widgets talk to each other?

You are very likely to add more that one widget to a webpage. When you do, you will probably want them to interact. For example, you might use the Saved Filters Widget to allow visitors to search the database, the Standard Filter Result to list the results of a search, and the Network Graph to display the results visually. When widgets are inserted into a page Heurist links the widgets together so that they interact correctly. You do not need to configure anything for this to happen—it is automatic.

More advanced users might wish to know how this works. Behind the scenes, Heurist divides the page into one or more search realms. All the widgets in a given search realm share data with one another. By default, the entire page is a single search realm, so that all widgets on the page will search, filter or display the same set of records at any given time. But it is also possible to divide a page into multiple search realms if required. It is even possible to have search realms which run across pages.

When you configure a widget, you have the option to specify which search realm it belongs to. You simply tell Heurist what search realms you would like to exist, and it will take care of creating and utilising them. If your 'Saved Filters' and 'Network Graph' are both in a search realm called 'Bob', then they will be linked. If you instead write 'Jane' in the search realm box for both widgets, then they will be linked together in a search realm called 'Jane'.

Types of widgets

Simple text box

image.png

The simplest of all components, the simple text box contains static WYSIYYG text (Simple text boxes can also be loaded in two and three column modes as a shortcut to individual positioning or flexboxes).

Simple text can be edited in WYSIWYG mode simply by clicking on the text in website edit mode:

image.png

Apart from the usual formatting options, one can create a link which inserts a new record in the database (Add Rec), one can insert images and other files from those previously uploaded or by uploading from your local drive or providing a remote URL (Add Media - see data entry of file fields for detailex explanation), or standard web hyperlinks (URL).

Filter

The Filter widget create a search box (as in the Explore menu) which can be used :

This widget has to be completed with the Standard filter results widget.

Filters Tab

The Saved filters allows you to display a selection of filters previously created and saved using the Facets Builder function described in chapter 7 (Explore menu), to enable your visitors to search your database by facet. This widget has to be completed with the Standard filter results widget.

embedded-image-qh4yaug0.png
Connect Tab

embedded-image-chgshzrc.png

Search group: Name the search realm that the widget belongs to. By default, all widgets belong to 'search_group_1'. If you choose to use this feature, do ensure that you type the names of each different search realm exactly. Any typo will prevent the feature from working.

Info directs to page: Use this feature if you wish to direct visitors to a different page on the site when they select a record on the map.

Unique widget id: A name for the map widget on this page. This feature is only useful if you are using custom Javascript or CSS in your website.

-------------------------------------------------------------------------------------------------------------------------

Standard filter results

This widget allows you to display a Filtered Results pane, displaying the records in your current 'result set'. 
The current 'result set' is the set of records retrieved by the filter you have most recently applied. (see chapter 7).

Setup Tab [to be described]

image.png

Controls tab [to be described]

image.png

Images/blog tab [to be described]

embedded-image-aat8yhom.png

Messages Tab [to be described]
image.png

The messages accept fairly basic html such as <b> <i> <u> &nbsp;
They can also use simple styles such as:

<p style="text-align:center;width:98%;border:2px solid green">
Please make a selection on the left</p>

We recommend spacing the messages down from the top and in from the left using simple inline CSS for a more attractive appearance. They should only be left in teh default position when space is at a premium.

Connect Tab [to be described]

embedded-image-3uvvp1ma.png

Custom report

The Custom Report widget lets you display the record selected in the results list in the form of a a custom template that allows you to display the results of a search in the desired format (see chapter 8a : the custom report template must first be built using the editor available in the Record view pane, via the “Report” tab.)

Setup Tab [to be described]

embedded-image-jy6lpvbd.png

Tools Tab [to be described]

embedded-image-rwjpby66.png

Messages Tab [to be described]

embedded-image-pyrkiesd.png

Connect Tab [to be described]

embedded-image-xabexfya.png

Table format

The Table format widget lets you display the results of a query in a table format.

The Table Tab  [to be described]

embedded-image-fhblavzk.png

Messages Tab [to be described]

embedded-image-e4fbxiia.png

Connect Tab [to be described]

embedded-image-lb7gkrwl.png

----------------------------------------------------------------------------------------------------

Map and Timeline

There are many options for controlling the appearance and functionality of the map widget.

 embedded-image-rz6ed98v.png

Controls Tab

General behaviours:

Layers Tab

embedded-image-sum9yy8t.png

Default global base map: Choose the 'basemap' that is used to create the image of the earth's surface. Heurist comes with many base maps. Advanced users can apply 'filters' to the base map to e.g. invert the colours or make the map sepia.

Superimpose map document: Select a Map Document from the database to govern the appearance of the map.

Infobox Tab

embedded-image-idpamr04.png

Click map item for info: You have three options for how record data will be displayed when a record is clicked on the map.

Map info popup format: If you don't wish to use the default format, you can define an alternative format using Heurist's Custom Report builder. If you do this, you will probably wish to change the Map popup size using.

Cluster tab

image.png

Connect Tab

embedded-image-e88xrome.png

Search group: Name the search realm that the widget belongs to. By default, all widgets belong to 'search_group_1'. If you choose to use this feature, do ensure that you type the names of each different search realm exactly. Any typo will prevent the feature from working.

Info directs to page: Use this feature if you wish to direct visitors to a different page on the site when they select a record on the map.

Unique widget id: A name for the map widget on this page. This feature is only useful if you are using custom Javascript or CSS in your website.

-----------------------------------------------------------------------------------------------------------------------------

Story Map [TO DO]


-----------------------------------------------------------------------------------------------------------------------------

Network Graph [TO DO]


-----------------------------------------------------------------------------------------------------------------------------

Menu [TO DO]

Add record

This widget display a button to add contributions to the database : it open a form to fill in, in the same way as in the populate menu.

The administrator has to define the Record Type in which the data will be created :

embedded-image-kthfsdwn.png

Email Us Form

The "email us form" widget allows you to add a contact form to your page, so that visitors can email you without you revealing your email address publicly on the internet. The form will send emails to the owner of the database.

image.png

image.png


====13/05/2025 - reprendre ici=====

2.2.4. Using CSS (=== Styling)

Adding CSS to your Heurist website

Publish > Website

Cascading Style Sheets (CSS) is a programming language used to format webpages on the internet. If you arrange the appropriate authorisation with your server administrator, then you will be able to write CSS code to adjust the appearance of your website. If you are willing learn some basic CSS, then you will be able to powerfully customise your Heurist site, changing its appearance significantly. If you choose to go further with CSS, you can  even introduce animations and mobile-friendly layouts to your site.

It can be daunting when you get started with CSS, but the best approach is trial-and-error. Edit the CSS, see how the website looks, then keep tinkering until you get the appearance you want. You can use the developer tools in Chrome or Firefox to explore the structure of your website, and to see exactly how the CSS is applying to it.

For a brief introduction to the fundamental concepts of CSS, and links to some useful resources, see our Publish Menu Tutorial.

There are five main ways you can incorporate custom CSS into your website. You can:

Before we cover these topics, however, you need to know how the custom CSS you write will link up with your website.

Controlling how CSS affects your website

A CSS file is made up of a series of selectors and declaration blocks . The  selector   says which elements of a page you would like to format, and the  declaration block says what formatting you would like to apply to the selected element. For example, let's say you wanted all paragraphs on your website to have blue text and two lines of space above and below them. You could write the following code:

p {
     color: blue;
     margin-block-start: 2em;
     margin-block-end: 2em;
 }

In this example, the selector is  p . It will apply to all  p tags – i.e. it will apply to all paragraphs.

But what if you only want to apply your formatting to  some elements? For example, perhaps you are writing an internet novel with two narrators. You want all the paragraphs spoken by Narrator One to be in blue, and all paragraphs spoken by Narrator Two to be in red. To achieve this, you can use CSS  classes . Take a look at the code below:

p.narrator-one {
     color: blue;
 }

p.narrator-two {
     color: red;
 }

In this example, we use a period "." to select only paragraphs that have a certain class. "p.narrator-one" selects all paragraphs with the class "narrator-one", and "p.narrator-two" selects all paragraphs with the class "narrator-two". You can actually use a class selector on its own. In this case, it will have a slightly different meaning:

.narrator-one {
     color: blue;
 }

This example will select all elements with the class .narrator-two, whether they are paragraphs or divisions or headings or any other element. Though this  particular example will only have an effect if the element contains some text, since the 'color' declaration only affect the colour of text. There are different CSS declaration for the colour of the element's border or background.

If you just want to style one particular element on a page, you can select it by id using the hash "#" symbol. For example: 

#my-special-element {
     border: solid green 5px;
 }

This will select the element on the page with the id 'my-special-element', and give it a green border 5 pixels thick. If you want to be more specific, you could also write something like h1#my-special-element, which would select just the heading level 1 that has the id 'my-special-element.'

We could go into much more depth about CSS selectors and declaration blocks, but if you really want to learn all the details, then you should do one of the many excellent CSS Tutorials available on the internet. The key question here is:

How do I assign a class or id to an element on my Heurist website?

Assign classes

To assign one or more classes to an element on a Heurist page, click on the element in the treeview and open the 'Classes' section. You can add as many classes as you like, seperated by spaces.

NB: Obviously this means that class names cannot have spaces in them. The convention in CSS is to replace spaces with hyphens. Hence in the example image, the classes are narrator-one, highlighted-element and blue-background.

embedded-image-ddwkj0ng.png

Assign an id or add element CSS (right image)

Every element you insert in the Heurist treeview is given an ID automatically. If you click 'Edit source', you will see the automatically assigned id in the ID field. You can change this as you wish. You will also see a box for applying CSS directly to this particular element. This box is only for special cases – as much as possible, you should use stylesheets that apply to entire pages or entire websites, as described below.

Editing the source (advanced; right image)

If you wish to apply CSS to particular elements inside one of the element in the treeview, then you will need to click 'Edit HTML source' under the 'Edit source' heading, and assign classes or an id to the relevant elements directly. There are good explanations about how to assign a class or give an id to an HTML element on W3Schools.

embedded-image-psyqaq1l.png


Some useful selectors (advanced)

If you are ambitious, and wish to develop a CSS template that thoroughly formats your whole website, it can be useful to know some of Heurist's key selectors. Click below to expand the list.

 Useful selectors for Heurist websites

#main-content: All Heurist sites by default are packaged into three main div elements. The #main-content element occupies most of the screen, and is where the content of the webpage is loaded. To apply formatting to elements inside #main-content, you can use a child or sibling selector . For example, the selector #main-content p {/* some formatting */} will apply formatting to all paragraphs inside the #main-content division.

#main-header: The #main-header element appears at the top of the screen. NB: If you wish to change the appearance of the #main-header using CSS, then you are strongly advised to define your own custom header in the 'custom header' field of the website record. Make sure to include all the named elements below (#main-title etc.), if you want Heurist to automatically generate the website's title, menu and so on.

#main-footer:The #main-footer element appears at the bottom of the screen.

#main-logo: The #main-logo is a div element in the left of the #main-header, which contains the site logo.

#alt-logo: The #alt-logo is a div to the right of the #main-header, which contains the site's second logo, if there is one.

#main-title: The #main-title div contains an <h1> element with the main title of the site

#main-menu: The #main-menu is a div in the #main-header containing an unordered list (a <ul> with <li> tags for each menu item).

.smarty-report: This class is assigned to the main-content of any custom reports embedded in your site. Any styles that you apply to your website will automatically be applied to custom reports as well. If you would like to define special styles that only apply to items inside a custom report, then you can use the .smarty-report selector. E.g. .smarty-report p { some styles } would apply to any paragraphs inside a custom report, but would not affect paragraphs in the rest of your site.

heurist-searchFaceted-header. define it in custom css. This is the header which appears above the facet searches

Where do I put my CSS?

As mentioned above, there are five main ways you can incorporate CSS into your website.

As a global stylesheet in the website record

The best place to put your CSS is in the database record for your website. Any CSS that you place here will be loaded when visitors first visit your site, and will be applied to every page of your website. This allows you to create a consistent look and feel for the entire website, with a coherent colour scheme, fonts, and layout.

To add CSS to your entire website, click 'Menu' in the top left of the treeview in the web editor, and then click 'configure website layout'. Go to the 'Advanced' tab, and you will see the textbox where you can type in your custom CSS.

embedded-image-59hpulf0.png

You can also access the website record in the Explore Menu, just like any other record. To find the website record, type 'website' in the searchbox, or filter by Entities in the Explore Tray, and choose 'CMS_Home' as the Record Type. Any websites you have created will appear as records in the Results Pane.

 embedded-image-uuvz6nni.png

 As a page stylesheet in a webpage record

You can also create page-specific CSS. This is a good idea when one particular page of your site has a special layout or functionality. That particular page may need a special set of CSS classes, and may have many special elements with particular ids.

To add CSS to a particular webpage, click 'Menu' in the treeview of the web editor, and find the relevant page in the treeview. Click the pencil icon to open the database record for that webpage. Under the 'Advanced Customisation' tab, you will find the text field for 'Page CSS'.

embedded-image-gni7up85.png

As with the website record, you can also locate page records through the Explore Menu. Simply look for the 'CMS Menu Entry' record type, or search for the name of the page you wish to add CSS to.

 embedded-image-ujzvupas.png

 Add CSS to a Custom Report

If you wish to style a Custom Report, then you can add CSS at the top of the report, as described in the Custom Report Advanced Usage page.

Add CSS to a particular element

Your final option for writing your own CSS is to use 'inline styles'. There are two ways to do this. As depicted above, when you edit an element of a webpage in the Treeview, you can find a box for 'CSS' in the 'Edit Source' section. Any CSS you insert here will be applied to that element of the page. If you wish to provide inline CSS for elements within the page element (e.g. paragraphs in a textbox), then you can click 'Edit HTML Source', and type the inline styles into the screen.

Generally we do not advise this use of CSS. It should only be used when you encounter problems with specificity, and cannot override a global style any other way.

 External CSS/JS

You can also import CSS from an external source, using the 'External Scripts and Styles' field in either the Website record or the record for a particular Webpage. The most likely use case is if you wish to use Bootstrap in your website. If you wish to use this feature, you should certainly get in touch with the Heurist team for more detailed advice.

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p" crossorigin="anonymous"></script>

If you have written CSS on your own machine, and wish to upload the stylesheet, then you can choose to do this as an 'External Stylesheet' using Heurist's 'Manage Files' tool. You may find this more convenient than copying-and-pasting the CSS into the 'Custom CSS' field, particularly if you have mulitple websites using the same CSS in your database.

If you wish to take this option, upload the CSS file using 'Manage Files', and then copy-and-paste the URL for the file using the built-in URL-copying tool. Then paste the URL using the below template into 'External Scripts and Styles':

 === A REPRENDRE A PARTIR D’ICI !===

Changing header styles

<to be written, please contact Heurist team for instructions / assistance>

Loading record view or custom format in a panel

The aim is to carry out a search, click on a record in the results panel, and display the data for the selected record in a separate panel. This is achieved in two steps:

embedded-image-i46stvtz.png 

embedded-image-v38bvcf3.png

Link/button to pop up edit form

To popup a new record form in a large window rather than a new tab (note that this also makes the record owned by the current user)

 <a href="#" onclick="{window.hWin.HEURIST4.ui.openRecordEdit(-1, null, {new_record_params:{rt:54,ro:'current_user',rv:'public'}});  return false;}"  

Running Javascript

To avoid the risks of out-of-control websites, this requires authorisation by the system adminstrator. Contact the system adminstrator / Heurist team to have your website added.

Editing pages in standard edit form

Although it is possible to edit the content of a web page directly in the standard Heurist record edit form, we recommend editing it within the CMS editor, as this provides additional capabilites including the insertion of images and database widgets (filters, visualisations and layouts). 

  embedded-image-0dykzve3.png

However direct editing in the standard data entry form can be useful if you are only dealing with entering text or fixing up text in existing records. 

FAQ

 [Custom style for Standard  Record view ?]

This issue can be resolved by setting custom styles for desired elements. I've added the following styles for your page:

.heurist-widget{
   font-size:18px !important;
   }
.recordTitle{
   font-size:20px !important;
   }

All font-size are relative to body font size 

Font-size is being taken from CSS for custom report widget

embedded-image-0bevsylb.png            

embedded-image-4naydyxr.png20px    embedded-image-rplovyvp.png10px

If it is not defined it takes font-size from user preferences

If both values above not defined it takes body.popup.font-size from h4styles.css 11px

Examples of how to lay out a web page using DIVs
Heurist blog page (with widgets removed)

Defines lefthand panel for saved filters or search widget and rfull height righthand panel for blog entries (a resutkls list in full content mode)

<div style="position:absolute;left:5px;width:315px;height:100%">
<p style="padding:0 5px;"></p>
<div … style="position: absolute;top:70px; bottom:5px; width: 315px;"… > </div>
</div>
<div … style="position: absolute; border: none; left:322; right:0;top:0;bottom:5px"… >
</div>

Cardinal view layout

<div id="cardinal1" style="background: white; position: relative; border: 1px solid gray; height: 100%; width: 100%;">
   <div id="westpane">WEST</div>
   <div id="centerpane">CENTER</div>
   <div id="eastpane">EAST</div>
</div>

<div id="mywidget_2203" class="mceNonEditable" data-heurist-app-id="heurist_Cardinals">
   {"container":"cardinal1", "tabs": {"west":{"id":"westpane","size":"300","minSize":"150"},"center":{"id":"centerpane"},"east":   
   {"id":"eastpane","initClosed":true}}}
</div>

Strategy

  1. Create the widgets you need without worrying too much where they are located
  2. Open the page in source edit and copy the source to a text editor such as notepad
  3. Return to WYSIWYG and add Cardinal layout widget
  4. Open source editor again and add the widgets within the cardinal layout divs, for example:

<div id="mywidget_6801" class="mceNonEditable" style="width:100;heigth:100;border: 1px solid gray;" data-heurist-app-id="heurist_Cardinals">{"container":"cont","tabs":{"west":{"id":"west","initClosed":true},"center":{"id":"center"},"east":{"id":"east","size":300,"minSize":200}}}</div>

Parameters for each panel can be found here https://plugins.jquery.com/layout/

Most important are: size, minSize, maxSize, resizable, closable, initClosed

<a href="?db=abc&website&id=123&pageid=456">Open page 456 of website 123</a>

Table View widget

datatable_custom_render = function(data, type) 
   { if (type === 'display') 
       { return '<span style="color: red; font-style: italic;">'+ data + '</span>'; } 
       return data; 
   };

{"columns": [{ "data":"rec_ID","title":"ID"},{"data":"1","title":"Title","render":datatable_custom_render}]}

It is possible to define a particular function for every column. In this case define this variable as array of function  datatable_custom_render=[foo1{}, foo2{}, foo3{}] and refer them on “column” by index:  "render":datatable_custom_render[2]

Load arbitrary style files

To enable bootstrap styles

{"classes":"table table-striped table-bordered","columns": [{ …...

==== à relire ====

 Treeview Navigation widget

This is an extension of the Navigation widget. Now it has 3 modes: horizontal, vertical and treeview. It loads a page depending on “target” field

  1. “Inline” with usage of target field from menu/page record. By default this is #main-content - page will be overloaded
  2. “Inline into #page-content div” (target field from menu/page record will be ignored).  You have to add <div id=”page-content”></div> next to widget div. In order they will be next to each other either use table or
  3. Float:left for menu widget and display:inline-block for page-content. Or display:inline-block for both

<div id="mywidget_879" class="mceNonEditable" style="background: none; position: relative; border: 1px solid green; height: 500px; width: 200px; float: left;" data-heurist-app-id="heurist_Navigation">{"menu_recIDs":"1092,1091,1090","use_next_level":false,"orientation":"treeview","target":"inline_page_content","init_at_once":true,"search_realm":"sr1"}</div>

<div id="page-content" style="display: inline-block; width: 400px; height: 500px; border: 1px solid red;">&nbsp;</div>

// Sep 2019: This file lists databases on this server which may include JS code in the CMS Home Page or CMS Menu records
// All other databases are excluded from executing such code. Order is unimportant.
balipaintings
ExpertNation
etc.

<a href="#" onclick="{window.hWin.HEURIST4.ui.openRecordEdit(-1, null,
{new_record_params:{rt:54,ro:'current_user',rv:'public'}});  return false;}"
rel="noopener">

CSS is responsible for colors and positions only. All other properties are set via widget options, although we define some color/appearance styles per every widget (border, background). I believe it would be better to apply our color scheme dialog for CMS website. I’ve added DT_SYMBOLOGY field to CMS_HOME in Heurist_Core_Definitions - need to synchronise CMS_HOME structure for existing databases (prior to ~21 Nov) using Structure > Browse templates. So user can set these colors via color scheme dialog.

In summary, the style of the website is defined through:

  1. Color scheme per CMS website - defined in color scheme dialog;
  2. Widget options - defined in widget properties dialog;
  3. Widget css - position styles (and optionally special color scheme) - defined in widget properties dialog;
  4. Header elements (#main-xxxx) position/visibility and optional colors - defined in “website css” field in “CMS home record”. Use “heurist-header” class for CMS header. 

Parameter “style” for map widget layout_param. For example: "style":{"color":"#00ff00","fillOpacity":0}. It takes precedence over style defined in 1) top most mapspace 2) user preferences

Further documentation is in the header of websiteRecord.php

#main_header.ent_header is hardcoded in websiteRecord.php. It has the following elements
#main-logo      - content defined via field "Site logo" (99-51.2-38). On click it reloads main page
#main-logo-alt  - content defined via field "Supplementary logo image" (99-51.2-926)
#main-title>h2  - field "Website title" (99-51.2-1)
#main-host      - information about host and heurist. Content defined in Heurist settings
#main-menu      - generated based on linked Menu/Page records (99-52)
#main-pagetitle>.webpageheading - loaded Page title "Menu label" (99-52.2-1)

#main-header{
    background:rgb(112,146,190);
}

#main-logo-alt {float:right; display:block !important; min-height: 73px; min-width: 130px;
 background:url('./?db=johns_hamburg&file=0b7475713789fb09e30334c7ae8e094b32e6bd71');
  margin: 7px 4px 0 0; background-size: contain;  }

main_header.ent_wrapper
main_header.ent_header   #main_header
main_header.ent_content_full   #main-content-container

Main setting for these elements is height of header. To change it set:

main_header.ent_header{height:180px} .ent_content_full{top:190px}

HEADER:

#main_header.ent_header is hardcoded in websiteRecord.php. It has the following elements

    #main-logo      - content defined via field "Site logo" (99-51.2-38). On click it reloads main page

    #main-logo-alt  - content defined via field "Supplementary logo image" (99-51.2-926)

    #main-title>h2  - field "Website title" (99-51.2-1)

    #main-host      - information about host and heurist. Content defined in Heurist settings

    #main-menu      - generated based on linked Menu/Page records (99-52)

    #main-pagetitle>.webpageheading - loaded page title "Menu label" (99-52.2-1)    

You may overwrite default styles for these elements in field "Website CSS" (99-51.99-46).

Background image for #main_header is defined in field "Banner image" (99-51.99-951).

 CONTENT:

#main-content-container.ent_content_full cosist of one element #main-content

This element is emptied and reloaded for every page of website. Its content is arbitrary and defined via CMS editor or direcееly via record editor in field

    "Website home page content"/"HTML content". (2-4)

    After load, Heurist invokes

    window.hWin.HAPI4.LayoutMgr.appInitFromContainer( document, "#main-content" )

    This method replaces all div elements with attribute data-heurist-app-id to appropriate Heurist widgets (search, map, result list etc)

There are 2 fields per menu/page record "target css" and "target element". They are reserved for future use. At the moment page content is always loaded into #main-content and applied general Heurist color scheme unless the style is overdefined for particular widget.

Content of website can be defined as custom smarty template in field 99-51.2-922.
In this case designer has to define at least one element with id #main-content.
Element with this name will be used as layout container for widget initialization.
All other elements (#main-xxx) are optional. 

INITIALIZATION workflow:

On server side:

  1. It loads Home page record 
  2. If there is DT_POPUP_TEMPLATE field, it executes smarty template, otherwise page html structure and cotent of #main-header is generated in websiteRecord.php

On client side

  1. HAPI initialization, DB defintions load -> onHapiInit -> onPageInit
  2. onPageInit: init LayoutMgr, init main menu in #main-menu element
  3. loadHomePageContent(pageid): Loads content of page into #main-content and calls widget initialization width LayoutMgr.appInitFromContainer
  4. If database configuration permits only:

    After widgets initialization it loads javascript (field 2-927) and incapsulate this code into afterPageLoad function. The purpose of this script is additional configuration of widgets on page (that can not be set via cms editor) - mainly addition of event listeners.

ToDo: This will need an explanation of how to set styles of target element - please could you give me a couple of examples here that I can expand upon:

For popup use can specify jquery dialog options: 

width:400px;height:200px;title:"Kuku";resizable:true;position:{ "my": "left top", "at": "left+100 top+200"},modal  draggable

Position is relative to window. User can define “of” param { "my": "left top", "at": "left+100 top+200", of:”#id-of-element”}

css for content:  background:red;font-size:4em and others

For non-pop this is usual css. After loading the different content to the same container, the original style will be restored.

Target style and popup option are applied on publishing only. In CMS editor it is difficult to cope with popups.

-----------

Open websiteRecord.php. If main page is not generated via smarty template the structure of page is defined in this php script:

main-header with elements: main-logo, main-title, main-host, main-menu, main-pagetitle

And container for current page main-content.

All other style selectors (such as .hie-result-list) are defined in tinymce editor and can vary from page to page.

If using a custom report (Smarty report), none of these selectors is applicable since user can define their own custom website with arbitrary html elements.

=== à relire (fin)===


For detailed instructions and tips on configuring a website, please refer to the top level CMS websites menu entry.

Heurist is tailored to publish data in the form of a website, using its core functions to present and organise data for the public.

The website editor screen consists of a Website editor panel on the left, and the current page being edited ("This page") on the right.

Editing this page
Applying CSS

The website can be styled through CSS files which may be stored in Heurist uploaded files, accessed through records containing uploaded files <check>, placed within custom reports or entered in the custom CSS fields of the website definition record (CMS_Home)

Page Item

CSS Selector

Website Header

#main-header

Website title

#main-title

Website logo container

#main-logo

Website logo image

#main-logo img

Alternative logo container

#main-logo-alt

Alternative logo image

#main-logo-alt img

Main menu / Navigation

#main-menu

Main menu headers (top)

#main-menu div > ul[role="menu"] > li

Main menu headers (all)

#main-menu ul[role="menu"] li

Main menu sub-menu

#main-menu ul[role="menu"] li > ul

Sign in button

#btn_signin

Language selector

#main-languages

Individual languages

#main-languages a

Selected language

#main-languages a.lang-selected



Page title

#main-pagetitle

Page container

#main-content-container

Page content

#main-content

Page widgets

#main-content .heurist-widget



Footer

#page-footer

Hosting information

#main-host

Location of CSS files

<where to put CSS ? >

Making custom header scroll with the page

div.heurist-website{
    overflow-x: hidden;
    overflow-y: auto;
}
#main-content-container{
 position:relative !important;
 top:0px !important;
}
#main-header{
    position: relative !important;
}

Positioning elements

The main thing I can recall that was useful was to divide the site mentally into two kinds of page: “static” pages with project information, team members etc, and “dynamic” pages with facetted searches or other exploratory tools. The CMS generally speaking is set up to make the dynamic pages work without much trouble. It was funnily enough the “static” pages that required more fiddling, so they would scroll correctly and fill the screen properly.

 As a concrete example, on a static page you often want the width to be capped. It can be difficult to read text if it stretches right across the screen. By contrast, you often want the dynamic pages to fill the screen. Heurist sites often look their best on a big wide screen, where you can have the facetted search and a nice big map fully visible.

This division between ‘static’ and ‘dynamic’ is really about the layout of the page, rather than its hydration with data. For example, I would often use a custom report for the ‘Project Team’ page, so that new team members could simply be added to the Heurist database. Thus the page is ‘dynamic’ in data terms, but ‘static’ in layout.

 Another point was – I often found it difficult to position elements, because they had the wrong “position” attribute in the CSS. Basically there is a tricky set of rules about how ‘static’, ‘relative’ and ‘absolute’-positioned elements interact with each other. From memory, there were too many elements with position:absolute in the CMS template, and as a result I would often find it impossible to make parts of the page behave properly. You would set something as having “height:100%” in the web editor, and it would have no effect because it was a child of an absolutely positioned element, for example. As much as possible, absolute and relative positioning should be eliminated from the public websites, if you would like the editing panel to do what it is supposed to. The most common workaround was for people to give a fixed size in pixels to elements on the screen (e.g. width:500px). This has the obvious downside that the element will no longer scale with different devices.

Responsive design


Javascript


Domains and Redirects, Apache


Custom reports

{$person=$heurist->getRecord($f247.f15)} {* Person *}
{$person.f1} {*Family name *} 

{$rel_record = $heurist->getRecord($Relationship.recRelationID)}
{$src_info = $heurist->getRecord($rel_record.f1160)}
Source de l'Information: {$src_info.recTitle}

Getting info from relationship records

       {* Get infromation from the relationship record *}
                    {$rel_record = $heurist->getRecord($Relationship.recRelationID)}
         {$src_info = $heurist->getRecord($rel_record.f1160)}
                        Source de l'Information: {$src_info.recTitle}
                        Start Date: {$rel_record.f10}
                        End Date: {$rel_record.f11}

embedded-image-sznseod2.png

Embedding IIIF in reports

I've tested the method for displaying a viewer in a report and it works for an IIIF image. However, I couldn't get it to work for an IIIF manifest. I imagine there are some small changes to be made, could you tell me what they are? I need to display a manifest in the registry.tpl template.

There are 3 ways

  1. Via wrap function (preferred)

        {wrap var=$r.f1200_originalvalue dt="file" width="1200" height="800"}<br/>             
  2. Via direct manifest URL : 

        <iframe width=1200 height=800 src="https://heurist.huma-num.fr/heurist/hclient/widgets/viewers/miradorViewer.php?
        db=pret19_test&recID=&url={urldecode($r.f1200)}"></iframe>
  3. Via file obfuscation ID {$r.f1200_originalvalue[0].ulf_ObfuscatedFileID}

        <iframe width=1200 height=800 src="https://heurist.huma-num.fr/h6-alpha/hclient/widgets/viewers/miradorViewer.php?
        db=pret19_test&iiif={$r.f1200_originalvalue[0].ulf_ObfuscatedFileID}"></iframe>

Displaying images, PDFs, Carousels

We need PDFs to open inline. In Beyond1914 they are handled by a fancybox gallery plugin. There is quite a bit of custom code written by artem to get fancybox to accept and display pdfs with heurist url obfuscation. The code doesn’t seem to be in a custom report (in fact I don’t even see the page as a custom report) so I don’t really know how he did it.
PDFs in heurist are served with a http response header that indicates they should be downloaded (probably somewhere in a php file) : Content-Type: application/pdf
Content-Disposition: attachment; filename="filename.pdf"
In order to be opened, the http response header should be 
 Content-Type: application/pdf
 Content-Disposition: inline; filename="filename.pdf"

Making websites public

Pour rendre son site web consultable sans avoir besoin d'un login utilisateur, il suffit de marquer les enregistrements CMS_Home et CMS_Menu-Page visble au publique, 

embedded-image-ro8vg8v2.png

 ainsi que tout les enregistrements qu'on veut qu'il/elles puissent voir (pour ce dernier il suffit de faire une recherche des enregistrements à rendre publique et choisir la fonction sous Share):  

embedded-image-wmakvcxm.png

et ensuite choisir Public (Record is editable by peut-être n'importe quel personne ou groupe):

embedded-image-tf2liihb.png

Or directly in code <a href=”588”>Project Aims</a>

For example:

At the moment it triggers/listens fortwo event types ON_REC_SEARCHSTART and ON_REC_SELECT

Client side functions

A client-side function to get the databaseID: 

window.hWin.HAPI4.sysinfo.db_registeredid

Besides there are helpers to convert concept codes back and forth to/from local ids

$Db.getConceptID  and  $Db.getLocalID  (hclient/core/utils_dbs.js)

There are two parameters: [rty | dty |  trm] and [ID]

$Db.getConceptID('rty', 10)   returns 2-10   concept code for Person record type 

$Db. getLocalID  ('rty', '2-10')   returns 2  local id  for Person record type  

Multilingual websites

We specify the language with a parameter such as &weblang=es ; if this is omitted the website uses the first or only (default) language, whatever that is. If a data value has no version for the specified language, it uses the first (default) value.

This capability can be use to define alternative site title and menu entries / rollover labels (in fields Menu label/page name, and Menu rollover descriptions). 

The first vlue is the default, additional values should start with a 2 character language code (standard international list) and a version in this language. If you switch to the non-default language and the requested language is missing from the menu entries, the default language is used. 

embedded-image-cdhkavwc.png

embedded-image-uypej9pt.png
   

embedded-image-7hglcszw.png  

Website programming

Common class to init layout - HLayoutMgr

  1. Separate widgets/page configurations (json) and html content. 
  2. Store json in the separate field and it is common for all lang versions of page
  3. Separate html content allows:
  4.  Avoid issues with escaping/encoding
  5. More human friendly/readable format - can be edited directly
  6. Ability translate entire page
Web publication:
  1. While editing, Cms content can be accessed as usual via url [server]/heurist?db=[db-name]&website=[rec-id]&page=[rec-id]
  2. Published website: [server]/[db-name]/web/[rec-id]/[pagename].html

Pagename is unique per website, human friendly name of page. 

On publishing, heurist generates html pages in generated-website folder. These html are crawler enabled (have full page header, can be loaded independently)

Smarty reports… 

Cms localization:

  1. Widgets - dialog (via configuration widget dialog) with list of strings and html snippets that can be translated semi-auto
  2. Html content -auto translation with web service

Custom PHP plugins for Smarty

Custom plugins can be located in vendor/smarty/smarty/libs/plugins/ (from Nov 2024). The system adminstrator can place any number of php files into this folder (the ability to do so is not part of the Heurist web interface for security reasons). Sample code :

<?php
use Smarty\Smarty;
array_push($heurist_security_policy->allowed_modifiers, 'date_format_fr');
$smarty->registerPlugin(Smarty::PLUGIN_MODIFIER, 'date_format_fr', 'smarty_modifier_date_format_fr');
function smarty_modifier_date_format_fr($value, $date_format_fr=null){
       $datetime = new \DateTime($value);
        if(!$datetime){    return $value;  }
        if(!$date_format_fr){ $date_format_fr = "d-m-Y";}
        $newdatestring = $datetime->format($date_format_fr);
        return $newdatestring;
}
?>

Adding custom styles in memo fields

"formats": {
                    "Beleg": {"inline":"span", "classes": "Beleg", "styles": {"font-weight": "bold", "background-color": "#F2E3F9"}},
                    "Ergaenzung": {"inline":"span", "classes": "Ergaenzung", "styles": {"font-style": "italic", "color": "#808080"}},
                    "Glosse": {"inline":"span", "classes": "Glosse", "styles": {"text-decoration": "underline"}},
                    "BelegGlosse": {"inline":"span", "classes": "BelegGlosse", "styles": {"font-weight": "bold", "background-color": "#F2E3F9", "text-decoration": "underline"}}
                },
                "style_formats": [
                    {"title": "Beleg", "format": "Beleg"},
                    {"title": "Ergaenzung", "format": "Ergaenzung"},
                    {"title": "Glosse", "format": "Glosse"},
                    {"title": "Beleg Glosse", "format": "BelegGlosse"}
                ],
                "block_formats": [
                ]
 }

Debugging browser behaviour

Sometimes the application appears not to have changed something you know you have changed.

The first step is simply to delete browsing data (downloaded files only, NOT the cookies) and reload the page. 

If this does not work, try the following.

1) First prove what Chrome is actually executing

  1. DevTools → Network
  2. Tick Disable cache (works only while DevTools is open)
  3. Reload
  4. Click the request for editCMS_SelectElement.js

Look at:

embedded-image-66z6dtj4.png

If the response still shows old code, it’s caching upstream (CloudFlare Service Worker)

2) If it’s a Service Worker (very common)

In DevTools:

embedded-image-mklgpryd.png

Application → Service Workers: tick Update on reload
Application → Storage: click Clear site data (or “Clear storage”)

Then reload again with Network tab open.



09b: Domains, URLs, PIDs and custom website templates

Integrating a website or individual pages
with your existing domain

Heurist can generate a complete self-contained website - typically consisting of a header, footer, menu and web pages embedded in this structure - or it can create individual web pages which can be displayed as standalone pages or embedded in another webiste. How do you make these part of your existing domain and/or website?

The website and/or individual web pages will normally include content (including data and images) and functionality (including searches, reports and visualisations) dependant on Heurist's database engine, and must therefpre be generated by an instance of Heurist - they cannot live independently on a web server as they are generally far more than simply static html. The server can be one of the public services (eg. heuristref.net or Heurist.Huma-Num.fr) or your own private Heurist server.

The database you wish to publish must be on the corresponding server - for security and sustainability reasons, each instance of Heurist only has access to databases on its own server (or stack of servers). 

Simplified/clean URLs

The standard Heurist URLs use parameters at the end such as ?db=my_database&tpl=xyz. These are not particularly 'friendly' for web indexing and interoperability. They can therefore be replaced on the servers managed by the Heurist team (HeuristRef.net and Heurist.Huma-Num.fr) as shown below. The system adminstrators on other servers can configure their servers appropriately to use these URLs (se later). 

          web - website    Hml - xml output    View - record view   Tpl - smarty output

For server administrators

The URLs above use Apache rewrite rules. See the program code under Server scripts for the full set of rewrites.

RewriteRule ^/([A-Za-z0-9_]+)/(web|tpl|hml|view)/(.*)$ /h7-alpha/redirects/resolver.php
RewriteRule ^/h6-alpha/([A-Za-z0-9_]+)/(web|tpl|hml|view)/(.*)$ /h7-alpha/redirects/resolver.php

 If the DBname is followed by a word listed in the URLSubstitutions.txt file (see below) replace the words with the corresponding numbers and process the result:

Examples:

Contacts 157/150
Tentang  174/175?lang=fre
MED/{d+} /tpl/TEST1/[{"t":"5"},{"f:203":"{1}"},{"sortby":"t"}]
IND/{d+} /tpl/TEST1/{1}
test2/{d+} ?w=a&template=test2.tpl&mode=html&q=[{"t":"5"},{"f:203":"{1}"}]

As a keys we can use patterns with simplified tokens:

      "{d+}" or "{\d+}"      => "([0-9]+)"        One or more digits
      "{d*}" or "{\d*}"      => "([0-9]*)"        Zero or more digits
      "{w+}" or "{\w+}"      => "([A-Za-z0-9_]+)" One or more word characters
      "{s+}" or "{segment}"  => "([^/]+)"         One URL/path segment
      "{any}"                => "(.+)"            One or more of any character

Or standard regex

~^orders/([0-9]+)$~u

Examples:

     "orders/{d+}"     => "~^orders/([0-9]+)$~u"

     "users/{w+}"      => "~^users/([A-Za-z0-9_]+)$~u"

     "pages/{segment}" => "~^pages/([^/]+)$~u"

     "files/{any}"     => "~^files/(.+)$~u"

     "~^orders/([0-9]+)$~u" is returned unchanged.

In values use {nnn} to replace regex matching values

Here is a typical example of the substitutions file allowing the use of textual URLs for the user in place of the numeric URLs which the system recognises:

image.png

Self-contained website

Whatever the server which serves the database and website, you can make this appear as part of your domain. You can use an existing domain or purchase one quite cheaply if you don't already have one (typically $10 - 40 per year for .net and .org domains, but depends on the 'desirability' of the name - do a search for Cheap domains and shop around). Then ask the domain to point to your database. 

There are two ways of pointing to the database; with or without masking.

With masking you will not see the URL change as you navigate within the website. These are good examples: http://digitalharlem.org/ and https://c18librariesonline.org/?db=Libraries_Readers_Culture_18C_Atlantic&website. The disadvantages are that you can't bookmark or address a specific page in the website or easily obtain page use statistics.

Without masking the domain will get you to the website, but then you will see the full Heurist URL. There are some advantages in this, notably that you can bookmark or point people directly to the URL of a specific page in the website and monitor its use, rather always getting the home page. The developers of website often think it is important to show simplified domain-specific URLs, but we think that concern is probably overdone, once users arrive on a website they are mostly looking at the page, not the URL. 

Existing website

If you already have a website with a domain, there are a number of options for integrating Heurist web pages.

First, migrate your existing website to Heurist. In the long term this can save you a lot of trouble and probably money, as well as increase the chances of longer-term sustainability, because you don't have to maintain a separate web service or keep upgrading the website as the underlying CMS changes (since 2020 we have worked on migrating a number of CMS websites for researchers who do not have the technical support or can see the ongoing cost of migration). Heurist can, with a bit of work, reproduce most websites, although you may need to stick with your existing CMS if you have developed a complex and graphically rich site with specialised interactions, or use a lot of special functions such as ecommerce components.

Secondly, set up a link, or one of the menu items in your existing website, to switch the user over to your Heurist website, or to a single page, in order to display interactive searches and visualisations from the database. Within the Heurist website or page, provide a link to switch back to your existing website (which presumably contains higher level description of the project, and perhaps other databases). This can be made fairly seamless eg. by reproducing a narrow header bar (to maximise real estate) in the style of the main website and putting a Home icon or Back to website link in that header bar. You can also make several menu links to separate standalone Heurist web pages, each of which will navigate back to a specific location. You could also generate these as popups. If you use a domain with masking you can also just use a Back instruction to go back to the point you came from in the main website. You could also reproduce the menu structure of the main website and have the menu entries jump back to the appropriate place in the main website.

The third method - not our preference - is to create one or more standalone Heurist web pages and embed them directly in the existing website using iframes. The problem lies in maximising the space available for the interactive Heurist page and avoiding double scrollbars. It can be done, but will require an understanding of divs, CSS and Javascript if you don't want it popping up in a too-small fixed size box.

Assistance

We (the Heurist development team / Heurist Network) are generally happy to help set up websites, but as this tends to be project-specific rather than general development of benefit to the whole community, we can only really afford to do this, beyond simple advice, for projects which help sponsor Heurist development. 


Custom default website layouts

Custom website layouts

Heurist defines a default style for websites it generates, which can be overriden to some degree with stylesheets within each website. However the owner of a Heurist server may want to define standard headers, footers and styles for websites run on their server to conform, for example, to corporate branding.

A server can be set up with one or more custom website layouts which determine the layout of the header and footer section of the website, and potentially of behaviours and styling within the content.

One layout may (optionally) be selected as the default which is used every time a new site is created, but the creator of the website can also specify a different layout among those defined.

embedded-image-pvajbyck.png

Website layout is controlled by files in hclient/widgets/cms. This contains a default template cmsTemplate.php which contains instructions on how to develop further templates.

Default layout

To set the default layout of new websites created on the server, place this file or an edited version of this file in the parent directory of the Heurist codebase, normally /var/www/html/HEURIST.

The location of the template files can also be set in heuristConfig.php, defined by $default_CMS_Template_Path 

Selecting a custom layout

If there are additional template files available, you can apply one of them to an individual website by setting the name in the Website template field of the CMS Homepage record (accessed through Publish > Website header / layout)

embedded-image-lv82o3ge.png

 The template name can be specified without a path, in which case Heurist looks for it in the parent directory of the Heurist codebase (normally /var/www/html/HEURIST) or the directory specified by $default_CMS_Template_Path, or it can be specified with a path relative to the codebase as shown above.

The template file is a .php file but the extension can be ommitted.

Creating a template

To create a Heurist CMS template, first look at the example in hclient/widgets/cms/templates/cmsTemplate.php

This is the standard template for Heurist websites, as used in this help system. It can be modified by addition and replacement to create the template you require.

The template requires certain elements:

1.    a php include in the <head> section:   include $websiteScriptAndStyles_php;  

2.    Definition of html elements with the following ids:  main-title, main-logo, main-logo-alt.
 The content of these elements can be replaced with values defined in the CMS Homepage record.

3.    Definition of an html element with id:  main-content.  It will be populated with content based on the menu item selected.

4.    For Heurist widget menu

        <div id="main-menu" class="mceNonEditable header-element" style="position:absolute;
           top:110px;width:100%;min-height:40px;border:2px none yellow;color:black;font-size:1.1em;"
           data-heurist-app-id="heurist_Navigation" data-generated="1">
           <?php print $page_header_menu; ?>
         </div>

5.    Optional: if using bootstrap as part eg. of a corporate website style, you may need to add the following for the bootstrap menu:

<?php 
 if($mainmenu_content!=null){print $mainmenu_content;} //output bootstrap menu
 ?>

3) Upload files for records to the different than HEURIST_FILESTORE folder. 

To define other that HEURIST_FILESTORE folder, system admin has to define

$defaultRootFileUploadPath and $defaultRootFileUploadURL parameters in heuristConfigIni.php

1) website template that uses UHH code of style (using insert.js)

There is cmsTemplate_HamburgUniversity.php. It uses https://www.uni-hamburg.de/onTEAM/inc/dom/v43/insert.js

User has to define the name of this template in “Custom website template file” field of main menu record.