Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation update #87

Open
wants to merge 3 commits into
base: dev
Choose a base branch
from
Open

Documentation update #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0817d0d
Update site-wide nav search documentation
techgique Feb 11, 2022
149b33c
Update Mukurtu customization docs
techgique Feb 28, 2022
d6146ae
added some customizations for newest update
Mar 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 151 additions & 55 deletions docs/customizations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,20 @@
- [New Content](#new-content)
- [All Existing Nodes](#all-existing-nodes)
- [Digital Heritage Browse Facets](#digital-heritage-browse-facets)
- [Customize Browse Facets via Admin UI](#customize-browse-facets-via-admin-ui)
- [Completely Disable Search Facets](#completely-disable-search-facets)
- [Disable on This Page Only](#disable-on-this-page-only)
- [Index a Field for Faceting](#index-a-field-for-faceting)
- [Enable a Facet Field](#enable-a-facet-field)
- [Add Facet Field to Page](#add-facet-field-to-page)
- [Customize Browse Facets via Admin UI](#customize-browse-facets-via-admin-ui)
- [Deprecated Facet Customization](#deprecated-facet-customization)
- [Completely Disable Search Facets](#completely-disable-search-facets)
- [Disable on This Page Only](#disable-on-this-page-only)
- [Add Facet Field to Page](#add-facet-field-to-page)
- [Digital Heritage Preview Displays](#digital-heritage-preview-displays)
- [Digital Heritage Full Display](#digital-heritage-full-display)
- [Allowed HTML Elements](#allowed-html-elements)
- [Add Customizable Footer](#add-customizable-footer)
- [Image Download Links](#image-download-links)
- [Add Site-wide Search](#add-site-wide-search)
- [Customize home page contents](#customize-home-page-contents)

## Account Registration
Admin Menu > Configuration > People > Account settings
Expand Down Expand Up @@ -61,6 +63,8 @@ Admin menu > Content > Comments.

## Digital Heritage Browse Facets

A brief outline of the customizations we have made:

- Remove Collection
- Remove Community
- Remove Keywords
Expand All @@ -74,6 +78,41 @@ Admin menu > Content > Comments.
facet by "Format", not "Format » Name"
- Type

The best way to handle this recently was to:
- Add the Tribal Affiliation, Name, and Name Format fields to the index
for faceting and reindex all items
- Then customize the browse facets via the Admin UI

### Index a Field for Faceting
Admin Menu > Configuration > Search and metadata > Search API

Click the drop-down arrow right of the Edit button for "Default node index" and
click Fields

Check the box next to the field with which you'd like to index, scroll to the
bottom, and click Save Configuration

Click the link to "re-index" in the confirmation message

Click "Index now" and wait while items reindex

Click the "Facets" tab at the top if you'd like to continue on to enable as a
facet field

### Enable a Facet Field
Admin Menu > Configuration > Search and metadata > Search API

Click the drop-down arrow right of the Edit button for "Default node index" and
click Facets

Check the box next to the field with which you'd like to facet, scroll to the
bottom, and click Save Configuration

Scroll to the facet you just enabled and click "Configure display"
- Set "Display widget" select to "Links with checkboxes"
- Scroll down to Global Settings > Hard limit and set to "No limit"
- Click Save configuration

### Customize Browse Facets via Admin UI
Sign in, click "Browse" (redirects to `/digital-heritage` path), click gear in
far upper right of page content, click "Edit Panel".
Expand All @@ -86,7 +125,9 @@ the gears right of the facets' names to customize labels, remove, etc. Click
Changes via the admin UI here will override changes to the file
`ma_digitalheritage.pages_default.inc` in stricken documentation below.

### Completely Disable Search Facets
### Deprecated Facet Customization

#### Completely Disable Search Facets
Admin Menu > Configuration > Search and metadata > Search API

Click the drop-down arrow right of the Edit button for "Default node index" and
Expand All @@ -96,7 +137,7 @@ One may uncheck the boxes next to facets to be completely disabled site-wide.
Guessing this is not the approach we want to take due to possibly unforseen
consequences elsewhere on the site.

### Disable on This Page Only
#### Disable on This Page Only
<s>
This appears to not be customizable via the admin UI.

Expand All @@ -112,37 +153,7 @@ Note a copy of a fully customized file is included in this repository in

See [Customize Browse Facets via Admin UI](#customize-browse-facets-via-admin-ui)

### Index a Field for Faceting
Admin Menu > Configuration > Search and metadata > Search API

Click the drop-down arrow right of the Edit button for "Default node index" and
click Fields

Check the box next to the field with which you'd like to index, scroll to the
bottom, and click Save Configuration

Click the link to "re-index" in the confirmation message

Click "Index now" and wait while items reindex

Click the "Facets" tab at the top if you'd like to continue on to enable as a
facet field

### Enable a Facet Field
Admin Menu > Configuration > Search and metadata > Search API

Click the drop-down arrow right of the Edit button for "Default node index" and
click Facets

Check the box next to the field with which you'd like to facet, scroll to the
bottom, and click Save Configuration

Scroll to the facet you just enabled and click "Configure display"
- Set "Display widget" select to "Links with checkboxes"
- Scroll down to Global Settings > Hard limit and set to "No limit"
- Click Save configuration

### Add Facet Field to Page
#### Add Facet Field to Page
<s>
Edit `(path to site)/master/sites/all/modules/custom/features/ma_digitalheritage/ma_digitalheritage.pages_default.inc`

Expand All @@ -159,8 +170,6 @@ Save the changes to the file and your new filter facet should appear on the
Digital Heritage browse page
</s>

See [Customize Browse Facets via Admin UI](#customize-browse-facets-via-admin-ui)

## Digital Heritage Preview Displays

These are the display formats we're customizing:
Expand All @@ -170,10 +179,13 @@ These are the display formats we're customizing:
- Teaser
- Hover over an item on a page such as `/tags/parents-and-siblings`, click the
gear, click "Manage display"
- Alternatively go to Admin > Structure > Content Types > Digital Heritage >
Manage display and click "Search result highlighting input" or "Teaser"

with the following field settings:
- Disable Mukurtu Mobile Sync even though field may say it is hidden
- Topic (renamed from Category)
- Click gear to right to set label, click Update
- Click gear to right to set label, uncheck "Link to term", click Update
- Summary
- Tribe(s) (renamed from Tribal Affiliation)
- Label: Inline
Expand All @@ -192,57 +204,64 @@ Admin UI Screenshots:
- [Teaser display config](images/digital-heritage-teaser-display-config.png)

## Digital Heritage Full Display
Browse to Digital Heritage item on the Browse page and click to it

Click the Item Menu, then click Manage display
Browse to Digital Heritage item on the Browse page and click to view it. Click
the Item Menu, then click Manage display. Alternatively go to Admin > Structure
> Content Types > Digital Heritage > Manage display and click "Full display".

Display customizations:
- Information below item images:
- Summary
- Description
- Image Identifier (renamed from Identifier)
- Citation
- Identifier (renamed from Image Identifier)
- Citation--make sure this is "Default" rather than "Services Raw" format
- Information in right-hand panel:
- Original Date
- Topic (renamed from Category)
- Tribe(s) (renamed from Tribal Affiliation)
- Tribe(s) (renamed from Tribal Affiliation)--make sure this is "Separated" rather than "Rendered Entity" format
- People
- Places (renamed from Location Description]
- Places (renamed from Location Description)
- Format
- Type
- Disabled:
- Author
- Community
- Protocol

Had to increase PHP config `max_input_vars` from 1000 for customizing "Category"
display as "Topic". Set the value to 2048 and then the change succeeded
- Keywords
- Language

Admin UI Screenshot:
- [Full content display
config](images/digital-heritage-full-content-display-config.png)

## Allowed HTML Elements
The allowed HTML elements within user-written and imported content may be
customized.
customized. For now, we've only added `<hr>` to the "Full HTML" list of allowed
tags.

Admin Menu > Configuration > Content authoring > Text formats

Click "configure" to the right of "Filtered HTML" or "Full HTML"
Click "configure" to the right of "Full HTML"

Scroll down to "Allowed HTML tags" and modify the space-separated list as
desired.

Click "Save configuration"

## Add Customizable Footer
Admin UI > Structure > Blocks
Go to Admin > Structure > Blocks

**Delete and recreate Custom Site Footer**

After the Mukurtu 3.0 update, the "Site custom footer" block had to deleted as
it wasn't providing an input for HTML. After deleting, click "Add box" on
Structure > Blocks page and set name and options as below.

Change "Custom site footer" to display in the Footer region

Click "configure" to the right
- Set the desired "Text format" to allow the HTML elements you'd like to use
- Enter the content you'd like to display in the footer
- Set the desired "Text format" to Full HTML
- Enter the content you'd like to display in the footer. Can be copied from
another instance of the site
- Click "Advanced Settings" and enter any custom CSS classes you'd like applied
- Click "Save block"

Expand Down Expand Up @@ -283,6 +302,7 @@ Started Guide".

Scroll down and click "Save blocks". Now close the admin UI.

### Mukurtu versions except 2.1.8
Mouse over the search form near the top of the page and click the gear in the
upper right corner. Click "Edit view".

Expand All @@ -297,3 +317,79 @@ Click "Save".

Searches should know work from anywhere on the site

### Mukurtu 2.1.8
Mukurtu wasn't able to handle the customization of the search form itself
via the Admin Menu and had to be handled via the code for this view.

If the view has been customized via the Admin Menu in the past, it should be
reverted so the view is loaded from the code rather than the database (in table
`views_display`).

Admin Menu > Structure > Views

Scroll down to Digital Heritage Browse. If underneath the title is the text
"Database overriding code' rather than "In code", one must click the arrow right
of the "Edit" button on the right side of the row. Then click "Revert".

Now we must modify the file controlling the display of this view, `(path to
site)/master/sites/all/modules/custom/features/ma_digitalheritage/ma_digitalheritage.views_default.inc`.
An example version of this file resides at
[/files/ma_digitalheritage_views_default_views.inc](../files/ma_digitalheritage_views_default_views.inc).
The section of code related to the view we're using for site-wide search begins
on line 215 for the view `digital_heritage_grid_list`. The specific "display"
which needs customization begins on line 307. This view just needs a "path"
display option added.

```php
/* Display: All */
$handler = $view->new_display('panel_pane', 'All', 'all');
$handler->display->display_options['exposed_block'] = TRUE;
$handler->display->display_options['inherit_panels_path'] = '1';
/* Custom site-wide nav search fix */
$handler->display->display_options['path'] = '/digital-heritage';
/* /Custom site-wide nav search fix */
```

This should make the site-wide nav search function as before.

For potential future troubleshooting, the settings that previously worked via
the Admin Menu were attempted here but these didn't even work when hardcoded.
Adding the `link_display` option with the value `custom_url` to the "default
Master" display, changing the `digital_heritage_grid_list` display's
`inherit_panels_path` option to `0`, and adding a `link_url` option with the
value `/digital-heritage` were the settings tried.

```php
/* Display: Master */
$handler = $view->new_display('default', 'Master', 'default');
$handler->display->display_options['css_class'] = 'browse-view';
/* Custom site-wide nav search fix */
// $handler->display->display_options['link_display'] = 'custom_url';
/* /Custom site-wide nav search fix */

...

/* Display: All */
$handler = $view->new_display('panel_pane', 'All', 'all');
$handler->display->display_options['exposed_block'] = TRUE;
/* Custom site-wide nav search fix */
$handler->display->display_options['inherit_panels_path'] = '0';
$handler->display->display_options['link_url'] = '/digital-heritage';
/* /Custom site-wide nav search fix */
```

## Customize home page contents
- Reference: https://mukurtu.org/support/configuring-front-page-content-blocks/
- View Admin > Structure > Context; Click `mukurtu_theme-front_page` > Edit
- Click Theme and check the box next to the Genoa theme
- Click Blocks
- Click the x's next to existing content in the middle column
- In the right column click MUKURTU_THEME_BLOCKS and check Mukurtu Theme Frontpage Hero Image, then click "+ Add" to the right of "Top Bar"
- In the right column click System and check Main page content, then click "+ Add" to the right of "Content"
- In the right column click View: Browse Digital Heritage by Category, then click "+ Add" to the right of "Content"
- Click Save
- On home page, near bottom
- Click gear at top right of category boxes
- Change Title to "Browse by Topic" (rather than "Browse by Category")
- Click Save

Loading