Configuring the Search component

The Search component has a number of configuration capabilities which can be set either in the URL directly, or within the dataset element of the HTML page added to the parent page where the component is to be used.

For example, the sessionId can be specified:

• In the URL, for example:

http://my-url/my-page?sessionId=THE_SESSION_ID

• In the dataset, for example:

<search-element data-session-id="THE_SESSION_ID"></search-element>

info

The capital letter properties require a - in the dataset configuration and the initial data prefix.

Thus, for example: sessionId becomes data-session-id, searchText becomes data-search-text, etc.

Search component configuration properties

Mandatory properties

Property	Description	Values	Example
servicesUrl	Defines a URL of the D1 server location. It is used for calling APIs on the server.	A unique URL value.	data-services-url="https://yoururl/services/"
sessionId	Specifies a login token generated by the D1 server.	A unique ID.	data-session-id= "20230801113256199-0e7ceb3a-769e-47f4-9fd2-3935367d74f9"
componentPrefix	Configures a prefix in the URL that points to a location where this UI component is deployed. It is required to correctly show images and icons used within the search components. It points to the prefix within the URL, between the services and the actual component folder.	A value of the prefix within the URL that is between the services and the actual component folder. The complete URL of internal images and icons will be data-services-url + data-component-prefix + actual image url	data-component-prefix="d1-ui-search/" The complete URL of the internal images could be: https://yoururl/services/d1-ui-search/image.png
contentType	Sets the default content type which will have its properties displayed in the By Properties search, and also within the Ordered By UI element.	The value is by default set to tribefire.adx.model.content.Content which is the base Content. This value can be overwritten by users when they select an entry in the Content Type field.	data-content-type="my.model.Invoice"
searchName	The mandatory display name of this search. This name is used when showing the search results in the Hit list. All tabs with search results have this property configured for them.	Unique text value.	data-search-name="My Saved Search"

Optional properties

Common search settings

Property	Description	Values	Example
accessId repositoryName	Sets the repository name from which data is to be retrieved. If the repositoryName is set, then it is used. The accessId should be used only when the repositoryName is not set. If none of the properties is set, then the default name is used as the repository name.	A unique alphanumeric value.	data-repository-name="test"
searchType	Configures search type.	ByCondition (the default) ByProperties.	data-search-type="ByCondition"
pageSizes	Configures values for the Results per Page list. By default, end users can specify the results per page by selecting one of the default values in a combo box (10, 20, 50, 100 and 200).	Numeric values separated by a comma.	data-page-sizes="10,50,100"
pageSize	Configures the default value specified within the Results per Page field. If this configuration parameter is not specified, then the first value configured within the pageSizes configuration is used.	A numeric value.	data-page-size="100"
childrenPageSize	Configures the page size to be used when loading folder contents (children data of a folder). When not set, the default value is used.	10 (default)	data-children-page-size="5"
locale	Sets the display language for the Search component. The set of available languages is the same as the one for the Web Reader.	En (default)	data-locale=de
showContentType	When a repository includes some custom types, they are displayed in the Content Type field next to the Entry Type field (it is the default behavior). When false is specified, then the Content Type field and the value configured for contentType are not shown.	true (default) false	data-show-content-type="false"
useNewTab	Specifies whether to always open search results in a new tab.	true(default) false	data-use-new-tab="true"
showUi	Specifies whether to display configuration with predefined values. In certain cases, the customers may want to have some searches with some predefined values, and not allowing the users to change whatsoever configuration of it. In those cases, they can have this showUi set to false. When set to false, then no UI component is shown. It defaults to true.	true false	data-show-ui="false"
showAdvancedSearch	Configures whether the Advanced Search button is displayed. The Advanced search displays a section where users can configure the Results per Page and the Order by Properties.	true (default) false	data-show-advanced-search="false"
showResultsPerPage	Сonfigures whether the Results per Page field is shown within the Advanced Search.	true (default) false	data-show-results-per-page="false"
showOrderedBy	Configures whether the Ordered By UI is shown within the Advanced Search.	true (default) false	data-show-ordered-by="false"
componentId	Defines a source component of an event. When sending events, this configuration is used as the componentSourceId in that event. This way, listeners can identify a source component of a received event. When no configuration is defined, the default value is search-component.	A unique ID of a source component.	data-component-id="my-saved-search"
targetComponentId	Defines a target component of an event. When sending events, you want to specify that a single component should react to it, you can configure the component target for the event.	A unique ID of a target component.	data-target-component-id="my-hitlist"

Search type specific settings

Property	Search type	Description	Values	Example
searchProperties	Search by properties	Specifies the properties list to be displayed in the UI. When the list is not specified by the configuration, all properties of the current type are displayed (used in the Content Type combo box), or properties configured via the contentType configuration when the combo box is not displayed.	A comma-separated list of property names.	data-search-properties="active, createdAt,createdBy"
entryType	Search by condition	Sets the default value of the entryType.	Content(default) Folder Content and Folder	data-entry-type="Folder"
showEntryType	Search by condition Search by properties	Specifies whether to display the Entry Type field.	true (default) false	data-show-entry-type="false"
includeProperties	Search by properties	Specifies a list of property names to be included in the search results.	Comma-separated text values.	data-include-properties="name,active, createdAt,number,value,id,owner, resource,mimeType"
excludeProperties	Search by properties	Specifies a list of property names to be excluded from the search results.	Comma-separated text values.	data-exclude-properties="resource,owner"
autoExclude	Search by properties	Indicates whether some predefined properties will be automatically excluded. This can be overridden for specific properties by explicitly mentioning them in the includeProperties list.	true false	data-auto-exclude="false"
includeVersions	Search by properties	Specifies whether to display all versions of a content or not. If true is defined, an entry for every version of the content will be displayed.	true false	data-include-versions="false"
searchText	Search by condition	Configures initial text displayed in the search field.	String value.	data-search-text="*"
enableSaveSearchByProperties	Search by properties	Specifies whether to save the current values filled into the properties to the cookies after performing a search. If true is defined (which is the default value), then the current values are saved and later retrieved automatically from the cookies.	true false	data-enable-save-search-by-properties="false"
allowChangeSaveSearchByPropertiesConfig	Search by properties	Specifies whether the users can manually disable the saving of the current values filled into the properties. If true is defined (which is the default value), a checkbox is presented to the users, asking them if they want to save the current state or not.	true false	data-allow-change-save-search-by-properties-config="false"

API reference

This section provides additional information that will help you to understand the specifics of some of the configuration parameters described in the previous section.

includeProperties

This parameter indicates which properties should be included on resulting RepositoryEntry instances.

Properties can contain wildcards (*) to match the propertyName by pattern. An empty collection means that all properties should be included (unless there is a specific excludeProperties declaration).

System relevant properties are always included (for example, id, active), so you can configure certain properties to be included within the search results. If you are missing some data from the search results, adding a property in configuration setting guarantees that it will be returned.

excludeProperties

This parameter indicates which properties will be excluded on the resulting RepositoryEntry instances.

Properties can contain wildcards (*) to match the propertyName by pattern. If the collection is empty, then no properties will be excluded. Excluded properties override properties that are also explicitly defined in the includeProperties set. System relevant properties are always included (for example, id, active, etc.), so you can configure some system properties to be excluded from the search results. Filling this with data that you do not need improves search.

autoExclude

This parameter indicates whether some predefined virtual properties (such as Folder.children) should be automatically excluded. This can be overridden for specific properties by explicitly mentioning them in the includeProperties list. It is a boolean flag, which is by default set to true.

includeVersions

Indicates whether all versions of a content should be included. It is also a boolean flag, and it is set to true by default.

Component custom events

There are configuration parameters which are used when sending events.

This section describes events current supported by the UI Components.

Every component can listen to and/or fire events. These events are used for interaction between our different components. Customers can also listen to and/or fire events on their own, since custom event handling is a feature provided by any browser with Javascript. Thus, we prepared a common structure for those custom events.

Custom Events Structure

Our all custom events have a well know name, which is d1-event. Custom events in general send their data through the detail property. Bellow you can see how the detail property of the event should look like.

detail {
  name: "name",
  componentSource: "source",
  componentSourceId: "sourceId",
  componentTarget: "target",
  componentTargetId: "targetId",
  data: {
    id: "id",
    name: "name",
    info: "info",
    type: "type",
    tag: "tag",
    reserved: {
      ...
    }
  }
}

• name - every kind of custom event that is supported in our components have its own unique name. This way, we can identify which event we will listen to, and how to react upon receiving them. e.g.: documentIdChange. This is required;

• componentSource - well know type name of the component which is sending this event. One can see a list of all known component names further in this document. This is optional, but all d1 components should send it when firing an event;

• componentSourceId - the id of the source component. This is optional, but all d1 components should send it when firing an event;

• componentTarget - well known type name of the component which is the target of this event, which means, the component which should handle this event upon receiving it. This is useful when one wants to send an event to a specific component type (for example, all search components, or all hitlists). This is optional, which means, when it is absent, every listener should handle the event in case they are interested on it;

• componentTargetId - the id of the component which is the target of this event, which means, the component which should handle this event upon receiving it. This is useful when one wants to send an event to a specific component. This is optional, which means, when it is absent, every listener should handle the event in case they are interested on it;

• data - the data which is sent by the event, with further information which is required by any event specifically. It contains the following parameters:

  • id - any id or list of ids (separated by ,) that are required by the event. For instance, the documentIdChange sends the document id(s) here;
  • name - any name or list of names (separated by ,) that are required by the event;
  • type - any type or list of types (separated by ,) that are required by the event. For instance, the searchTypeChange sends the new search type here;
  • info - any info eg message;
  • tag - any tag or list of tags (separated by ,) that are required by the event;
  • reserved - in case none of the other well known parameter is enough for your event, you can send further data in here

Supported events

This section describes currently supported events and their data properties:

documentIdChange

This event sends new document id(s) that should be displayed by the web-reader component. Note that this type is either content or folder. The hitlist component is the one sending this event, currently.

detail {
  name: "documentIdChange",
  data: {
    id: "SOME_DOCUMENT_ID,SOME_OTHER_DOCUMENT_ID",
    type: "content,folder"
  }
}

documentClickEvent

This event sends the clicked document id which was either clicked ("LEFT" button), double clicked, or right ("RIGHT" button) clicked. Also, it sends which special key (if any, between "SHIFT", "ALT", "CTRL" or "META") which was pressed during the click event. The hitlist component is the one sending this event, currently.

detail {
  name: "documentClickEvent",
  data: {
    id: "SOME_DOCUMENT_ID",
    type: "content",
    reserved: {
      button: "LEFT",
      keys: "CTRL,SHIFT",
      doubleClick: false
    }
  }
}

searchTypeChange

This event sends the new search type which should be used by the search component. The possible values are:ByProperties and ByCondition. It is useful for changing a search component search type on the fly. It is a good idea to send the componentTargetId, as multiple search components can exist at the same time.

detail {
  name: "searchTypeChange",
  componentTarget: "search-component",
  componentTargetId: "the-search-component-id",
  data: {
    type: "ByCondition"
  }
}

fireSearch

This event is listened by the search component, and it simply fires its currently configured search, as if the search button was pressed. This is useful when using the search component without any visible UI (showUI configuration set to false). It is a good idea to send the componentTargetId, as multiple search components may exist at the same time.

detail {
  name: "fireSearch",
  componentTarget: "search-component",
  componentTargetId: "the-search-component-id"
}

searchStarted

This event is sent when a new search request has been sent. It is useful, for example, for adding a loading indicator on the component which is waiting for the search results (sent in the searchPerformed event). In the info, there is the search text, in case the search type is other than ByProperties. Also, we are setting the servicesUrl where the search will be performed, together with the repositoryName and the `sessionId. This information is useful when we want a hitList to show results from different sources. The search component is the one sending this event, currently.

detail {
  name: "searchStarted",
  data: {
    info: "TEXT",
    id: "THE_SESSION_ID",
    name: "THE_REPOSITORY_NAME",
    type: "THE_SERVICES_URL"
  }
}

searchPerformed

This event sends search results which are currently sent from the search component and listened on the hitlist component in order to display the search results. The EntriesResponseobject contains a search response. Also, the contentTypes is sent which are the types returned by the content-types/by-technical-name call. The pageSize and current offset are also added to the event data. It is a good idea to set the componentSourceId, because this will be the component updated upon receiving a pageChange event. The info property of the detail event is filled with the configured searchName. If search is configured to always use a new tab, then this information is also sent. The search component is the one sending this event, currently.

detail {
  name: "searchPerformed",
  componentSource: "search-component",
  componentSourceId: "the-search-component-id",
  componentTargetId: "the-id-of-the-target-component",
  info: "the-search-name",
  data: {
    reserved: {
      entriesResponse: EntriesResponse,
      contentTypes: ContentTypes,
      searchConfiguration: SearchConfiguration,
      pageSize: page_size,
      offset: the_offset,
      useNewTab: usew_new_tab,
      condition: "the-condition-used-on-search"
    }
  }
}

pageChange

This event notifies that a page has been changed in the hitlist. This event sends a new page and the current page size information. It is a recommended to set the componentTargetId so that a component that delivered the search results, via the searchPerformed event, is notified. Thus, this ID must be a value received via the searchPerformed event in the componentSourceId. When changing a page while loading data of a folder, the folder is sent. The hitlist component is the one sending this event, currently.

detail {
  name: "pageChange",
  componentSource: "hitlist-component",
  componentSourceId: "the-hitlist-component-id",
  componentTargetId: "the-target-component-id"
  data: {
    reserved: {
      page: the_page,
      pageSize: page_size,
      folder: the_folder,
      searchConfiguration: SearchConfiguration
    }
  }
}

pageChanged

This event sends the data resulted by the loading of a new page. It is currently sent from the search component and listend on the hitlist component in order to display the next load of data. The EntriesResponse is the object containing the response of the loading.

detail {
  name: "pageChanged",
  componentSource: "search-component",
  componentSourceId: "the-search-component-id",
  componentTargetId: "the-id-of-the-target-component",
  data: {
    reserved: {
      entriesResponse: EntriesResponse,
      offset: the_offset
    }
  }
}

loadFolder

This event triggers the loading of the children content of a given folder. When the results must be shown in a new tab, useNewTab is set to true. It is false otherwise. When we are loading the children of a folder in an inline way (which means, the result should be shown at the same place where they are being loaded), then inline must be true. The hitlist component is the one sending this event, currently.

detail {
  name: "loadFolder",
  componentSource: "hitlist-component",
  componentSourceId: "the-hitlist-component-id",
  componentTargetId: "the-id-of-the-target-component",
  data: {
    reserved: {
      folder: the_folder,
      offset: the_offset,
      useNewTab: use_new_tab,
      inline: inline
    }
  }
}

folderLoaded

This event sends the data resulted by the loading the children content of a given folder. It is currently sent from the search component and listened on the hitlist component in order to display the data. The EntriesResponse is the object containing the response of the loading. When useNewTab is true, then the info contains the name of the parent folder. It contains the search name otherwise. Also, the contentTypes is sent, which are the types returned by the content-types/by-technical-name call. The pageSize and current offset are also added to the event data. When loading another page of data, changingPage must be sent to true.

detail {
  name: "folderLoaded",
  componentSource: "search-component",
  componentSourceId: "the-search-component-id",
  componentTargetId: "the-id-of-the-target-component",
  info: search_title
  data: {
    reserved: {
      entriesResponse: EntriesResponse,
      contentTypes: ContentTypes,
      searchConfiguration: SearchConfiguration,
      pageSize: page_size,
      offset: the_offset,
      useNewTab: useNewTab,
      inline: inline,
      condition: "the-condition-used-on-search",
      changingPage: changingPage,
      folder: the_parent_folder
    }
  }
}

propertyValueChanged

This event sends the property name, and the new property value of a property which was edited. It is currently sent from the property component and listened on the hitlist component in order to update its data.

detail {
  name: "propertyValueChanged",
  componentSource: "property-component",
  componentSourceId: "the-property-component-id",
  componentTargetId: "the-id-of-the-target-component",
  data: {
    id: THE_CONTENT_ID_CHANGED,
    name: THE_PROPERTY_NAME_CHANGED,
    info: THE_PROPERTY_VALUE_CHANGED
  }
}

notification

This event sends the Notification Message and type to the listener (currently used by the WebReader).

detail {
  name: "notification",
  data: {
    info: "Text Message",
    type: "refreshAll",         //"none" -no action/no Button, "refreshAll", "refreshDocument", "refreshComment", "openDocument"
    id: "REFRESH_DOCUMENT_ID",
  }
}

Component names

Our current list of component names for the componentSource and componentTarget are:

1. web-reader-component
2. search-component
3. hitlist-component

Examples

Fire example

This is a simple code which exemplifies how to send a documentIdChange event:

document.dispatchEvent(new CustomEvent("d1-event", {
  bubbles: true,
  composed: true,
  detail: {
    name: "documentIdChange",
    componentSource: "search-component",
    componentTarget: "web-reader-component",
    data: {
      id: "NEW_DOCUMENT_ID"
    }
  }
}));

The bubbles event javascript property indicates whether the event should bubble up through the DOM tree or not. Check more here: https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles

The composed event javascript property indicates whether the event will propagate across the shadow DOM boundary into the standard DOM. Check more here: https://developer.mozilla.org/en-US/docs/Web/API/Event/composed

Notice that, in this case, we are sending the optional componenttarget, configuring that only the Web Reader should react on this event.

Listen example

This is a simple code which exemplifies how to listen to a documentIdChange event (imagining we are writing this code within the WebReader):

document.addEventListener("d1-event", event => {
  const detail = (<CustomEvent>event).detail;
  if (detail.componentTarget && detail.componentTarget !== "web-reader-component")
    return; //since this is in the web reader, I am only interested in events sent without any target, or specifically for the web-reader

  if (detail.name !== "documentIdChange")
    return; //we are only interested in the documentIdChange event

  const eventData = detail.data;
  alert("Thew documentId(s) received is(are): " + eventData.id);
});

Search component configuration example

<!-- Place code into your HTML Body part -->

<!-- Define container size for UI Component -->
<div style="width: 100%; height: 150px;">
    <!-- UI Component - Search -->
    <search-element
        id="search-all"
        data-log-level="info"
        data-locale="en"
        data-search-type="ByCondition"
        data-search-text="name like '*'"
        data-show-ui="true"
        data-show-content-type="true"
        data-show-advanced-search="true"
        data-show-results-per-page="true"
        data-show-ordered-by="true"
        data-page-size="10"
        data-component-id="d1-search-component"
        data-search-name="Default Search"
        data-session-id="20231116171002297-b6d90899-37e5-4966-9b4a-78b01c57f961"
        data-services-url="https://dev-phoenix-adx.staging.document.one/services/"
        data-include-properties="name,active,createdAt,number,value,id,owner,resource,mimeType"
        data-component-prefix="d1-ui-search/"
        data-repository-name="default"
    >
        <!-- UI Component - Load module (.js) and style (.css) -->
        <script src="https://dev-phoenix-adx.staging.document.one/services/d1-ui-search/js/d1-search-component.js" id="d1-search-js" type="module"> </script>
        <link rel="stylesheet" type="text/css" href="https://dev-phoenix-adx.staging.document.one/services/d1-ui-search/js/d1-search-component.css">
        <link rel="stylesheet" type="text/css" href="https://dev-phoenix-adx.staging.document.one/services/d1-ui-search/global.css">
    </search-element>
</div>