newObjects Active Label ActiveX control is a visual ActiveX control
designed for usage on WEB pages and in ActiveX host applications. Its
functionality can be explained as such as of a simple report generator
or design application. Active Label can show and print independently
labels and other single page small format materials. It enables the user
put, arrange and format a variety of graphical elements on them:
barcodes, text labels, text boxes, images, shapes. Each of the elements
put on the label is accessible as object as well as the Active Label
ActiveX and its service objects. This enables both DTHML pages and
ActiveX control host applications to fully control the appearance and
behavior of the ActiveX.
Therefore the Active Label ActiveX is an
almost complete application enclosed in in-process ActiveX DLL. The
applications can use it to implement everything from the interactive
design to the printing without need of complicated code.
Where the ID attribute specifies
a reference name that can be used further to access the created object.
In this documentation we will most often use in the example code lines
VisiLabel as reference name thus assuming that we have created an Active
Label control with ID="VisiLabel". In other applications, such
as applications written in VB, C++, Delphi, .NET languages the creation
is done with the corresponding methods the language/tool offers. Further
the usage of the created ActiveX does not differ much in the different
environments except for the syntax and the techniques for the particular
language. Thus we will present any example code in Javascript assuming
that the ActiveX is in a HTML page, but what they illustrate is also
applicable for the other applications except a few specific features.
In this section we will explain in short the Active Label
features and point out the chapters in the documentation that describe
them in detail.
The Active Label is not a single-object ActiveX it has an
internal structure represented by many objects. See the Active Label object
model for diagram and details. All the internal objects are
accessible through the Active Label's root object VisiLabel.
As an ActiveX designed for the WEB Active Label has many features to
support standards and operations related to the WEB programming. In
many aspects the ActiveX is very similar to the Microsoft Internet
Explorer itself - the object model, the behavior of the elements on the
label, the ability to download and upload data dynamically. Once put on
a HTML page the Active Label ActiveX becomes a naturally looking
extension of the HTML page - a special part of it that can perform tasks
the page can't do or can't do the way you want. Among other things this
includes the independent printing where Active Label can print multiple
copies of the same label or set of labels driven by data arranged on
pages (see VisiLabel.Print, Label
object and Page object). Here are the
feature highlights and links to the overview and reference pages about
them:
Instantiation and initialization. Once created the
Active Label can be initialized in many different ways:
Text commands passed in a set
of PARAM elements between the opening and closing OBJECT tags.
Programmatically
by setting the VisiLabel.Src
property or calling VisiLabel.Reload
thus instructing the object to initialize from an URL or a physical
path.
Using a single PARAM element between the opening and closing
OBJECT tags:
<object classid="clsid:09A02CEE-410B-47BA-A837-E62C9C8D70BF" id="VisiLabel">
<PARAM NAME="SRC" VALUE="somelabel.activelabel">
</object>
Which is equivalent to setting the VisiLabel.Src property
programmatically but does not require separate code to do that - it
is done during the creation of the control.
Using
DATA attribute of the OBJECT element:
<object
classid="clsid:09A02CEE-410B-47BA-A837-E62C9C8D70BF" id="VisiLabel"
DATA="label.activelabel"></object>
Which is much like the previous but the difference is that
with DATA attribute you instruct the browser to load the data and
pass it to the ActiveX while in the previous case the ActiveX does
this alone. Note that DATA attribute may not work properly with some
custom protocols (others than HTTP and file).
Partially
(meaning change some settings, add data) through VisiLabel.MergeSrc
for example.
Programmatically by passing the data on your own.
This is done through the VisiLabel.TextCommands
property.
In applications built in C++ and other sophisticated
environments with lower level COM capabilities by using the standard
IPersistStreamInit or IPersistPropertyBag interface.
In all those cases the initialization data format can be the same - see
the Data, file and command formats.
Extracting
the label design data and settings, saving or uploading the label.
The application can obtain the label data and preserve it for future
usage (for example to use it for initialization of the ActiveX on
other pages). Because the ActiveX supports interactive editing this is
needed when you want to preserve the label design and settings made by
the user.
Obtain ready-to use HTML code for OBJECT element with text
commands in set of PARAM elements - see VisiLabel.ObjectParams.
Obtain
text commands as string from VisiLabel.TextCommands.
Upload
the label data to an URL. See VisiLabel.Dst
and VisiLabel.PostData. The
upload and download functionality is explained in depth in How to Download and Upload.
Printing. The Active Label prints the label
configured in it by placing series of labels on the pages.
Printing
is initiated through VisiLabel.Print
method. The ActiveX prints copies of the same label or set of labels
over the specified data set (see below about the data connectivity) from left to right and from top to the
bottom (as shown above). The size of the page and the settings that
affect how the labels are arranged are specified through the
properties of the VisiLabel.Page object
(see also the figure above).
Each label has the same size and
margins which are controlled through the VisiLabel.Label
object. The figure below shows the main settings:
The elements on the label. On the label you can put
any number of these elements:
Barcode. Support most of the
standard 1-d barcode symbologies used today.
Image.
Picture in almost any popular image format. Supports
transformations, smart sizing and dynamic download/upload. The
element behaves like the <IMG> elements on a HTML page, but in
addition they can also be uploaded separately to any URL (with or
without transformations applied over them). For
downloading/uploading see How to Download and Upload.
Simple
text label. A text line which can have specific font,
orientation (can be rotated) and other characteristics.
Text
box. A multiline text which may have specific font and other
characteristics.
Symbol. Much
like text labels, but this object offers a bit different interface
which makes it perfect for placing sole symbols from symbol fonts.
Simple
shape. Simple shapes such as lines, ovals, lines and
rounded rectangles. Can be filled or transparent.
The labels are designed by using one or more of those elements
placed on the label surface. Almost any property of any of the
elements can be linked to the data set thus allowing the application
print sets of labels where each label obtains the desired
characteristics from the fields in the data set.
Data
connectivity and data sets. Apparently we need the ability to
print sets of labels over a set of data - changing barcodes, text
labels according to the fields in a data set for example. To
accomplish this Active Label supports two methods for binding data
with the label. Both are controlled by the VisiLabel.Variables
object which has a recordset-like behavior.
External data base connection. Version 1.0 allows you
configure any ADO compatible database connection
string and execute any supported by the database on the other
side SELECT query over it. The
data obtained this way is used as data set over which the label sets
are generated and printed. The application can also enable the user
to navigate through the
data set and see the preview of the label for each record (see VisiLabel.Variables.UpdateLabel
for instance).
Internal cache. It is actually a 2-d array
managed internally by the VisiLabel.Variables
object. It provides the same functionality (even extended
functionality in fact) over it as in the case of external data base.
The difference is that this internal cache is auto-configured to
match the record structure specified by the application by
configuring fields (Field object) into
the Variables object (see also VisiLabel.Variables.AddField).
Further the data in this cache can be filled in different manners:
As part of the label initialization putting CACHEDATA
entries containing the field values into the initialization data
(see above). This can be used with any of the supported initialization
techniques.
Programmatically at run-time using the Variables
object (see VisiLabel.Variables.Update,
VisiLabel.Variables.AddNew)
by setting the values of its fields (each is represented by a
Field object) and adding new records as needed.
By downloading
data from an URL - see VisiLabel.MergeSrc.
As you can see above the internal cache can be filled by putting
PARAM entries in the OBJECT tag, or by the server-side script that
extracts a stored label from your database appending it with
CACHEDATA entries, or by separate server side script that generates
only such entries. This means that you can use the same techniques
you use for outputting WEB pages in your application (no matter what
the language is - ASP, JSP, PHP or anything else). Note that this is
most often the easiest way because the WEB pages of your application
will most likely need the same data or part of it for other purposes
as well. Thus the work you need to do is practically the same - you
just need to format the output to match the CACHEDATA
entries syntax which is almost always as simple as printing a
formatted string.
Linking the data to the elements. No matter what kind
of data source is used the linking works the same way. Each Field
object has two properties that specify which element on the label
is controlled by it. These are Field.Element
and Field.Property and they
specify the name of the element and which property of the specified
element to fill with the data in the field when the data set is
navigated. The ActiveX provides also user interface that can be used
for that purpose - for example each element has a Data connection
property sheet.
The limitation caused by this approach is that one
data field can be linked to only one element and only one of its
properties. Most often this is enough and if it is not the duplication
of a field is not difficult - you just need to configure two fields
that will be filled with the same values or if you use external
database duplicate the output in the query.
Interactive
editing. The Active Label ActiveX implements the full set of
features needed for interactive editing. The application or WEB page
that hosts the control needs to do very little to incorporate full
interactive label editing. For instance it needs to provide a few user
interface elements such as buttons that create new elements on the
label, some other elements that would provide the user with convenient
way to control some of the general control view settings (such as zoom
for example) and some UI elements to invoke load/save operations for
example. Most of the work is done by the control itself and the
application/page needs to implement only some simple method calls or
change certain properties in response to the user actions. The control
implements many property sheets that implement suitable user interface
for managing the settings of the entire control and its elements - see
the ShowProperties methods of each object. Although every
developer will have his/her own opinion about how such user interface
should look having it saves the need to implement such. Of course if
you want to provide alternative way to manage some of the settings you
can do so in your application/page, but every time you need to hurry
you can simply provide means for opening the control's property pages
without spending efforts on this. Later if the time permits it you can
add more pretty-looking replacements for the parameters most often
used in your case.
Active Label provides methods that allow the user
to draw the frame or click the location where a new element is to be
created - see VisiLabel.Edit.IntereactiveNew
and VisiLabel.Edit.IntereactiveCancel.
Sometimes it is preferred to create the new elements at predefined
locations and then allow or not allow (as appropriate) the user to
change them. You can use VisiLabel.CreateElement
to do that. The interactive mode is controlled by the VisiLabel.Edit
object, the VisiLabel.Edit.EditMode
property switches between view and edit mode. In edit mode the user
can also use the keyboard to change the selection or move the selected
element, or invoke its property sheets by double click or pressing
Enter. The keyboard shortcuts are described in the ActiveX UI help
file (which can be also invoked from any of the control's dialog
boxes).
Through the property pages of the Active Label objects the
user has access to the connectivity options - see the Load and Save
property pages. For example if the user opens the property pages of an
image element he/she can load an image in it from any location. These
property pages also give the user means to upload data, but this is,
of course of little use except for the administrators and the
developers because the user must know where to upload. Therefore the
saving/upload of the label or the elements on it should be simplified
by the application/page that hosts the control. This means that the
application should configure the control for upload and minimize the
information that needs to be supplied by the user. For example an WEB
application can just provide a button that the user clicks. In
response to this the page on which the control resides can invoke
upload of the images on the label and then the label itself to the URL
on which resides the application's label repository script/module
which is of course known to the page when it is loaded. Thus the user
is simply required to click a button and the rest of the work can be
done without need of more user interactions. The developer should
notice that the upload of a label with images requires a bit more
attention - the page needs to upload the images, if everything is ok
update the references into the label to the locations from which the
saved images can be obtained from that point further and just then
upload the label. The Active Label ships with some examples that
illustrate this. Typically it requires 10-20 lines of Javascript code
to invoke the operation and handle the OnPostCompleted
event. The other side (on the server) is quite simple as well. In
contrast to the file upload implemented by the browsers the Active
Label uses simpler mechanisms which require no additional components
or libraries on the server and almost all of the work the
script/module needs to do is to check a few URL arguments and decide
where to put the received data depending on the applications
structure. See the next section or go directly to the How to Download and Upload
for more specific information.
Connectivity. This has
been mentioned in the other sections. Lets summarize the connectivity
capabilities of the Active Label:
Download/load: The VisiLabel
object, the Image element and the Text
(box) element support common features available through their Src
property and Reload method. The entire label (through the VisiLabel
object) or the image displayed by the image element, or the text
displayed in a text element can be downloaded dynamically from a
local or remote source through any URL protocol. The download is
asynchronous (except while printing) and the application can stay
unformed about the the result of any such operation initiated by it
by intercepting the VisiLabel object's events - see OnDownloadCompleted.
By "dynamic" we mean that changing the Src property of the
objects that support it invokes an immediate download of the data
pointed by the new URL put into the property. This is just like the
IMG element in MS Internet Explore.
Upload/post. The VisiLabel
object, the Image element and the Text
(box) element support common features available through their Dst,
PostVerb, PostParams properties and the PostData method. The label
(through the VisiLabel object) or the data of the individual Image
or Text elements can be uploaded/posted to the URL put into the Dst
property. The operation proceeds asynchronously and the application
can keep in touch with the results by handling the VisiLabel
object's events - see OnPostCompleted.
The
details about the download and upload operations are discussed in How to Download and Upload.
A
question you may ask: If it is possible to upload the label or some
of its elements separately to any URL is it possible to save them to
the local file system?
The answer is not simple: A C++ application that hosts the control
can use the IPersistStreamInit supported by the VisiLabel object and
the Image and Text element objects to direct the data to a file
stream. However from a script on a WEB page this is not possible for
security reasons. Still, if you use a solution like Active Local
Pages (ALP) you can save the data locally by posting to an URL and
writing an acceptor script which will do the actual file writing.
Solutions like ALP work like WEB servers but they are doing
everything locally only imitating network functionality. Thus the
code you will need in such an environment will be the same as on a
WEB server that supports the same programming language (in the ALP
case you can use ASP). Obviously it is not appropriate to allow data
from the control to be saved directly to the disk, because this will
enable any WEB page to mess with the local file system and to avoid
this a complicated security mechanisms would be required.
