How to use the use_adv_search parameter in the WebApp include tag, along with a URL parameters, to search for within specific fields of an item.

Prerequisites

• You have created a WebApp

• You have added a WebApp List View to a Page

Introduction

Advanced search allows you to use AND or OR logic to filter WebApp items by specific fields.

If you are looking to search for WebApp items which match any of your search terms in any of their fields using OR logic, see Searching - Keyword.

Steps

1. Identify the IDs of the Custom Fields that you want to filter by

2. Add the use_adv_search parameter to WebApp include tag

3. Setting the match type for String fields

4. Setting the match type for Array fields

5. Test by adding a URL query parameter

6. Build a form to allow Users to enter a search query

Step 1 - Identify the IDs of the Custom Fields that you want to filter by

In the database, each field has an ID that is different from their user-friendly name. In order to use the advanced search, you will need to know the ID of the field.

You can learn more about why we use Custom Field IDs and how to find the one you need for a WebApp or Module here: Custom Field IDs

Once you've checked that Article and found the ID of the Custom Field you need, you can move on to Step 2.

Step 2 - Add the use_adv_search parameter to WebApp include tag

{%- include 'webapp'
    id: '1'
    layout: 'my_layout'
    per_page: '10'
    use_adv_search: 'true' 
-%}

Step 3 - Setting the match type for String fields

Let's work with a field ID of webapp_field_1_1. You have 2 options for setting the match type when searching:

• AND (default) - The search will return exact matches for the search term it receives

• OR - The search will return results where there is a match on any of the search terms it receives. These terms are comma separated.

  • For example, if we have webapp_field_1_1=content 1,content 2&webapp_field_1_1_match_type=OR then we will be looking for items where webapp_field_1_1 is either equal to 'content 1' OR 'content 2'.

You can find what type your fields are here.

Step 4 - Setting the match type for Array fields

Let's work with a field ID of webapp_field_1_2. You have 2 options for setting the match type when searching:

• AND (default) - The search will return items that contain all search terms. These terms are comma separated.

  • For example, if we have webapp_field_1_2=option1,option2&webapp_field_1_2_match_type=AND then we will be looking for items where webapp_field_1_2 contains both 'option1' AND 'option2'.

• OR - The search will return results where there is a match on any of the search values it receives. These terms are comma separated.

  • For example, if we have webapp_field_1_2=option1,option2&webapp_field_1_2_match_type=OR then we will be looking for items where webapp_field_1_2 contains either 'option1' OR 'option2'.

You can find what type your fields are here.

Step 5 - Test by adding a URL query parameter

Now use_adv_search has been added, Siteglide is watching the query parameters for any parameters with a key including "field_". It will use these to carry out the search when the page is loaded, so it can display the WebApp items which match.

To see how the filter works, start by manually adding parameters to the URL in your browser. Remember the example Custom Field ID and keyword is unlikely to be found in your unique WebApp, so choose something you know is there! You should see your WebApp's results adjust as only items which match are returned.

Example 1

https://my-website.staging.oregon.platform-os.com/webapp-list?webapp_field_1_1=my%20search%20terms

Example 2

https://my-website.staging.oregon.platform-os.com/webapp-list?webapp_field_1_2=option1,option2&webapp_field_1_2_match_type=OR

Step 6 - Build a form to allow Users to enter a search query

You can now build an input form to pass the user's chosen keywords as parameters to the URL.

Installation

Our GeoJSON update for WebApps will work with both newly created WebApps, and WebApps that have been updated after the release of this update.

To apply the update to an existing WebApp, simply go to the WebApp Builder view, and click 'Save'.

Editing the WebApp item

Webapp items have 2 new fields by default:

• location - GeoJSON - Stores the location value of your item as coordinates - [long, lat]

• address - Text - Stores the human-readable address value of your item

To set these values in Siteglide you will see the new 'Location' tab on the WebApp item edit view. Here you have 2 choices:

1. Search for an address and then select it from the results dropdown - Recommended

2. Manually enter the Address and Longitude/Latitude values for your item

Querying the data

Our new Location Search feature relies on 2 URL parameters to work:

1. longlat - LongLat - The coordinate value of the center point for the search - long,lat

2. distance - Int - The number of kilometres from the center point

Example - /map?longlat=-1.2660643,51.3926564&distance=18

To display results from these parameters you will need the new use_location_search parameter on your WebApp include:

use_location_search - 'true' or 'false' - default: 'false'

Example -

_Note - Location Search `(use_location_search) and Text Search(use_search`) will not work together at the same time_

Example

Example code to search a WebApp by location, and output the results on a map or in a list.

Introduction

In this example we'll show you how to add a location search to a Page, and then output the results of that search both in a list and on a map. Items will display in the result set when they are within the radius of a chosen location. One example of how you can use this is as a Store Locator for a franchise of Shops.

1 - Add an HTML Form and JavaScript to take User input to decide starting position and search radius

Two different options are provided in this example:

Current location (using browser default functionality) and desired search radius

Add HTML and JavaScript

:::codeblocktabs

:::

2 - Output the results on the Page in a simple list

Use a Layout of your choice.

3 - Output the results on a map

This relies on there being a layout named 'json'. See the contents of 'json' in the 2nd block of code.

Add HTML + Liquid

The Liquid makes sure the map is only outputted after the Page has been refreshed by the JavaScript and the correct parameters are available in the URL for filtering the results.

Add JavaScript

The following function is triggered by the script from step 1, only after it has finished loading- this occurs because the function's name is referenced in the URL parameter fetching the Script. The code must be placed above the <script> tag from step 1.

Layout 'json':

Full example

WebApp - Front End Submit Forms - Update

Introduction

If a logged-in visitor to your Site has submitted a WebApp Item, they can now edit it too.

The WebApp Creator

Most WebApps, including those created by the Admin and those created by visitors who are not logged in will not store the ID of a creator.

However, any WebApps created Front-End by a logged in User will store their creator's ID in the creator field.

Filtering a WebApp List by creator

Finding WebApp Items created by the current user

Finding WebApp Items created by any specific user

In this example we create a variable by hard-coding a specific User ID.

Outputting information about the creator in the WebApp Layout

You can now access the following fields inside a WebApp Layout:

• {{this.creator.id}}

• {{this.creator.name}}

• {{this.creator.first_name}}

• {{this.creator.last_name}}

• {{this.creator.created_at}}

Viewing the Edit Form and Permissions

Under default settings, only a WebApp owner can see and also submit the edit form. A WebApp gets an owner when a user is logged in and submits the original WebApp create form. Their User ID is stored in the user_id field against the webapp.

It is possible to modify the owner of a WebApp in the Siteglide Admin.

It is also possible to set the "Anyone can edit" setting to true in the Siteglide admin in the "View Table" area for that WebApp.

Setting this to true means that default edit protections are removed for that WebApp on the front-end. You will then be responsible for writing your own Liquid code to wrap around the form if you wish to set custom Secure Zone permissions.

Find other WebApp items with the same creator

You could of course combine both of these features- creating a link to the same page including the creator_id as a query parameter and then filtering by that ID using context.params to fetch the ID from the URL.

Syntax for the Edit Form

Including the Form inside a WebApp Layout

Unlike the "Add" Form, the Front End WebApp Edit Form must be linked to the specific WebApp Item it will Edit. This means you can only output the Form inside a WebApp Detail or List Layout file.

To include the Edit Form inside a WebApp Layout, add the Liquid tag:

Parameters:

• layout - Optional - Choose the name of your Layout file

Developing the Form Layout

The Edit Form will work if you use the same Layout as you used for your add Form.

However, you may wish to use an alternative Layout so you can add some additional features.

Dynamic Fields from the WebApp

As you're including the Edit Form inside a WebApp Item, you have access to the WebApp fields that are inherited from the WebApp Layout.

One example might be adding a Title to the Form which dynamically references the WebApp Item: <h3>Edit {{this.name}}</h3>

Another example might be displaying the creator's name: <h4>By {[this.creator.name}}</h4>

Pre-filling values

In a Form Layout, we use the form_builder variable to dynamically add the correct name Attribute to inputs. You can use this to output the pre-filled value; instead of the name property, output the value property.

For this example WebApp field:

...you can use the name field and replace .name with .value to add a value attribute:

Introduction

When your Users have created WebApp items front-end, you can now give them the option to delete the items they no longer need.

A User will only be able to delete a WebApp item they own. Generally a User will own a WebApp item they've already created, but it's now possible to change WebApp ownership in Admin. You can use Liquid to further control when the button is presented to Users.

This changes if you turn on "anyone can edit" for the WebApp in the Siteglide Admin. Then, you are responsible for adding your own custom Liquid logic to control access to the button.

You can use optionally use JavaScript to change the behaviour when the button is successful, or when it errors.

Syntax

Including the button

To include the delete button, add the following syntax inside a WebApp Layout of your choice

Nesting this inside a WebApp Layout allows it to easily pick up the ID of the current WebApp item.

Security

We recommend wrapping the Layout in the following Liquid to make sure the button is only visible to those Users who have the minimum permission needed to successfully delete the current item:

Note that on the backend we will be running an additional check that the WebApp ID passed through is owned by the currently logged in User- so it won't be possible for malicious Users to delete items they don't own by passing through different IDs.

Developing the Layout

Including the button in Liquid as above will require a small Layout- which allows you to customise the way the button looks and functions.

File Structure

Layouts for this button are stored at the following path: layouts/webapp_components/webapp_delete/my_layout.liquid

Calling the Main JavaScript Function

To make the delete button functional, you need to run the s_owned_webapp_delete() function on an event (usually a click event).

You should pass the following arguments:

Customising the JavaScript

You can add custom JavaScript functions to customise the way the button behaves on success and failure. Examples are included on the default layout.

If you don't provide custom functions, the default behaviour will be to:

• On success, show a success message alert and reload the Page.

• On failure, show an error message alert.

Here's an example of custom functions defined and then passed into the 3rd and 4th arguments in the function:

Additionally, you could add in custom behaviour before the main delete function runs, for example to provide a confirmation message to Users to check they really want to delete the WebApp item:

How to use the use_search parameter in the WebApp include tag, along with a keyword parameter in the URL, to search for items.

Prerequisites

• You have

• You have

Introduction

This is the easiest way to allow users to search for WebApp items on the Front End.

You can use a string of words to search all fields in the WebApp. Using OR logic, Siteglide will return all results where at least one keyword matches in one of the item's fields. The number of results will still be limited by pagination.

If you want to control which fields are searched, see .

Steps

1. Add the use_search parameter to WebApp include tag

2. Test by adding a URL query parameter

3. Build a form to allow Users to enter a search query

Step 1 - Add the use_search parameter to WebApp include tag

Step 2 - Test by adding a URL query parameter

Since you have added the use_search parameter to the Liquid, Siteglide is now checking the URL for the keyword parameter.

It will use this parameter's value to search all your WebApp's fields and return all items where at least one of keyword's words matches at least one word in the WebApp's fields.

With your site open in your browser, add the parameter to the URL to test this. Remember the example keyword is unlikely to be found in your unique WebApp, so choose something you know is there! You should see your WebApp's results adjust as only items which match are returned:

https://my-website.staging.oregon.platform-os.com/webapp-list?keyword=my%20search%20terms

Step 3 - Build a form to allow Users to enter a search query

You can now build an input form to pass the user's chosen keywords as parameters to the URL.

WebApp - Front End Submit Forms - Create

When you make a new WebApp, a front-end form file is automatically generated within your WebApp, in a folder called form. It automatically contains all fields from your WebApp. You can view this folder using Code Editor, it is next to the detail and list folders for your WebApp.

Syntax

Output your WebApp form on a page:

{%- include 'webapp_form', id: 'custom_webapp_1' -%}

Toolbox has support for WebApp input forms, and the following options will be given in the modal, or you can set them yourself:

• enabled - default is false - Boolean - Determines if items are auto-enabled or not

• expiry_date - default is never expires - Timestamp - When the new item will expire

• release_date - default is as soon as the form is submitted - Timestamp - When the new item will be released

• upload_dir - String - default is documents/form_uploads/webapp_1/ Where uploaded files will be stored. Must follow this format - 'folder/optional_folder/'

Standard Fields

Some fields are required for the form to be able to set up the WebApp items correctly. These fields are for 'enabled', 'expiry_date', 'release_date', 'upload_dir', and 'slug'. They stay the same each form, and don't have a WebApp specific ID attached to them.

<input class="form-control" 
       name="{{ form_builder.fields.properties.enabled.name }}" 
       value="{{_enabled}}" 
       type="hidden"
/>
<input class="form-control" 
       name="{{ form_builder.fields.properties.expiry_date.name }}" 
       value="{{_expiry_date}}" 
       type="hidden"
/>
<input class="form-control" 
       name="{{ form_builder.fields.properties.release_date.name }}" 
       value="{{_release_date}}" 
       type="hidden"
/>
<input id="s_redirect" 
       value="/home" 
       type="hidden"
/>
<input class="form-control upload_dir" 
       value="{{_upload_dir}}" 
       type="hidden"
/>
<input class="form-control" 
       name="{{ form_builder.fields.properties.slug.name }}" 
       type="hidden"
/>

All forms should be wrapped in a Liquid form tag: `

` All forms need a submission button:`Submit`

Category Field (optional)

Example 1

This example can be used for a WebApp Submit form that is displayed within a the layout of another WebApp or Module.

<input class="form-control" 
  name="{{ form_builder.fields.properties.category_array.name }}" 
  value="{{this.category_array[0]}}" 
  type="hidden"
/>

this.category_array[0] - finds the first category the current item is categorised to and can be changed to be a full array, or specific category ID.

Example 2

This example can be used on pages other than WebApp and Module layouts.

<input class="form-control" 
       name="{{ form_builder.fields.properties.category_array.name }}" 
       value="123456" 
       type="hidden"
/>

123456 - replace with the ID of a category of your choice.

Location Field (optional)

You can submit a Location value for a WebApp item as shown in the following example:

<input class="form-control" 
  name="{{ form_builder.fields.properties.location.name }}" 
  value='{"type": "Point","coordinates": [-0.10045,51.49495]}' 
  type="hidden"
/>

The value should be a stringified JSON object.