applications/content/src/docs/asciidoc/content.adoc - ofbiz-framework - Git at Google

 ////
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

 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.  See the License for the
 specific language governing permissions and limitations
 under the License.
 ////
 = Content Management
 The Document Content Management System (DMS/CMS) is designed to store data once and then allow it to be reused
  in multiple arrangements.

 == Overview
 The term 'content management' generally refers to a system for acquiring, storing and retrieving electronic data
  in varying formats - such as text, images or proprietary formats.

 Content management systems (CMS) usually incorporate a rendering system to let the developer display the content
  in various formats.

 While some CMSs are rigid in the manner in which content is entered and rendered, the content management module of OFBiz
  is more of a set of tools which can be used in a variety of situations.

 In addition to HTML, the content can be rendered in non-Web modes, such as PDF or email newsletters.

 The OFBiz CMS is designed to store data once and then allow it to be reused in multiple arrangements.

 Hence, there are basically two aspects

 * the back-end storage subsystem, which is oriented around the DataResource entity,
 * and the front-end association subsystem, which revolves around the Content entity.

 Note that the Content entity has a foreign key pointing to one and only one DataResource entity,
 but the same DataResource entity can be referenced by multiple Content entities.

 It is a general rule that data can only be accessed via a Content entity,
 but one common exception is that images are typically served up using the DataResource primary key.

 Content entities are related to other content via ContentAssoc entities.
 The ContentAssoc entity has a four part primary key and other fields that are used to relate content.
 The key specifies the 'to' Content and the 'from' Content, as well as the type of association and its effective date.
 See the discussion of the ContentAssoc entity for more information on how content is related.

 == Security
 All services defined in the content component are safely secured. If you are in a safe environment, want to save more complex contents and get blocked by the security policy you might want to override the security only in the content component.

 Typically when using content/control/WebSiteCms?webSiteId=CmsSite (ie "Edit[ing] WebSite CMS For: CMS Web Site [CmsSite]"), the service updateTextContent may prevent you to save contents with a message like

 [WARNING]
 The Following Errors Occurred:
 In field [textData] by our input policy, your input has not been accepted for security reason. Please check and modify accordingly, thanks.

 To override the security you can change definitions of other content services by changing the security on field "textData" from "safe" to "any". That's of course an example and you may find other similar cases.

 You may also prefer to change the security policy at an upper level. See owasp.properties file.

 == Major CMS entities

 === DataResource
 The DataResource entity acts as the gateway to actual content retrieval. +
 There are two important fields for determining the format and storage of a resource :

 * the 'mimeTypeId'
 * the 'dataResourceTypeId'.

 ==== mimeTypeId
 The mime type is the standard Multipurpose Internet Mail Extension, of which, 'text/html' and 'image/gif' will be
  two of the more common examples.

 The mimeTypeId indicates the format of the content as it is stored.

 This must be compared to the desired output format to see if the rendering system can handle the request.

 For example, if the DataResource.mimeTypeId equals, 'image/png', and the target output format is 'text/html',
 the rendering system could make the logical supposition that it should return an HTML "img.../" tag.
 If the output format were 'application/pdf' then it will need to determine if it can convert the image to a PDF format.

 ==== dataResourceTypeId
 The dataResourceTypeId field indicates the storage mechanism for the resource. +
 It could be of type ELECTRONIC_TEXT, which indicates that there is an entry in the ElectronicText table that is related
  to the DataResource by its primary key.

 If the mimeTypeId is of type image, then the dataResourceId could be IMAGE_OBJECT (stored in the database ImageDataResource table),
  OFBIZ_FILE (stored in a file the path of which is relative to the OFBiz home directory) or
  URL_RESOURCE (could be accessed via HTTP protocol).


 === dataTemplateTypeId
 One of the powerful concepts of the OFBiz CMS is that it can store templates that can be used to control the formatting of data.

 In this case, the resource pointed to by the DataResource entity will not be rendered, itself;
 instead, it will be used as a template to format data that is associated with it.

 The currently supported templating types are FreeMarker (FTL) and the OFBiz Screen Widget (SCREEN_COMBINED) format.
 If the value of dataTemplateTypeId is empty or equal to NONE,
 then the data pointed to by the dataResource entity is rendered directly.

 === objectInfo
 If dataResourceTypeId is ELECTRONIC_TEXT or IMAGE_OBJECT, then objectInfo is not used,
  but for other types, it will contain the resource storage information.

 If dataResourceTypeId is one of OFBIZ_FILE, CONTEXT_FILE, LOCAL_FILE or URL_RESOURCE; then objectInfo contains path info.

 If dataResourceTypeId equals SHORT_TEXT, then objectInfo will contain the actual resource (short text) value.

 ==== ElectronicText
 ElectronicText contains ASCII text data. +
 An ElectronicText entity can be associated with only one DataResource entity and vice-versa. +
 The mimeTypeId field of the DataResource entity must be checked to determine the format of the ElectronicText data.

 ==== ImageDataResource
 ImageDataResource is the equivalent of ElectronicText for binary image data. +
 The DataResource.mimeTypeId must be checked to determine the format of the data.

 == Content
 The Content entity determines how DataResources are rendered.

 It does this on a 'local' level, in that it has a mimeTypeId, localeString and other fields that indicate
  to the rendering system how the DataResource should look, but it can also control the larger picture because
  it can act as a placeholder and head for other content.

 The Content.dataResourceId does not need to point to anything, instead a Content entity can be related to
  other Content via ContentAssoc entities.

 At some point, some of the child Content entities must point to DataResources, else nothing will ever be displayed.

 === dataResourceId
 The dataResourceId points to a DataResource entity that represents content associated with the parent Content entity.

 The related DataResource could be data that is rendered or it could be a template that indicates how child Content
  of the parent Content are rendered.

 === contentName
 contentName is the field that is used to represent the Content entity in lists.
 The contentName field value must be less than 100 characters.

 === description
 description is used in cases where a short summary or description of the Content is desired.
 The description field value must be less than 255 characters.

 === templateDateResourceId
 The templateDataResourceId field points to a DataResource entity that is used to transform
  the data contained in the DataResource pointed to by the Content.dataResourceId field.

 The dataTemplateTypeId of the DataResource pointed to by templateDataResourceId will be checked
  to determine what sort of transform will be applied.


 == ContentRole
 The ContentRole entity is used to assign permission authority to a piece of content.

 The ContentRole entity identifies the Content to which the authority is being attached and
  the Party that has that authority and what sort of authority (role) that party has.

 The ContentRole also establishes the time frame (from/thruDate) for which that authority is valid.

 == ContentPurpose
 The ContentPurpose entity adds extra information to a Content entity that is used to determine what permissions
  are required to access that Content.

 == ContentPurposeOperation
 ContentPurposeOperation is used to setup permission validation rules.

 == ContentAssoc
 ContentAssoc relates one Content entity to another.

 A sense of direction is conveyed in the fact that one field is named contentIdTo (the from field is contentId).

 === contentId
 This is the 'parent' Content in a Content-to-Content relationship.

 === contentIdTo
 This field is the 'from' or 'child' field in a Content-to-Content relationship.

 === contentAssocTypeId
 The contentAssocTypeId field is used to add information about the type of a Content-to-Content relationship.
 It is part of the primary key.

 Two Content entities can be related by multiple ContentAssoc entities if the contentAssocTypeId field varies
  (or the fromDate is different).

 === fromDate
 the fromDate field is part of the primary key.
	////
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	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. See the License for the
	specific language governing permissions and limitations
	under the License.
	////
	= Content Management
	The Document Content Management System (DMS/CMS) is designed to store data once and then allow it to be reused
	in multiple arrangements.

	== Overview
	The term 'content management' generally refers to a system for acquiring, storing and retrieving electronic data
	in varying formats - such as text, images or proprietary formats.

	Content management systems (CMS) usually incorporate a rendering system to let the developer display the content
	in various formats.

	While some CMSs are rigid in the manner in which content is entered and rendered, the content management module of OFBiz
	is more of a set of tools which can be used in a variety of situations.

	In addition to HTML, the content can be rendered in non-Web modes, such as PDF or email newsletters.

	The OFBiz CMS is designed to store data once and then allow it to be reused in multiple arrangements.

	Hence, there are basically two aspects

	* the back-end storage subsystem, which is oriented around the DataResource entity,
	* and the front-end association subsystem, which revolves around the Content entity.

	Note that the Content entity has a foreign key pointing to one and only one DataResource entity,
	but the same DataResource entity can be referenced by multiple Content entities.

	It is a general rule that data can only be accessed via a Content entity,
	but one common exception is that images are typically served up using the DataResource primary key.

	Content entities are related to other content via ContentAssoc entities.
	The ContentAssoc entity has a four part primary key and other fields that are used to relate content.
	The key specifies the 'to' Content and the 'from' Content, as well as the type of association and its effective date.
	See the discussion of the ContentAssoc entity for more information on how content is related.

	== Security
	All services defined in the content component are safely secured. If you are in a safe environment, want to save more complex contents and get blocked by the security policy you might want to override the security only in the content component.

	Typically when using content/control/WebSiteCms?webSiteId=CmsSite (ie "Edit[ing] WebSite CMS For: CMS Web Site [CmsSite]"), the service updateTextContent may prevent you to save contents with a message like

	[WARNING]
	The Following Errors Occurred:
	In field [textData] by our input policy, your input has not been accepted for security reason. Please check and modify accordingly, thanks.

	To override the security you can change definitions of other content services by changing the security on field "textData" from "safe" to "any". That's of course an example and you may find other similar cases.

	You may also prefer to change the security policy at an upper level. See owasp.properties file.

	== Major CMS entities

	=== DataResource
	The DataResource entity acts as the gateway to actual content retrieval. +
	There are two important fields for determining the format and storage of a resource :

	* the 'mimeTypeId'
	* the 'dataResourceTypeId'.

	==== mimeTypeId
	The mime type is the standard Multipurpose Internet Mail Extension, of which, 'text/html' and 'image/gif' will be
	two of the more common examples.

	The mimeTypeId indicates the format of the content as it is stored.

	This must be compared to the desired output format to see if the rendering system can handle the request.

	For example, if the DataResource.mimeTypeId equals, 'image/png', and the target output format is 'text/html',
	the rendering system could make the logical supposition that it should return an HTML "img.../" tag.
	If the output format were 'application/pdf' then it will need to determine if it can convert the image to a PDF format.

	==== dataResourceTypeId
	The dataResourceTypeId field indicates the storage mechanism for the resource. +
	It could be of type ELECTRONIC_TEXT, which indicates that there is an entry in the ElectronicText table that is related
	to the DataResource by its primary key.

	If the mimeTypeId is of type image, then the dataResourceId could be IMAGE_OBJECT (stored in the database ImageDataResource table),
	OFBIZ_FILE (stored in a file the path of which is relative to the OFBiz home directory) or
	URL_RESOURCE (could be accessed via HTTP protocol).


	=== dataTemplateTypeId
	One of the powerful concepts of the OFBiz CMS is that it can store templates that can be used to control the formatting of data.

	In this case, the resource pointed to by the DataResource entity will not be rendered, itself;
	instead, it will be used as a template to format data that is associated with it.

	The currently supported templating types are FreeMarker (FTL) and the OFBiz Screen Widget (SCREEN_COMBINED) format.
	If the value of dataTemplateTypeId is empty or equal to NONE,
	then the data pointed to by the dataResource entity is rendered directly.

	=== objectInfo
	If dataResourceTypeId is ELECTRONIC_TEXT or IMAGE_OBJECT, then objectInfo is not used,
	but for other types, it will contain the resource storage information.

	If dataResourceTypeId is one of OFBIZ_FILE, CONTEXT_FILE, LOCAL_FILE or URL_RESOURCE; then objectInfo contains path info.

	If dataResourceTypeId equals SHORT_TEXT, then objectInfo will contain the actual resource (short text) value.

	==== ElectronicText
	ElectronicText contains ASCII text data. +
	An ElectronicText entity can be associated with only one DataResource entity and vice-versa. +
	The mimeTypeId field of the DataResource entity must be checked to determine the format of the ElectronicText data.

	==== ImageDataResource
	ImageDataResource is the equivalent of ElectronicText for binary image data. +
	The DataResource.mimeTypeId must be checked to determine the format of the data.

	== Content
	The Content entity determines how DataResources are rendered.

	It does this on a 'local' level, in that it has a mimeTypeId, localeString and other fields that indicate
	to the rendering system how the DataResource should look, but it can also control the larger picture because
	it can act as a placeholder and head for other content.

	The Content.dataResourceId does not need to point to anything, instead a Content entity can be related to
	other Content via ContentAssoc entities.

	At some point, some of the child Content entities must point to DataResources, else nothing will ever be displayed.

	=== dataResourceId
	The dataResourceId points to a DataResource entity that represents content associated with the parent Content entity.

	The related DataResource could be data that is rendered or it could be a template that indicates how child Content
	of the parent Content are rendered.

	=== contentName
	contentName is the field that is used to represent the Content entity in lists.
	The contentName field value must be less than 100 characters.

	=== description
	description is used in cases where a short summary or description of the Content is desired.
	The description field value must be less than 255 characters.

	=== templateDateResourceId
	The templateDataResourceId field points to a DataResource entity that is used to transform
	the data contained in the DataResource pointed to by the Content.dataResourceId field.

	The dataTemplateTypeId of the DataResource pointed to by templateDataResourceId will be checked
	to determine what sort of transform will be applied.


	== ContentRole
	The ContentRole entity is used to assign permission authority to a piece of content.

	The ContentRole entity identifies the Content to which the authority is being attached and
	the Party that has that authority and what sort of authority (role) that party has.

	The ContentRole also establishes the time frame (from/thruDate) for which that authority is valid.

	== ContentPurpose
	The ContentPurpose entity adds extra information to a Content entity that is used to determine what permissions
	are required to access that Content.

	== ContentPurposeOperation
	ContentPurposeOperation is used to setup permission validation rules.

	== ContentAssoc
	ContentAssoc relates one Content entity to another.

	A sense of direction is conveyed in the fact that one field is named contentIdTo (the from field is contentId).

	=== contentId
	This is the 'parent' Content in a Content-to-Content relationship.

	=== contentIdTo
	This field is the 'from' or 'child' field in a Content-to-Content relationship.

	=== contentAssocTypeId
	The contentAssocTypeId field is used to add information about the type of a Content-to-Content relationship.
	It is part of the primary key.

	Two Content entities can be related by multiple ContentAssoc entities if the contentAssocTypeId field varies
	(or the fromDate is different).

	=== fromDate
	the fromDate field is part of the primary key.