@wider/utils_proto
Version:
A set of extensions to basic objects giving uniform behaviour in various technical environments
114 lines (105 loc) • 5.74 kB
JavaScript
/** *
* @module @wider/utils_proto/proto_string/contextParse
*
* @copyright Copyright (C) 1985..2021 Martin Baker. http://y-d-r.co.uk
* @author Martin W Baker
* @license ISC Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*/
/**
* @typedef {objectname} rowId - the name of a unique row in the dataset - this is regardless of the table in which the row lives. Also used to identify other components in the system such as resource. Format is
*
* @property {NCName} tableName - table reference name - often the same as that tag name for the element to which it relates
* RowId_ // fixed delimiter
* number // being the nth item that was created - this is not the nth item is the current set of rows as some rows may have been deleted and the remainder are not renumbered
*[.number] // zero or more numbers, one per required child depth related to instances of a child element. Numbers here restart anew for each of the parent numbers
* `</pre>
*@example
* contactrowsRowId_2345
*/
/**
* A ydr context may be considered like a url except that is provides a reference to data, normally to a specific single attribute or its containing element, or to a collection of elements. Contexts are used pervasively to link server side XSD schema and its related data to client side processing.
*
* Just like a url - this is a reference. To use this to actually access the data to which it refers requires the use of code that is authorised to access the data
*
* Contexts can also be extended with hints as to what a application or client browser might do with the reference
*
* @typedef {object} wider_context
* @property {objectname} [urn] - the unique identifier for the database zone - as used for example in `$wider.data.find(urn)` to obtain access to a dataset related to the current login. Optional when the **id** is a system wide unique row id, mandatory otherwise.
* @property {rowId | objectname} id - a YDR @see {@link rowId} or the name of the table that holds the data
* @property {objectname} [attribute] - the name of an attribute in the selected row - if omitted then the context refers to the whole row
* @property {xpath} [xpath] - if present then defines a path from the selected row to the required child element
* @property {enum} [buttons] - possible values |pane|subPane|absent| used only in the schema document to direct the way this attribute or row might be rendered on a form
* @property {enum} [selector] - possible values |table|tableWithAttributesList|tableBase| a suggestion as to which process or report might be related to accessing this context
* @property {enum} [action] - possible values |_edit|_delete|_help| at run time as hints from the client to the server as to what to do next
* @property {string} context - stays fixed as the value originally used to create this object - to be kept static.
*
* Use `.toString()` method on this object for the new string context value if anything has changed
* @property {*} target - deprecated - do not use f
*/
/**
* @param {string} context
*
* turns a context string such as appears in @data-ydr-context in HTML into an object so that names of the components are available to the application
*
* For more information on the use of this structure see the type documentation of `wider_contextParse()`
*
* ```javascript
* "userDetails:contactrowsRowId_27:RENEW:CONTACT_MEMBERSHIP".wider_contextParse()
*
* //{
* // "urn":"userDetails",
* // "id":"contactrowsRowId_27",
* // "target":"contactrowsRowId_27",
* // "attribute":"RENEW",
* // "xpath":"CONTACT_MEMBERSHIP",
* // "context":"userDetails:contactrowsRowId_27:RENEW:CONTACT_MEMBERSHIP"
* //}
* //
* ```
*/
class ContextParse {
/**
* The documentary name for error messages of this class
*/
/**
*
* @param {string} context -the string representation of a context - same structure as the result of the `.toString()` method of this class
*/
constructor(context) {
let contextArr = context.split(":"); // note must use ":" rather than /:/ for silly aged microsoft compatibility in this regexp
this.urn = contextArr[0] || "";
this.target = /* name target deprecated always use .id*/ this.id = (contextArr[1] || "").wider_unescape(); /* a row id or the name of a table */
this.attribute = contextArr[2] || "";
this.xpath = (contextArr[3] || "").wider_unescape();
this.buttons = contextArr[4];
this.selector = contextArr[5];
this.action = contextArr[6];
this.context = context;
}
get target() {
return this.id;
}
/**
* @returns {string} the string representation of this instance of the class, being a colon delimited string of **urn**, **id**, **attribute**, **xpath**.
*
* If this object has any of **button**, **selector** or **action**, then those are also colon delimited appended to the default result
*/
toString() {
let extension = ((this.buttons || this.selector || this.action) ?
(":" + (this.buttons || "") +
((this.selector || this.action) ?
":" + (this.selector || "") +
(this.action ? ":" + this.action : "") :
"")) :
"");
return this.urn + ":" + this.id.wider_escape() + ":" + this.attribute +
((this.xpath || extension) ?
":" + this.xpath.wider_escape() + extension :
"");
}
}
ContextParse.$moduleName = "@wider/utils_proto/proto_string";
ContextParse.$moduleTitle = ContextParse.$moduleName + "data reference context parser";
export default ContextParse;